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.

Synopsis

firmis scan [path] [options]

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

Description

firmis scan maps the attack surface of your AI agent components using 324 detection rules across 21 threat categories. It reads your Claude Skills, MCP server configs, Cursor rules, CrewAI agents, and 5 more platforms without modifying any files. Static scanning is always free and unlimited.

When you want AI-powered confirmation of whether a finding is a real exploitable risk, add --deep. Deep scan runs server-side semantic analysis on each finding and verifies true positives. It requires a Firmis account (free: 1 deep scan per month, Pro and Business: unlimited, uses AI credits).

Scan fits at every point in your workflow: local spot-checks, pre-commit hooks, and full CI gates. For a single command that runs the complete pipeline (discover + BOM + scan + report), see firmis ci.

Examples

Scan current directory (auto-detect all platforms)

Terminal

npx firmis-cli scan

Scan only MCP servers, get JSON output

Terminal

npx firmis-cli scan --platform mcp --json

Fail CI if any high or critical findings exist

Terminal

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

Scan a specific path, suppress known false positives

Terminal

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

Generate a shareable HTML report

Terminal

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

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

Terminal

npx firmis-cli scan --severity high

Run AI-powered deep analysis

Terminal

# Log in first (one-time)
npx firmis-cli login

# Run deep scan
npx firmis-cli scan --deep

Deep scan runs AI-powered semantic security analysis server-side. No API keys needed on your machine. It catches threats that static rules miss — third-party content ingestion, credential extraction patterns, permission bypass semantics — and verifies whether static findings are true positives.

Deep scan uses 5 AI credits per component analyzed. One free deep scan per month on Free tier. Unlimited on Pro and Business (uses AI credits). Learn more.

Disable cloud sync for a one-off scan

Terminal

npx firmis-cli scan --no-sync

What you get

Running npx firmis-cli 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 known vulnerabilities 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.
--deep	boolean	false	Enable AI-powered deep analysis. Requires firmis login. See Deep Scan.
--no-sync	boolean	false	Disable auto-sync of scan results to your cloud workspace
--global	boolean	false	Scan project directory and home directory for agent configurations
--contribute	boolean	false	Opt in to anonymous telemetry and persist the preference for future runs

Exit codes

Code	Meaning
0	Scan completed. No findings above your --fail-on threshold, or --fail-on not set.
1	Known vulnerabilities found at or above your --fail-on threshold. Fix them.

HTML report

By default, every scan auto-generates firmis-report.html and opens it in your browser. This is a self-contained HTML report you can share with your team. Use --json or --sarif to switch to machine-readable formats instead.

Output formats

Format	Flag	Use case
Terminal	(default)	Interactive review with color and grade
JSON	--json	Scripting, custom dashboards, piping to other tools
SARIF	--sarif	GitHub Security tab, GitLab SAST, any SARIF-compatible system
HTML	--html	Shareable report for your team or stakeholders

See also

• Threat Categories - all 21 categories Firmis detects across 324 detection rules
• Ignoring Findings - suppress specific rules or files without deleting them
• CI Pipeline - full discover + BOM + scan + report in one command
• Deep Scan - AI-powered verification of findings