Skip to main content

Static pre-install scanner (scan)

belay scan is a static, pre-install analyzer. Point it at code before you run or install it — a directory, a single file, a git URL, or a zip — and it reports what the code can do, scores the risk, and gives an install/run recommendation. It is deterministic by default and emits SARIF 2.1.0 for CI code-scanning.

When to use​

  • Before installing a package, plugin, MCP server, or agent extension from an untrusted source.
  • In CI, as a gate on pull requests or third-party dependencies (via SARIF output).
  • Any time you want a fast, offline, second opinion on "is this safe to run?"

Analyzers​

scan runs several complementary analyzers and combines them with a provenance-weighted score:

AnalyzerLooks for
PatternsKnown dangerous constructs and secret-shaped strings.
ASTStructural code analysis beyond flat text matching.
TaintData flowing from untrusted sources to dangerous sinks.
YARASignature matches against malware/behavior rules.
OSVKnown-vulnerable dependencies (open-source vulnerability data).

The result carries a severity, a numeric score, and an explicit install/run recommendation.

Steps​

1. Scan a target​

belay scan ./suspicious-package        # a directory
belay scan ./file.js                    # a single file
belay scan https://github.com/org/repo  # a git URL
belay scan ./archive.zip                # a zip

2. Choose an output format​

The default output is JSON. Use --format sarif for CI code-scanning ingestion:

belay scan ./pkg --format json    # default
belay scan ./pkg --format sarif   # SARIF 2.1.0 for CI

3. (Optional) Enable the LLM cascade​

Add --llm to route findings through an LLM-judge pass that filters false positives:

belay scan ./pkg --llm

The --llm cascade​

When --llm is set, providers are selected from the environment and tried in order, falling back to a deterministic heuristic when none are configured:

ProviderEnabled byModel
AnthropicANTHROPIC_API_KEYclaude-sonnet-4-5
OpenAIOPENAI_API_KEYgpt-4o
OllamaOLLAMA_BASE_URL (+ optional OLLAMA_MODEL)llama3 (default)
Heuristicalways availabledeterministic fallback
No keys required

With no API keys configured, the cascade runs the heuristic provider only, and its output is identical to the deterministic path. The LLM pass is an optional false-positive filter, not a requirement — scan is fully functional offline.

CI integration

Emit SARIF and upload it to your platform's code-scanning view to see scanner findings inline on pull requests:

belay scan . --format sarif > belay.sarif

Standards alignment​

Findings are tagged against the OWASP Agentic Security Initiative (ASI) Top 10, the OWASP LLM Top 10, and MITRE ATLAS, and the SARIF output conforms to SARIF 2.1.0.

Host malware scan

belay scan analyzes untrusted code before you install it. To sweep files already on the host, use belay host-scan (home / downloads / full scope) and manage findings with belay quarantine.