scan subcommands

hooks, inspect, inventory, attack-paths, shadow, phantom, fix env, cron, install-hook and the rest of aspex scan.

Subcommand	Runs
init	Write a starter .aspex.yaml policy in the current directory
hooks	Discover and judge agent lifecycle hooks
doctor	2-second offline pre-flight. Own page →
inspect <target>	Scan a single server by command string or URL
inventory	List every detected server and all their tools
attack-paths	Every server’s capabilities with evidence, and the compositions they form
shadow	Tool name collisions across servers
phantom	Servers that return different tool lists on successive calls
fix env	Migrate hardcoded credentials from config to macOS Keychain
explain <server>	Full risk narrative for one server
redteam	Active adversarial probing. See aspex attack
install-hook	Git pre-commit hook that blocks risky MCP config changes
cron	Run on a schedule for continuous monitoring
corpus test	Run the public benchmark. Corpus →

​

hooks

Reads the lifecycle hooks in ~/.claude/settings.json and the project’s .claude/settings.json: commands the agent runs on its own, before or after a tool call, on stop, or on prompt submit. Every hook is surfaced, benign ones included; a hook is standing executable state most people forget, and the target a persistence path (AP003) would write. Rules HOOK000–HOOK005 in Rules.

​

inspect

aspex scan inspect "npx -y @modelcontextprotocol/server-filesystem ~/projects"
aspex scan inspect https://mcp.example.com/sse

One server, not yet in any config. Useful before pasting a README’s config block, and for cloud connectors that have no local file.

​

attack-paths

Every server’s capabilities with evidence, allowed roots, file scope, and the agent-state files a writable root reaches, then the compositions. Also shown in a normal scan; this view adds --json with the full capability list.

​

shadow and phantom

shadow finds two servers exposing a tool with the same name; the model may route calls to either non-deterministically. phantom connects twice and diffs the tool lists; a tool that appears only on the second call is hiding from enumeration.

PHANTOM TOOLS DETECTED
  Server: analytics-mcp
    Call 1:  query_db, export_csv
    Call 2:  query_db, export_csv, exfil_data   ← appeared on second call

Phantom tool behavior is a strong indicator of malicious intent. Remove the server until you can audit its source.

​

fix env

Finds every hardcoded credential in MCP config env blocks and moves it to macOS Keychain, replacing the plaintext value with a $(security find-generic-password ...) substitution resolved at server start.

  ✓ GITHUB_TOKEN   → keychain:aspex/github/GITHUB_TOKEN
  ✓ SLACK_TOKEN    → keychain:aspex/slack/SLACK_TOKEN
Config updated. Plaintext values removed.

​

install-hook and cron

install-hook writes a Git pre-commit hook that runs aspex-scan --no-exec --fail-on high and blocks the commit on a HIGH or CRITICAL finding; it reads your .aspex.yaml, so accepted risks apply. cron --interval 6h keeps a scan loop running in the foreground and can post new HIGH or CRITICAL findings to a webhook with --notify. For active development, aspex scan --watch is lighter: it re-scans on any config change and prints the security-relevant drift.

​

Reports

--share writes a privacy-safe Markdown summary with server commands, env values and paths redacted. --report soc2 or --report iso27001 maps findings to controls and emits PASS/FAIL per control.

--html writes a self-contained report (one file, no external assets) built to be shared: attach it to a PR, drop it in Slack, or open it in a browser. Alongside the per-server findings it renders the two things that are hard to read as terminal text:

• Attack paths. Each composed cross-server path drawn hop by hop, from the source instruction through the servers involved to where the data leaves, with the impact and what removes it.
• Blast radius. The overall reach (HIGH/MEDIUM/LOW), with every contributing reason listed present or absent, and a note explaining any score cap.

aspex scan --html report.html

The report contains no secret values, only what a scan already prints. Server tool names and descriptions are HTML-escaped, so an untrusted server cannot inject markup into a report you share.