Precedents: Dataset and MCP Server for AI Auditors

The hacks library as data: one record per exploit or audit finding, with its root cause, the vulnerable code and the fix. An agent reviewing a contract can ask whether a pattern has failed before, read how, and cite the case. It is all static files; nothing runs on a server.

Connect it to your agent

The lookup is an MCP server that runs on your machine and reads the files below. It needs Node 18 or later. The package is itself a static file on this site, so npx installs it from here:

npx -y https://crypto.training/precedents/crypto-training-precedents-mcp.tgz

In Claude Code:

claude mcp add crypto-training-precedents -- npx -y https://crypto.training/precedents/crypto-training-precedents-mcp.tgz

In any client that takes a JSON server entry:

{
  "mcpServers": {
    "crypto-training-precedents": {
      "command": "npx",
      "args": ["-y", "https://crypto.training/precedents/crypto-training-precedents-mcp.tgz"]
    }
  }
}

It downloads the search index once, caches it on disk, and answers from memory. Search keeps working offline; opening a record you have not opened before needs the network.

The four tools

Tool	Use it to
`search_precedents`	Find cases whose root cause matches a bug you describe, or code you paste. Filter by kind, vulnerability class, chain and year.
`get_precedent`	Read one case: the full root cause, every vulnerable-code block, the fix and references. The attack walkthrough comes back when you ask for it.
`similar_precedents`	List other cases with the same root cause as one you already have.
`list_vulnerability_classes`	See the vulnerability taxonomy with record counts, to pick a class filter.

The same code answers from a shell, printing exactly what the tools return:

npx -y https://crypto.training/precedents/crypto-training-precedents-mcp.tgz search "no nonce in the signed digest, so the signature can be replayed"
npx -y https://crypto.training/precedents/crypto-training-precedents-mcp.tgz get 2023-07-AzukiDAO
npx -y https://crypto.training/precedents/crypto-training-precedents-mcp.tgz similar 2023-07-AzukiDAO --kind audit-finding

What a search returns

Each hit is meant to be judged without a second call. It shows which distinctive words of the query appear in the record’s root cause (and which only in its code), gives the root cause in whole sentences, what the attack needs, and a few lines of the vulnerable code.

2. Common Pool — signature omits nonce/expiry and can be reused
   slug: 52006-signature-does-not-take-all-parameters-into-account-and-can
   audit finding · 2024-07 · Common Pool / RFX · severity high
   classes: signature/incomplete-scope, auth/replay
   bug class: Incomplete signature domain / replay
   overlap with your query: root cause — nonce, replayed, signed, signature
   root cause: Anti-replay fields exist in the struct and are validated against live state, but because they are outside the signed message an attacker can freely rewrite them to match the current epoch.
   needs: An approved signer has produced at least one valid `allocateFunds` signature (visible on-chain). Pool still holds inventory for another deposit of the same payload size.
   vulnerable code:
      bytes32 input = keccak256(abi.encode(keccak256(bytes(DEPOSIT_STRUCT)), amount)); // @> VULN
      // FIX: also encode sig.nonce and sig.expiry into input before signing/verifying
      checkReport(sig, input, orderNonce);
   page (write-up + in-browser replay of the exploit): https://crypto.training/hacks/52006-signature-does-not-take-all-parameters-into-account-and-can/

Write the query as the mechanism, in one sentence (“share price read from pool balances that a flash loan can move”). Pasting the code under review also works, but it finds contracts that use the same calls, which is not the same as sharing the bug. Matching is by vocabulary, not by meaning, so name the behaviour precisely. The tool cannot see your code: a precedent about a missing check does not apply to code that has the check, and when no root cause fits, the right answer is that no precedent applies.

Use the files directly

If you would rather not run the server, the same data is plain JSON:

File	Contents
all.jsonl	Every record, one JSON object per line.
`<slug>.json`	One record. The slug is the last part of the page URL, for example 2023-03-euler.json.
index.json	The prebuilt search index (3.6 MB before compression).
manifest.json	Schema version, counts, how many records have each field, and which records lack one.

Record fields

Field	Meaning
`slug, url, title`	Identity. The URL is the write-up page, which hosts the in-browser replay.
`kind, source`	“incident” (exploited on-chain) or “audit-finding”, and where it comes from.
`date, chain, protocol, loss`	Context. Audit findings usually have no chain and no loss.
`vulnTags, categories, bugClass`	Classification, most specific first.
`rootCause`	Why the bug exists. Taken only from the write-up’s own root-cause section.
`vulnerableCode[]`	The code the write-up quotes as vulnerable. Blocks rebuilt from a trace are flagged “reconstructed”.
`preconditions, attack, impact`	What the attack needs, how it ran, and what it cost.
`remediation`	The fix, with code where the write-up gives it.
`references`	Attack transaction, runnable Foundry PoC, upstream PoC or original audit finding.

How far to trust it

Each field comes from its own section of the write-up. A write-up with no root-cause section has an empty rootCause; nothing is borrowed from the summary or the attack story to fill it. 91% of records have one, 90% quote vulnerable code, and 74% have a fix.
Audit findings are thinner than incidents. They are shorter, and about a fifth carry no vulnerability class yet, so a class filter skips them.
Search is lexical. A query that shares no vocabulary with a write-up will not find it. Describing the mechanism in other words usually does.
A write-up can cover more than one flaw. Rely on the part that matches the mechanism you searched for.

Sources and credit

Incidents derive from DeFiHackLabs by SunWeb3Sec and from original research published here. Audit findings derive from AuditVault. Every record links to its upstream source. When you cite a precedent, link its page under /hacks/.

Precedents for AI auditors