solidity-sentinel 🛡️

Static security audit for Solidity smart contracts — for AI agents and developers.

solidity-sentinel is an MCP server and a pay-per-call x402 HTTP API. Paste a contract's source (or the raw deployed bytecode of an unverified contract) and get a CRITICAL / HIGH-RISK / REVIEW / LOW-RISK / CLEAN verdict with a 0–100 risk score and, in the deep tier, a full finding list — each with its exact line, the source→sink dataflow, a code-evidence snippet, the SWC + CWE id, a confidence score, an exploit explanation, and a concrete fix.

⚠️ Heuristic static screen, not a formal audit. It pattern-matches source structure and dataflow; it cannot prove a contract safe and can miss novel bugs. Absence of a finding is not a guarantee. Always pair with tests, fuzzing and a manual review before risking funds.

Why it exists (the moat)

An AI agent asked to "check this contract for bugs" makes one pass and produces a few regex-grade observations. A real review is the accumulated depth of an auditor working through the whole surface. solidity-sentinel encodes that depth:

• A flow-sensitive taint/dataflow engine (CFG-based). It tracks attacker-controlled values (function params, msg.sender, external-call returns) into dangerous sinks (delegatecall/call targets, selfdestruct, transfer amounts, array indices, sstore slots). It does not walk statements linearly — it builds a control-flow graph and runs a forward dataflow with a JOIN at branch confluences (a value tainted on any path is tainted after the merge), loop fixpoints (taint a loop body creates reaches code after the loop), and revert/early-return guards (if (msg.sender != owner) revert(); makes the fall-through path trusted). A guard on one branch does not sanitise the merge. This catches if (g) { t = userInput; } else { t = safe; } … t.delegatecall(d) and stays silent on owner-guarded / immutable-target code — killing both false negatives and false positives.

• Multi-level interprocedural + cross-contract. Taint follows internal call chains several hops deep (entry → mid → inner → sink) and across contracts in the same project (router.run(tainted) into another contract's delegatecall), recording the full call/contract chain in the evidence.

• High-value DeFi families where the money is: flash-loan-manipulable accounting, ERC-4626 first-depositor / share inflation, read-only reentrancy (stale view price during a transfer), callback-based reentrancy (ERC-777/1363 + flash-loan callbacks), MEV / sandwich exposure (no slippage bound), TWAP-window manipulation, unsafe liquidation, governance/timelock bypass, EIP-2612 permit replay, spot-price oracles.

• Deployed-bytecode screening for unverified contracts (no source): it disassembles runtime bytecode and flags DELEGATECALL/SELFDESTRUCT capabilities and calldata-controlled delegatecall takeover at the EVM level — ground truth a misleading source comment can't hide.

• The classics, done right: a tokenizer that isn't fooled by strings/comments, a parser that knows each function's visibility/mutability/modifiers, CEI ordering dataflow, interprocedural reentrancy, and version-aware arithmetic.

The engine ships with 227 automated tests, including a 153-case calibration corpus modelled on real incidents (TheDAO, Parity, bZx, Cream, Euler, Beanstalk, Nomad, Lendf.me, Wormhole, Ronin, Multichain, Mango, Rari, Visor, Qubit, BadgerDAO, KyberSwap, Sentiment, Penpie, Sushi RouteProcessor…) and audited-clean contracts. Measured on that corpus: 100% recall, 0 false positives — every must-flag fires, and safe CEI code, guarded reentrancy, immutable-target / beacon-proxy delegatecall, revert-guarded sinks, bounded indices, complete EIP-712 permits, slippage-bounded swaps, windowed TWAPs and .call text inside comments/strings are not flagged. A coverage drift-guard test asserts every detector id the engine fires is documented in the SWC/severity/confidence map — the docs can't silently fall out of sync with the code.

Related MCP server: Smart Contract Security Analyzer

What it analyses (taint engine + 12 detector families)

Each finding is mapped to its SWC and CWE id. SWC coverage (documented in detectors/coverage.ts and asserted in sync by coverage.test.ts): SWC-100, 101, 102, 103, 104, 105, 106, 107, 112, 114, 115, 116, 117, 118, 120, 121, 128, 132, 133 — plus the DeFi/dataflow families that have no SWC number (oracle manipulation, flash-loan accounting, ERC-4626 inflation, read-only reentrancy, MEV/sandwich, TWAP-window, governance timelock). Severity and confidence are calibrated per detector and further adjusted at runtime by path guards, interprocedural depth and cross-contract distance.

Tiers

The deep engine never runs in the locally-installed package — deep=true is forwarded to the hosted /pro/run endpoint, gated by x402 or a prepaid key. The premium engine (the taint/dataflow CFG, the DeFi families, the full detector suite, the calibration corpus) is not shipped in the npm package at all: the files allowlist publishes only the free client, and the deep path is a lazy import() of modules that exist solely on the server. npm pack contains zero premium source — the moat cannot be extracted from the installed package.

Use as an MCP server

{
  "mcpServers": {
    "solidity-sentinel": {
      "command": "npx",
      "args": ["-y", "solidity-sentinel-mcp"],
      // optional — unlocks the deep audit with a prepaid key:
      "env": { "SENTINEL_KEY": "<your-key>" }
    }
  }
}

Tool: audit_contract — { source: string, deep?: boolean }.

• deep omitted/false → free verdict (runs locally).

• deep: true with a SENTINEL_KEY → full deep audit (server-side).

• deep: true without a key → you still get the free verdict plus how to unlock the deep tier.

Use as an HTTP API

# Free verdict
curl -s -X POST https://solidity-sentinel.vercel.app/run \
  -H 'content-type: application/json' \
  -d '{"source":"pragma solidity ^0.8.0; contract C { ... }"}'

# Deep audit — pay per call with x402 (USDC on Base), or a prepaid key:
curl -s -X POST https://solidity-sentinel.vercel.app/pro/run \
  -H 'authorization: Bearer <your-key>' \
  -H 'content-type: application/json' \
  -d '{"source":"..."}'

A request to /pro/run without payment returns 402 with both payment lanes (x402 challenge + a Stripe checkout link). Buy a prepaid card key at /pro/checkout.

Develop

npm install
npm run build        # tsc + sync landing
npm test             # 227 tests: engine + 153-case CVE/hack calibration corpus + taint/CFG/bytecode units + coverage drift-guard
npm run dev:http     # local server (FORCE_LISTEN); /run, /pro/run, /mcp

License

MIT — see LICENSE.