Scanner CLI Reference - Oxvault Docs

The scanner binary is oxvault. Every command below is verified against the CLI source in scanner/cmd/.

oxvault [command] [flags]

Available commands:
  scan        Scan an MCP server or model artifact for vulnerabilities
  pin         Pin tool description hashes for rug-pull detection
  check       Check for rug pulls (tool description changes since last pin)
  push        Upload the most recent scan to the Oxvault platform
  init        Create ~/.oxvault/config.toml with sensible defaults
  agent       Long-poll the platform for queued scans and run them locally
  completion  Generate a shell autocompletion script
  help        Help about any command

Global flags:
  -h, --help      Help for a command
  -v, --version   Print the oxvault version

`scan`

oxvault scan [target] [flags]

Scans a single target, or — with --config — every MCP server declared in a client config file.

Targets

Target form	Resolved as
`./my-server`	Local project directory or single file
`@company/mcp-server`	npm package (installed into a temp dir, then scanned)
`github:user/repo`	GitHub repository (cloned, then scanned)
`hf:org/model`	Hugging Face model (downloaded, cached, then scanned)
`./model.pkl`	A single model artifact file (pickle/ONNX/safetensors)
`./model-dir/`	A directory of model artifacts (mixed formats)

The resolver classifies the target and dispatches to the MCP flow or the model-artifact (AIBOM) flow automatically.

Core flags

Flag	Default	Description
`-f, --format`	`terminal`	Output format: `terminal`, `sarif`, or `json`
`--fail-on`	`critical`	Exit non-zero at this severity or above: `critical`, `high`, `warning`, `info`
`--min-confidence`	`low`	Minimum confidence to report: `low`, `medium`, `high`
`-v, --verbose`	`false`	Verbose output
`--no-color`	`false`	Disable ANSI color (for CI or piping)
`--config`	—	Scan an MCP client config file (a path, or `auto` to auto-detect all known configs)
`--show-suppressed`	`false`	Print suppressed findings in a separate section

Analyzer toggles

Skip individual MCP analyzers to speed up a scan or narrow its focus:

Flag	Skips
`--skip-sast`	Source code analysis
`--skip-manifest`	Tool description analysis (the MCP connection)
`--skip-egress`	Network egress detection
`--probe-network`	Enables a runtime probe that spawns the server and watches outbound connections (requires `strace` on Linux)

Scanning Hugging Face models

hf:org/model targets download into a local cache before scanning. Tune with:

Flag	Default	Description
`--hf-token`	`$HF_TOKEN`	Hugging Face API token for gated/private repos
`--hf-revision`	`main`	Branch, tag, or commit SHA to fetch
`--hf-cache-dir`	`~/.cache/oxvault/hf`	Where downloaded files are cached
`--hf-max-file-bytes`	4 GiB	Max bytes per downloaded file
`--hf-max-cache-bytes`	16 GiB	Max total cache size

Model-artifact (AIBOM) flags

Each --skip-* flag drops findings from one model sub-analyzer:

Flag	Skips findings with prefix
`--skip-pickle`	`aibom-pickle-*`
`--skip-onnx`	`aibom-onnx-*`
`--skip-safetensors`	`aibom-safetensors-*`
`--skip-modelcard`	`aibom-modelcard-*`
`--skip-signature`	`aibom-signature-*`

Tuning:

Flag	Default	Description
`--max-pickle-size`	2 GiB	Max bytes disassembled per pickle (values above the default are clamped)
`--trusted-issuers`	—	Comma-separated OIDC issuer URLs that replace the default trusted-issuer list for signature verification
`--additional-trusted-issuers`	—	Comma-separated OIDC issuer URLs that merge into the default list

Uploading results (`--push`)

The scanner can upload a completed scan to the Oxvault platform. This is opt-in — the free tier stays entirely local.

Flag	Default	Description
`--push`	`false`	Upload the result after the scan (requires `OXVAULT_API_KEY`)
`--api-key`	`$OXVAULT_API_KEY`	Workspace API key (must start with `ox_`)
`--api-url`	`$OXVAULT_API_URL` or `https://platform.oxvault.dev`	Platform base URL
`--console-url`	derived from `--api-url`	Console URL used in the success link
`--push-quiet`	`false`	Suppress the success banner

Auto-push is gated to terminal output, so --format json/sarif runs never upload unexpectedly. See push for the standalone uploader.

Output formats

terminal (default) — findings grouped into sections (Source Code Analysis, Install Hook Analysis, Tool Description Analysis, Credential Analysis, Other Findings), sorted critical-first, followed by a summary and a verdict line. Progress and banners go to stderr; the report goes to stdout, so piping stays clean.

json — a JSON array of finding objects on stdout:

[
  {
    "rule": "aibom-pickle-os-system",
    "severity": 3,
    "confidence": 3,
    "confidenceLabel": "high",
    "message": "dangerous pickle GLOBAL \"os.system\" at offset 0x17 — spawns shell command (CWE-502)",
    "file": "/path/to/weights.pkl",
    "cwe": "CWE-502"
  }
]

severity and confidence are integers. Severity maps 0 = INFO, 1 = WARNING, 2 = HIGH, 3 = CRITICAL; confidence maps 1 = low, 2 = medium, 3 = high. Other optional fields include line, tool, fix, and references.

sarif — SARIF 2.1.0 for GitHub code scanning and other SARIF consumers. The tool driver is oxvault; each result carries a ruleId, a level (error for critical/high, warning, note for info), a message, and a location with a path relativized to the working directory.

Exit codes

Code	Meaning
`0`	Scan completed; no finding reached the `--fail-on` threshold
`1`	A finding at or above `--fail-on` was found, or the scan itself errored

Examples

# Local project, human-readable
oxvault scan ./my-server

# CI gate: fail the build on HIGH or worse, emit SARIF
oxvault scan ./my-server --format sarif --fail-on high > results.sarif

# Only high-confidence findings
oxvault scan ./my-server --min-confidence high

# Scan every server in your MCP client configs
oxvault scan --config auto

# Scan a specific client config
oxvault scan --config ~/.claude/claude_desktop_config.json

# Scan a model, pinning a revision
oxvault scan hf:org/model --hf-revision v1.0 --hf-token "$HF_TOKEN"

`pin` and `check`

Rug-pull detection: MCP servers can quietly change a tool’s description or schema after you have approved it. pin records a baseline; check compares against it later.

# Record SHA-256 hashes of each tool's name, description, and input schema
oxvault pin npx -y @company/server

# Later — detect any change since the pin
oxvault check npx -y @company/server

Hashes are stored in .oxvault/pins.json in the current directory. Both commands take the MCP server launch command and its arguments (everything after the subcommand is passed through to the server). check exits 1 when any tool description has changed since the last pin. Both accept -v, --verbose and --no-color.

`push`

Upload the most recent local scan to the platform. The scan is read from ~/.oxvault/last-scan.json, which oxvault scan writes after every successful run.

OXVAULT_API_KEY=ox_… oxvault push
oxvault push --api-key ox_… --api-url https://platform.oxvault.dev
oxvault push --scan-file ./scan.json

Flag	Default	Description
`--api-key`	`$OXVAULT_API_KEY`	Workspace API key (must start with `ox_`)
`--api-url`	`$OXVAULT_API_URL` or `https://platform.oxvault.dev`	Platform base URL
`--console-url`	derived	Console URL for the success link
`--scan-file`	`~/.oxvault/last-scan.json`	A specific saved scan to upload
`-q, --quiet`	`false`	Suppress the success banner

Mint an API key in the console at /settings/api-keys.

`init`

Write a starter ~/.oxvault/config.toml. The file is created commented-out (inert by default); it holds a [push] section where you can set auto (push on every scan), api_key, api_url, console_url, and quiet. The directory is created 0700 and the file 0600, since it may hold an API key.

oxvault init            # errors if the file already exists
oxvault init --force    # overwrite an existing file

`agent`

Run a long-poll loop against the platform. The agent picks up scan jobs queued from the console (for example, a “re-scan” button) and runs them against your local working directory — code never leaves your machine. It is the inverse of push: push uploads a scan already on disk, agent runs the scan the platform asked for.

oxvault agent \
  --target-map=asana-mcp=./node_modules/@asana/mcp-server \
  --target-map=cloudflare-mcp=./vendor/cloudflare-mcp

Flag	Default	Description
`--api-key`	`$OXVAULT_API_KEY`	Workspace API key
`--api-url`	`$OXVAULT_API_URL` or `https://platform.oxvault.dev`	Platform base URL
`--console-url`	derived	Console URL for log lines
`--agent-id`	hostname	Identifier surfaced in audit logs
`--target-map`	—	Map an artifact name to a local path (`name=path`); repeatable
`--one-shot`	`false`	Process at most one job, then exit (useful in CI)
`-v, --verbose`	`false`	Verbose log output

Without a --target-map entry, the agent probes a few conventional locations under the working directory (./<name>, ./examples/<name>, ./vendor/<name>, ./node_modules/<name>, and any npm scope). Artifact names are validated to prevent path traversal.

Suppressing findings

The scanner supports two suppression mechanisms, applied after analysis:

Inline comments — add an oxvault:ignore comment to the offending source line:

result = eval(expr)  # oxvault:ignore
result = eval(expr)  # oxvault:ignore mcp-code-eval   # suppress only this rule

Both # (Python) and // (JS/TS/Go) comment styles are recognized. With no rule name, every rule on that line is suppressed; with a rule name, only that rule.

.oxvaultignore file — drop a file in the scanned directory:

# Ignore a whole rule everywhere
!mcp-hardcoded-secret

# Ignore all findings in a file glob
tests/**
*_test.py

# Ignore one rule in one file
server.py:mcp-cmd-injection

Suppressed findings are hidden from the report and do not affect the exit code. Run with --show-suppressed to list them in a separate section.

See Detection rules for the full catalog of rule IDs.

scan