> ## Documentation Index
> Fetch the complete documentation index at: https://aspex.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 →](/tools/doctor)                  |
| `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](/tools/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 →](/reference/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](/reference/rules#agent-hooks).

## inspect

```sh theme={"dark"}
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
```

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

## 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.

```sh theme={"dark"}
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.