Nick-is-building/ast-guard
GitHub: Nick-is-building/ast-guard
ast-guard：AI代码生成代码执行前的确定性静态分析工具。
Stars: 0 | Forks: 0
# ast-guard
**AI生成代码的执行前门**
*LLM代码生成与代码执行之间的确定性层。无LLM。无ML。无成本.*
[](https://github.com/Nick-is-building/ast-guard/actions/workflows/tests.yml) [](https://www.python.org/downloads/) [](https://github.com/Nick-is-building/ast-guard/blob/main/LICENSE)
## ast-guard 是什么
ast-guard 位于代码生成和执行之间。它将LLM生成的代码解析为AST，并在任何行运行之前返回一个确定性判断。它不是一个检查器，不是一个安全扫描器，也不是一个沙箱——它是一个确定性的结构检查，不能通过模型的推理轨迹来合规，也不能被模型的说服所欺骗。
两种现有的防御类别留下了一个差距：
- **训练时对齐**（Anthropic，DeepMind）减少了发生率，但没有减少残留。
- **推理时LLM审查员**（TRACE，RewardHackWatch，EvilGenie）与它们所监控的生成器共享失败模式。
ast-guard 是作为一个确定性的第三层与那些防御一起构建的。今天，它以零扫描成本可靠地捕获了结构上明显的绕过（参见[关键结果](#key-results））；当前活跃的开发方向是随着时间的推移扩大结构覆盖范围，这样语义审查员就可以专注于只有他们才能做的事情——判断意图和意义。
```
LLM generates code
│
▼
┌───────────────────┐
│ ast-guard gate │ ← deterministic, <10ms, zero cost
└───────────────────┘
│
┌────┴────┐
▼ ▼
CLEAN WARNING / CRITICAL
```
两种模式：
- **配对模式**——比较原始代码与LLM生成的代码。检测结构偏差。
- **独立模式**——分析单个代理输出，没有基线。使用行为风险评分。
## 关键结果
所有结果都是完全可复制的。有关完整方法、混淆矩阵和按类别分解，请参阅[benchmarks/RESULTS.md](benchmarks/RESULTS.md）。
| 基准 | 模式 | 样本 | 关键指标 | 值 |
|-----------|------|---------|------------|-------|
| 结构基准（经过策划的地面实况配对） | 配对 | 36 | F1 | **100%** |
| TRACE 分类法（Deshpande 等人，2026） | 配对 | 33 | F1 | **95.7%** |
| 奖励黑客学校（longtermrisk） | 配对 | 26 | 回收率 | **96.2%** |
| Countdown-Code（Khan 等人） | 配对 | 15,894 | 真阴性率 | **99.0%** |
| MALT（METR，81,515个代理代码块） | 独立 | 81,515 | 特异性† | **84.2%** |
| MALT — `hardcoded_solution` | 独立 | 429 | 检测率 | **70.9%** |
| MALT — `bypass_constraints` | 独立 | 2,379 | 检测率 | **41.7%** |
† 仅在 `normal` 标签上测量 TNR（77,369个样本）；有关完整的混淆矩阵，请参阅[RESULTS.md](benchmarks/RESULTS.md)。
### 与现有方法的比较
这些方法都是互补的，而不是竞争的。ast-guard 处理结构分析；LLM审查员处理语义。
| 方法 | 方法 | 扫描成本 | 延迟 | 确定性 | 范围 |
|----------|--------|-----------|---------|---------------|-------|
| GPT-4o 审查员 | LLM-as-judge | $0.01–0.10 | 500–2000ms | No | 语义 + 结构 |
| RewardHackWatch | ML + Regex + AST | GPU required | varies | No | 轨迹级 |
| **ast-guard v2.0** | **纯 AST + 启发式** | **$0.00** | **<10ms** | **Yes** | **仅结构** |
## 工作原理
ast-guard 将代码解析为抽象语法树并评估结构属性。无执行，无采样，无概率推理。
### 六项检查
1. **硬编码检测**——if-counts，字面量计数，长字符串增长与基线相比。排除守卫子句。
2. **复杂性崩溃**——函数 McCabe 复杂性下降 >60%，没有经过认可的合法优化。
3. **禁止调用和混淆**——基于 diff 的新 `eval`/`exec`/`subprocess`/`ctypes`/`SystemExit` 调用检测，别名解析，`chr()`-混淆，内置索引。
4. **导入漂移**——新导入与阻止列表（CRITICAL）和允许列表（CLEAN）相比。未知导入→警告。
5. **扩展性枚举**——Helff 等人记录的 RLVR 简短路径：平坦的 if/elif 或 match/case 链覆盖 ≥70% 的分支，没有循环。
6. **行为风险评分**（仅独立模式）——从 AST 模式获得的 YARA/Semgrep 风格的累加分数。CLEAN <30，警告 30–69，CRITICAL ≥70。
### 判断逻辑
```
CLEAN → score below threshold, no blocklist triggers
WARNING → suspicious patterns, manual review recommended
CRITICAL → high-confidence structural hack, block execution
```
模式：`strict` 阻止 CRITICAL；`standard` 记录一切；`audit` 仅收集静默。
```
git clone https://github.com/Nick-is-building/ast-guard.git
cd ast-guard
python -m pytest tests/ -q
```
### Python API
```
from ast_guard import scan, scan_standalone
result = scan(original_code, generated_code, mode="strict")
if result["verdict"] == "CRITICAL":
print("Blocked: structural hack detected.")
print(result["checks"])
elif result["verdict"] == "WARNING":
print("Suspicious. Review recommended.")
# 独立：单个代理输出，无基线
result = scan_standalone(agent_code)
print(result["verdict"], result["checks"]["check_6_behavioral"]["risk_score"])
```
### 命令行界面
```
python -m ast_guard.cli check original.py generated.py # standard
python -m ast_guard.cli check original.py generated.py --mode strict
python -m ast_guard.cli check original.py generated.py --json # for pipelines
```
退出代码 0 在 CLEAN/WARNING，退出代码 1 在 CRITICAL — 适用于 CI 门。
```
pip install ast-guard[multilang]
```
| 语言 | 后端 | 检测 |
|----------|---------|---------|
| Python | 本地 `ast` | 所有 6 项检查 |
| Bash | tree-sitter-bash | 危险调用（curl，wget，eval，rm，chmod），PATH 操作，LD_PRELOAD |
| JavaScript | tree-sitter-javascript | eval，Function()，require('child_process')，execSync |
Bash 和 JS 适配器是预览质量：比 Python 核心更窄的模式覆盖范围。
## 集成
### MCP 服务器
ast-guard 包含内置的 [模型上下文协议](https://modelcontextprotocol.io/) 服务器。
```
pip install ast-guard[mcp]
```
```
{
"mcpServers": {
"ast-guard": {
"command": "ast-guard-mcp",
"type": "stdio"
}
}
}
```
工具：`ast_guard_scan`（比较原始与生成），`ast_guard_feedback`（提交分类反馈）。
### GitHub 动作
```
- uses: ./.github/actions/ast-guard
with:
original: path/to/original.py
generated: path/to/generated.py
mode: strict
upload-sarif: "true"
```
SARIF 输出与 GitHub 安全标签兼容。
## 配置
阈值、阻止列表和允许列表可通过 TOML 配置。层次结构：CLI 参数 > `.ast-guard.toml` > `~/.ast-guard/config.toml` > 默认值。
```
[thresholds]
if_count_rel_increase = 0.50
literal_count_rel_increase = 2.0
literal_count_abs_min = 10
long_string_len = 200
complexity_rel_decrease = 0.60
complexity_abs_min = 5
enumeration_ratio = 0.70
enumeration_min_ifs = 5
[imports]
blocklist = ["os", "sys", "subprocess", "pickle", "importlib"]
allowlist = ["functools", "itertools", "collections", "math"]
[settings]
mode = "standard"
telemetry = false
```
## 设计原则
- **确定性。**相同的输入 → 相同的判断。无随机性，无网络调用。
- **核心无依赖。**仅 Python 标准库。
- **实时。**每扫描 <10ms，不会降低执行循环。
- **设计互补。**结构分析是一层；语义审查是另一层。
- **隐私设计。**遥测仅存储匿名化的 AST 指标——永不存储代码、文件名、路径或时间戳。始终选择加入。
- **三种模式**（`audit` → `standard` → `strict`）在承诺之前允许风险无评估。
## 已知限制
- **独立模式的精度低于配对模式** 是有意为之。没有基线，上下文区分更难。MALT 在 `normal` 样本上的假阳性率是当前的校准点——有意保持保守。
- **语义黑客不在范围内。**结构上正常但逻辑上错误的代码，或在没有结构痕迹的情况下玩弄任务规范，需要语义理解。这是基于LLM的审查员和下游测试套件的工作。
- **Bash 和 JavaScript 适配器不如 Python 核心成熟。**模式覆盖范围更窄；假阳性校准不够精细。
- **阈值是经验校准的。**默认值是信息化的起点，而不是最终优化点。有关完整的迭代历史，请参阅[METHODOLOGY.md](benchmarks/METHODOLOGY.md)。
## 评估
- [benchmarks/RESULTS.md](benchmarks/RESULTS.md) — 所有数据集的精确度、召回率、F1、混淆矩阵。
- [benchmarks/METHODOLOGY.md](benchmarks/METHODOLOGY.md) — 6 次迭代的校准历史，包括回归。
- [benchmarks/structural_benchmark/](benchmarks/structural_benchmark/) — 12 个结构黑客类别中的 36 个经过策划的地面实况配对。
重放：
```
python -m benchmarks.run_benchmark --benchmark structural
python -m benchmarks.run_benchmark --benchmark all
# MALT 需要数据集在 ~/.ast-guard/benchmarks/malt-public/
python -m benchmarks.run_benchmark --benchmark malt --mode strict
```
## 相关工作
- **TRACE**（Deshpande 等人，2026，[arXiv:2601.20103](https://arxiv.org/abs/2601.20103)) — 54 类别的奖励黑客分类法。ast-guard 覆盖 15 个结构类别，F1 为 95.7%；其余的是语义。
- **MALT**（METR 2025）— 10,919 个手动审查的代理转录，81,515 个提取的代码块。该领域最大的标记数据集。
- **Helff 等人** ([arXiv:2604.15149](https://arxiv.org/abs/2604.15149)) — RLVR 训练模型中的扩展性枚举快捷方式。直接激发第 5 项检查。
- **RewardHackWatch** — 结合 ML + regex + AST 的运行时检测器。ast-guard 是其确定性的结构补充。
- **EvilGenie** — 推理时 LLM 审查员；ast-guard 的基准加载器之一。
- **ZeroFalse** ([arXiv:2510.02534](https://arxiv.org/abs/2510.02534)) — 静态分析发现的校准置信水平。激发 ast-guard 的置信度评分模块（`ast_guard/confidence.py`）。
## 引用
```
@software{ast_guard_2026,
title = {ast-guard: Pre-Execution Gate for AI-Generated Code},
author = {Nick},
year = {2026},
url = {https://github.com/Nick-is-building/ast-guard},
version = {2.0.0}
}
```
*ast-guard 正在积极开发。有关版本历史，请参阅 [CHANGELOG.md](CHANGELOG.md)，有关贡献指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。*
标签：AI代码生成, AST解析, DNS解析, LLM代码审查, Python, TLS抓取, 云安全监控, 代码安全, 代码结构检查, 安全扫描, 开源项目, 数据管道, 无后门, 时序注入, 漏洞枚举, 自动化payload嵌入, 软件安全, 软件工程, 逆向工具, 静态分析