tallyguard/tallyguard

# Tallyguard 一款确定性的静态分析工具，用于捕获 AI 编程工具经常遗漏在 Web 应用中的危险错误，在它们发布之前将其揪出。它在本地运行，不使用 LLM，且你的源代码永远不会离开你的机器。 Tallyguard 能发现传统代码扫描器在结构上难以应对的问题，因为这涉及到一个**缺失的**防护措施，而不是恶意的模式： - **未受保护的敏感/昂贵 endpoint**（无 rate limit），这是导致“拒绝钱包”（一个被滥用的 AI endpoint 可能会产生巨额的 OpenAI/Anthropic 账单）、暴力破解登录和外部垃圾信息的原因。 - **没有幂等键的支付扣款**（Stripe），这会在重试或重新传递 webhook 时导致重复扣款。_（检查即行动的竞态条件，规则 2b，目前仍在计划中。）_ ## 为什么存在 很大一部分新应用是使用 AI 编程工具构建的，这些工具生成的可用代码会遗漏资深工程师自动添加的防护措施。Tallyguard 通过经典的、确定性的静态分析（检测路径中没有 LLM）来解决这个问题，因此结果是可复现且低噪声的。其设计理念是**精确率优先于召回率**：一个嘈杂的检查器会被卸载，因此它只会标记那些在没有可达 rate limiter 的路径上真正触及敏感 sink 的 endpoint。（[为什么此 bug 类别很重要](docs/guide/why-rate-limiting-matters.md)。） ## 目前可检测的内容 **`rate-limit/unprotected-sensitive-endpoint`**：一个触及敏感 sink 且路径上没有可识别的 rate limiter 的服务器 endpoint。 **`money/missing-idempotency-key`**：在其选项中没有幂等键的 Stripe 扣款/结账调用（`paymentIntents`/`charges`/`refunds`/`transfers`/`checkout.sessions` `.create`），这会在重试或重新传递 webhook 时导致重复扣款。请在第二个参数中传入一个（`{ idempotencyKey }`）。 关于 rate limit 检测器的详细信息： - **入口：** Next.js App Router 路由、Next.js server actions（`"use server"`）、NextAuth / Auth.js Credentials 登录，以及 Express（文件内路由、跨文件 controller 和 router，以及挂载）。 - **Sink：** LLM 调用（OpenAI、Anthropic、Google、Mistral、Groq、Cohere、Hugging Face、Bedrock；Vercel AI SDK；LangChain；或向已知 LLM 主机发起的原始 `fetch`）、身份验证（bcrypt/argon2）、外部电子邮件和短信。 - **已理解的 Limiter**（因此不会被标记）：常见的 package、路由/handler/`app.use` limiter（包括覆盖已挂载 router 的路径作用域 `app.use('/api', rateLimit())`）、本地 limiter 包装器、自定义以 rate-limit 命名的函数，以及 `middleware.ts` 匹配器。 可达性分析支持跨文件追踪调用（包括 `@/` 别名和 CommonJS）。完整的细节和真实的召回率限制：**[Tallyguard 可检测的内容及其限制](docs/guide/detection-and-limits.md)**。 ## 快速开始 在它发布到 npm 之前，请从源码构建并运行： ``` npm install npm run build node dist/cli/index.js scan ./path/to/your-app ``` 一旦发布，这将变为 `npx tallyguard scan ./path/to/your-app`。 ### 示例 ``` error app/api/chat/route.ts:7 rate-limit/unprotected-sensitive-endpoint POST /api/chat reaches a sensitive sink (ai) with no rate limiter reachable on this route. 1 finding(s): 1 error, 0 warning, 0 suppressed ``` ### 输出与 CI - `--json` 用于结构化报告，`--sarif` 用于 SARIF 2.1.0（可上传至 GitHub 代码扫描）。退出码：`0` 代表干净，`2` 代表有发现，`1` 代表工具错误。 - [CLI 参考](docs/guide/cli-reference.md) 和 [CI 集成指南](docs/guide/ci-integration.md)。 ## 配置与抑制 可选的 `tallyguard.config.json` 可设置规则级别、边缘情况处理、未知防护策略和抑制规则；内联的 `tallyguard-disable*` 注释（默认必须提供原因）可抑制特定的发现，且被抑制的发现始终仍会被报告。请参阅[抑制与配置指南](docs/guide/suppression-and-config.md)。 ## 限制（坦诚且简要） - **框架：** 仅支持 Next.js App Router 和 Express。Hono、NestJS、tRPC、SvelteKit、Remix 以及 Next.js 的 `pages/api` router 尚未建模（它们不会产生任何发现，这是召回率上的差距，而不是误报）。 - 可达性分析有深度限制（默认为 2）；更深的调用链或动态分发可能会被漏掉（使用 `--max-depth` 加深）。 - 具有无法识别名称的自定义 guard 可能会被标记；请提供一个原因将其抑制。 - 检测器 2（金钱）尚未实现。 完整列表：[检测与限制](docs/guide/detection-and-limits.md)。 ## 文档 - **指南：** [检测与限制](docs/guide/detection-and-limits.md)， [CLI 参考](docs/guide/cli-reference.md)， [CI 集成](docs/guide/ci-integration.md)， [抑制与配置](docs/guide/suppression-and-config.md)， [为什么 rate limiting 很重要](docs/guide/why-rate-limiting-matters.md)。 - [基准测试结果/拆解](benchmark/RESULTS.md)，[规则 ID 与抑制规范](docs/specs/SUPPRESSION-AND-FALSE-POSITIVES.md)。 - [CONTRIBUTING.md](CONTRIBUTING.md) 和 [SECURITY.md](SECURITY.md)。 ## 许可证 [Apache-2.0](LICENSE)。

标签：Express, MITM代理, SOC Prime, Stripe, 代码安全审计, 安全专业人员, 开发工具, 自动化攻击, 错误基检测, 静态代码分析