Tushar-Pandey-31/Critikal
GitHub: Tushar-Pandey-31/Critikal
一款自主智能合约安全研究 Agent，通过 LLM 驱动的侦察、知识图谱热点映射和对抗式辩论验证，实现从漏洞发现到 Foundry PoC 利用证明的全流程自动化。
Stars: 7 | Forks: 2
# Critikal
[](https://github.com/Tushar-Pandey-31/Critikal/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/ruff)
**自主智能合约安全研究 Agent。**
Critikal 像攻击者一样思考。给它一个仓库 URL，它将自主发现真实的、可利用的漏洞——从初步侦察到经过验证的 Foundry PoC 测试。
## 它的功能
1. **摄取**仓库（克隆 + Slither + 知识图谱）
2. **侦察**协议（文档、NatSpec、Etherscan 链上数据）
3. **映射攻击面**（来自图信号的热点评分）
4. **形成假设**（攻击 worker + 并行语义发现）
5. **验证**（4 门限预过滤 → 陪审团辩论 → 深度分析）
6. **证明**（带有自我纠正的 Foundry PoC 测试生成）
7. **报告**（带有已验证漏洞利用的 HTML + Markdown 审计报告）
## 快速开始
### 0. 前置条件
在开始之前，您需要安装以下依赖。如果您想跳过所有这些步骤，请直接跳转到 [Docker](#docker) 部分——该镜像捆绑了所有内容。
| 依赖 | 版本 | 原因 | 安装 |
|---|---|---|---|
| **Python** | `>=3.12.1, <3.13` | Runtime | [python.org/downloads](https://www.python.org/downloads/) 或 `pyenv install 3.12` |
| **Poetry** | `>=1.8`（支持 2.x） | 依赖 / 虚拟环境管理器 | `curl -sSL https://install.python-poetry.org \| python3 -` |
| **Git** | 任何最新版本 | 克隆审计目标 | `apt install git` / `brew install git` |
| **Foundry**（`forge`、`cast`、`anvil`） | 最新 | 编译并运行生成的 PoC 测试 | `curl -L https://foundry.paradigm.xyz \| bash && foundryup` |
| **solc-select** | 最新 | 根据目标切换 Solidity 编译器版本 | `pip install solc-select && solc-select install 0.8.20 && solc-select use 0.8.20` |
| **Node.js** | `>=20` | 审计目标引入的某些 Solidity 工具链所需 | [nodejs.org](https://nodejs.org/) 或 `nvm install 20` |
| **构建基础工具**（仅限 Linux） | — | 某些原生 Python 依赖所需 | `sudo apt install build-essential` |
您还需要至少以下 API 密钥（见第 2 步）：
- `OPENAI OR GEMINI OR ANTHROPIC OR XAI` — 建议使用多个 API 密钥以获得强有力的 JURY 决策。
- `ETHERSCAN_API_KEY` — 建议用于链上侦察
### 1. 安装
```
# 1. Clone
git clone https://github.com/Tushar-Pandey-31/critikal.git
cd critikal
# 2. 解析并固定 dependency graph (刷新 poetry.lock)
poetry lock
# 3. 将所有 deps 和 `critikal` entry point 安装到项目本地的 venv 中
poetry install
```
Poetry 会将所有内容安装到 `./.venv/` 中，并在 `./.venv/bin/critikal` 注册一个 `critikal` 可执行文件。该二进制文件目前**尚未**在您的 `PATH` 中——请参阅第 3 步。
### 2. 配置
```
cp .env.example .env
# 必需 (默认): OPENAI_API_KEY 和 XAI_API_KEY
# Critikal 的默认配置仅通过 GPT-5 和 Grok-4 路由。设置这两个
# key 即可使开箱即用的配置生效。
# 可选 / opt-in: ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY
# 仅在您将 *_MODEL_NAME env vars 覆盖为 claude-* / gemini-* / openrouter/* 时才需要。
# 推荐: ETHERSCAN_API_KEY 用于 on-chain recon
```
编辑 `.env` 并填入您的密钥（使用任意编辑器，例如 `nano .env`）。
### 3. 运行
从以下三种模式中**选择一种**——它们是等价的，只是访问项目虚拟环境中 `critikal` 二进制文件的不同方式。
**选项 A — `poetry run`（无需激活，可在仓库中的任何位置使用）：**
```
# Full audit — headless mode
poetry run critikal --repo https://github.com/theredguild/damn-vulnerable-defi
# 自定义 prompt
poetry run critikal --headless "Focus only on reentrancy and flash loan attack surfaces"
# 交互式 TUI
poetry run critikal
```
**选项 B — 每个 shell 激活一次虚拟环境：**
```
# Poetry 2.x
eval $(poetry env activate)
# 或者，在任何 Poetry 版本上，直接 source venv
source .venv/bin/activate
# 现在 `critikal` 已位于您的 PATH 中，直到您执行 `deactivate`
critikal --repo https://github.com/theredguild/damn-vulnerable-defi
critikal --headless "Focus only on reentrancy and flash loan attack surfaces"
critikal
```
**选项 C — 使用 pipx 全局安装（推荐日常使用）：**
```
pipx install --editable .
# `critikal` 现在可从任何目录通过 PATH 访问；对 src/ 的修改会实时生效
critikal --repo https://github.com/theredguild/damn-vulnerable-defi
```
## CLI 参考
```
critikal [OPTIONS]
--repo URL Repository to audit (URL or local path)
--headless PROMPT Run with custom prompt (no TUI)
--interactive Force interactive TUI mode
--model MODEL Override agent brain model (default: grok-4-1-fast-reasoning)
--budget USD Maximum spend in USD
--permission-mode ask | auto | yolo (default: auto)
--resume ID Resume a previous engagement
--dream [ID] Run memory consolidation
--schedule CRON Schedule recurring audit
--list-schedules List scheduled tasks
--legacy [DEPRECATED] Use old pipeline
-v / --verbose Verbose logging
```
## 输出
报告在 `data/reports/_/` 中生成：
- `report.html` — 交互式暗色模式报告，包含证据徽章、陪审团裁决、链上分析
- `report.md` — 适用于 Immunefi / HackerOne 提交的 Markdown
- `graph.html` — 知识图谱可视化（D3.js）
- `exploits/` — 已验证的 Foundry `.t.sol` PoC 测试文件
## Pipeline 模式
通过 `AUDIT_MODE` 环境变量进行控制（或设置各个标志）：
| 模式 | Static | Semantic | Jury | Depth | TestWriter |
|------|--------|----------|------|-------|------------|
| `fast` | ✓ | | | | |
| `standard` | ✓ | | | ✓ | ✓ |
| `deep` | ✓ | ✓ | ✓ | ✓ | ✓ |
| `semantic_only` | | ✓ | ✓ | ✓ | ✓ |
## 模型路由
默认仅通过 xAI (Grok) 和 OpenAI (GPT) 进行路由。每个角色均可通过环境变量进行覆盖——将任何角色指向 `claude-*`、`gemini-*` 或 `openrouter//`，系统将使用匹配的 API 密钥。
| 角色 | 默认 | 环境变量 |
|------|---------|---------|
| Agent 大脑 | `grok-4-1-fast-reasoning` | `AGENT_MODEL_NAME` |
| 攻击 worker（创造性攻击者） | `grok-4-1-fast-reasoning` | `ATTACK_MODEL_NAME` |
| 假设 worker（0day） | `grok-4-1-fast-reasoning` | `ASSUMPTION_MODEL_NAME` |
| 侦察 / 语义 / 执行轨迹 worker | `gpt-5.4-mini` | `RECON_MODEL_NAME`、`SEMANTIC_MODEL_NAME`、`EXECUTION_TRACE_MODEL_NAME` |
| 门限过滤器 | `gpt-5.4-mini` | `GATE_MODEL_NAME` |
| 深度 worker | `gpt-5.4-mini` | `DEPTH_MODEL_NAME` |
| Jury 怀疑者 | `gpt-5.5` | `JURY_SKEPTIC_MODEL` |
| Jury 攻击者 | `grok-4-1-fast-reasoning` | `JURY_ATTACKER_MODEL` |
| Jury 审计员 | `gpt-5.4-mini` | `JURY_AUDITOR_MODEL` |
| Jury 裁判 | `grok-4-1-fast-reasoning` | `JURY_JUDGE_MODEL` |
| 测试编写器 | `grok-code-fast-1` | `TEST_WRITER_MODEL_NAME` |
| Fuzz 生成器 | `grok-code-fast-1` | `FUZZ_MODEL_NAME` |
| 记忆 / 梦境 / 压缩 / 子 Agent | `gpt-5.4-mini` | `MEMORY_EXTRACT_MODEL`、`DREAM_MODEL_NAME`、`COMPACT_MODEL_NAME`、`SUB_AGENT_MODEL_NAME` |
## 架构
```
CLI (src/cli.py)
└── HeadlessRunner / CritikalApp (TUI)
└── QueryLoop (src/agent/query_loop.py)
├── LLM via LangChain (provider-agnostic)
├── 29 tools (pipeline + graph + file/shell/web + chain + meta)
├── AutoCompactor (context management)
├── PermissionHandler
└── SessionMemory (~/.critikal/memory//)
Pipeline tools invoke workers from src/pipeline/workers/:
ingest_repo → RepoManager + AnalysisEngine + GraphBuilder
run_recon → ReconWorker (7 parallel intel sources)
find_hotspots → HotspotEngine + graph_queries
threat_intel → ThreatProfiler + AttackVectorDB
run_attack_analysis→ AttackHypothesis + Assumption + ExecutionTrace workers
run_semantic_analysis → InvariantHunter + EconomicAttacker + TrustBoundary + CrossContract
run_gate_filter → 4-gate pre-filter (fast LLM)
run_jury_debate → 4-LLM adversarial debate
run_depth_analysis → StateTrace / EdgeCase / External depth workers
run_chain_analysis → ChainAnalyzer (deterministic multi-step linking)
search_exploits → RAG similarity search (ChromaDB)
write_exploit_test → TestWriterWorker (Phoenix loop + sandboxed Foundry)
generate_fuzz_tests→ FuzzGenerator (invariant fuzz tests for CRITICAL findings)
generate_report → ReportGenerator (HTML + Markdown + D3 graph)
Generic tools: bash, file_read/write/edit, grep, glob, web_fetch, web_search
Chain tools: sandbox_run (Foundry), deploy_contract, cast (on-chain RPC)
Meta tools: spawn_agent (sub-agent for parallel investigation)
```
## Docker
```
docker-compose build
docker-compose run critikal /bin/bash
```
Docker 镜像包含 Python 3.12、Node.js 20、Foundry 和 solc-select。
## 免责声明
Critikal 是一款自动化研究工具。它不能替代专业的手动审计。请始终在安全、隔离的环境中验证发现。仅对您拥有测试授权的目标使用。
标签：DLL 劫持, DoH影响, Etherscan, Foundry, IP 地址批量处理, LLM驱动, MITM代理, PoC生成, Slither, Solidity, URL发现, Web3安全, 人工智能, 区块链, 区块链安全, 大语言模型, 安全检测, 实时处理, 密码管理, 攻击者思维, 攻击面分析, 智能合约审计, 概念验证, 热点映射, 用户模式Hook绕过, 自主安全研究, 自动化渗透测试, 请求拦截, 逆向工具, 错误基检测, 静态代码分析