Critikal - Autonomous smart contract security research agent

项目说明

Critikal

![CI]()
![Python 3.12]()
![Code style: ruff]()

Autonomous smart contract security research agent.

Critikal thinks like an attacker. Give it a repository URL and it will autonomously find real, exploitable — from initial recon through pro PoC tests.

!Critikal TUI demo

---

What it does

1. Ingests the repository (clone + Slither + knowledge graph)
2. Recons the protocol (docs, NatSpec, Etherscan on-chain data)
3. Maps attack surface (hotspot scoring from graph signals)
4. Forms hypotheses (attack workers + semantic discovery in parallel)
5. (4-gate pre-filter → jury debate → depth analysis)
6. Proves (Foundry PoC test generation with self-correction)
7. Reports (HTML + Markdown audit report with pro)

---

Quick Start

0. Prerequisites

You need the following installed before you start. If you'd rather skip all of
this, jump to the Docker section — the image bundles e.

| Dependency | | Why | Install |
|---|---|---|---|
| Python | >=3.12.1, <3.13 | Runtime | python.org/downloads or pyen 3.12 |
| Poetry | >=1.8 (2.x supported) | Dependency / ven | curl -sSL \| python3 - |
| Git | any recent | Cloning audit targets | apt install git / brew install git |
| Foundry (forge, cast, anvil) | latest | Compiles + runs the generated PoC tests | curl -L \| bash && foundryup |
| solc-select | latest | Switches Solidity compiler per target | pip install solc-select && solc-select install 0.8.20 && solc-select use 0.8.20 |
| Node.js | >=20 | Required by some Solidity toolchains pulled in by audit targets | nodejs.org or n 20 |
| Build essentials (Linux only) | — | Needed for some nati deps | sudo apt install build-essential |

You'll also need at least these API keys (see step 2):

1. Install

Poetry installs e into ./.venv/ and registers a critikal
executable at ./.venv/bin/critikal. That binary is not on your PATH
yet — see step 3.

2. Configure

Edit .env and fill in your keys (use any editor, e.g. nano .env).

> Model Picker now allows you to pick any model from all the a provider api keys, use /model to check it out
> Model Routing table below for
> the full list.

3. Run

Pick one of the three patterns below — they're equi, just different
ways to reach the critikal binary inside the project venv.

Option A — poetry run (no acti, works from anywhere in the repo):

Option B — activate the venv once per shell:

Option C — install globally with pipx (recommended for daily use):

> If you see critikal: command not found, you almost certainly skipped the
> acti step — use one of the three options above.

---

CLI Reference

---

Output

Reports are generated in data/reports/<name>_<timestamp>/:

---

Pipeline Modes

Control via AUDIT_MODE env var (or set indi flags):

| Mode | Static | Semantic | Jury | Depth | TestWriter |
|------|--------|----------|------|-------|------------|
| fast | ✓ | | | | |
| standard | ✓ | | | ✓ | ✓ |
| deep | ✓ | ✓ | ✓ | ✓ | ✓ |
| semantic_only | | ✓ | ✓ | ✓ | ✓ |

---

Model Routing

Defaults route through xAI (Grok) and OpenAI (GPT) only. Every role is
o via env var — point any role at claude-*, gemini-*, or
openrouter/<provider>/<model> and the matching API key will be used.

| Role | Default | Env Var |
|------|---------|---------|
| Agent brain | grok-4-1-fast-reasoning | AGENT_MODEL_NAME |
| Attack worker (creati) | grok-4-1-fast-reasoning | ATTACK_MODEL_NAME |
| Assumption worker (zero-day) | grok-4-1-fast-reasoning | ASSUMPTION_MODEL_NAME |
| Recon / Semantic / Execution-trace workers | gpt-5.4-mini | RECON_MODEL_NAME, SEMANTIC_MODEL_NAME, EXECUTION_TRACE_MODEL_NAME |
| Gate filter | gpt-5.4-mini | GATE_MODEL_NAME |
| Depth workers | gpt-5.4-mini | DEPTH_MODEL_NAME |
| Jury Skeptic | gpt-5.5 | JURY_SKEPTIC_MODEL |
| Jury Attacker | grok-4-1-fast-reasoning | JURY_ATTACKER_MODEL |
| Jury Auditor | gpt-5.4-mini | JURY_AUDITOR_MODEL |
| Jury Judge | grok-4-1-fast-reasoning | JURY_JUDGE_MODEL |
| TestWriter (Foundry PoC) | grok-code-fast-1 | TEST_WRITER_MODEL_NAME |
| Fuzz generator | grok-code-fast-1 | FUZZ_MODEL_NAME |
| Memory / dream / compact / sub-agent | gpt-5.4-mini | MEMORY_EXTRACT_MODEL, DREAM_MODEL_NAME, COMPACT_MODEL_NAME, SUB_AGENT_MODEL_NAME |

---

Architecture

---

Docker

The Docker image includes Python 3.12, Node.js 20, Foundry, and solc-select.

---

Disclaimer

Critikal is an automated research tool. It is not a substitute for professional manual audits. Always findings in a safe, isolated en. Only use on targets you ha to test.

项目信息

开发语言：Python

Star 数：15

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Autonomous smart contract security research agent — finds and proves exploits via LLM-driven recon, hotspot mapping, and Foundry PoC generation.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。