bourne44/agenstral

# Agenstral 让 AI agent 在真实的代码库中自由运行是一件让人捏把汗的事，这并非因为它 带有恶意，而是因为当出现问题时，你并不总是能解释清楚到底 发生了什么。当别人问起具体是哪些代码行、什么时候以及为什么被修改时，一句*“agent 改了我们的部署脚本”*是交代不过去的。而*“相信我，日志没问题”*也绝对不是你想给合规审查人员的那类回答。 Agenstral 是一个轻量级的本地 CLI 工具，它能帮你在将代码库交给 agent 运行的前后，回答以下三个问题： - **代码库里到底有哪些真实风险？** 硬编码的机密信息、`curl | bash` 脚本、未锁定的 actions、连接到不可信触发器的 AI agent 工作流（即 GitLost 类问题）、游离的 MCP 配置。 - **这个 agent 被允许做什么？** 一份清晰易读的纯 JSON 策略，且每次都以相同的方式进行评估。 - **到底发生了什么？** 每一条记录都与上一条进行哈希链式绑定的审计日志，任何篡改都会破坏链条，从而被 `audit verify` 发现。 所有的运行都在你的本地机器上完成。没有云端，没有遥测，不需要账号，也不存在供应商锁定，日志完全归你所有。它是免费且开源的 (Apache-2.0)：一个严格的 TypeScript CLI，并且具有**零运行时依赖**。 ## 30 秒上手 本代码库附带了一个刻意包含风险的示例项目，位于 [examples/demo](examples/demo) 中。将扫描器指向它： ``` npm install npm run build node dist/cli.js scan --workspace examples/demo ``` 你会看到真实的扫描结果： ``` Agenstral Scan Workspace: .../examples/demo MCP servers: 0 Guidance files: 1 Findings: 13 - [high] AI agent workflow can be triggered by untrusted input (issue_comment -> agent) - [critical] Secret-looking value in package script (AWS key in a deploy script) - [high] Command downloads and executes remote code (curl | bash in postinstall) - [high] Command can destroy repository state (rm -rf ./ in a script) - [high] GitHub Actions workflow uses pull_request_target - [high] GitHub Actions workflow grants write-all permissions - [medium] GitHub Actions workflow uses unpinned actions - [medium] Command uses an unpinned package runner (npx ...@latest) - [medium] Agent guidance is missing safety-critical sections ... ``` 在 CI 环境中，你可以添加 `--fail-on medium` 参数，这样当扫描发现问题时，命令将以非零状态码退出。 ## 安装 从源码安装（目前可用）： ``` git clone https://github.com/bourne44/agenstral.git cd agenstral npm install npm run build npm link # makes `agenstral` available on your PATH ``` 一旦发布到 npm： ``` npm install -g agenstral # 或者，无需安装： npx agenstral scan --workspace . ``` ## 日常命令 请在你要让 agent 工作的代码库目录中运行以下命令。 ``` # 1. 在 agent 启动前查看风险项 agenstral scan --workspace . agenstral scan --workspace . --fail-on medium # gate for CI agenstral scan --workspace . --sarif --out .agenstral/scan.sarif # for GitHub code scanning # 2. 设定规则，然后针对它们测试单个 tool call agenstral policy init agenstral check --call examples/dangerous-tool-call.json # -> Decision: DENY # 3. 让 agent 通过 Agenstral 执行操作（对每个 action 执行 policy + audit） agenstral run --approve-ask -- node --version # a shell command agenstral proxy -- # an MCP server # 4. 证明发生了什么 agenstral audit verify .agenstral/audit.jsonl # verifies the hash chain agenstral report # local HTML report agenstral bundle # portable evidence bundle for handoff agenstral state # one-shot summary of everything ``` 审计日志是纯粹的追加式 JSONL 文件，没有什么花哨的，也没有用到什么区块链。每条 记录只是携带了前一条记录的哈希值。如果你编辑或删除了任何过去的记录行，`audit verify` 就会失败并报出 `hash mismatch`。这就是它的全部原理，但这足以证明历史记录在事后没有被篡改过。 ## 命令参考 - `scan`：发现 MCP 配置、agent 指导文件、有风险的 package 脚本、有风险的 GitHub Actions 工作流（包括连接到不可信触发器的 AI agent）、暴露的机密信息，以及缺失的项目控制措施。 - `doctor`：跨清单、必要文件、CI、scan、audit、Git 状态以及被忽略的生成路径，检查发布和交接的准备就绪情况。 - `policy init`：创建一个初始的 `.agenstral/policy.json`。 - `check`：根据策略评估单个 tool-call JSON 文件。 - `run`：通过 Agenstral 策略和审计日志执行本地 shell 命令。 - `proxy`：在 Agenstral 策略和审计日志的约束下运行 stdio MCP server。 - `audit view` / `audit verify`：打印紧凑的时间线 / 验证哈希链。 - `map`：为贡献者打印项目组件映射图。 - `report`：生成包含扫描结果、审计时间线、Git 状态和系统映射的本地 HTML 报告。 - `bundle` / `bundle verify`：生成 / 验证可移植的 JSON 证据包以及同步的 HTML 报告。 - `state`：打印紧凑的项目状态。 ## 状态 这是一个处于早期的项目，我宁愿坦诚相待。目前我认为比较可靠的部分是 **scan** 和 **tamper-evident audit**。它们现在已经非常稳定且实用了。 通过 `proxy` 进行的运行时中介目前有意设计得比较保守，并且仍在不断完善中；我宁愿发布一个言出必行的小工具，也不愿发布一个虚张声势的大而全的玩意。 [Roadmap](docs/ROADMAP.md) 中规划了它未来的发展方向。 如果你克隆了它并把它指向一个真实的代码库，我非常乐意听听你的 期望与实际发现之间的差异。欢迎提交 Issues 和反馈粗糙的边缘问题。 ## 设计原则 - **本地优先**：无需账号、云服务或遥测即可发挥作用。 - **确定性**：策略决策是可解释且可测试的。 - **小而精的核心**：策略、扫描、审计和代理代码相互分离。 - **默认安全**：除非策略另有规定，否则未知的 tool calls 需要经过批准。 - **朴素的接口**：JSON 策略、JSONL 审计、CLI 命令以及可预测的输出结果。 ## 文档 - [项目映射图](docs/PROJECT_MAP.md)：为贡献者提供的简洁导航。 - [架构](docs/ARCHITECTURE.md)：各个层级、契约以及扩展路径。 - [威胁模型](docs/THREAT_MODEL.md)：Agenstral 能防护什么，不能防护什么。 - [工作流](docs/WORKFLOW.md)：本地开发循环与发布关卡。 - [发布](docs/RELEASE.md)：本地发布流程和发布检查清单。 - [路线图](docs/ROADMAP.md)：短期与长期的发展方向。 - [项目定位](docs/POSITIONING.md)：本项目是什么，以及刻意不去碰什么。 - [更新日志](CHANGELOG.md)：按版本记录的显著变更。 ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。完整的本地检查流程命令为 `npm run release:check`。 ## 许可证 Apache-2.0。请参阅 [LICENSE](LICENSE)。

标签：AI编程代理, DevSecOps, Homebrew安装, TypeScript, 上游代理, 多模态安全, 安全合规, 安全插件, 文档结构分析, 时序数据库, 网络代理, 自动化攻击