Scan skills & MCP configs
Run offline heuristic checks on instruction files or MCP JSON, and save reports only when you choose.
On this page
beam scan checks a local text file for risky patterns without executing it. The default kind is a skill or instruction file. Add --mcp for an MCP configuration so the scanner also validates JSON and examines version pinning.
Scan a file
beam scan SKILL.md
beam scan .mcp.json --mcp
The scanner runs offline and loads custom rules from the Beam configuration directory. No collector or account is needed. It does not recursively audit every referenced file or contact servers named in the input.
Interpret the report
The JSON report contains findings with severity, a title, explanation, and matched evidence. Review the exact text and context. A destructive command in a warning example can match the same pattern as an instruction to run it; the scanner does not establish intent.
A successful process exit means the command completed. It is not a “zero findings” exit status. In automation, parse the report and apply your own reviewed severity/confidence policy instead of treating exit code zero as a safety gate.
MCP-specific checks
Use valid JSON for --mcp. Review unpinned dependency references alongside server identity, transport, tool permissions, and environment variables. A pinned version improves reproducibility but does not prove that package safe. The scan does not launch the MCP server or inspect its live tool behavior.
Save a report
beam scan SKILL.md --save
beam scan .mcp.json --mcp --save
Saving contacts the running local collector and persists its normalized report. An enrolled collector may forward saved scans to the workspace. Use the plain offline command when you only want a local one-time inspection.
Input limits
CLI file reads are capped at 2 MB. Scanned content must be nonempty and is further bounded to 500,000 text characters. The collector's /scan request has its own 500 KB bound. A file accepted by the file reader can therefore still exceed the scan or request limit. Split large inputs into meaningful reviewed sections and note the resulting coverage gap.
Follow up on a finding
Read the source, inspect referenced scripts without executing them, establish artifact identity, and evaluate the requested capabilities. Security skills provide structured review workflows. Scanning gives evidence for a human decision; it is not semantic malware analysis or a guarantee against prompt injection.