balyakin/refraction
GitHub: balyakin/refraction
refraction 是一个确定性离线扫描器，用于在 AI 代码审查之前检测源码仓库和软件包中的 prompt injection、混淆 payload、Trojan Source 等可能干扰自动审查的供应链攻击模式。
Stars: 0 | Forks: 0
# 折射
`refraction` 是一个确定性的离线扫描器，用于扫描源代码仓库和软件包构件。它用于查找那些
在内容到达 LLM、代码审查机器人或安全分类队列之前，可能会破坏 AI 辅助审查的内容。
它在运行时极其单调且保守：没有网络调用，没有软件包安装，没有模型推理，也不会执行被
扫描的文件。
## 为什么开发此工具
AI 审查现已成为许多供应链和应用程序安全工作流的一部分。这带来了一个虽然狭窄但真实存在的故障
模式：软件包中可能包含试图让自动审查器拒绝任务、忽略可疑文件或
报告干净结果的文本。
`refraction` 是解决此问题的一个低成本预过滤器。在执行成本高昂或受策略限制的分析之前运行它，若出现
新发现则使构建失败，并将生成的证据发送给人工审查员。
它不试图证明意图。一个发现只意味着：“此构件包含一种曾导致审查系统
跳过、误读或隐藏风险的模式。”
## 它能捕获什么
`refraction` 内置了针对以下内容的规则：
- 源代码或包文本中已知的 LLM 拒绝诱饵
- 针对自动审查器和扫描器 prompt 的 prompt injection
- 放置在非功能区域以触发安全拒绝机制的 CBRN/WMD 诱饵
- 可解码为可疑文本的 base64、hex、URL、HTML 实体和 Unicode 转义 payload
- 在常见生态系统中用于下载、执行或隐藏行为的 install 和 build hook
- Trojan Source、BiDi 控制字符、零宽字符簇、混合脚本标识符以及易混淆的文件名
- 清单诡计，例如可能欺骗简单解析器的重复包键
报告会在可能的情况下掩码敏感的 prompt/拒绝 payload 和解码内容，同时保留足够的文件、行号、规则
和指纹数据以供分类。
## 安装
```
go install github.com/balyakin/refraction/cmd/refraction@latest
```
或者构建一个本地静态二进制文件：
```
CGO_ENABLED=0 go build -o refraction ./cmd/refraction
```
环境要求：
- Go 1.22 或更新版本
- Linux、macOS 或 Windows
## 快速开始
扫描当前代码仓库：
```
refraction .
```
使用更严格的 CI 风格阈值：
```
refraction --min-severity warning --min-confidence medium .
```
输出 JSON 报告：
```
refraction --format json --pretty --output-file refraction.json .
```
在决定修复还是抑制规则之前，先查看规则解释：
```
refraction --explain PRM001
```
列出处于激活状态的规则集：
```
refraction --list-rules
```
## CLI
```
refraction [flags] [path...]
```
常用标志：
| 标志 | 用途 |
| --- | --- |
| `--format text` | 人类可读的终端输出。 |
| `--format json --pretty` | 用于存储或审查工具的结构化报告。 |
| `--format ndjson` | 每行一个 JSON 对象，便于流式摄取。 |
| `--format sarif` | 用于代码扫描系统的 SARIF 输出。 |
| `--format github` | GitHub Actions 工作流注解。 |
| `--format markdown --summary` | 用于评论或构件的简短 Markdown 报告。 |
| `--min-severity warning` | 仅在出现 `warning` 或更高等级的新未抑制发现时报错退出。 |
| `--min-confidence medium` | 仅在出现 `medium` 或更高置信度的新未抑制发现时报错退出。 |
| `--baseline .refraction-baseline.json` | 防止旧有的发现导致构建失败。 |
| `--update-baseline .refraction-baseline.json` | 生成或刷新基线。 |
| `--config refraction.json` | 加载抑制规则、忽略路径和严重性覆盖配置。 |
| `--ignore-path 'fixtures/generated/**'` | 从命令行添加一个忽略 glob 匹配模式。 |
| `--timeout 30s` | 限制整个扫描过程的总时间。 |
## 配置
配置采用 JSON 格式。抑制规则必须提供原因；这是刻意为之的。未来的审查员应当能够
分辨出一个发现是已接受的风险、测试夹具，还是生成内容带来的噪音。
```
{
"suppress": [
{
"rule_id": "OBF001",
"path_glob": "testdata/**",
"reason": "intentional fixture for decoder tests"
}
],
"ignore_paths": ["fixtures/generated/**"],
"severity_overrides": {
"OBF001": "warning"
}
}
```
同时也支持内联抑制：
```
refraction:ignore PRM001 documented training fixture
```
JSON schema 位于 [`schemas/refraction-config.schema.json`](schemas/refraction-config.schema.json)。
## 基线
对于现有的代码仓库，请从记录当前状态开始：
```
refraction --update-baseline .refraction-baseline.json .
```
然后仅针对新发现强制执行失败策略：
```
refraction --baseline .refraction-baseline.json --min-severity warning --min-confidence medium .
```
基线用于那些仍需要迁移路径的旧有发现。对于有意设置的夹具、
生成的文件或已记录的误报，使用抑制规则是更好的选择。
## CI
GitHub Actions：
```
name: refraction
on: [pull_request, push]
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.22'
- run: go run ./cmd/refraction --format github --min-severity warning --min-confidence medium .
```
GitLab CI（将 SARIF 作为构件）：
```
refraction:
image: golang:1.22
script:
- go run ./cmd/refraction --format sarif --output-file refraction.sarif .
artifacts:
when: always
paths: [refraction.sarif]
```
pre-commit：
```
repos:
- repo: local
hooks:
- id: refraction
name: refraction
entry: refraction --min-severity warning --min-confidence medium
language: system
pass_filenames: false
```
## 退出代码
| 代码 | 含义 |
| ---: | --- |
| `0` | 扫描成功，且没有新的未抑制发现达到配置的阈值。 |
| `1` | 新的未抑制发现达到了配置的阈值。 |
| `2` | 使用错误、配置无效、缺少路径或未知的格式。 |
| `3` | 内部扫描器、报告、超时或写入失败。 |
| `4` | 扫描成功，但没有符合扫描条件的文件。 |
## 库 API
CLI 是主要接口，但 Go 程序也可以直接调用扫描器：
```
package main
import (
"fmt"
"log"
"github.com/balyakin/refraction/pkg/refraction"
)
func main() {
opts := refraction.DefaultOptions()
opts.MinSeverity = "warning"
opts.MinConfidence = "medium"
result, err := refraction.Scan([]string{"."}, opts)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%d findings in %d scanned files\n", len(result.Findings), result.FilesScanned)
}
```
## 设计边界
`refraction` 不是恶意软件分类器、SAST 引擎或防病毒产品。它在 v1 版本中不会获取依赖项、解压
归档文件、执行代码，也不会通过询问模型来判断某物是否危险。
这种克制正是其核心所在。该扫描器应当能够安全地在带有恶意的仓库上运行，并且具有足够的可预测性，以便放入 CI 中，
而无需担心它在后台执行了什么操作。
更多背景信息：
- [`docs/THREAT_MODEL.md`](docs/THREAT_MODEL.md)
- [`docs/ADVERSARY.md`](docs/ADVERSARY.md)
- [`docs/INTEGRATION_GUIDE.md`](docs/INTEGRATION_GUIDE.md)
- [`docs/ROADMAP.md`](docs/ROADMAP.md)
## 开发
运行测试套件：
```
go test ./...
```
构建 CLI：
```
CGO_ENABLED=0 go build -o refraction ./cmd/refraction
```
检查内嵌的扫描器和签名版本：
```
refraction --version
```
该命令会同时打印这两个版本，例如：
```
refraction 0.1.0 signatures 2026.06.15.1
```
## 许可证
Apache-2.0。详见 [`LICENSE`](LICENSE)。
标签：DNS 反向解析, EVTX分析, Go, Homebrew安装, LNA, Ruby工具, 代码审查, 提示词注入检测, 文档结构分析, 日志审计, 聊天机器人, 静态扫描