Saferico Cli

CI npm node dependencies

Solidity security scanning with 201 detectors that run on your machine. Your source code is never uploaded.

npx saferico scan ./contracts

That is the whole quick start. No account, no API key, no signup — the detector engine is downloaded from saferico.com, verified against a published SHA-256, and executed locally in a sandboxed VM context.

---

Why local

The audit needs far more CPU than an edge request may use, and — more importantly — sending a client's unreleased contracts to a third party to find out whether they are safe is a strange thing to ask. So the heavy engine runs where the code already is: your laptop, your CI runner, your agent's process.

What leaves your machine: one HTTPS request for the engine files. What does not: your source, your findings, your file names.

Commands

saferico scan [path]     # audit every .sol under path (default: .)
saferico skill [path]    # review agent skills and MCP configs under path
saferico mcp             # local MCP server on stdio, for AI agents
saferico engines         # list published engine versions
saferico version

Scan options

Flag	Meaning
--fail-on <sev>	critical | high | medium | low | none (default high)
--json	print the full result as JSON instead of a table
--output <file>	write the JSON result to a file
--sarif <file>	write SARIF 2.1.0 for GitHub code scanning
--engine-version <v>	pin the engine for a reproducible scan
--exclude <a,b>	extra globs (lib/**, **/mocks/**) or plain path fragments (test/) to skip
--max-files <n>	stop after n files (default 400)
--config <file>	read options from JSON (CLI flags win)
--quiet / --verbose	less / more progress on stderr

Skill options

saferico skill reads the .md, .json, .yaml and .toml files an agent treats as instructions or configuration — skill files, MCP server configs, tool permissions — and reports what an attacker could do with them. It makes no network request at all: the rules are compiled into this package, so nothing is uploaded and no key is needed.

Flag	Meaning
--fail-on <sev>	critical | high | medium | low | none (default critical)
--json	print the full result as JSON instead of a report
--max-files <n>	stop after n files (default 200)

The default gate is critical, not high as in scan. The two commands measure different things: a high-severity Solidity finding is a bug in code that is supposed to be correct, while a high here is very often a decision somebody made on purpose — a wildcard permission in their own private tooling, a documented "without asking". Failing every build on those gets the check switched off within a week, and a check that is switched off protects nothing.

Exit codes

Code	Meaning
0	clean, or findings below the gate
1	the gate was crossed — the build should fail
2	the tool could not run (bad path, unreachable engine, bad arguments)

Reproducible scans

A security gate that cannot tell "the code changed" from "the detectors changed" is not much of a gate. Every engine release is archived and hashed:

saferico engines                                  # what exists
saferico scan ./contracts --engine-version 2026.09.01

Pinned or not, every downloaded file is checked against the SHA-256 published in https://saferico.com/engine/manifest.json. A mismatch is a hard refusal, not a warning: this tool downloads code and runs it, so "we could not verify it" must never be the same outcome as "it verified".

An unknown version is an error — a pin that silently stops pinning is worse than no pin.

In CI

- name: SaferICO security scan
  run: npx saferico scan ./contracts --sarif saferico.sarif --fail-on high

- name: Upload to code scanning
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: saferico.sarif

Pin --engine-version on a release branch when you need byte-identical results.

MCP server (local)

Gives an AI agent the full audit, locally:

{
  "mcpServers": {
    "saferico": { "command": "npx", "args": ["-y", "saferico", "mcp"] }
  }
}

Tools: scan_path, scan_source, engine_info. No API key, nothing uploaded.

There is also a hosted MCP server at https://saferico.com/mcp for the lightweight on-chain reads (token facts, honeypot simulation, explorer verification status, deployed-bytecode analysis, balances, gas). That one needs an API key; this one does not, and this one is the only one that can run the 201 detectors.

Programmatic use

import { scanPath, scanSource } from "saferico";

const result = await scanPath("./contracts", { failOn: "high" });
console.log(result.counts, result.gate.verdict);

Configuration file

saferico.json in the working directory:

{
  "path": "./contracts",
  "failOn": "high",
  "engineVersion": "2026.09.01",
  "exclude": ["test/", "script/"],
  "maxFiles": 400
}

Dependencies

None. A security tool that pulls a dependency tree onto the machine it is auditing is arguing against itself.

Licence

MIT — see LICENSE.

The MIT grant covers this package: the command line, the local MCP server and the scanning harness. It does not cover the detector engine (sfi-engine.js, scan-safedb.js), which is not distributed here — it is downloaded from saferico.com at run time, verified against a published SHA-256, and remains the property of SaferICO under the terms at https://saferico.com/terms. See NOTICE.

How this is tested

CI runs on Node 18, 20 and 22, and once a day on a schedule — because the detector engine is not in this repository. It is downloaded at run time, so this package can break without a commit here; the daily run is the canary on that.

Each run installs from a packed tarball (what a user actually receives, which catches a missing entry in files), then audits a deliberately broken contract in test/contracts/ and asserts the findings, the exit code, the SARIF output, the local MCP tool list, and that the dependency count is still zero.

Security

Found a vulnerability? See SECURITY.md. Short version: email [email protected] with SECURITY in the subject, and please do not open a public issue.

Limits

• Solidity only.
• Static analysis: it reads code, it does not execute contracts or simulate transactions. It will not find every bug, and a clean result is not a certificate.
• It describes risk and shows evidence. It never says a contract is "safe".

Docs: https://saferico.com/docs · Engine manifest: https://saferico.com/engine/manifest.json