nchantarotwong/heatcheck-action
GitHub: nchantarotwong/heatcheck-action
专为 Python 项目设计的 GitHub Action 静态污点分析工具，自动检测 LLM 生成代码中常见的注入类安全漏洞，零配置即可集成到 CI/CD 流水线中。
Stars: 0 | Forks: 0
# heatcheck-action
[](https://github.com/nchantarotwong/heatcheck-action/actions/workflows/test.yml)
[](https://github.com/nchantarotwong/heatcheck-action/releases)
[](LICENSE)
heatcheck 遍历 Python 项目的 AST，通过赋值、返回和元组解包追踪来源，并报告攻击者控制的输入到达需要净化值（sanitized value）的危险函数（sink）的情况。它基于 LLM 实际的失败模式构建——而非通用的 Python lint。
## 快速开始
```
name: heatcheck
on: [push, pull_request]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: nchantarotwong/heatcheck-action@v1
```
就是这样。无需配置文件，无需选择规则，无需在代码中添加注解。heatcheck 会根据其识别的导入和调用位置——Flask、FastAPI、Django、SQLAlchemy、requests、MCP server 装饰器等——推断出源标签（`@user_input`、`@network_input`、`@untrusted_storage` 等）。
违规情况将显示为：
- PR Files 选项卡上的**内联注解**，每次违规对应一个。
- 运行底部的**工作流摘要**，按 sink 代码分组。
- 默认情况下的**作业失败** (rc=1)——设置 `fail-on-violations: false` 可将 heatcheck 设为建议模式。
## 输入
| 输入 | 默认值 | 描述 |
|-------|---------|-------------|
| `paths` | `.` | 以空格分隔的要扫描路径。heatcheck 会自动跳过点目录（`.git`、`.venv`、`__pycache__` 等）。路径不能包含空格。 |
| `fail-on-violations` | `true` | 设为 `false` 可将操作设为建议模式（始终 rc=0）。 |
| `heatcheck-version` | (action ref) | 要下载二进制文件的 Release 标签。默认为 action 自身的 ref——`uses: ...@v1.0.0` 会下载 `v1.0.0` 的二进制文件。仅在需要独立于包装器（wrapper）固定二进制文件版本时才进行覆盖。 |
| `python-version` | `3.11` | PATH 上的 Python 版本（heatcheck 会调用 CPython 的 `ast` 模块）。 |
| `upload-report` | `false` | 将 `.heatcheck/report.html` 作为工作流产物（artifact）上传以供浏览。 |
| `timeout-seconds` | `600` | heatcheck 二进制文件的单次运行超时时间。 |
## 输出
| 输出 | 描述 |
|--------|-------------|
| `violations` | 所有扫描文件中的违规数量。发生内部故障时为 `-1`（未生成 JSON）。 |
| `json-path` | Runner 文件系统上原始 JSON 报告的路径。可在需要以编程方式解析违规的下游步骤中使用。 |
## heatcheck 能捕获什么
| 代码 | Sink | 示例 |
|------|------|---------|
| HC-001 | 路径遍历 | `open(f"/cfg/{user_name}.cfg")` |
| HC-002 | 命令注入 | `subprocess.run(cmd, shell=True)` |
| HC-003 | 代码注入（eval / exec） | `eval(user_expr)` |
| HC-004 | 不安全的反序列化 | `pickle.loads(payload)`，`yaml.load(s)` |
| HC-005 | SQL 注入 | `cursor.execute(f"... {user_id}")` |
| HC-006 | SSRF | `requests.get(user_url)` 且未设置 allowlist |
| HC-007 | 模板注入 | `Template(user_html).render()` |
| HC-008 | NoSQL 注入 | `db.users.find({"$where": user_q})` |
| HC-009 | XPath 注入 | `tree.xpath(f"//user[name='{name}']")` |
| HC-010 | LDAP 注入 | `conn.search_s(base, scope, f"(uid={u})")` |
| HC-011 | XXE / billion-laughs 攻击 | `etree.fromstring(request.body)` |
| HC-012 | TLS 验证被禁用 | `requests.get(url, verify=False)` |
## 示例
### 最小配置——扫描所有内容，遇到违规则使构建失败
```
- uses: actions/checkout@v4
- uses: nchantarotwong/heatcheck-action@v1
```
### 扫描特定目录
```
- uses: actions/checkout@v4
- uses: nchantarotwong/heatcheck-action@v1
with:
paths: src api/handlers
```
### 建议模式——展示发现的问题而不使构建失败
适用于在现有代码库中采用 heatcheck，在清理完积压问题之前不阻塞 PR。
```
- uses: actions/checkout@v4
- uses: nchantarotwong/heatcheck-action@v1
with:
fail-on-violations: 'false'
```
### 可重现的 CI——固定到特定版本
```
- uses: actions/checkout@v4
- uses: nchantarotwong/heatcheck-action@v1.0.0 # immutable patch version
```
当需要跨多次运行获得字节级相同的扫描结果时，请固定到确切的补丁版本（例如 `@v1.0.0`），而不是浮动的主版本（`@v1`）。
### 将 HTML 报告作为 Artifact 上传
```
- uses: actions/checkout@v4
- uses: nchantarotwong/heatcheck-action@v1
with:
upload-report: 'true'
```
然后从运行的 Artifacts 面板下载；它会作为一个静态 HTML 页面打开，每次违规对应一个部分。
### 在下游步骤中读取 JSON
```
- uses: actions/checkout@v4
- id: heatcheck
uses: nchantarotwong/heatcheck-action@v1
with:
fail-on-violations: 'false'
- name: Post to Slack on violations
if: steps.heatcheck.outputs.violations != '0'
run: |
jq '.violations[] | "\(.code) \(.file):\(.line) — \(.message)"' \
"${{ steps.heatcheck.outputs.json-path }}"
```
请参阅 [examples/](examples/) 获取可以直接放入 `.github/workflows/` 的完整工作流文件。
## Runner 支持
| Runner | 支持 |
|--------|-----------|
| `ubuntu-latest` (x86_64) | ✓ |
| `ubuntu-24.04-arm` (arm64) | ✓ |
| `macos-latest` (arm64) | ✓ |
| `macos-13` (x86_64) | ✗ ——没有针对 Darwin x86_64 的预编译二进制文件。请使用 `macos-14`+。 |
| `windows-latest` | ✗ ——引导链假定使用 Unix shell。 |
## 运行方式
在缓存未命中时（该 Runner 上特定 Release 标签的首次运行），该操作会：
1. 验证输入及操作系统/架构。
2. 通过 `actions/setup-python` 设置 Python（heatcheck 会调用 CPython 的 `ast` 模块进行解析）。
3. 从 action 自身的 ref（例如 `@v1.0.0` → `v1.0.0`）解析 heatcheck-action 的 Release 标签。
4. 从 GitHub Release 下载 `heatcheck-{linux|darwin}-{x86_64|arm64}` 及其 `.sha256` 文件。
5. 验证 SHA256 校验和。
6. 在配置的路径上运行该二进制文件。
二进制文件按 `version/os/arch` 为键缓存在各个 Runner 上。冷缓存运行大约需要 10-20 秒（下载 + 运行）；缓存命中运行大约需要 5 秒。
## 权限
该操作不需要任何 `permissions:` 块——它不会发布评论或推送提交。注解通过 stdout 工作流命令发出，这些命令使用默认 token 即可工作。
如果您开启了 `upload-report`，Artifact 上传步骤会使用 `actions/upload-artifact`，这需要默认的 `actions: write` 权限（在公共仓库中默认授予）。
## 版本控制
- `v1` ——当前的稳定主版本。
- `main` ——最前沿版本，可能随时发生破坏性变更。请勿在 CI 中固定到 `main`。
当 `v2` 发布时，`v1` 将在一个过渡窗口期内继续接收错误修复。主版本号提升仅涵盖输入/输出 schema 的变更；内部变更将直接发布到 `v1`。
## 许可证
Apache 2.0。详见 [LICENSE](LICENSE)。
标签：AV绕过, CI/CD安全, CISA项目, DevSecOps, Django, DOE合作, FastAPI, Flask, GitHub Actions, Llama, SAST, SQLAlchemy, SQL注入检测, SSRF防护, XXE防御, 上游代理, 代码安全审计, 代码审查, 命令注入, 安全扫描工具, 提示注入防御, 模板注入, 源代码安全, 盲注攻击, 网络安全, 自动笔记, 路径穿越, 逆向工具, 隐私保护, 静态污点分析