mcp-audit: Instructions file for Claude Code

mcp-audit

An open-source, privacy-first CLI tool that scans MCP (Model Context Protocol) server configurations for security vulnerabilities. Think "Snyk for MCP servers."

What this project does

Developers use MCP servers to give AI agents (Claude, Cursor, VS Code Copilot) access to tools — file systems, databases, APIs, etc. These servers are configured via JSON files and can be poisoned, misconfigured, or compromised. mcp-audit scans those configs and flags security issues.

Business model

Fully open source under Apache 2.0 — every feature is free for every user. There is no Community / Pro / Enterprise split, no license-key gate, and no paid tier. All paid-license plumbing (Ed25519 signing, revocation lists, activate / license commands, the gate() shim) was removed in v0.2.0; anything that still references licensing.py or _gate.py is stale. Funding is requested via GitHub Sponsors (handle configured in .github/FUNDING.yml, with a "Support" section in README.md), not through feature gating.

Tech stack

• Python 3.11+, managed with uv
• CLI: Typer + Rich
• Data models: Pydantic v2
• Testing: pytest + pytest-asyncio
• Linting: Ruff + Bandit
• Packaging: hatchling via pyproject.toml

Project layout

src/mcp_audit/
├── cli/               # Typer app package — one submodule per command group
│   ├── __init__.py      # Defines `app` + sub-apps (baseline/rule/policy/extensions/
│   │                    #   agent-files); re-exports `run_scan`, `discover_configs`,
│   │                    #   `parse_config`, and `_REGISTRY_CACHE_PATH` so test
│   │                    #   patches at `mcp_audit.cli.*` continue to intercept.
│   │                    #   Imports the command submodules at the bottom so their
│   │                    #   `@app.command()` decorators register.
│   ├── __main__.py      # `python -m mcp_audit.cli` entry (plus PyInstaller target)
│   ├── _helpers.py      # Cross-cutting helpers (`_write_output`)
│   ├── scan.py          # scan, discover, pin, watch (+ `_drift_to_findings`,
│   │                    #   `_scoped_state_path`, `_newest_last_seen`).  The
│   │                    #   `scan` command is composed from `_apply_*` pipeline
│   │                    #   stages (baseline drift, governance, SAST, extensions,
│   │                    #   agent-files, severity filter) and `_write_*` output
│   │                    #   helpers — see "scan() pipeline conventions" below.
│   ├── check.py         # check command: one-page practitioner verdict (+ _write_pdf_report)
│   ├── fix.py           # fix command: apply safe remediations to config files
│   ├── diff.py          # diff command: MCP-aware diff for PR review / CI gates
│   ├── baseline.py      # baseline sub-app: save / list / compare / delete / export
│   ├── registry.py      # update-registry, verify
│   ├── rules.py         # rule sub-app: validate / test / list
│   ├── policy.py        # policy sub-app: validate / init / check (+ `_POLICY_TEMPLATE`)
│   ├── extensions.py    # extensions sub-app: discover / scan
│   ├── agent_files.py   # agent-files sub-app: discover / scan (skills, memory, hooks)
│   ├── plugins.py       # plugins sub-app: discover / scan (Claude Code plugins, STORY-0080)
│   ├── sast.py          # sast command
│   ├── sbom.py          # sbom command: CycloneDX 1.5 SBOM export
│   ├── vet.py           # vet command: pre-install package verdict (offline, facts not grades)
│   ├── shadow.py        # shadow command: shadow MCP server sweep (+ --continuous daemon)
│   ├── killchain.py     # killchain command: top blast-radius-cutting changes
│   ├── snapshot.py      # snapshot command: signed forensic snapshots (+ --rehydrate/--stream)
│   ├── dashboard.py     # dashboard command
│   ├── fleet.py         # merge command (+ `_collect_json_paths_from_dir`,
│   │                    #   `_print_fleet_report`)
│   ├── push_nucleus.py  # push-nucleus command: scan + push to Nucleus FlexConnect API
│   ├── register.py      # register command: interactive opt-in flow, --clear, --status
│   ├── advise.py        # advise command + feed sub-app (feed verify): OSV advisory feed
│   └── version.py       # version command
├── scanner.py         # Orchestrator: discovery → parsing → analysis → output
├── scoring.py         # Scan score calculation (0–100) and letter grade (A–F) formatting
├── discovery.py       # Finds MCP config files across all supported clients; `_PROJECT_AUTOEXEC_SPECS` drives the TRUST-003/008 auto-run walk (`--project`) and the TRUST-003/008 cwd-root check of a default scan (skipped when cwd is `$HOME`) (`discover_cwd_autoexec_files`, called from `scanner._cwd_autoexec_findings`); see docs/agent-execution-surface.md
├── config_parser.py   # Parses JSON configs, normalizes across client formats
├── models.py          # Pydantic models: Finding, ServerConfig, ScanResult, ScanScore, Severity, AttackPath, MachineInfo
├── owasp_mcp.py       # Single source of truth for OWASP MCP Top 10 codes/names (MCP01–MCP10)
├── verdict.py         # Pure verdict builder for `vet` (shared with the mcp-audit.dev generator)
├── watcher.py         # Filesystem watcher for continuous monitoring (mcp-audit watch); _McpConfigEventHandler serialises callbacks via _scan_lock with single-event coalesced re-trigger
├── mcp_client.py      # Live MCP server connection via MCP SDK (--connect)
├── _paths.py          # data_dir() and resolve_bundled_resource() — shared helpers for locating bundled data in source, wheel, and PyInstaller frozen contexts
├── _network.py        # NetworkPolicy + require_offline_compatible() — centralised --offline mutual-exclusion enforcement for network-touching flags
├── _gitignore.py      # Is a file git-ignored? Read-only (never runs git): gitignore(5) matcher with linear-time wildcards; reads .gitignore files (symlinked ones skipped, as git ≥2.32), .git/info/exclude and the global excludes file (core.excludesFile / XDG, a plain [include] path followed one level); BOM, `***`, empty segments as git; 1 MiB per file, 512-file / 8 MiB budget, anchored patterns longer than the path rejected up front, 5,000,000-step matching budget (MatchMeter); unreadable or over budget → IgnoreStateUnknownError + error text without absolute paths (STORY-0093)
├── analyzers/
│   ├── base.py         # BaseAnalyzer abstract class — all analyzers inherit this
│   ├── poisoning.py    # Tool description poisoning detection (regex-based); PATTERNS list reused by agent_files; also owns POISON-041/042 concealment-channel extract/decode/rescan (scan_concealed_channels, build_concealment_finding), shared with agent_files
│   ├── credentials.py  # Secret/API key exposure in configs (SECRET_PATTERNS)
│   ├── transport.py    # Transport security (TLS, localhost binding, etc.)
│   ├── supply_chain.py # Package provenance and typosquatting detection (registry-backed); SC-007 unscoped twins (takes precedence over SC-001..003) and SC-008 OSV MAL-* exact-name matches (STORY-0097); redact_command() for evidence
│   ├── config_hygiene.py # Config-file filesystem hygiene (CFHYG-001..007; CFHYG-007 = project settings `env` redirecting API traffic, STORY-0090); hook-command checks HOOK-001/002 and harness posture HARNESS-001..007 (STORY-0079, STORY-0087, STORY-0090) via analyze_config; repo-planted auto-run files TRUST-003 (VS Code) and TRUST-008 (Gemini CLI, Codex, Claude Code scheduled tasks/workflows, STORY-0090) via analyze_autoexec_file
│   ├── rug_pull.py     # Config-entry change detection via hashing (command, args, env key names, raw entry; not live tool definitions)
│   ├── toxic_flow.py   # Cross-server capability tagging and dangerous pair detection (TOXIC-001..011, INTEG-001; COMMS_OUT sinks TOXIC-008..011, STORY-0101)
│   ├── auth.py         # Remote server authentication checks (AUTH-001, AUTH-002)
│   ├── collision.py    # Tool-name collision detection across --connect servers (COLLIDE-001)
│   ├── delegation.py   # Cross-tool delegation in live tool descriptions (DELEG-001..003, STORY-0100): names another
│   │                   #   server's tool / trigger + action its server lacks / rewrite another tool's arguments;
│   │                   #   token-based, budgets shared fairly per server, redacted evidence; runs in run_scan_async
│   │                   #   after COLLIDE-001 (needs --connect: the lock holds digests, not text); SHIPPED_SEVERITY
│   │                   #   must equal results.json's measured gate decision
│   ├── git_exec.py     # Git can run code (TRUST-006/007, STORY-0089): tolerant git-config parser, command-key table (_RULES), includes/worktree configs/gitfiles, hooks, nested bare repos; scan_cwd_repository() (default scan/check, via scanner._discover_and_parse) and scan_git_surfaces() (--project, via discovery.discover_project_git_surfaces); check_git_config() is the standalone per-file API (STORY-0096). Never runs git; not a BaseAnalyzer
│   ├── permissions.py  # Claude Code permission-rule linter (PERM-001..007, STORY-0092): public settings parser (load_claude_settings, reused by sandbox checks); PERM-001..006 via config_hygiene.analyze_config, PERM-007 as _run_static_pipeline step 5b and again across scopes in cli/scan._apply_project_scan; every rule quoted from code.claude.com/docs (docs/permission-rules.md)
│   ├── sandbox.py      # Claude Code sandbox settings a repository can loosen (SANDBOX-001..005, STORY-0093): reuses permissions.load_claude_settings; all five run as _run_static_pipeline step 0b (analyze_sandbox_files, NOT analyze_config), each file in its own try: a SandboxContext says whose file it is (shared project file = repository; settings.local.json = repository only when no ignore file covers it or .claude is a symlink, MEDIUM cap when its git state is unknown, user's own when ignored or outside a work tree; user settings get only SANDBOX-004) and carries UserSettingsLocks read from ~/.claude/settings.json (strictAllowlist → SANDBOX-003/proxy ports INFO; defaultMode bypassPermissions/auto → SANDBOX-002 HIGH); SANDBOX-005 (local settings headed for git, home paths with a masked username) via _gitignore.py; errors prefixed "SANDBOX checks: "; key scopes from code.claude.com/docs settings-reference (docs/permission-rules.md)
│   └── attack_paths.py # Multi-hop attack path detection and greedy hitting set algorithm; one path per hop sequence, the most severe pair's (STORY-0101)
├── agent_files/       # Agent instruction/memory file scanner (SKILL-001/002/003, MEM-001..004; also emits POISON-041/042, analyzer="poisoning")
│   ├── __init__.py    # Package marker; offline-only invariant docs
│   ├── models.py      # AgentFile dataclass (+ follows_imports, imported_from, edges), AgentFileSurface StrEnum, MEMORY_SURFACES, ImportEdge
│   ├── discovery.py   # discover_agent_files(); user-global + project-tree walk (mirrors discovery.py conventions); AGENT_INSTRUCTION_PATTERNS incl. AGENTS.md, CLAUDE.local.md, .claude/rules, OpenClaw workspace files (STORY-0098); discover_root_agent_files() / discover_user_heartbeat_files() for the default scan; 4 MiB per-file read cap and a per-call budget
│   ├── imports.py     # Claude Code @path imports (documented rules: relative to importer, 4 hops, code/comments skipped) and "read X" prose references; follow_references() never reads outside the root or through a symlink (TRUST-002/004), budgeted (STORY-0098)
│   ├── gitignore.py   # .gitignore matcher read by file (never runs git), non-backtracking wildmatch; MEM-003's "ignored" case
│   ├── heartbeat.py   # MEM-004 detector: HEARTBEAT_OK/NO_REPLY/notify:false forced, paired with hiding, or after an action
│   ├── reach.py       # MEM-003/MEM-004 in the default scan (cwd root + ~/.openclaw/workspace/HEARTBEAT.md, via scanner._cwd_instruction_reach_findings) and scan --project (cli/scan._apply_project_instruction_reach); never raises
│   ├── analyzer.py    # analyze_agent_files(); imports PATTERNS from analyzers/poisoning.py (never forked), plus scan_concealed_channels/build_concealment_finding for POISON-041/042; calls skill_package.sidecar_findings for a skill's other prose files; MEM-003/004 via analyze_instruction_reach(); imported files get the importer's rules, secrets redacted. NB: HOOK-001/002 live in analyzers/config_hygiene.py, not here
│   ├── skill_package.py # STORY-0095: every file in a skill folder (SKILL-005..008), default scan/check (scanner._discover_and_parse → scan_default_skills) and scan --project (cli/scan._apply_project_skills; a skills-dir plugin's config is listed once, as claude-code-plugin, and not re-analysed when the default scan already did); a nested SKILL.md folder is its own package only when discovery returns it (else walked with the parent); .git text records are read, git binaries magic-checked; follows a symlink directly under a skills dir one level when it points at a skill (TRUST-004 INFO; a repo link leaving the repo is TRUST-002 HIGH, not read; decision 2026-10-26) and no other symlink (TRUST-002/004/005), O_NOFOLLOW reads under per-file/per-skill/per-scan budgets, errors → ScanResult.errors; skills-directory plugin (.claude-plugin/plugin.json) servers join discovery as "claude-code-plugin" (discovery._skills_dir_plugin_configs); carried .mcp.json routed through per-server analyzers as "claude-code-skill" (never discovered; check never offers `fix`)
│   ├── install_steps.py # STORY-0095: pure text/byte checks (no I/O): SKILL-005 install-step shapes with per-file literal gates (parity-tested), SKILL-006 text shapes, SKILL-007 format/blob identification, redact()
│   └── subagents.py   # Claude Code subagent definitions (STORY-0094): frontmatter read the way Claude Code's loader reads it (1 MiB file cap, split at the first `---` anywhere, quote-and-retry on a YAML error) plus the `---`-line reading, findings from both; repeated/unreadable security keys are findings; node/nesting/alias budgets; agent_mcp_servers() (one server per item, repeats `name#2`), analyze_agent_definition() AGENT-001..004; files join default discovery as client "claude-code-agent" (discover_configs(include_agents=True); never with --path; lock opts out; auto-verify skips them and lists project ones under a lock root in `lock_status.not_covered`; rug-pull state key excludes), step 0 via ConfigHygieneAnalyzer.analyze_agent_definition (+HOOK-001/002)
├── plugins/           # Claude Code plugin inventory + integrity (PLUGIN-001/002); offline, reads ~/.claude/plugins records only
│   ├── models.py      # InstalledPlugin dataclass; GIT_SOURCE_TYPES; pinned_sha / source_type
│   ├── discovery.py   # discover_installed_plugins(), plugin_agent_files(), plugin_mcp_config_paths(); plugin MCP servers join default auto-discovery (discover_configs(include_plugins=True) is the default; never with an explicit --path; lock opts out; lock auto-verify skips them, listing a repository's skills-directory plugin servers under a lock root in `lock_status.not_covered`; excluded from the rug-pull state key) as client "claude-code-plugin" — skills-directory plugins (`~/.claude/skills/<name>/.claude-plugin/plugin.json`, cwd `.claude/skills/…`) join the same way (STORY-0095), except that the cwd's are `is_project_scoped` and stay in the rug-pull state key so one repository's plugin servers never show up as RUGPULL-003 in another's scan
│   ├── analyzer.py    # analyze_plugin_integrity() — PLUGIN-001 (recorded version != pinned sha prefix), PLUGIN-002 (unpinned git source)
│   └── mods.py        # Claude Code mods (STORY-0085): discover_mods() (installed plugins, ~/.claude/dev-mods, CLAUDE_CODE_PLUGIN_DIRS), static read of hooks modules (never executed), read_guard_state() (managed-settings file), analyze_mods() MOD-001..005, analyze_plugin_dirs_setting() MOD-006; wired into default discovery next to PLUGIN-001/002
├── ci_workflows/      # GitHub Actions workflows that run an AI agent (WORKFLOW-001..003, STORY-0091); YAML read with safe_load, never run
│   ├── discovery.py   # discover_workflow_files(): <root>/.github/workflows/*.y{a,}ml (top level only); walk=True (--project) adds nested repo roots (a .git entry); a symlinked .github or workflows dir is not read and every file must resolve inside root; 256 KiB per file, 4 MiB per call; size/budget skips and an unreadable workflow dir or file (stat(), not is_dir(), which hides EACCES from 3.13) reported to the caller's errors; every probe catches OSError
│   └── analyzer.py    # analyze_workflow_files(): steps using claude-code-action / claude-code-security-review / run-gemini-cli × stranger-writable trigger × secret in with/env × write (or absent) permissions × tool posture per vendor docs; workflow_call evaluated once per local caller path (triggers + token ceiling); every pass over untrusted text is linear — ${{ }} extraction (no lazy-dot regex), whole-shell rule matching (no adjacent \s* quantifiers), claude_args splitting (_posix_split, not shlex, whose per-char token concatenation is quadratic); parse cached by SHA-256 of the bytes
├── lock/              # mcp-lock.json (ADR-0005): committable record of approved servers
│   ├── model.py       # ownership boundary + top-level checksum ({lock_version, generated_by, servers})
│   ├── writer.py      # regenerate()/write_lock(); foreign sections preserved; owned `tools` merged
│   ├── verifier.py    # lock --verify: LOCK-001..005, and LOCK-006..009 with --connect
│   ├── tool_digests.py # `tools` section (STORY-0086): per-tool definition/contract digests, own _checksum
│   └── identity.py, resolve.py, discovery.py, auto_verify.py
├── advisory/          # OSV 1.6.0 advisory records + signed feed (mcp-audit advise / feed verify)
│   ├── __init__.py    # Package marker; re-exports Advisory, build_advisory, write_feed, sign_feed, verify_feed
│   ├── schema.py      # Advisory dataclass → OSV 1.6.0 JSON; stable `x_MCPSA-<12hex>` IDs; MCP metadata under affected[].database_specific; FINDING_CLASS_TO_OWASP + owasp_for(); rejects codes owasp_mcp.py does not define
│   ├── classify.py    # finding ID → finding_class / observation / CVSS 3.1 vector (cvss_base_score reconciliation); owasp_codes_for() validates against owasp_mcp.py; is_advisable() excludes non-vulnerability findings
│   ├── canonical.py   # RFC 8785 JCS canonicalization (UTF-16 key order, ECMAScript number format) — the bytes that get signed; depth/size bound (CanonicalError)
│   ├── freshness.py   # snapshot_version / published_at / expires on index.json only; TTL; seen.json keyed on signing identity
│   ├── feed.py        # build_advisory / build_advisories / write_feed (advisories/, index.json, osv/all.json+zip); resolve_package, redact; feed_version 1.1
│   ├── sign.py        # cosign (default) + minisign backends, static project key; sign_feed / verify_feed / feed_is_signed; signing block embedded in index.json
│   ├── validate.py    # validate_osv() against the vendored schema; ValidationUnavailableError when jsonschema is absent
│   └── osv_schema/    # Vendored osv-1.6.0.json — pinned, offline, bundled in wheel and PyInstaller binary
├── attestation/       # Supply-chain integrity verification (Layer 1 hashes, Layer 2 Sigstore)
│   ├── __init__.py    # Package marker
│   ├── hasher.py      # HashResult dataclass; compute_hash_from_file/url; resolve_npm/pip_tarball_url; verify_package_hash
│   ├── verifier.py    # verify_server_hashes(); extract_version_from_server(); bridges registry → hasher → Finding objects
│   ├── sigstore_client.py   # Layer 2 Sigstore bundle discovery/verification via npm + PyPI registry APIs
│   └── sigstore_findings.py # AttestationResult → Finding translation for Layer 2 Sigstore verification
├── baselines/
│   ├── __init__.py    # Package marker
│   └── manager.py     # BaselineManager, Baseline, BaselineServer, DriftFinding, DriftType; save/load/compare
├── registry/
│   ├── __init__.py    # Package marker
│   ├── loader.py      # KnownServerRegistry, RegistryEntry, load_registry(); Levenshtein helper
│   ├── twins.py       # TwinIndex: unscoped-twin keys derived from registry entries (SC-007, STORY-0097); pure, no I/O
│   └── malicious.py   # load_known_malicious(), assess(): registry/known-malicious.json (OSV MAL-*) for SC-008 and vet; tolerant loader with size/entry caps, load_error surfaced in ScanResult.errors
├── rules/
│   ├── __init__.py    # Package marker
│   └── engine.py      # PolicyRule, RuleMatch, MatchCondition, RuleEngine; load_rules_from_file/dir; load_bundled_community_rules
├── governance/
│   ├── __init__.py    # Package marker
│   ├── models.py      # GovernancePolicy, ApprovedServers, ScoreThreshold, TransportPolicy, RegistryPolicy, FindingPolicy, ClientOverride, PolicyMode
│   ├── loader.py      # load_policy(); resolution order: explicit → cwd → repo root → user config
│   └── evaluator.py   # evaluate_governance(); per-server policy checks; produces Finding objects with analyzer="governance"
├── vulnerability/     # OSV.dev CVE lookups for `scan --check-vulns` (network, opt-in)
│   ├── __init__.py    # Package marker
│   ├── models.py      # ResolvedPackage, VulnAdvisory data models
│   ├── resolver.py    # extract_ecosystem_and_version(); resolve_latest_version() from a ServerConfig
│   ├── depsdev.py     # fetch_transitive_deps() — transitive dependency graph from deps.dev
│   ├── osv.py         # query_vulns_batch() — OSV.dev batch CVE query
│   └── scanner.py     # check_vulnerabilities() — orchestrates resolver → depsdev → osv → Finding objects
├── diff/              # MCP-aware diff engine (mcp-audit diff)
│   ├── __init__.py    # Package marker
│   ├── loader.py      # Load diff inputs (directory, JSON scan file, or git SHA) into ServerConfig lists
│   ├── comparator.py  # Compare two ServerConfig lists → flat list of Change objects
│   ├── risk.py        # Risk classification for diff changes
│   └── render.py      # Render diff to terminal, JSON, and PR-comment Markdown
├── fixer/             # Safe-remediation engine (mcp-audit fix)
│   ├── __init__.py    # Package marker
│   ├── fixer.py       # Fixer orchestrator — load config, apply strategies, write atomically with .bak
│   └── strategies/
│       ├── __init__.py     # Package marker
│       ├── base.py         # FixStrategy abstract base
│       ├── credentials.py  # CRED-001/002/003 — redact plaintext secrets with ${ENV_KEY}
│       ├── transport.py    # TRANSPORT-001 — upgrade http:// URLs to https://
│       └── pinning.py      # SC-001/002 — replace typosquat with verified registry name @version
├── killchain/         # Decision engine over the attack-path graph (mcp-audit killchain)
│   ├── __init__.py    # Package marker
│   ├── recommender.py # Rank kill switches from the hitting-set output by incremental path reduction
│   ├── simulator.py   # What-if simulation: re-run summarize_attack_paths against the modified server list
│   ├── patches.py     # Generate governance-policy denylist / PR-comment patch snippets
│   └── render.py      # Markdown and JSON output formatters for killchain results
├── shadow/            # Shadow MCP server detection (mcp-audit shadow)
│   ├── __init__.py    # Package marker
│   ├── allowlist.py   # Operator allowlist of sanctioned servers; load/match
│   ├── classifier.py  # Pure sanctioned-vs-shadow classification given server + allowlist
│   ├── risk.py        # RiskLevel scoring for a single server (toxic-flow capability logic)
│   ├── events.py      # Structured events for --continuous daemon mode (new_shadow_server, server_drift, server_removed)
│   └── state.py       # first_seen/last_seen state at <user-config-dir>/mcp-audit/shadow/state.json (0o600)
├── snapshot/          # Forensic snapshot rehydrate/diff (mcp-audit snapshot)
│   ├── __init__.py    # Package marker
│   ├── rehydrate.py   # Reconstruct the historical attack-path graph from a recorded snapshot JSON
│   └── diff.py        # "What changed since the snapshot?" — servers added/removed/changed
├── output/
│   ├── __init__.py    # Package marker
│   ├── base.py        # BaseFormatter abstract class — all formatters inherit this
│   ├── terminal.py    # Rich-formatted console output (default); renders score/grade panel
│   ├── sarif.py       # SARIF for GitHub Security integration
│   ├── nucleus.py     # Nucleus FlexConnect formatter
│   ├── dashboard.py   # Self-contained HTML dashboard with embedded D3 v7 graph and grade badge
│   ├── check.py       # One-page security verdict formatter for `mcp-audit check` (_HINTS)
│   ├── advisory.py    # AdvisoryFormatter(BaseFormatter) — ScanResult → JSON array of OSV 1.6.0 records; byte-identical to feed/osv/all.json (feed *directories* stay in advisory/feed.py)
│   ├── cyclonedx.py   # CycloneDX SBOM formatter (supports cyclonedx-python-lib 7.x–11.x)
│   ├── snapshot.py    # Snapshot formatters: CycloneDX AI/ML-BOM and native JSON
│   └── pdf.py         # Letter-size PDF compliance report (mcp-audit scan --report pdf)
├── extensions/
│   ├── __init__.py    # Package marker
│   ├── models.py      # ExtensionManifest, ExtensionVulnEntry Pydantic models
│   ├── discovery.py   # discover_extensions(), parse_manifest(); EXTENSION_PATHS per-client config
│   └── analyzer.py    # analyze_extensions(); check_known_vulns, check_permissions, check_wildcard_activation, check_provenance, check_sideloaded, check_stale; load_vuln_registry()
├── registration/
│   ├── __init__.py    # Package marker; privacy-invariant docs
│   ├── models.py      # RegistrationConfig, RegistrationPostPayload, RegistrationPingPayload Pydantic models
│   ├── manager.py     # load/save/clear_registration(); build_registration(); 0o600 file write; platformdirs storage
│   └── client.py      # post_registration() (PII POST, once); post_ping() (no-PII, per `check` run); _REGISTER_ENDPOINT constant (docs/privacy.md must name it; tests/test_registration.py checks); urllib.request only
├── sast/
│   ├── __init__.py    # Package marker
│   ├── runner.py      # SastResult; find_semgrep(); find_rules_dir(); run_semgrep(); parse_semgrep_output(); severity mapping
│   └── bundler.py     # get_bundled_rules_path() — resolves semgrep-rules/ in PyInstaller builds
├── fleet/
│   ├── __init__.py    # Package marker
│   └── merger.py      # FleetMerger, MachineReport, DeduplicatedFinding, FleetStats, FleetReport; fleet HTML generation
└── data/
    ├── known_npm_packages.yaml  # Legacy npm package list (retained for reference; superseded by registry)
    └── d3.v7.min.js             # Bundled D3 v7 (embedded inline in dashboard HTML)