iamved/stoa-agent-risk

# Stoa **[stoa-agent-risk.dev](https://stoa-agent-risk.dev)** · [案例研究](https://stoa-agent-risk.dev/case-study) · [在线演示报告](https://stoa-agent-risk.dev/demo-report) · [PyPI](https://pypi.org/project/stoa-agent-risk/) **一款本地优先的 AI agent 清单和风险扫描器**，能够识别 agent 候选对象并提供支持证据，映射其能力和集成情况， 并防止新引入的高置信度严重风险进入 代码库。 Stoa 对 Python、JavaScript 和 TypeScript 代码库进行静态扫描 —— 无需 运行时 hooks，无需上传，无需账号。 ## Stoa 的功能 - **发现潜在的 AI agent**（LangChain、LangGraph、CrewAI、AutoGen、 LlamaIndex、OpenAI Agents SDK、PydanticAI、Bedrock Agents、Semantic Kernel、 LiteLLM 以及原始 provider 调用），使用加权证据，并准确展示 检测到每个候选对象的*原因*。 - **映射 provider、框架、集成和功能** —— 例如，一个 具有支付访问权限、数据库读取权限和 Slack 消息传递功能的 agent 候选对象。 - **检测高置信度风险**：硬编码的凭证、硬编码的 密码、插值 SQL、被吞没的异常、不安全的 HTTP、缺失的 请求超时以及控制审查 prompt。 - **生成本地报告**：适合管理者查看的独立 HTML 报告 和确定性的、带版本的 JSON 注册表。 - **默认仅拦截新引入的关键发现** —— 现有的 技术债绝不会阻碍无关的 pull request。 Stoa 报告的是*候选对象*和*证据*，而非确定性结果。“未观察到控制” prompt 仅作为审查提示，并非已证实的漏洞。 ## 快速开始 ``` pipx install stoa-agent-risk cd my-repository stoa scan . open stoa-report.html ``` `stoa scan .` 会写入 `stoa-report.html` 和 `stoa-registry.json`，并且除非配置了拦截机制，否则将以退出代码 0 退出 （仅报告模式）。该 JSON 也设计为可供 编程助手读取： ``` stoa scan . --json stoa-registry.json ``` ## GitHub Actions ``` stoa init github ``` 这将创建（不会覆盖现有文件 —— 使用 `--force` 进行 覆盖）： - `.github/workflows/stoa.yml` —— 完整历史 checkout、固定版本的 Stoa 安装、 全代码库扫描、与 PR 基础分支的 diff、GitHub annotations、 job 摘要、上传的 HTML/JSON artifacts，以及一个**仅** 在 PR 引入新的高置信度严重发现时才会失败的拦截机制。 - `.stoaignore` —— gitignore 风格的路径排除。 - `stoa.toml` —— 带有文档化默认值的配置。 ## CLI ``` stoa scan [PATH] --html PATH HTML report (default stoa-report.html) --json PATH JSON registry (default stoa-registry.json) --base GIT_REF enable diff-aware behavior (e.g. origin/main) --strict fail on all unsuppressed high-confidence criticals --fail-on {none,high,critical} --fail-on-new {none,high,critical} applies with --base --github-annotations emit ::error/::warning workflow commands --summary-file PATH write a GitHub job-summary Markdown file --config PATH explicit stoa.toml --no-git skip git metadata --include / --exclude extra path patterns (repeatable) --verbose / --quiet ``` 退出代码：`0` 拦截通过 · `1` 拦截失败 · `2` 参数或 配置无效 · `3` 扫描器执行错误。 只有符合拦截条件规则（SEC001、SEC002）的高置信度发现才会导致 扫描失败；SQL 插值、网络和审查 prompt 规则仅报告而 不进行拦截，因为静态正则表达式分析无法证明其可利用性。 ## 屏蔽 内联屏蔽，在同一行或上一行，始终带有明确的规则 ID： ``` # stoa: ignore[SEC003] 来自内部 enum 的受信任 identifier query = f"SELECT * FROM {table_name}" ``` ``` const endpoint = "http://staging.internal.corp"; // stoa: ignore[NET001] ``` 文件级屏蔽： ``` # stoa: ignore-file[CTRL001,CTRL002] ``` 被屏蔽的发现会被计算并显示在报告中 —— 绝不会 被静默丢弃。不存在全局的 `ignore-all`。 ## 配置 代码库根目录下的 `stoa.toml`（显示的所有值均为默认值）： ``` fail_on = "none" # gate on all findings at/above this severity fail_on_new = "critical" # gate on newly introduced findings (with --base) max_file_bytes = 1000000 follow_symlinks = false respect_gitignore = true ignore_paths = [ # merged with built-in defaults (node_modules, dist, …) "tests/snapshots/**", ] [severity] # per-rule severity overrides NET001 = "info" [rules] # per-rule enable/disable CTRL003 = false ``` `.stoaignore` 使用 gitignore 语法进行路径排除。测试和 fixtures *不会*被默认忽略 —— 在这些地方进行密钥扫描仍然很有用 —— 但它们在 agent 检测中的权重会被降低，并且适用 占位符密钥启发式规则。 ## 规则 | 规则 | 标题 | 默认严重程度 | 是否拦截？ | |---|---|---|---| | SEC001 | 可能的硬编码 API 凭证 | critical | 是（仅限高置信度） | | SEC002 | 可能的硬编码密码 | high（高置信度时为 critical） | 是（仅限高置信度） | | SEC003 | 插值 SQL 语句 | high | 否 | | REL001 | 被吞没的异常 | medium | 否 | | NET001 | 不安全的非本地 HTTP endpoint | medium | 否 | | NET002 | 未观察到请求超时 | medium | 否 | | CTRL001–003 | 未观察到 Auth / 验证 / 速率限制控制 | info | 从不 | ## 安全模型 - **本地优先。** 任何源代码都不会被上传；Stoa 不会进行网络 调用，也不收集任何遥测数据。 - **密钥在序列化前会被屏蔽。** 检测到的凭证在 匹配到的瞬间就会被替换为 `prefix…[REDACTED:sha256-fingerprint]`；原始 值永远不会出现在终端输出、JSON、HTML、 annotations、摘要或日志中。 - 静态分析存在**误报和漏报**。发现结果是用于 审查的证据，而非最终结论。 ## Schema 稳定性 JSON 输出已版本化且以添加为主 —— 请参阅 [SCHEMA.md](SCHEMA.md)。 使用者必须忽略未知字段。字段名 `autonomy_level`、 `loss_scenarios`、`liveness_state`、`policy_lines` 和 `exposure_class` 是 为未来版本保留的。请将 `stoa-registry.json` 视为 CI artifact； 不建议将其提交到代码库中。 ## 局限性 - 基于正则表达式和模式；没有 AST 或语义分析。 - 没有运行时行为：能力证据无法证明某个代码路径 会被执行，且调用点并非 API 调用计数。 - 没有跨代码库或组织级的基础设施可见性：“在此文件中未观察到”的 控制可能存在于其他地方。 - 没有明确的归属权推断 —— “最后修改者”只是提交历史， 而不是归属权；CODEOWNERS 支持涵盖了 GitHub 模式语法中常见的 gitignore 风格子集 （区分顺序，最后匹配优先；不支持括号 字符类和按文件分区语法）。 - 仅支持 Python、JavaScript 和 TypeScript。 - 仅参考代码库根目录下的 `.gitignore` 和 `.stoaignore`。 ## CI 绕过注意事项 - 该工作流从 PyPI 安装**固定版本**的 Stoa 发布版，而不是 从 pull request 执行扫描器代码，因此 PR 无法修改 扫描器来绕过强制执行。 - 使用 CODEOWNERS 和分支保护来保护 `.github/workflows/stoa.yml`、`stoa.toml` 和 `.stoaignore` —— 修改这些文件的 PR 可能会削弱 拦截机制，因此这些修改需要经过审查。 - 内联屏蔽（`# stoa: ignore[...]`）会改变拦截机制看到的内容； 请像审查任何其他与安全相关的更改一样审查它们。 ## 开发 ``` python -m venv .venv && .venv/bin/pip install -e ".[dev]" .venv/bin/pytest ``` ## 许可证 MIT —— 请参阅 [LICENSE](LICENSE)。

标签：云安全监控, 后端开发, 数据可视化, 逆向工具, 静态分析, 风险扫描