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.

What it analyses (taint engine + 12 detector families)

Family	Examples it catches
🌊 Dataflow / taint (flow-sensitive)	attacker-controlled value → delegatecall/call target, selfdestruct beneficiary, transfer amount, array index, sstore slot — CFG-based with branch JOINs, loop fixpoints, revert-guards, multi-level interprocedural and cross-contract propagation, with guard/sanitiser suppression
🔁 Reentrancy	classic ETH reentrancy (CEI violated), cross-function reentrancy on shared state, read-only reentrancy (stale view price), callback-based (ERC-777/1363 + flash-loan callbacks), ERC-777/721/1155 receiver-hook reentrancy (no raw .call needed), guard-aware suppression
🔐 Access control	unprotected selfdestruct, unprotected/attacker-targeted delegatecall (immutable/beacon-target aware), privileged mutators (mint/withdraw/upgrade/setFee…) and infinite-mint / arbitrary-credit shapes with no onlyOwner/role check, unprotected initializer (proxy takeover)
🏦 DeFi families	flash-loan-manipulable accounting, ERC-4626 first-depositor inflation, MEV / sandwich (no slippage bound), TWAP-window manipulation, unsafe liquidation (no health check), governance without timelock, EIP-2612 permit missing deadline/nonce
➕ Arithmetic	pre-0.8 overflow/underflow without SafeMath, unchecked{} blocks, division-before-multiply precision loss, unsafe downcasts, strict balance equality
☎️ Low-level calls	tx.origin auth (phishable), unchecked call/send return, .send() 2300-gas trap, arbitrary external call with caller-controlled target
🎲 Randomness	weak randomness from block.timestamp/prevrandao/blockhash, timestamp-dependent logic
📉 Oracle	spot-price (getReserves/balanceOf) used as a price feed (flash-loan manipulable), Chainlink usage without staleness checks, deprecated latestAnswer()
✍️ Signatures	ecrecover without address(0) check, signature replay (no nonce / no chainId), malleability, abi.encodePacked hash collision
⬆️ Proxy / upgradeability	constructor-init in upgradeable contracts, UUPS without _authorizeUpgrade, risky inline assembly
🧱 DoS	unbounded loops, push-payment loops a single revert can brick, O(n) array shifting
✅ ERC-compliance & gas	approve race, raw ERC-20 transfer (no SafeERC20), missing zero-address checks, floating/outdated pragma, public→external gas, deprecated constructs
🧬 Deployed bytecode	disassembles runtime bytecode of unverified contracts; flags DELEGATECALL/SELFDESTRUCT and calldata-controlled delegatecall takeover

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

	Free	Deep (paid)
Detectors	4 high-signal	flow-sensitive taint engine + all 16 families + bytecode mode
Output	verdict + risk score + finding counts + top issue titles	every finding: line, the source→sink flow, evidence, SWC/CWE, confidence, exploit reasoning, fix, + per-contract surface inventory
Runs	locally in the installed package	server-side, behind payment
Cost	free (rate-limited)	$0.05 USDC per call via x402, or a prepaid API key (card)

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.