Rul1an/assay
GitHub: Rul1an/assay
面向 MCP 兼容 AI Agent 的策略即代码工具，提供确定性测试、运行时强制执行和可验证的审计证据。
Stars: 1 | Forks: 0
# Assay
[](https://crates.io/crates/assay-cli)
[](https://github.com/Rul1an/assay/actions/workflows/ci.yml)
[](https://github.com/Rul1an/assay/blob/main/LICENSE)
**面向 AI Agent 的 Policy-as-Code。**
离线运行。无遥测。无供应商锁定。
Assay 根据策略验证 AI agent 的行为。记录 trace，生成策略，运行确定性的 CI 门禁，生成用于审计的证据包。适用于任何兼容 MCP 的 agent。
**为何 Assay 在 2026 年的 agent 安全领域胜出：** Assay 最强的切入点是在工具调用路径上的确定性治理。MCP 碎片化 IPI 实验线表明，有状态的序列策略在负载碎片化和工具跳转方面仍然有效，而仅包装的词法检查则会失效。Assay 并不声称能解决普遍的语义劫持问题，也不单独阻止原始出站网络字节；它以可审计的策略决策和个位数毫秒的开销来治理 sink-call 路由。参见 `/Users/roelschuurkes/assay/docs/ops/EXPERIMENT-MCP-FRAGMENTED-IPI-2026Q1-RESULTS.md`、`/Users/roelschuurkes/assay/docs/ops/EXPERIMENT-MCP-FRAGMENTED-IPI-WRAP-BYPASS-2026Q1-RESULTS.md` 以及 `/Users/roelschuurkes/assay/docs/ops/EXPERIMENT-MCP-FRAGMENTED-IPI-SECOND-SINK-2026Q1-RESULTS.md`。
## 立即体验
[](https://codespaces.new/Rul1an/assay?quickstart=1)
无需安装。打开基于浏览器的终端，预装了已编译的 Assay 和演示 fixtures。
```
# 在 Codespace 终端中：
make demo # See the full break & fix flow
make test # Run a safe trace (PASS)
make fail # Run an unsafe trace (FAIL)
```
或者在本地安装：
## 安装 ``` cargo install assay-cli ``` ## 快速入门 ### 从头开始 ``` # 从项目默认值生成 policy + config assay init --ci # 运行冒烟测试 (使用捆绑的 traces，无 API 调用) assay ci --config ci-eval.yaml --trace-file traces/ci.jsonl ``` ### 从现有 trace ``` # 从记录的 agent 行为生成 policy assay init --from-trace trace.jsonl # 验证 assay validate --config eval.yaml --trace-file trace.jsonl ``` ### 从 MCP Inspector 会话 ``` # 导入 trace assay import --format inspector session.json --out-trace traces/session.jsonl # 运行测试 assay run --config eval.yaml --trace-file traces/session.jsonl ``` ## 命令 ### 测试与验证 | 命令 | 功能 | |---------|-------------| | `assay run` | 针对 trace 文件执行测试套件并写入 `run.json`/`summary.json`。 | | `assay ci` | CI 模式运行。添加 `--sarif`、`--junit`、`--pr-comment` 输出。 | | `assay validate` | 无状态策略检查。文本、JSON 或 SARIF 输出。 | | `assay replay` | 从自包含 bundle 重放（离线、密封）。 | ### 策略与配置 | 命令 | 功能 | |---------|-------------| | `assay init` | 脚手架项目：策略、配置、CI 工作流。`--from-trace` 用于现有 trace。 | | `assay generate` | 从 trace 或多次运行 profile 生成策略。`--heuristics` 用于熵分析。 | | `assay profile` | 多次运行稳定性分析。Wilson 区间门控。 | | `assay doctor` | 诊断配置、trace 和基线问题。 | | `assay explain` | 针对策略的逐步 trace 解释。终端、markdown、JSON 输出。 | ### 证据与合规 | 命令 | 功能 | |---------|-------------| | `assay evidence export` | 创建证据包（tar.gz、内容寻址、Merkle root）。 | | `assay evidence verify` | 验证 bundle 完整性。 | | `assay evidence lint` | 对 bundle 进行 lint 并输出 SARIF。支持 `--pack` 用于合规规则。 | | `assay evidence diff` | 对比两个已验证的 bundle（网络、文件系统、进程变更）。 | | `assay evidence explore` | 交互式 TUI 浏览器。 | | `assay evidence push/pull/list` | BYOS：S3、GCS、Azure Blob、R2、B2、MinIO。 | | `assay bundle create/verify` | 重放 bundle（可移植、离线测试制品）。 | ### 运行时 | 命令 | 功能 | |---------|-------------| | `assay mcp wrap` | 使用策略执行包装 MCP 进程（基于 stdio 的 JSON-RPC）。 | | `assay sandbox` | Landlock 沙箱执行（Linux，无 root）。 | | `assay monitor` | eBPF/LSM 运行时强制执行（Linux，需要 capabilities）。 | ### 杂项 | 命令 | 功能 | |---------|-------------| | `assay sim run` | 攻击模拟套件（完整性、混沌、差异化）。 | | `assay import` | 从 MCP Inspector 或 JSON-RPC 日志导入 trace。 | | `assay tool sign/verify/keygen` | Ed25519 + DSSE 工具签名。 | | `assay fix` | 针对策略问题的交互式自动修复建议。 | ## CI 集成 ### GitHub Actions ``` - uses: Rul1an/assay/assay-action@v2 ``` 该 action 会安装 assay，运行你的门禁，将 SARIF 上传到 Security 标签页，并发布包含结果的 PR 评论。 ``` # .github/workflows/assay.yml name: Assay Gate on: [push, pull_request] permissions: contents: read pull-requests: write security-events: write jobs: assay: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: Rul1an/assay/assay-action@v2 ``` 或者生成一个工作流： ``` assay init --ci github # writes .github/workflows/assay.yml assay init --ci gitlab # writes .gitlab-ci.yml ``` ### 手动 CI ``` assay ci \ --config eval.yaml \ --trace-file traces/golden.jsonl \ --sarif reports/sarif.json \ --junit reports/junit.xml \ --pr-comment reports/pr-comment.md \ --replay-strict ``` 退出码：`0` 通过，`1` 测试失败，`2` 配置错误，`3` 基础设施错误。 ## 配置 两个文件：一个测试配置（`eval.yaml`）和一个策略（`policy.yaml`）。 **eval.yaml** — 定义要测试的内容： ``` version: 1 suite: "my_agent" model: "trace" tests: - id: "deploy_args" input: prompt: "deploy_staging" expected: type: args_valid schema: deploy_service: type: object required: [env] properties: env: { type: string, enum: [staging, prod] } ``` **policy.yaml** — 定义允许的内容： ``` version: "1.0" name: "my-policy" allow: ["*"] deny: - "exec" - "shell" - "bash" constraints: - tool: "read_file" params: path: matches: "^/app/.*|^/data/.*" ``` 策略包：`assay init --pack default|hardened|dev` ## 证据包 防篡改的 `.tar.gz` 包，包含 `manifest.json`（SHA-256 哈希、Merkle root）和 `events.ndjson`（CloudEvents 格式，内容寻址 ID）。 ``` assay evidence export --profile profile.yaml --out bundle.tar.gz assay evidence verify bundle.tar.gz assay evidence lint --pack eu-ai-act-baseline bundle.tar.gz assay evidence diff baseline.tar.gz current.tar.gz ``` ## Python SDK ``` pip install assay ``` ``` from assay import AssayClient client = AssayClient("traces.jsonl") client.record_trace(tool_call) ``` Pytest 插件： ``` @pytest.mark.assay(trace_file="test_traces.jsonl") def test_agent(): pass ``` ## 项目结构 ``` crates/ assay-cli/ CLI binary assay-core/ Eval engine, store, trace replay, report formatters assay-metrics/ Built-in metrics (args_valid, sequence_valid, regex_match, etc.) assay-evidence/ Evidence bundles, lint engine, diff, sanitize assay-mcp-server/ MCP proxy for runtime enforcement assay-sim/ Attack simulation harness assay-monitor/ eBPF/LSM runtime (Linux) assay-policy/ Policy compilation (kernel + userspace tiers) assay-registry/ Pack registry client (DSSE, OIDC, lockfile) assay-common/ Shared types assay-ebpf/ Kernel eBPF programs assay-python-sdk/ Python SDK (PyO3 + pytest plugin) ``` ## 贡献 ``` cargo test --workspace cargo clippy --workspace --all-targets -- -D warnings ``` 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE)
## 安装 ``` cargo install assay-cli ``` ## 快速入门 ### 从头开始 ``` # 从项目默认值生成 policy + config assay init --ci # 运行冒烟测试 (使用捆绑的 traces，无 API 调用) assay ci --config ci-eval.yaml --trace-file traces/ci.jsonl ``` ### 从现有 trace ``` # 从记录的 agent 行为生成 policy assay init --from-trace trace.jsonl # 验证 assay validate --config eval.yaml --trace-file trace.jsonl ``` ### 从 MCP Inspector 会话 ``` # 导入 trace assay import --format inspector session.json --out-trace traces/session.jsonl # 运行测试 assay run --config eval.yaml --trace-file traces/session.jsonl ``` ## 命令 ### 测试与验证 | 命令 | 功能 | |---------|-------------| | `assay run` | 针对 trace 文件执行测试套件并写入 `run.json`/`summary.json`。 | | `assay ci` | CI 模式运行。添加 `--sarif`、`--junit`、`--pr-comment` 输出。 | | `assay validate` | 无状态策略检查。文本、JSON 或 SARIF 输出。 | | `assay replay` | 从自包含 bundle 重放（离线、密封）。 | ### 策略与配置 | 命令 | 功能 | |---------|-------------| | `assay init` | 脚手架项目：策略、配置、CI 工作流。`--from-trace` 用于现有 trace。 | | `assay generate` | 从 trace 或多次运行 profile 生成策略。`--heuristics` 用于熵分析。 | | `assay profile` | 多次运行稳定性分析。Wilson 区间门控。 | | `assay doctor` | 诊断配置、trace 和基线问题。 | | `assay explain` | 针对策略的逐步 trace 解释。终端、markdown、JSON 输出。 | ### 证据与合规 | 命令 | 功能 | |---------|-------------| | `assay evidence export` | 创建证据包（tar.gz、内容寻址、Merkle root）。 | | `assay evidence verify` | 验证 bundle 完整性。 | | `assay evidence lint` | 对 bundle 进行 lint 并输出 SARIF。支持 `--pack` 用于合规规则。 | | `assay evidence diff` | 对比两个已验证的 bundle（网络、文件系统、进程变更）。 | | `assay evidence explore` | 交互式 TUI 浏览器。 | | `assay evidence push/pull/list` | BYOS：S3、GCS、Azure Blob、R2、B2、MinIO。 | | `assay bundle create/verify` | 重放 bundle（可移植、离线测试制品）。 | ### 运行时 | 命令 | 功能 | |---------|-------------| | `assay mcp wrap` | 使用策略执行包装 MCP 进程（基于 stdio 的 JSON-RPC）。 | | `assay sandbox` | Landlock 沙箱执行（Linux，无 root）。 | | `assay monitor` | eBPF/LSM 运行时强制执行（Linux，需要 capabilities）。 | ### 杂项 | 命令 | 功能 | |---------|-------------| | `assay sim run` | 攻击模拟套件（完整性、混沌、差异化）。 | | `assay import` | 从 MCP Inspector 或 JSON-RPC 日志导入 trace。 | | `assay tool sign/verify/keygen` | Ed25519 + DSSE 工具签名。 | | `assay fix` | 针对策略问题的交互式自动修复建议。 | ## CI 集成 ### GitHub Actions ``` - uses: Rul1an/assay/assay-action@v2 ``` 该 action 会安装 assay，运行你的门禁，将 SARIF 上传到 Security 标签页，并发布包含结果的 PR 评论。 ``` # .github/workflows/assay.yml name: Assay Gate on: [push, pull_request] permissions: contents: read pull-requests: write security-events: write jobs: assay: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: Rul1an/assay/assay-action@v2 ``` 或者生成一个工作流： ``` assay init --ci github # writes .github/workflows/assay.yml assay init --ci gitlab # writes .gitlab-ci.yml ``` ### 手动 CI ``` assay ci \ --config eval.yaml \ --trace-file traces/golden.jsonl \ --sarif reports/sarif.json \ --junit reports/junit.xml \ --pr-comment reports/pr-comment.md \ --replay-strict ``` 退出码：`0` 通过，`1` 测试失败，`2` 配置错误，`3` 基础设施错误。 ## 配置 两个文件：一个测试配置（`eval.yaml`）和一个策略（`policy.yaml`）。 **eval.yaml** — 定义要测试的内容： ``` version: 1 suite: "my_agent" model: "trace" tests: - id: "deploy_args" input: prompt: "deploy_staging" expected: type: args_valid schema: deploy_service: type: object required: [env] properties: env: { type: string, enum: [staging, prod] } ``` **policy.yaml** — 定义允许的内容： ``` version: "1.0" name: "my-policy" allow: ["*"] deny: - "exec" - "shell" - "bash" constraints: - tool: "read_file" params: path: matches: "^/app/.*|^/data/.*" ``` 策略包：`assay init --pack default|hardened|dev` ## 证据包 防篡改的 `.tar.gz` 包，包含 `manifest.json`（SHA-256 哈希、Merkle root）和 `events.ndjson`（CloudEvents 格式，内容寻址 ID）。 ``` assay evidence export --profile profile.yaml --out bundle.tar.gz assay evidence verify bundle.tar.gz assay evidence lint --pack eu-ai-act-baseline bundle.tar.gz assay evidence diff baseline.tar.gz current.tar.gz ``` ## Python SDK ``` pip install assay ``` ``` from assay import AssayClient client = AssayClient("traces.jsonl") client.record_trace(tool_call) ``` Pytest 插件： ``` @pytest.mark.assay(trace_file="test_traces.jsonl") def test_agent(): pass ``` ## 项目结构 ``` crates/ assay-cli/ CLI binary assay-core/ Eval engine, store, trace replay, report formatters assay-metrics/ Built-in metrics (args_valid, sequence_valid, regex_match, etc.) assay-evidence/ Evidence bundles, lint engine, diff, sanitize assay-mcp-server/ MCP proxy for runtime enforcement assay-sim/ Attack simulation harness assay-monitor/ eBPF/LSM runtime (Linux) assay-policy/ Policy compilation (kernel + userspace tiers) assay-registry/ Pack registry client (DSSE, OIDC, lockfile) assay-common/ Shared types assay-ebpf/ Kernel eBPF programs assay-python-sdk/ Python SDK (PyO3 + pytest plugin) ``` ## 贡献 ``` cargo test --workspace cargo clippy --workspace --all-targets -- -D warnings ``` 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 [MIT](LICENSE)
标签：Agent, AI 安全, AI 治理, CI/CD 安全, Docker镜像, MCP, Policy-as-Code, Rust, Web报告查看器, 可视化界面, 可验证证据, 大模型安全, 工具调用管控, 提示注入防御, 数据投毒防御, 智能体安全, 源代码安全, 确定性测试, 策略即代码, 网络流量审计, 聊天机器人安全, 运行时执行, 逆向工具, 通知系统, 通知系统, 通知系统, 防火墙, 验证与测试