solidity-cot-auditor: Open-Source Solidity Auditor

What Is solidity-cot-auditor?

solidity-cot-auditor is an open-source Smart Contract Security Auditing pipeline built by butthtio that turns Slither findings into four LLM roles: Explainer, ExploitWriter, Fixer, and Judge. It is one of the best Smart Contract Security Auditing tools for Solidity developers, auditors, and security engineers who need actionable context instead of terse detector output. The tool keeps the original Slither signal, then adds explanation, exploit sketch, and minimal patch guidance in a single report.

Quick Overview

Who Should Use solidity-cot-auditor?

• Audit teams reviewing Slither output who need a readable explanation, a likely exploit path, and a patch suggestion without rewriting the finding by hand.
• Solidity engineers shipping DeFi, NFT, or protocol code who want a second-pass review before merging a release candidate.
• CI owners who already run Slither in GitHub Actions or another pipeline and want a structured LLM layer on top of JSON findings.
• Security researchers comparing true positives, false positives, and fix quality across multiple contracts or branches.

Not ideal for:

• Teams that need fully deterministic findings with no model variance.
• Projects that cannot send code context to an external or self-hosted LLM endpoint.
• Users who want a source-level analyzer without Slither in the workflow.

Key Features of solidity-cot-auditor

• Four-role reasoning chain — The pipeline separates work into Explainer, ExploitWriter, Fixer, and Judge. That structure reduces generic output because each role has one job and one prompt boundary.
• Slither JSON ingestion — solidity-cot-auditor reads Slither output instead of scanning source from scratch. That means the tool inherits Slither's fast static analysis and adds a narrative layer on top of concrete detector results like reentrancy-eth.
• Minimal-fix diffs — The Fixer role emits a unified diff rather than a vague recommendation. For Solidity code, that is the difference between a review note and a patch you can inspect in git apply or a pull request.
• Exploit sketch for defenders — The ExploitWriter role is aimed at validation, not offense. It sketches a minimal proof-of-concept so auditors can see whether a finding is actually exploitable in the current contract shape.
• Judge-based quality check — The Judge role scores the chain and flags contradictions or logical misses in earlier stages. That extra pass matters when an Explainer sounds plausible but misses the actual state transition that causes the bug.
• Provider flexibility — solidity-cot-auditor works with OpenAI-compatible endpoints, local vLLM servers, Together AI, Fireworks, and direct Anthropic support. That makes it usable in air-gapped labs, self-hosted setups, and teams that prefer Claude for reasoning-heavy reviews.
• Severity filtering and caps — Flags like --min-severity and --max-findings keep low-signal results out of the LLM chain. That matters because informational findings, style issues, and compiler noise can burn tokens without improving the final report.

solidity-cot-auditor vs Alternatives

Pick Slither instead when you only need raw detector output and want zero model cost. It is the source signal that solidity-cot-auditor depends on, so the two tools are complementary rather than competing substitutes.

Pick Mythril when you need symbolic execution to explore execution paths that static pattern matching may miss. Pick Foundry when the next step is reproducing the bug with tests, fuzzing, or an invariant harness.

For CI runners that already orchestrate build and audit jobs, djevops is the adjacent piece. If you want a place to inspect output trails and compare runs, OpenTrace is the closest site tool match.

How solidity-cot-auditor Works

The architecture is straightforward: Slither emits structured JSON, solidity-cot-auditor filters that stream by severity, and each retained finding flows through a role-specific LLM stage. The design choice is intentional. A single prompt that asks for explanation, exploitability, and remediation tends to blur responsibilities and produce generic output, while role separation keeps the data model narrow and reviewable.

The core abstraction is the finding object. Each finding carries the detector name, severity, contract location, and any metadata Slither exposes, and the pipeline uses that object as the input contract for the next stage. The Explainer produces a technical summary and a true or false positive verdict, the ExploitWriter sketches a minimal attack path, the Fixer returns a diff, and the Judge checks the chain for internal consistency.

A typical CI-style run looks like this:

slither MyToken.sol --json slither_out.json
solidity-cot audit-json slither_out.json --project MyToken --source-root ./contracts --min-severity medium

That sequence first generates deterministic findings and then asks solidity-cot-auditor to enrich them. Expect the second command to spend time on LLM calls, so latency and token usage scale with the number of retained findings and the model you select.

Provider selection is also part of the architecture. If you want a local setup, point the tool at a vLLM endpoint and keep traffic inside your network. If you prefer hosted reasoning, set LLM_PROVIDER=anthropic or use an OpenAI-compatible base URL, then let the same JSON pipeline run unchanged.

Pros and Cons of solidity-cot-auditor

Pros:

• Turns terse static-analysis labels into reviewable prose, exploit context, and patch diffs.
• Keeps Slither as the deterministic front end, so the tool augments analysis instead of replacing it.
• Lets you skip exploit or judge stages when a lighter report is enough.
• Supports OpenAI-compatible and Anthropic-backed deployments, which makes it easy to fit into different privacy and cost models.
• Produces Markdown plus JSON output, so the results work in both human review and automation.
• Uses a fake LLM client in tests, which means the repository can be validated without burning API credits.

Cons:

• Adds model latency, so it is slower than a pure static-analysis run.
• Quality depends on the selected model, prompt settings, and the accuracy of the underlying Slither finding.
• Requires Slither and a Solidity toolchain, which means it is not a single-binary install.
• Can still generate a plausible but wrong explanation if the finding context is thin.
• Is less useful for informational or style findings where a semantic explanation adds little value.

Getting Started with solidity-cot-auditor

The fastest path is to install the package in editable mode, install Slither separately, and run the audit command against either a Solidity file or a saved JSON report.

pip install -e '.[dev]'
pip install slither-analyzer
export OPENAI_API_KEY=sk-...
solidity-cot audit ./contracts/MyToken.sol --output reports/

After that first run, solidity-cot-auditor writes a report directory with the enriched findings. If you already have Slither JSON from CI, use audit-json instead of rescanning source, and pass --skip-judge when you want faster output for a quick internal review.

Verdict

solidity-cot-auditor is the strongest option for turning Slither output into actionable smart contract review notes when you want explanation plus minimal-fix diffs in one pass. Its biggest strength is structured reasoning across four roles, and its main caveat is LLM cost and variance. Use it as the review layer, not the source of truth, and it earns a place in a Solidity security pipeline.