CodeAudit 是一个依赖漏洞可达性审计 Agent。给定一个 Python 仓库，它会先查询直接依赖的已知漏洞（通过 OSV 漏洞库），再阅读实际代码判断每一个漏洞在当前代码中是否真的可达——从而把"真风险"与"仅清单上挂着、实际用不到"的误报区分开，最终输出一份带证据的报告。
它区别于 pip-audit 这类只列 CVE 清单的工具：CodeAudit 会读源码、追踪 import 与调用链，据此判断某个被标记的依赖是否真的被用到。这正是 Agent 的增量价值所在。
在 6 个真实 CVE 样本（全部来自公开 OSV 库，非编造）上，CodeAudit 判断依赖漏洞可达性：
- 通过率 6/6，无漏报、无误报、无未收敛
- 平均 ~7.4 步 / ~16s / ~2.5 万 token，整轮估算成本 ~$0.05
- 每条结论均给出
文件:行号证据，区分「可达 / 不可达 / 无风险」
当前为 canary 冒烟套件（单依赖、漏洞点清晰），采用
--seeds 3多数投票 + LLM 评审为主判分。评测的方法、真实 CVE 溯源、可信度分析与复现方式见docs/EVAL.md。
CodeAudit 基于原生 OpenAI SDK 从零构建，不依赖 LangChain 等 Agent 框架。核心是一个经典 Agent 循环：
model decides -> hooks gate -> tool executes -> observation feeds back
- Tool 注册：
tools.py用分发映射（TOOL_HANDLERS）管理所有工具；添加一个工具 = 加一个 schema + 一个 handler，循环本身不变。 - 只读设计：所有工具均不修改仓库，Agent 只检查、不改代码。
- 权限边界：
permission.py/hooks.py在每次工具调用前把关；safe_path路径沙箱拒绝逃逸工作区的路径，.env*密钥文件被禁止读取。 - 任务规划：模型用
todo清单自我规划，并通过blockedBy表达步骤依赖。 - 外部数据：进程内 MCP 桥接 OSV 服务，其工具以
mcp__osv__query形式接入，查询真实 CVE 数据库。 - 完成判定：独立的、无工具"完成判定器"（goal-loop）在循环返回前判断审计是否真正有依据（OSV 结果 / 可达性结论 / 文件:行号证据），防止模型"裸宣告完成"。
- 上下文管理：多阶段压缩让长审计保持在模型窗口内；跨会话记忆可召回历史结论。
- 任务委派：
task工具将高成本调查交给子 Agent，避免污染父上下文。
前置条件：Python 3.11+、一个 OpenAI 兼容的 API Key（默认为 DeepSeek）。
git clone https://github.com/Th1rtynine/codeaudit-agent.git
cd codeaudit-agent
python -m venv venv
# Windows: venv\Scripts\activate | macOS/Linux: source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env # 然后填入 DEEPSEEK_API_KEY运行（审计当前工作目录）：务必用项目 venv 的解释器，而不是系统的 python（否则会因缺 openai 等依赖报 ModuleNotFoundError）。
# 1) 进入项目目录（确保能看到 venv 目录）
cd D:\Project\codeaudit
# 2) 确认依赖已装好（应打印 deps ok；若报错则先执行 pip install -r requirements.txt）
.\venv\Scripts\python.exe -c "import openai, dotenv, yaml; print('deps ok')"
# 3) 建议先设 UTF-8，避免 Windows 控制台中文乱码（乱码只影响显示，不影响功能）
$env:PYTHONUTF8 = 1
# 4) 启动对话
.\venv\Scripts\python.exe -m codeaudit.cli启动后出现 codeaudit >> 输入任务，q 退出；... 提示符，输入审计请求（例如 审计这个仓库的依赖漏洞可达性 或 审计当前仓库的依赖漏洞可达性）回车，agent 会逐步执行并在最后输出最终审计报告。想继续可再输入请求；输入 q / exit 退出。加 --trace 可打印完整步骤追踪；--from-trace <trace.json> 可零 token 重放一次已落盘的 trace 并渲染失败诊断（用于失败后定位）。运行中可用 /goal 查看、/goal clear 清除、/goal <目标> 设置完成判定目标。
CodeAudit 审计的是当前工作目录（WORKDIR = cwd）。要审计其他仓库，可先 cd 到目标仓库，并确保 codeaudit 包可被导入（例如把本项目加入 PYTHONPATH）。
Windows 下中文输出请设置
PYTHONUTF8=1。
配置（.env）：DEEPSEEK_API_KEY、BASE_URL、MODEL、MAX_STEPS、MAX_TOKENS、TEMPERATURE、LLM_MAX_RETRIES、LLM_BACKOFF_BASE，以及可选的 goal-loop 调优参数（GOAL_EVALUATOR_MODEL、GOAL_MAX_BLOCKS、GOAL_RECENT）。完整键名与默认值见 .env.example。
codeaudit/
cli.py CLI 入口
loop.py Agent 循环（model -> hooks -> tool -> observation）
tools.py 只读工具 + 动作路由
config.py 环境配置 + 系统提示词
llm.py OpenAI 兼容客户端
mcp.py MCP 桥接（OSV 服务）
todo.py 规划工具（todo_write，依赖有序）
goal.py 独立完成判定器
compactor.py 上下文压缩
memory.py 跨会话记忆
skill_loader.py 按需技能加载
subagent.py 子 Agent 委派
permission.py 权限策略
hooks.py PreToolUse 钩子
trace.py 追踪日志
skills/
cve-reachability/ 可达性审计领域技能
code-review/ Code review 技能
evals/
run_evals.py 评测框架入口
fixtures/ 各样本仓库（requirements.txt + app.py）
expected/ ground truth（在审计范围之外）
docs/
EVAL.md 评测记录与可信度分析
design.md 设计复盘
本项目为教学与工程实践结合的 Agent 落地项目，用于展示从零构建 Agent 的完整链路（推理 -> 观察回传 -> 动作路由），并可作为依赖漏洞可达性审计的参考实现。