aspex scan

Every configured server, its live tool list, the attack paths they compose, and the blast radius. Offline; nothing is sent anywhere.

aspex scan                  # every configured server, live tool lists, attack paths, blast radius
aspex scan --no-exec        # configs only, nothing launched, under a second
aspex scan hooks            # the commands your agent runs automatically
aspex scan doctor           # 2-second pre-flight: leaked secrets, broad paths, plaintext HTTP

aspex scan reads every MCP client config on the machine, connects to each server (stdio and HTTP/SSE), enumerates tools, resources and prompts, and produces a scored report. Servers are inspected in parallel, so a scan takes about as long as the slowest server.

Reading the output

Per-server findings come first, then the compositions across servers. Each attack path shows the two capabilities, the evidence for both, the path hop by hop, and a fix. This is real output; every server in it is an official, well-behaved package.

  CRITICAL  AP001  Potential sensitive data exfiltration path  confidence: high
     filesystem
       └─ read_file: reads files by path
       └─ allowed root /Users/steven (home directory: includes ~/.ssh, ~/.aws, browser profiles)
     playwright
       └─ browser_navigate: reaches network destinations (takes a URL parameter)

     Path
         instruction from a prompt, document, or tool result
       ↓ filesystem.read_file reads credential files such as ~/.ssh and ~/.aws
       ↓ contents enter the agent's context
       ↓ playwright.browser_navigate sends them to any network destination

     Why it matters
       An instruction the agent processes could combine these two
       capabilities to expose credential files such as ~/.ssh and ~/.aws
       outside this machine. Nothing here proves it has happened; the
       path exists.

     Fix
       scope filesystem to specific project directories instead of
       /Users/steven; constrain playwright to an allowlist of
       destinations. Either change alone removes the path.

Severity	From what the composition reaches. A home-scoped read next to open egress is critical; the same read scoped to a project is high.
Confidence	From how the capabilities were observed: high from a live tool list, medium when inferred from a well-known package (--no-exec).
Evidence	The tool, or the allowed root from your own config. Nothing is asserted without one.

The six attack paths

ID	Composition	Highest
AP001	Local file read + network egress or external channel	critical
AP002	Credential or environment read + egress	critical
AP003	External content ingress + writable agent config, hooks, instructions or memory	critical
AP004	External content ingress + persistent memory write	medium
AP005	Command execution + open egress	critical
AP006	External content ingress + command execution, no open egress	high

A capability on its own is never a path. One critical path caps the overall score at 39; one high path at 69. Why, and the full severity rules →

Flags

Flag	Description
--no-exec	Configs only; nothing is launched. Capabilities inferred for well-known packages at medium confidence
--explain	Evidence and full advisory for every finding: WHY, EXPLOIT, IMPACT, CONFIDENCE
--fail-on <sev>	Exit 1 when any finding or path reaches critical, high, medium or low. .aspex.yaml can set the default
--json · --sarif · --html	Machine-readable output, GitHub Code Scanning, or a self-contained, shareable report (attack paths and blast radius included)
--baseline <file> · --save-baseline <file>	Hide known findings and never fail on them; write the current set as a new baseline
--with-trace · --trace-since	Correlate findings with what your agents actually did (default window 7d)
--clients	Limit to specific clients, e.g. --clients claude,cursor
--watch	Re-scan on config change and print the security-relevant drift
--share · --report soc2|iso27001	Privacy-safe Markdown summary; compliance PASS/FAIL report
-j, --concurrency	Servers inspected in parallel (default 8)
--config	Path to .aspex.yaml (default ./.aspex.yaml, then ~/.config/aspex/config.yaml)

See Policy, baselines and prioritization for how --fail-on, --baseline and .aspex.yaml fit together.

Subcommands

The ones you will reach for most. Each is described in scan subcommands.

hooks

Commands your agent runs automatically, judged

doctor

2-second offline pre-flight

inspect <target>

One server by command string or URL

attack-paths

Capabilities with evidence, and compositions

shadow · phantom

Name collisions; tool lists that change between calls

fix env

Move plaintext credentials to Keychain

Rules

140+ rules across prompt injection, code execution, credential access, exfiltration, persistence, surveillance, supply chain and more. Findings map to OWASP LLM Top 10 2025, MITRE ATLAS and CWE. All rules →

Run aspex scan before adding any new MCP server. aspex mcp lets your agent do this itself: pass a proposed .mcp.json to aspex_security_impact and see the new attack paths before the edit lands.