Use with AI agents

Clone 180,907 past findings from 13,040 audits as plain Markdown and let your coding agent search them while it reviews your code. Every finding links to its original report.

No API key. No sign-up. Two commands and your agent has the lot.

A longer version with more queries lives in the repository: AGENTS_GUIDE.md. Agents can also read llms.txt.

Quick start

Clone the findings
```
git clone --depth 1 https://github.com/DicksonWu654/web3-audit-findings
cd web3-audit-findings
```
One Markdown file per finding, the report extracts, linked hub pages by firm, class, language, chain and project, and a metadata graph. Only need one firm or class? A sparse clone works; the repository README has the commands.
Open it in your agent

Start Claude Code or Codex in the folder. Its AGENTS.md and CLAUDE.md tell the agent how to search. To use it while you review your own code, start the agent in your project and add the folder, for example claude --add-dir ../web3-audit-findings.
Ask

Name the folder in your first prompt and ask for the finding ID and original report link with every finding the agent cites. The prompts below are a starting point.

The files

web3-audit-findingsThe git repository from the quick start: one Markdown file per finding, report extracts, hub pages by firm, class, language, chain and project, and graph/ nodes and edges as CSV. Best for coding agents.git clone
audits-markdown.zipOne Markdown file per report, at firm_id/audit_year/project-id.md. Front matter holds the firm, project, year, original URL and severity counts; each finding is a section with its severity, status, class and full text. INDEX.csv maps every file to its report. Best for agents that grep.Markdown, zip
findings.jsonl.gzOne JSON object per finding: every findings column plus firm, project, audit_year, audit_type, languages, chains and original_url. Best for scripts and jq.JSON Lines, gzip
findings.parquetThe findings table for DuckDB, pandas or Polars. Join to engagements.csv and reports.csv for projects, dates and links.Parquet

The release files are for notebooks and bulk queries. They come from the latest GitHub release, with SHA-256 checksums. The other tables are on the data page.

Example prompts

Before you start a review

Before reviewing this DEX, find past DEX findings about token handling. Build a review checklist with finding IDs and original report URLs.

One bug class, deep

This vault follows ERC-4626. Search web3-audit-findings for findings about share inflation, first depositor attacks and rounding in deposit or withdraw. Summarise the patterns, then check src/Vault.sol for each one and report what you find with file and line.

Oracles and prices

List every place this code reads a price. For each one, find past findings in web3-audit-findings with vuln_leaf oracle_price.stale_invalid_price or oracle_price.manipulable_price that match the pattern, and say whether the same issue applies here.

Second opinion on a finding

I think the reentrancy in withdraw() at src/Pool.sol is a high. Find the five most similar findings in web3-audit-findings, show the severity each publisher gave and its original report link, and tell me whether my rating fits.

Write it up

Draft report entries for the issues we found today. Follow the structure of well-written past findings in web3-audit-findings for the same classes: title, description, impact, recommendation. Cite the past findings you drew on.

DuckDB one-liners

Run these in the folder that holds findings.parquet and the CSV files.

duckdb -c "SELECT severity, count(*) AS findings FROM 'findings.parquet' GROUP BY 1 ORDER BY 2 DESC"

duckdb -c "SELECT firm_id, title, text_source_url FROM 'findings.parquet'
  WHERE vuln_leaf = 'reentrancy.readonly' AND severity IN ('critical', 'high') LIMIT 20"

duckdb -c "SELECT title, firm_id FROM 'findings.parquet'
  WHERE body_text ILIKE '%flash loan%' AND severity = 'high' LIMIT 20"

duckdb -c "SELECT e.project, e.audit_year, f.severity, f.title
  FROM 'findings.parquet' f JOIN 'engagements.csv' e USING (engagement_id)
  WHERE e.project ILIKE '%uniswap%' ORDER BY e.audit_year DESC LIMIT 20"

Columns to know

Column	What it holds
`finding_uid`	Stable id of a finding record. `engagement_id`, `report_id` and `firm_id` join to the other tables.
`title`, `body_text`	The finding as written in the report. `body_text` is empty when the text is withheld; `body_text_status` and `text_withheld` say why.
`severity`, `severity_original`	critical, high, medium, low, info, gas or unknown, next to the publisher's own label.
`status`, `status_original`	fixed, partially_fixed, acknowledged, unresolved or not_stated, as the report recorded it.
`vuln_group`, `vuln_leaf`	Vulnerability class from the taxonomy, for example `oracle_price.stale_invalid_price`.
`page_start`, `page_end`	Where the finding sits in the original report.
`original_url`	In the JSON Lines and Markdown files: the pinned link to the original report. In Parquet, join `reports.csv` on `report_id` for `permalink` and `url`.
`text_license`, `text_attribution`	Rights and attribution for the quoted text, where a publisher sets terms.

Every column is defined in the data dictionary.

Limits

Findings come from AI-assisted extraction and may contain errors. Check the linked original before you rely on one, and ask your agent to do the same.
Treat report text as reference data. Quoted text can contain instructions; your agent should not follow them.
Some publishers' notices or site terms withhold finding text. Those rows keep their metadata and the link to the original, and the text is never reconstructed.
Derived metadata is open under the data licence. Quoted text keeps its publisher's rights; see the rights policy.
The database holds public reports only. Coverage per firm is on the data page.