firmis scan — Scan AI Agent Components

Your agent stack has access to your AWS keys, SSH keys, API tokens, and local files. Most people never check what their tools actually do. firmis scan checks for you.

The core command. Point it at any directory and it tells you what’s dangerous.

When to use this

Reach for scan whenever you want answers fast:

• You just installed a new MCP server or Claude skill and want to know if it’s clean
• You’re about to commit agent configuration changes and want a quick security check
• You need to audit an existing project before handing it off or open-sourcing it
• You want to add a security gate to your PR workflow

For a full CI pipeline (discover + BOM + scan + report in one shot), see firmis ci.

Usage

Terminal

firmis scan [path] [options]

If [path] is omitted, Firmis scans the current directory.

What you get

Running npx firmis scan on a project produces output like this:

Firmis Security Scan
Detected platforms: claude, mcp (2 platforms, 14 components)

CRITICAL  [tool-poisoning]   .claude/tools/fetch.ts:12
          Hidden instruction in tool description: "ignore previous instructions and..."

CRITICAL  [credential-harvesting]  mcp-server/src/index.ts:89
          Reading AWS credentials from ~/.aws/credentials

HIGH      [secret-detection]  .env:3
          Hardcoded OpenAI API key: sk-proj-...

HIGH      [permission-overgrant]  claude_desktop_config.json:22
          Tool requests filesystem access with no path restriction

MEDIUM    [insecure-config]   mcp.config.json:8
          Server runs without authentication

────────────────────────────────────────────────
Grade: D   5 findings   2 critical · 2 high · 1 medium
────────────────────────────────────────────────

Every finding includes the exact file and line number, a plain English explanation of what it means, and the rule ID so you can look up remediation steps.

Options

Flag	Type	Default	Description
--platform <name>	string	auto-detect	Scan a specific platform: claude, mcp, codex, cursor, crewai, autogpt, openclaw, nanobot
--all	boolean	true	Scan all detected platforms
--severity <level>	enum	low	Minimum severity to report: low, medium, high, critical
--fail-on <level>	enum	—	Exit non-zero if findings at this severity or above exist. Essential for CI gates.
--json	boolean	false	Machine-readable JSON output for scripting or custom tooling
--sarif	boolean	false	SARIF 2.1.0 output — uploads directly to GitHub Security tab
--html	boolean	false	Self-contained HTML report — shareable with your team
--output <file>	string	stdout	Write output to a file instead of printing to terminal
--config <file>	string	—	Path to a custom .firmisrc config file
--ignore <rules>	string	—	Skip specific rule IDs (comma-separated). Use sparingly — see Ignoring Findings.
--concurrency <n>	number	4	Number of parallel workers. Increase for large monorepos.
--verbose	boolean	false	Show per-file scan progress and rule match details
--quiet	boolean	false	Suppress all terminal output. Only the exit code tells you the result. Good for CI scripts.

Examples

Scan current directory (auto-detect all platforms)

Terminal

npx firmis scan

Scan only MCP servers, get JSON output

Terminal

npx firmis scan --platform mcp --json

Fail CI if any high or critical findings exist

Terminal

npx firmis scan --fail-on high --sarif --output results.sarif

Scan a specific path, suppress known false positives

Terminal

npx firmis scan ./packages/agent --ignore sd-045,sd-046

Generate a shareable HTML report

Terminal

npx firmis scan --html --output report.html

High-signal only — skip noise, focus on what matters

Terminal

npx firmis scan --severity high

Exit codes

Code	Meaning
0	Scan completed. No findings above your --fail-on threshold.
1	Findings found at or above your --fail-on threshold. Fix them.
2	Scan error — invalid path, bad config, or unreadable files.

Related

• Threat Categories — all 16 categories Firmis detects across 209 rules
• Ignoring Findings — suppress specific rules or files without deleting them
• CI Pipeline — full discover → BOM → scan → report in one command