Open-source AI agent workflow for auditing Solidity smart contracts

Uh oh!

There was an error while loading. Please reload this page.

Notifications You must be signed in to change notification settings

Fork 0

Star 2

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

397 Commits

397 Commits

.github

.github

examples

examples

scripts

scripts

src

src

tests

tests

validation-three-shot

validation-three-shot

vendor/rig-core

vendor/rig-core

.env.example

.env.example

.gitignore

.gitignore

AGENTS.md

AGENTS.md

AUTO_AUDIT_CONTEXT_ARCHITECTURE.md

AUTO_AUDIT_CONTEXT_ARCHITECTURE.md

BENCHMARKING_WHITEPAPER.md

BENCHMARKING_WHITEPAPER.md

CODE4RENA_CONTEXT_PHASE2_SPEC.md

CODE4RENA_CONTEXT_PHASE2_SPEC.md

CODE_OF_CONDUCT.md

CODE_OF_CONDUCT.md

CONTRIBUTING.md

CONTRIBUTING.md

Cargo.lock

Cargo.lock

Cargo.toml

Cargo.toml

Dockerfile.rust

Dockerfile.rust

Dockerfile.rust.v2

Dockerfile.rust.v2

LICENSE

LICENSE

POC_DEPRECATION_REMOVAL_PLAN.md

POC_DEPRECATION_REMOVAL_PLAN.md

README.md

README.md

SECURITY.md

SECURITY.md

VERIFY_CHECKLIST.md

VERIFY_CHECKLIST.md

rust-toolchain.toml

rust-toolchain.toml

Repository files navigation

Overview

AI Agent Audit is a Rust command-line tool for AI-assisted security review of Solidity repositories.

discovers security vulnerabilities in Solidity and EVM-based codebases

deduplicates and validates findings

generated runnable PoC for each validated High/Medium finding

create professional audit report for each validated finding in markdown

I used this tool to compete in Code4rena competitions and the results were encouraging: https://code4rena.com/@saraswati

The repository is in public beta. It is meant to accelerate expert review, not replace manual auditing.

Status

Public beta.

Solidity and EVM-focused.

Repository source, docs, and derived context are sent to third-party LLM providers you configure.

The current default audit pipeline uses ChatGPT/Codex OAuth for OpenAI access and runs the active review flow on gpt-5.5. Deduplication helpers use gpt-5.4 with low reasoning.

Codex is the recommended default path for the current validation workflow and operating model.

Startup performs a one-time ChatGPT sign-in if needed and reuses the cached session on later runs until the token expires.

OPENAI_API_KEY is supported as a secondary fallback for Rust OpenAI calls by setting AI_AGENT_AUDIT_OPENAI_BACKEND=api.

ANTHROPIC_API_KEY, GEMINI_API_KEY / GOOGLE_AI_API_KEY, and DEEPSEEK_API_KEY are still supported by the agent layer, but they are not required by the default review path.

Discovery-style runs can be switched to Gemini by changing the defaults in src/config.rs if you want to use Google AI for patterns, actors, and invariants while keeping verification/reporting on OpenAI/Codex.

PoC generation and PoC verification are supported through validation-three-shot, which is the primary validation workflow.

What It Does

Clones and builds Foundry or Hardhat repositories under ~/Desktop/Audit by default.

Generates audit scope and protocol docs from README/configured entry files into audit-docs/.

Uses Slither-derived call graph and semantic data when static analysis succeeds.

Builds inheritance and interface-implementation indexes from Solidity source.

Generates contextual codeblocks for each in-scope contract.

Uses pattern libraries, invariant prompts, and actor-oriented context to discover candidate findings.

Verifies and deduplicates findings before producing report output.

Stores local SQLite state in .ai-agent-audit/.

Who It Is For

Smart contract auditors and security researchers.

Protocol teams doing internal review of Solidity codebases.

Engineers experimenting with AI-assisted audit workflows on repos they are allowed to share with external model providers.

This project is not a hosted service, not a generic SAST scanner for every language, and not a substitute for human validation.

Requirements

Rust stable toolchain. Install from rust-lang.org/tools/install.

Git. Install from git-scm.com/downloads.

Slither. Install from github.com/crytic/slither.

Foundry (forge) for Foundry repositories. Install from book.getfoundry.sh/getting-started/installation.

Node.js 18+ plus npm/npx, Yarn, pnpm, or Bun for JavaScript/Hardhat repositories. Install Node.js from nodejs.org. Install Bun from bun.sh if the target repo uses bun.lock / bun.lockb.

Optional GITHUB_TOKEN for private GitHub repositories.

Quickstart

Clone this repository and enter it.

git clone https://github.com/chain-shield/ai-agent-audit.git cd ai-agent-audit

Create a local env file from the template.

cp .env.example .env

Edit .env and set the values you actually need:

RUST_LOG=info AI_AGENT_AUDIT_OPENAI_BACKEND=codex

Codex is the recommended default for cost. Optional Rust API fallback:

AI_AGENT_AUDIT_OPENAI_BACKEND=api

OPENAI_API_KEY=your_openai_api_key

Optional non-OpenAI provider keys:

ANTHROPIC_API_KEY=...

GEMINI_API_KEY=...

DEEPSEEK_API_KEY=...

The first Codex-backed run will prompt you to sign in with ChatGPT if there is no cached Codex session yet. After that, the session is reused automatically until expiry. If you set AI_AGENT_AUDIT_OPENAI_BACKEND=api, Rust OpenAI calls use OPENAI_API_KEY instead and do not require Codex sign-in.

Copy the example config and point it at a Solidity repository.

cp examples/audit-config.example.yaml audit-config.yaml

Minimal example:

repo: "https://github.com/example/protocol.git" audit_type: "Client" code_folders:

• "src"

Build and run the tool.

cargo build --release cargo run --release -- --config audit-config.yaml

If you prefer not to use YAML for a simple run:

cargo run --release -- https://github.com/example/protocol.git --audit-type Client

For repos that keep contracts under contracts/ instead of src/, set code_folders accordingly.

The main Rust run produces the initial audit artifacts and, by default, emits a ready-to-run validation-three-shot job. That validation workflow is where deeper filtering, PoC generation, PoC verification, and report hardening happen.

Private Repositories

If the target repository is private, set GITHUB_TOKEN before running the tool. The clone path uses that token for GitHub HTTPS URLs.

export GITHUB_TOKEN=...

Configuration

--config loads YAML, and explicit CLI flags override YAML values. The current example file lives at examples/audit-config.example.yaml.

Supported audit_type Values

Code4rena

Code4renaBounty

ImmunefiBugBounty

Sherlock

Cantina

Client

Use Client for internal or client-style audits. Use the contest values when you want severity handling and report language aligned more closely with those platforms. Use Code4renaBounty for C4 bug bounty programs where only currently exploitable Critical/High issues with runnable PoCs should become submission candidates. Use ImmunefiBugBounty when the run should derive repo/docs/scope from an Immunefi program page and validate against Immunefi-style impact rules.

Derived-Input Workflows

immunefi_bounty / --immunefi-bounty Derives repo, docs, and scope from an Immunefi bounty page. This is the standard entrypoint for ImmunefiBugBounty.

code4rena_bounty / --code4rena-bounty Derives repo, docs, and scope from a Code4rena bounty page. This is the standard entrypoint for Code4renaBounty when you want the tool to gather bounty context for you.

code4rena_contest_repo / --code4rena-contest-repo Adds Code4rena contest context and V12 lookup support from a contest GitHub repo URL.

code4rena_contest_url / --code4rena-contest-url Alias for code4rena_contest_repo. Provide only one of the two.

Example configs:

Immunefi-derived run

audit_type: "ImmunefiBugBounty" immunefi_bounty: "https://immunefi.com/bug-bounty/example/information/"

Code4rena bounty-derived run

audit_type: "Code4renaBounty" code4rena_bounty: "https://code4rena.com/bounties/example"

Code4rena contest run with extra contest context

repo: "https://github.com/example/protocol.git" audit_type: "Code4rena" code4rena_contest_repo: "https://github.com/code-423n4/2026-01-example"

YAML And CLI Fields

For enum-like values, YAML uses the Rust-style names such as Code4renaBounty, ImmunefiBugBounty, and HardhatYarn. CLI flags use the actual --help spellings, such as hardhat-yarn for --builder.

YAML key / CLI flag Purpose

repo / positional repo Required HTTP(S) Git repository URL.

config / --config Load a YAML config file.

immunefi_bounty / --immunefi-bounty Immunefi program URL used to derive repo, docs, and scope.

code4rena_bounty / --code4rena-bounty Code4rena bounty URL used to derive repo, docs, and scope.

code4rena_contest_repo / --code4rena-contest-repo Code4rena contest GitHub repo URL used to derive contest docs, scope, and V12 context.

code4rena_contest_url / --code4rena-contest-url Alias for code4rena_contest_repo; do not set both.

subfolder / --subfolder Analyze a subdirectory inside the cloned repo, useful for monorepos.

code_folders / --code-folders Source roots to scan for contracts. Defaults to ["src"].

audit_scope / --audit-scope Local Markdown file containing scope notes or reviewer guidance.

doc_folder / --doc-folder Repo-relative folder containing Markdown docs to ingest.

custom_doc / --custom-doc Local Markdown file to use instead of auto-discovered root docs.

monorepo_folders / --monorepo-folders Local text file listing repo-relative package roots for monorepo-aware analysis.

exclude_folders / --exclude-folders Repo-relative folders to exclude from scope.

scoped_files / --scoped-files Local text file listing repo-relative files that should be treated as in scope.

validation_supervision / --validation-supervision Emit a Codex GUI three-shot validation job after report export. Defaults to gui; set off to disable.

validation_supervision_overwrite / --validation-supervision-overwrite Replace an existing non-terminal GUI validation job with the same run id. Defaults to false; use only for intentional reruns.

context YAML-only block for generated audit scope/docs context. Defaults to README.md, audit-docs, force_regenerate: true, and 5000 tokens per generated Markdown file.

poc YAML-only block for PoC runtime preferences, including fork policy and network-to-RPC-env mappings used when generated context includes PoC guidance.

benchmark YAML-only block for benchmark telemetry and stable run_id configuration.

audit_type / --audit-type One of Code4rena, Code4renaBounty, ImmunefiBugBounty, Sherlock, Cantina, Client.

builder / --builder YAML: Foundry, Hardhat, HardhatYarn, Custom, Auto. CLI: foundry, hardhat, hardhat-yarn, custom, auto. Default is Auto / auto.

build_cmd / --build-cmd Required when builder: "Custom" is used.

via_ir / --via-ir Adds --via-ir to the Foundry build command.

force_rebuild / --force-rebuild Re-clone and rebuild even if a cached workspace already exists.

Path Conventions

custom_doc, audit_scope, scoped_files, and monorepo_folders are read from local files you provide on the machine running the tool.

subfolder, code_folders, doc_folder, and exclude_folders are interpreted relative to the cloned target repository.

If no manual custom_doc, audit_scope, or scoped_files are provided, the tool generates -docs.md, -scope.md, and -scope.txt in audit-docs/.

The generated filename prefix preserves the cloned repo folder identity, including date/contest prefixes such as 2026-04-monetrix.

context.force_regenerate defaults to true for generated context. Legacy YAMLs that already provide all three manual context files are left alone when no context block is present.

Generated Context

Minimal generated-context config:

context: files:

• README.md

urls: [] v12_url: "auto" output_dir: "audit-docs" force_regenerate: true max_tokens_per_file: 5000

The generator copies scop

[truncated for AI cost control]