Seinarukiro2/wraith

# wraith [](https://pypi.org/project/wraith/) [](https://github.com/Seinarukiro2/wraith/actions) [](LICENSE) 一款极速 AI 代码 Linter，使用 Rust 编写。 *捕捉你的 AI 忘记检查的内容* —— 幻觉 API、幽灵包、硬编码机密、AI 痕迹和供应链风险。20 条规则，零配置。

``` $ wraith check . src/api/handler.py:42:5 AG001 pandas.read_csv: unknown parameter "fast_mode" → did you mean "mode"? (auto-fixable) src/api/handler.py:78:1 PH001 import "ai-utils-secure": package not found on PyPI → possible slopsquatting target src/utils/auth.py:15:0 VC001 hardcoded secret: API_KEY = "sk-proj-..." → known secret prefix; use os.environ["API_KEY"] instead (auto-fixable) src/utils/auth.py:89:4 VC011 potential secret leak: 'api_key' passed to print() → avoid logging or printing secret variable 'api_key' Found 4 issues (2 auto-fixable). Run with --fix to apply. Checked 128 files in 0.34s ``` ## 为什么选择 wraith？ AI 代码生成器会产生幻觉 API、捏造包，并在代码中留下机密信息。传统的 Linter 无法捕捉到任何这些问题。

## 安装 ``` pip install wraith ``` ## 快速开始 ``` wraith check . # scan current directory wraith check . --fix --diff # preview fixes as unified diff wraith check . --fix # apply fixes wraith rules # list all 20 rules ``` ## 功能特性 - **幻觉 API 检测** —— 通过 Python 内省捕捉不存在的函数、kwargs 和已弃用的调用 - **幽灵包检测** —— 根据 PyPI 验证导入，捕捉抢注 和滥注 行为 - **机密检测** —— 多层分析：已知前缀 (sk-, ghp_, AKIA)、香农熵、双字符名称分类、字符类过滤 - **污点分析** —— 跟踪从 `os.environ` 到 `print()`/`logging` 接收器的数据流 - **供应链检查** —— 未锁定的依赖、缺失的 lockfile、危险文件 - **AI 痕迹清理** —— 移除 `# Generated by Claude` 注释、调试代码、pdb 导入 - **`# noqa` 抑制** —— 行业标准的行内抑制，兼容 Ruff/flake8 - **SARIF 输出** —— `--format sarif` 用于 GitHub Code Scanning 和 VS Code 集成 - **置信度评分** —— `--min-confidence 0.8` 过滤噪音，每个发现都有置信度评分 ## 规则 ### AG — API Guard | 代码 | 名称 | 修复 | 描述 | |------|------|-----|-------------| | AG001 | non-existent-attribute | 是 | `os.path.joinn()` → 你是指 `join` 吗？ | | AG002 | non-existent-kwarg | 是 | `makedirs(exst_ok=True)` → `exist_ok` | | AG003 | deprecated-api | — | PEP 702 + 源码分析，零误报 | | AG004 | bare-call | 是 | `read_csv()` → `pd.read_csv()` | | AG005 | missing-import | 是 | `np.array()` 但没有 `import numpy` | | AG006 | contextual-mismatch | 是 | `pd.read_excel("data.csv")` → 扩展名错误 | ### PH — Phantom | 代码 | 名称 | 描述 | |------|------|-------------| | PH001 | package-not-found | 包在 PyPI 上不存在 (滥注风险) | | PH002 | package-not-installed | 包存在但不在当前环境中 | | PH003 | suspicious-package | 抢注名称、新包、下载量低 | ### VC — Vibe Check | 代码 | 名称 | 修复 | 描述 | |------|------|-----|-------------| | VC001 | hardcoded-secret | 是 | 熵 + 前缀 + 双字符分析 | | VC002 | ai-artifact-comment | 是 | `# Generated by Claude`、`# Copilot` | | VC003 | debug-code | 是 | print/breakpoint *(严格模式，默认关闭)* | | VC004 | pdb-import | 是 | `import pdb` / `import ipdb` | | VC005 | source-map-exposure | — | `sourceMappingURL` 引用 | | VC006 | suspicious-endpoint | — | 无认证的 `/debug/`、`/admin/` | | VC007 | dangerous-file | — | 项目中的 `.env`、`.pem`、凭证 | | VC008 | unpinned-dependency | — | requirements.txt 中无版本锁定 | | VC009 | missing-lockfile | — | 缺少 poetry.lock / uv.lock | | VC010 | source-map-full-source | — | 包含 `sourcesContent` 的 `.map` | | VC011 | secret-leak | — | 机密变量 → print/logging 接收器 | ## 配置 ``` # 选择特定规则 wraith check . --select AG,VC001 # 跳过 PyPI 检查 (离线) wraith check . --offline # 包含测试文件 (默认排除) wraith check . --include-tests # 启用 pedantic 规则 (VC003 print 检测) wraith check . --pedantic # 仅限高置信度发现 wraith check . --min-confidence 0.8 # CI/CD 集成 wraith check . --strict --format sarif > wraith.sarif ``` ## 行内抑制 ``` print("debug") # noqa: VC003 API_KEY = "sk-secret" # noqa: VC001 import pdb # noqa ``` ## Python API ``` import wraith results = wraith.check_source('API_KEY = "sk-secret"') fixed = wraith.fix('import pdb\nbreakpoint()') ``` ## 工作原理 | 组件 | 内容 | 方式 | |-----------|------|-----| | **解析器** | AST 提取 | tree-sitter-python，非正则表达式 | | **符号表** | 名称解析 | PEP 227 LEGB，作用域感知 | | **内省** | API 验证 | Python 子进程，`inspect.signature()` | | **机密检测** | 4 层 | 前缀 → 熵 → 双字符 → 字符类 | | **污点分析** | 源 → 接收器 | 过程内，基于名称 | | **包检查** | PyPI 验证 | HTTP + SQLite 缓存 (24h TTL) | ## 研究 基于同行评审的研究： - [AST Hallucination Guard](https://arxiv.org/abs/2601.19106) (FORGE '26) — 通过库内省进行 API 验证 - [Package Hallucinations in LLMs](https://arxiv.org/abs/2501.19012) — 20% 的 AI 生成导入是幽灵包 - [Slopsquatting](https://arxiv.org/abs/2509.20277) — 通过幻觉包名进行的供应链攻击 - [VibeGuard](https://arxiv.org/abs/2604.01052) — AI 代码痕迹清理（源于 Claude Code 源码映射泄露事件） - [Secrets in Source Code](https://scholar.google.com/scholar?q=Saha+2020+secrets+source+code) (Saha et al. 2020) — 用于机密检测的字符类分布 - [Argus](https://arxiv.org/abs/2512.08326) — 用于机密检测的分层引用分析 ## 贡献 发现误报？缺少规则？[提交 issue](https://github.com/Seinarukiro2/wraith/issues) —— 附带代码样本的错误报告是改进 wraith 的最快方式。 ## 许可证 MIT

标签：AI 代码安全, API 验证, AST 分析, Python Linter, Rust, SAST, Slopsquatting, StruQ, 可视化界面, 大语言模型安全, 威胁情报, 对抗攻击, 幻影包检测, 开发者工具, 敏感信息检测, 文档安全, 机密管理, 模块化设计, 盲注攻击, 硬编码密钥, 网络流量审计, 自动化修复, 逆向工具, 通知系统, 错误基检测, 零配置, 静态代码分析