RamilRamil/sr-agent

# SR-agent 一个智能合约安全审计 agent，旨在实际演示什么是**安全的 AI agent**。 ## 双重目标 大多数 agent 框架侧重于能力。SR-agent 则同时关注两者： 1. **审计智能合约** — 跨越 3 个阶段的 pipeline（发现 → CheckRunner → 综合）检测重入攻击、预言机操纵、MEV 漏洞以及其他 EVM 安全问题 2. **自身也是一个安全的 agent** — 实施当前所有针对抗 MI、可审计且实现了主体隔离的 AI agent 的最佳实践 第二个目标是其研究贡献。SR-agent 是一个参考实现，它对自身安全的重视程度丝毫不亚于它所审计的合约的安全。 ## 威胁：Memory Injection Memory Injection (MI) 是一种攻击方式，通过在 agent 的 memory 中植入恶意内容，导致其在未来的会话中采取有害行动——例如泄露数据、跳过分析或发布虚假的安全判定。针对未受保护 agent 的攻击成功率 (ASR) 高达 **55–85%**，具体取决于攻击类型（来自论文 [2503.16248](https://arxiv.org/abs/2503.16248)）。 SR-agent 通过架构控制而非 prompt 工程将其降低至 **≤ 5% ASR**。 ## 安全架构 核心理念：将 **Orchestration Plane**（确定性代码）与 **LLM Context Plane**（概率模型）分离。所有的安全保证都存在于 orchestration plane 中——无论注入的内容指示 LLM 做什么，LLM 都无法覆盖它们。 ``` ┌─────────────────────────────────────────────────────────┐ │ Orchestration Plane │ │ HMAC sign/verify · source_type hierarchy · status gate │ │ action whitelist · path traversal guard · OOB confirm │ └──────────────────────────┬──────────────────────────────┘ │ controlled interface ┌──────────────────────────▼──────────────────────────────┐ │ LLM Context Plane │ │ Claude Opus (Stage 1/3) · Qwen3-4B fine-tuned (Stage 2) │ │ All external data wrapped in [DATA START]...[DATA END] │ └─────────────────────────────────────────────────────────┘ ``` **Memory 完整性** — Episodic Memory 中的每条记录都由 orchestrator 进行 HMAC-SHA256 签名。签名无效的记录在进入 LLM context 之前会被静默丢弃。签名密钥永远不会离开 orchestration plane。 **仅追加 memory** — 没有 `update_memory` 或 `delete_memory` 工具。更正操作是带有 `supersedes` 指针的新记录。只有 `source_type=human_input` 才能发布更正。 **Source type 层级** — 每条 memory 记录都带有来源标签。特权状态（`verified_safe`、`skip_analysis`、`audit_complete`）需要 `source_type=human_input`。LLM 尝试通过 `llm_inference` 设置这些状态时，会被确定性拒绝。 **Action 白名单** — 该 agent 没有 `run_command(cmd: str)`。每个工具都是命名且类型化的操作（`run_slither`、`read_file`、`analyze_transactions`）。工具描述在启动时会针对 `TOOL_REGISTRY` 进行哈希验证，以防止供应链攻击。 **Out-of-band 确认** — 不可逆操作（`write_poc`、`run_tests`、`deploy_test_contract`）会暂停执行，并在继续之前通过单独的 CLI 调用要求明确的人工批准。 **始终保持 Extended thinking** — Claude Opus 的 extended thinking 是 Stage 1/3 调用的一项安全要求，而不是性能选项。根据研究，它提供了约 5 倍的抗 MI 能力提升。 ## 3 阶段审计 pipeline ``` Stage 1 — Discovery (ReAct, Claude Opus) Build call graph → identify high-risk targets → prioritized list Stage 2 — CheckRunner (for-loop, Qwen3-4B fine-tuned, local) Per-target: apply 12 preconditions checklist → structured findings Code never leaves your machine Stage 3 — Synthesis (ReAct, Claude Opus) Combine findings → identify multi-contract attack paths → final report ``` Stage 2 通过 Ollama 运行本地微调的 Qwen3-4B——没有任何合约代码被发送到外部 API。Stage 1/3 通过 Anthropic API 使用带有 extended thinking 的 Claude Opus。 ## 架构决策 所有技术决策都记录在 [`specs/001-secure-memory-agent/`](specs/001-secure-memory-agent/) 中，包含基本原理和考虑的替代方案。关键文件： - [`research.md`](specs/001-secure-memory-agent/research.md) — 17 项架构决策 - [`data-model.md`](specs/001-secure-memory-agent/data-model.md) — 所有实体和状态转换 - [`contracts/`](specs/001-secure-memory-agent/contracts/) — 模块接口契约 框架研究（为什么我们没有使用 LangGraph、Mem0、Hermes、LangMem、NeMo Guardrails）记录在 [`research/frameworks.md`](research/frameworks.md) 中。 ## 快速开始 完整的设置说明请参阅 [`specs/001-secure-memory-agent/quickstart.md`](specs/001-secure-memory-agent/quickstart.md)。 ``` cp .env.example .env # 填写 ANTHROPIC_API_KEY 并生成 SR_SECRET_KEY： python -c "import secrets; print(secrets.token_hex(32))" docker compose up -d ollama langfuse pip install -e ".[dev]" sr-agent audit ./path/to/contracts/ sr-agent demo-attack # run MI attack scenarios, verify ASR ≤ 5% ``` ## 运行测试 ``` pytest tests/unit/ # fast, no external dependencies pytest tests/security/ # MI resistance tests, no LLM calls needed pytest tests/integration/ # requires Docker ``` ## 参考文献 - [2503.16248](https://arxiv.org/abs/2503.16248) — Memory Injection 攻击、ASR 测量、extended thinking 抗性 - [2606.03387](https://arxiv.org/abs/2606.03387) — Bastet 数据集：849 个专家标注的 Code4rena 发现，46 标签分类法 - [2606.05986](https://arxiv.org/abs/2606.05986) — AttackPathGNN：基于前提条件的漏洞检测

标签：AI安全, AI风险缓解, Chat Copilot, 区块链安全, 大语言模型代理, 提示注入防御, 智能体安全, 智能合约审计, 源代码安全, 请求拦截, 逆向工具