Security Scan
scanRun a full AI supply chain security scan and return an AI-BOM.
Instructions
Run a full AI supply chain security scan and return an AI-BOM.
Point it at a target with one of:
• project_path — a local project / repo directory ("scan this repo";
must be inside home or AGENT_BOM_MCP_WORKSPACE_ROOTS)
• repo_url — a public git repo URL (cloned + scanned, no checkout)
• config_path — a local MCP-config directory
• image — a Docker image
• sbom_path — an existing CycloneDX/SPDX SBOM
• package — a single package or MCP launch command (pair it with
ecosystem when the spec names no launcher)
With none of these, it auto-discovers local MCP clients (Claude Desktop,
Cursor, Windsurf, VS Code Copilot, OpenClaw, etc.).
It extracts package dependencies, looks up CVEs (online via OSV.dev and advisory sources unless offline mode is requested or configured), assesses config security (credential exposure, tool access), computes blast radius, and returns structured results. Scanning is fully static and read-only — repository and image contents are parsed, never executed.
Returns: JSON. By default a bounded summary: counts (packages, agents, findings by severity/category), top findings, affected paths, and a result_id. Page any full-fidelity section with scan(result_id=..., section='findings', offset=0, limit=25). An incomplete scan (e.g. vulnerability source unavailable) is returned as an error result whose body is still JSON.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image | No | Docker image to scan (e.g. 'nginx:1.25', 'ghcr.io/org/app:v1'). | |
| limit | No | Maximum items per page of `section` (1-200). | |
| detail | No | JSON output only. 'summary' (default): counts, top findings, affected paths, and a result_id for paged follow-ups. 'full': the whole AI-BOM document, shortened structurally (still valid JSON, with _truncation metadata) if it exceeds the response budget. | summary |
| enrich | No | Enable NVD CVSS, EPSS probability, and CISA KEV enrichment. | |
| offset | No | Zero-based item offset into `section`. | |
| policy | No | Policy object to evaluate alongside scan results, e.g. {"rules": [{"id": "no-critical", "severity_gte": "critical", "action": "fail"}]}. | |
| offline | No | true: use the local vulnerability DB only and skip registry, OSV, GHSA, and NVIDIA network lookups (requires a populated DB from `agent-bom db update`). false: query those sources online. Omitted: online unless the server operator set AGENT_BOM_OFFLINE or AGENT_BOM_VULN_DB_OFFLINE. | |
| package | No | Direct package or MCP launch command to scan, e.g. 'npx @modelcontextprotocol/server-filesystem@2025.1.14' or '@modelcontextprotocol/server-filesystem'. A bare 'name@version' spec is assumed to be npm — pass ``ecosystem`` for anything else. | |
| section | No | Section of a stored result to page, e.g. 'findings', 'blast_radius', 'packages', 'exposure_paths'. | |
| repo_url | No | Public git repository URL to clone and scan, e.g. 'https://github.com/org/repo'. Maps the repo's dependencies, project structure, secrets, IaC, and AI/MCP usage into an AI-BOM. Static and read-only: the repository is shallow-cloned into a temporary directory, scanned without ever executing its code, then deleted. The fastest way to point this tool at a target — no local checkout required. | |
| ecosystem | No | Ecosystem of ``package`` when the spec does not name a launcher: 'npm', 'pypi', 'go', 'cargo', 'maven', 'nuget', 'rubygems', 'composer', 'swift', 'pub', 'hex', 'conda', 'deb', 'apk', or 'rpm'. Omitted, the ecosystem is inferred from the spec (PEP 440 specifiers such as 'flask==0.12.2' are PyPI) and any assumption is reported in the result warnings. | |
| result_id | No | result_id from a previous scan response. With it, no new scan runs: returns that result's summary, or one page of `section`. | |
| sbom_path | No | Path to existing CycloneDX or SPDX JSON SBOM file to ingest. | |
| scorecard | No | Enrich packages with OpenSSF Scorecard scores (requires resolvable GitHub repos). | |
| db_sources | No | Comma-separated DB sources to sync before scanning (e.g. 'nvd,ghsa,osv,epss,kev'). | |
| transitive | No | Resolve transitive dependencies for npx/uvx packages. | |
| config_path | No | Local directory to scan — a project root or an MCP client config directory. Auto-discovers installed MCP clients if omitted unless no_discover=true. Same sandbox as project_path. Mutually exclusive with project_path and repo_url. | |
| no_discover | No | Disable ambient host MCP-client discovery. Explicit repo/config, image, SBOM, and package targets are still scanned; use this for deterministic CI. | |
| project_path | No | Local project / repository directory to scan, e.g. the agent's current workspace checkout. Scans dependency manifests and lockfiles, project MCP configs, source AI usage, secrets (values redacted), IaC, and GitHub Actions, statically and read-only. Must resolve (symlinks followed) to an existing directory inside the user's home or a root listed in AGENT_BOM_MCP_WORKSPACE_ROOTS; traversal, symlink escapes, files, and missing paths are refused with AGENTBOM_MCP_VALIDATION_INVALID_PATH. Mutually exclusive with config_path and repo_url. | |
| fail_severity | No | Return failure status if vulns at this severity or higher: critical, high, medium, low. | |
| output_format | No | Output format: 'json' (default), 'sarif', 'cyclonedx', 'spdx', 'junit', 'csv', or 'markdown'. | json |
| warn_severity | No | Return warning status (gate_status=warn, exit 0) when vulns at this severity or higher exist. Use with fail_severity for two-tier CI gates, e.g. warn_severity='medium', fail_severity='critical'. | |
| auto_update_db | No | Explicitly refresh the local vuln DB when older than the daily freshness target before scanning. | |
| verify_integrity | No | Verify package SHA-256/SRI hashes and SLSA provenance against registries. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |