SeamStressDev/seamstress

# SeamStress **SeamStress 旨在发现那些导致客户被重复扣款的 bug。** 不是崩溃。而是那种隐蔽的 bug。比如重试时触发了两次的支付，四十条路由中唯一一条缺失了 auth 检查的路由，或者是将一个租户的数据提供给了另一个租户的 cache key。孤立地看，每一部分似乎都是正确的。但组合在一起却并非如此。这些就是 seam bug，它们隐藏在资金、授权和租户隔离跨越边界的地方。Linters 和扫描器在设计上就无法发现它们。SeamStress 随附了一个[公开基准测试](benchmark/README.md)，对其进行了诚实的评分。这些是从有记录的真实事件中还原的真实 bug，并且旁边记录了未命中的情况。 Linter 只能匹配模式。SeamStress 则会阅读你代码库中高风险的边界——一个 Stripe webhook、一个结账操作、一个上传配额、一个按用户划分的数据查询——并提出一位细心的审查者会问的问题：*这个防护真的生效了吗？一个用户能访问到另一个用户的数据吗？这会静默失败吗？配额是实质性的还是摆设？* 然后它会根据你的真实代码检查每一个答案，并且只报告它能够证明的内容，并引用具体的代码行。 它仍处于早期阶段，需要自带 API key，并且只在少量代码库上进行了验证。本 README 会确切地告诉你它能做什么和不能做什么。 SeamStress 针对的那类 bug——即在资金、auth 和多租户 seam 处发生的业务逻辑故障——在有记录的真实公开事件中有所记载，详见 [Seam-Bug 目录](https://github.com/SeamStressDev/seam-bug-catalog)。 这项纪律本身可以免费安装：[SeamStress Scaffold](https://github.com/SeamStressDev/seam-scaffold) 封装了五种行为协议，使编码代理能够优先进行调查，对不可逆操作设置门控，并证明其主张。 ## 快速开始 **前置条件：** Node 22+ 和一个 [Anthropic API key](https://console.anthropic.com/)。 ``` git clone https://github.com/SeamStressDev/seamstress cd seamstress npm install # 提供你的 key — 可以是一个 .env 文件： cp .env.example .env # then edit .env and set ANTHROPIC_API_KEY # ...或者直接 export 它： export ANTHROPIC_API_KEY=sk-ant-... # 在任意本地 repo 上运行它： npm run map -- /path/to/your/repo ``` 这会将 Markdown 风险报告打印到标准输出。要将其写入文件，或者获取 HTML 报告： ``` npm run map -- /path/to/your/repo --out report.md # Markdown → file npm run map -- /path/to/your/repo --html report.html # standalone HTML report npm run map -- /path/to/your/repo --max 40 # cap how many candidates are reviewed ``` 不需要构建步骤——运行脚本会直接执行 TypeScript。 **成本：** 使用的是你自己的 key。SeamStress 会发起真实的 Anthropic API 调用——每个 seam 发起几次——因此每次运行都会消耗你账户的真实用量。`--max` 标志可以限制其审查的代码量。 报告中的发现大致如下所示： 有关示例报告以及 SeamStress 审查其自身报告生成器的案例研究（包括它在自身代码中发现的一个 bug 以及随后的修复），请参阅 [`examples/`](./examples/)。 ## 工作原理 分为两个阶段，均由 LLM 驱动并辅以程序化防护机制： 1. **检测** — 一种轻量级的启发式预过滤器将代码库缩小到候选的高风险文件，然后由 LLM 确认或拒绝每一个文件是否为真正的 *seam*，并进行分类（auth、资金路径、PII、数据删除、关键交付）。 2. **审查** — 每个 seam 由多个**盲审、去相关的评审者**（他们看不到彼此的发现）进行审查，接着是一个**综合 (synthesis)** 步骤来整合并按影响范围排序，最后是一个**验证 (verification)** 步骤，根据实际源码检查每一个发现。 其核心原则是验证门控：**只有当发现通过引用的代码行在你的真实代码中得到确认时，才会显示为“已验证”。** 工具无法在源码中找到依据的主张不会被作为事实呈现——它会被丢弃或被标记为需要主观判断，绝对不会在没有任何支撑的情况下被渲染成一个充满信心的“已验证”状态。 ## 能做与不能做的事 SeamStress 的范围是刻意受限的。它寻找的是**业务逻辑和 "seam" bug**——即涉及资金、授权和多租户数据跨越边界的地方，其中每个单独的部分都是正确的，但组合起来却很危险。它的构建初衷是运用判断力去推理这些 seam，而不是用噪音淹没你。 **能够做到的：** - 检测并审查代码库中的高风险 seam——auth/授权、资金路径、PII 处理、数据删除、关键交付。 - 根据真实代码验证每一个浮现的问题，并引用出错的代码行；按严重程度排序。 - 输出一份通俗易懂的 Markdown 或自包含的 HTML 报告，供开发者（或非安全领域的创始人）采取行动。 诚实地面对局限性也是该工具的一部分： - **它推理的是代码，而非意图。** 一项发现可能在*代码层面是准确的*，但描述的却是你刻意决定的事情。SeamStress 无法看到存在于代码之外的设计决策——问题追踪器、架构记录、有文档记录的权衡。请将发现视为**代码引发的问题**，而非结论：“代码允许了 X——这是有意的吗？”最终决定权在你。 - **它不是通用的安全扫描器。** SeamStress 不能替代 SAST 工具、依赖扫描器或密钥检测工具。它关注的是那一类特定的、难以自动化的 bug，而这些工具在结构上往往会漏掉它们——同时它也会漏掉这些工具能捕捉到的东西。请将其与它们配合使用，而不是取而代之。 - 检测**针对 JavaScript/TypeScript (Next.js) 和 Python (Django) 进行了最佳调整**。在其他技术栈上它仍然可以运行，但报告中会明确指出这一点，并将自身视为风险的底线，而非完整的清单——其启发式方法可能会漏掉它无法识别信号的 seam。 - 它还处于**初期**，只在少量代码库上进行了验证。它能发现真实的 bug，但不能替代安全审计。 - **它无法查看运行时行为。** 任何仅在执行期间才会表现出来的东西——时序、实时配置、实际流量——都不在静态分析的范畴内。一个在源码中看起来没问题的 seam，在负载下仍可能失败，反之亦然。 - **验证存在上限。** 当 SeamStress 仅靠代码无法确认某项发现时（例如，依赖于外部提供商语义的行为），它会将其标记出来。未确认的发现并不是误报——它是一个诚实的“值得人工检查”的提示。 有关 SeamStress 表现的证据——包括它在哪里失效——请参阅[基准测试及其公开结果记录](benchmark/README.md)，该记录在命中的旁边也记录了未命中的情况。 ## 负责任的使用 SeamStress 会对您提供的源代码执行**静态分析**。它只读取代码；不执行代码、连接任何系统或与任何正在运行的内容进行交互。它无法访问系统、网络或任何你手头没有的代码。 话虽如此，运行分析是您的责任： - **请在你拥有所有权或获得授权审查的代码上使用 SeamStress。** 你有责任确保自己有权对你运行它的任何代码进行分析——这就像你在编辑器中打开该代码所承担的责任一样。 - **SeamStress 不会授予任何访问权限。** 它只分析你已经拥有的源代码。它不是扫描器、探针或漏洞利用工具，它不会对任何实时系统进行任何操作。 - **对发现的处理由你负责。** 如果你分析的代码不属于你——例如，一个公开的开源项目——请将任何真实的发现视为安全披露，而不是公开发布。请参阅 [SECURITY.md 中的“报告不属于你的代码中的发现”](SECURITY.md#reporting-findings-in-code-you-dont-own)。 SeamStress 是一个用于构建更安全软件的工具，正是出于这种精神免费提供。使用它来帮助他人——或你自己——编写更值得信赖的代码，正是其初衷所在。 ## 发布前的 seam 审查 如果你正在推出一款涉及资金、auth 或多租户数据的 AI 辅助产品，我提供一项范围固定的发布前 seam 审查——即本代码库中的方法论，加上它无法自动化的判断力。我自己也在使用 AI 辅助进行开发；SeamStress 的诞生，正是因为我想要一种能跟上这种速度的审查准则。 交付的成果是您的代码在最危险边界处引发的问题：即按实际编写情况来看，资金、auth 和租户 seam 实际上允许了什么——每一项观察结果都会根据您的源代码进行验证并引用相应代码行，以便由你来决定这是缺陷还是有意为之。这是一次专注的 seam 审查，而不是全面的安全审计，也不会承诺一个具体的 bug 数量。 该服务为固定范围——如需展开沟通，请发送邮件至 hello@seamstress.dev。 ## License Copyright (C) 2026 SeamStress contributors. Licensed under the GNU Affero General Public License v3.0 — see [LICENSE](LICENSE).

标签：AI编程助手, GNU通用公共许可证, MITM代理, Node.js, 业务逻辑, 云安全监控, 代码审查, 自动化攻击, 静态分析