CrossroadCode-Labs/TrailStax

# TrailStax ### *构建信任的技术栈。* ## [](LICENSE) [](https://python.org) [](https://github.com/wishuponascar22/RealAgentID) [](https://github.com/TrailStax/StaxVault) [](docs/TrailStax_OWASP_Gap_Analysis.docx) [] [] [] ## TrailStax 是什么 TrailStax 是一个**安全的 ModelOps 治理平台** —— 这是一个加密信任栈，能够让 AI agent pipeline 的安全性达到可在受监管环境中发布的水平。 **我们没有等待那个未来。我们亲手构建了它。** - **权限** → RealAgentID - **配额** → quota.py *(开发中)* - **策略** → guardian.py + validator.py *(开发中)* ## 问题所在 **40% 的平台团队报告他们生成的 AI 代码并不稳定。** **74.9% 的平台团队已经托管或即将托管 agent。** **大多数平台对于这些 agent 的操作并没有治理层。** 云控制台已经容易受到内部威胁的攻击。Agentic AI 成倍放大了这种风险 —— 一个权限配置错误或身份被泄露的 agent 可以修改 IAM 角色、提升权限，或引入恶意依赖，其速度远超任何人工审查所能察觉的范围。 更糟糕的是：大多数企业级 agent 平台将审计追踪锁定在平台内部。这不是治理。这只是一种权宜之计。 TrailStax 的构建基于一个完全不同的前提： ## RealAgentID 的首次实现 [RealAgentID](https://github.com/wishuponascar22/RealAgentID) 确立了该协议 —— 专为 AI agent 设计的加密身份。**TrailStax 是该协议在现实世界中运行的场所。** TrailStax 中的每一条审计追踪记录、代码提交和包安装都绑定到经过 RealAgentID 验证的 agent 身份，从而生成一份完整、防篡改的记录，包含： - **谁**是这个 agent —— 由 RealAgentID 密钥对验证 - 它做了**什么** —— 仅追加、哈希链式操作日志 - 它运行了**什么代码** —— 仅追加、哈希链式代码提交注册表 - 它安装了**什么** —— 带有安装前验证的签名包注册表 没有平台锁定。不需要 MCP 这种权宜之计。这条追踪链属于你。 ## 真实世界的验证 **2026 年 5 月 —— Grafana Labs 供应链攻击：** 一个被入侵的 TanStack npm 包导致了 GitHub workflow token 被盗、仓库访问权限泄露，并受到了勒索要求。`guardian.py` 的安装前哈希验证和签名注册表直接解决了这种攻击模式。 **行业数据：** - 40% 的平台团队报告 AI 生成的代码不稳定 *(Weave Intelligence, State of AI in Platform Engineering)* - 74.9% 的平台团队已经托管或即将托管 AI agent *(platformengineering.org)* - 供应链攻击正处于 Gartner Hype Cycle（技术成熟度曲线）的“幻灭低谷期” —— 这意味着真正的买家现在正在寻找真正的解决方案 ## 模块 ### `trail.py` — Agent 操作审计日志 ✅ Alpha 防篡改、仅追加的日志，记录 agent 在会话期间执行的每一项操作。从创世区块进行哈希链接 —— 修改任何条目都会破坏其后的所有哈希值。 ``` from trailstax import TrailStax trail = TrailStax(agent_id="recon-agent-001") trail.log("session.start", {"target": "example.com", "mode": "passive"}) trail.log("iam.role_check", {"role": "storage.admin", "granted": True}) trail.log("session.complete", {"duration_ms": 2140, "findings": 2}) print(trail.verify_chain()) # True — untampered trail.export("session_trail.json") ``` ### `codebank.py` — 代码提交注册表 ✅ Alpha 仅追加的注册表，记录 agent 被授权运行的每个代码制品。在文件获批时对其进行哈希处理。在执行前验证其未被更改。 ``` from trailstax import CodeBank bank = CodeBank(agent_id="recon-agent-001") bank.register_file("agents/recon_agent.py") bank.register_file("agents/utils.py", metadata={"version": "1.2.0"}) ok, detail = bank.verify_file("agents/recon_agent.py") print(ok, detail) # True, {"match": True, "label": "recon_agent.py"} ``` ### `guardian.py` — 供应链防御 ✅ Alpha 针对 Python agent 环境的预安装验证和 pip hook 强制执行。在执行前拦截每一次 `pip install`，根据签名包注册表进行验证，并在发生任何被阻止的尝试时通过 Redis pub/sub 向 agent mesh 发出警报。 ``` # 安装 pip hook python guardian.py install-hook # 批准 packages python guardian.py approve requests 2.31.0 python guardian.py approve redis 5.0.1 # 现在每次安装尝试在执行前都会被验证 pip install requests # [guardian] ✓ requests — 已批准 # 查看防篡改的 audit trail python guardian.py trail ``` **特性：** - 通过 RealAgentID 密钥实现 HMAC-SHA256 签名包注册表 - agent mesh 间共享的 Redis 支持的注册表（可回退到本地文件） - 哈希链式审计追踪 —— 每次尝试（无论批准还是阻止）均被记录 - 阻止安装时通过 Redis pub/sub 向所有 agent 广播警报 - 对固定版本进行 PyPI 哈希验证 ### `validator.py` — Prompt 验证层 🔨 开发中 输入清理、意图验证和输出 schema 强制执行。解决 ASI01（Agent Goal Hijack，Agent 目标劫持）—— OWASP Agentic Top 10 中未缓解的最严重威胁。 ### `quota.py` — 资源配额强制执行 🔜 计划中 基于 Redis 的按 agent 速率限制。跟踪 API 调用、token 消耗和计算时间。超过配额的 agent 将被自动从 mesh 中隔离。解决 ASI05（Resource Overuse，资源滥用）。 ### `codeguard.py` — 自动生成代码扫描 🔜 计划中 针对 AI 生成代码的签名前静态分析关卡。在 `codebank.py` 签署任何内容之前运行 Semgrep 和 Bandit。防止任何存在漏洞或恶意的生成代码进入签名注册表。 ### `lifecycle.py` — 模型生命周期管理 🔜 计划中 管理完整的模型生命周期：训练 → 评估 → 预发布 → 提升 → 监控 → 检测偏移 → 重新训练 → 回滚。由 RealAgentID 控制的提升操作。偏移检测触发自动的 Ira 重新训练 pipeline。 ### `sentinel.py` — 漏洞情报 🔜 计划中 研究监控 agent。持续摄取 arXiv、OWASP 更新、CVE 订阅源和 HackerOne 公开的报告。根据 TrailStax 合规框架对发现进行分类，并起草威胁模型更新。基于 Ira 的摄取模式构建。 ### `reasoning.py` — 推理可审计性 🔜 计划中 通过图查询测量并比较 GPT/Gemini/Claude 在推理跳跃、死胡同和置信度信号方面的模型推理。集成 Neo4j。这是位于 RealAgentID、trail 和 codebank 之上的第四个信任层。 ## 架构 ``` TrailStax ├── trailstax/ │ ├── __init__.py │ ├── trail.py Append-only hash-chained agent action audit log │ ├── codebank.py Append-only hash-chained code commit registry │ └── sign.py RealAgentID keypair signing layer (v0.5 roadmap) ├── guardian.py Supply chain defense — pip hook + signed registry ├── tests/ │ ├── test_trail.py │ └── test_codebank.py ├── docs/ │ ├── TrailStax_OWASP_Gap_Analysis.docx │ └── Ira_Threat_Model_v1.docx ├── COMPLIANCE.md 7-framework alignment including OWASP Agentic Top 10 ├── CHANGELOG.md ├── setup.py └── README.md ``` ### 链式结构是如何工作的 每个条目 —— 无论是操作日志、代码提交还是安装尝试 —— 都会与其前一个条目的哈希值一起进行哈希计算。该链从创世哨兵（`0x000...000`）开始，以仅追加的方式向前增长。修改链中任何位置的任何条目都会破坏其后的所有哈希值。检测是瞬间完成的。 ``` GENESIS (0x000...000) │ ▼ [Entry 0] ──hash──▶ [Entry 1] ──hash──▶ [Entry 2] ──hash──▶ ... ──hash──▶ [Entry N] session.start iam.role_check firewall.query session.end Tamper any entry here ──────────────────^ breaks every hash forward ``` ## 威胁模型 |威胁 |TrailStax 响应 | |----------------------------------------------|----------------------------------------------------| |内部人员在执行前替换了 agent 代码 |codebank.py 在注册时检测到哈希不匹配 | |被入侵的依赖项混入 pipeline |guardian.py 在安装时阻止 —— 在执行之前 | |安装后脚本执行恶意代码 |guardian.py 的 pip hook 在 pip 运行前拦截 | |Agent 在运行时自我修改 |trail.py + codebank.py 捕获差异 | |Agent 静默更改 IAM / 防火墙规则 |trail.py 记录带有完整 payload 的每个操作 | |平台将审计数据作为人质 |JSON 导出可在任何地方运行 —— 无需供应商 | |对 agent 身份的重放攻击 |RealAgentID TTL 强制执行阻止过期的凭证| |自动生成的代码引入了漏洞|codeguard.py 静态分析关卡 *(计划中)* | |生产环境中的模型偏移 |lifecycle.py 偏移检测 + 回滚 *(计划中)* | |通过 agent 输入进行 prompt 注入 |validator.py 意图验证 *(开发中)* | Ira 集成的完整威胁模型：[`docs/Ira_Threat_Model_v1.docx`](docs/Ira_Threat_Model_v1.docx) ## OWASP Agentic Top 10 覆盖范围 TrailStax 映射到 OWASP Top 10 for Agentic Applications（2025–2026）： |ASI ID|类别 |状态 |模块 | |------|----------------------------|----------------|--------------------| |ASI01 |Agent Goal Hijack (Agent 目标劫持) |🔨 开发中|validator.py | |ASI02 |Tool Misuse (工具滥用) |🟡 部分覆盖 |RealAgentID 身份| |ASI03 |Identity & Privilege Abuse (身份与权限滥用) |✅ 已覆盖 |RealAgentID | |ASI04 |Memory Poisoning (内存污染) |🟡 部分覆盖 |codebank.py | |ASI05 |Resource Overuse (资源滥用) |🔜 计划中 |quota.py | |ASI06 |Supply Chain Vulnerabilities (供应链漏洞)|✅ 已覆盖 |guardian.py | |ASI07 |Data Exfiltration (数据泄露) |🟡 部分覆盖 |trail.py 取证 | |ASI08 |Cascading Failures (级联故障) |🟡 部分覆盖 |trail.py 追踪 | |ASI09 |Insecure Output Handling (不安全的输出处理) |🟡 部分覆盖 |codebank.py | |ASI10 |Shared Resource Abuse (共享资源滥用) |🟡 部分覆盖 |Redis + RealAgentID | 完整的差距分析：[`docs/TrailStax_OWASP_Gap_Analysis.docx`](docs/TrailStax_OWASP_Gap_Analysis.docx) ## 合规框架对标 |框架 |控制措施 | |--------------------|--------------------------------| |NIST CSF |DE.CM-3, RS.AN-1, PR.PT-1 | |SOC 2 |CC7.2, CC4.1, CC6.1 | |ISO 27001 |A.12.4.1, A.12.4.3, A.9.4.1 | |NIST AI RMF |GOVERN 1.2, MEASURE 2.5, MAP 1.5| |NIST SP 800-53 |AU-9, AU-10, AU-12 | |NIST SP 800-161 |供应链风险管理 | |OWASP Agentic Top 10|ASI01–ASI10 *(框架 7)* | 完整的控制映射在 [`COMPLIANCE.md`](COMPLIANCE.md) ## 快速开始 ``` git clone https://github.com/TrailStax/StaxVault.git cd StaxVault pip install -e . python demo.py # guardian.py 供应链防御 python guardian.py install-hook python guardian.py approve requests 2.31.0 python guardian.py status ``` ## 路线图 |版本|功能 |状态 | |-------|----------------------------------------------------------|----------------| |v0.1 |`trail.py` — 哈希链式操作审计日志 |✅ Alpha | |v0.2 |`codebank.py` — 哈希链式代码提交注册表 |✅ Alpha | |v0.3 |`guardian.py` — 供应链防御 + pip hook + Redis |✅ Alpha | |v0.4 |`validator.py` — prompt 验证和意图验证|🔨 开发中| |v0.5 |`quota.py` — 基于 Redis 的按 agent 资源配额 |🔜 计划中 | |v0.6 |Ollama 模型服务集成 |🔜 计划中 | |v0.7 |`codeguard.py` — 自动生成代码静态分析关卡 |🔜 计划中 | |v0.8 |`lifecycle.py` — 模型生命周期管理 |🔜 计划中 | |v0.9 |`sentinel.py` — 持续漏洞情报 |🔜 计划中 | |v1.0 |`reasoning.py` — 推理可审计性 + Neo4j |🔜 计划中 | ## 与 RealAgentID 的关系 |层 |项目 |回答的问题 | |--------------|-------------------------------------------------------------|----------------------------------------------------------| |协议 |[RealAgentID](https://github.com/wishuponascar22/RealAgentID)|这个 agent 是谁？ | |实现|TrailStax |它做了什么？它运行了什么代码？它安装了什么？| |结合 |两者 |这个 agent 的操作能否实现端到端的可信？ | ## 与 Ira 的关系 [Ira](https://github.com/Ira-Digital-Blueprints/Ira) 是一个安全的 ModelOps 平台，它将组织数据映射为数字蓝图，并在该蓝图上训练特定于组织的开源模型。TrailStax 是 Ira 的治理支柱： - RealAgentID —— 所有 Ira agent 的加密身份 - trail.py —— 每个 pipeline 事件的审计追踪 - codebank.py —— 所有数据集和模型的签名注册表 - guardian.py —— 所有 Ira 依赖项的供应链防御 - lifecycle.py —— 模型生命周期管理 *(计划中)* ## 设计哲学 TrailStax 的构建围绕着一个核心管理原则，该原则借鉴了现存保证级别最高的软件工程环境： **每个执行路径都必须是可追踪、可预测且可验证的。** 这与 F-35 等系统中的飞行中央软件所遵循的原则相同 —— 在这些系统中，不可预测的控制流不是一个性能问题，而是安全隐患。在 Agentic AI 系统中，虽然利害关系不同，但原则是完全一致的。一个在没有可验证审计追踪的情况下行动的 agent，就是一个在生产环境中无法被信任的 agent。 TrailStax 在基础设施层面强制执行此原则： - **仅追加哈希链** —— 没有静默修改，没有遗漏 - **加密的 agent 身份** —— 每一个操作都与经过验证的执行者绑定 - **确定性的审计追踪** —— 发生了什么、何时发生以及谁授权了它 - **供应链完整性** —— 每一个依赖项都被固定、扫描和签名 我们构建 TrailStax 并不是因为它很方便。我们构建它是因为，无论组织是否准备好，Agentic AI 都将席卷而来 —— 而大多数组织并没有准备好。 TrailStax 是让它们准备就绪的治理层。 *“未来的 AI 平台可能会将 AI agent 视为一种平台角色，配备相应的权限、配额和策略。”* -platformengineering.org 我们没有等待未来。我们构建了它。 ## 许可证 MIT —— 随意使用它，基于它进行构建，并在你发表时引用它。 *由 [CrossroadCode](https://github.com/wishuponascar22) 构建 —— 站在信任与自动化的十字路口。*

标签：AI治理, ModelOps, 密码学, 手动系统调用, 搜索引擎查询, 权限管理, 模型越狱, 逆向工具