invariant-systems-ai/aiir

# AIIR — AI Integrity Receipts **为 AI 辅助的 commits 提供可验证的来源。生成收据。验证发布。为审计员提供证明。** 🧾 [](https://github.com/marketplace/actions/aiir-ai-integrity-receipts) [](https://pypi.org/project/aiir/) [](https://github.com/invariant-systems-ai/aiir/actions/workflows/ci.yml) [](https://opensource.org/licenses/Apache-2.0) [](https://github.com/invariant-systems-ai/aiir) [](https://gitlab.com/explore/catalog/invariant-systems/aiir) [](https://scorecard.dev/viewer/?uri=github.com/invariant-systems-ai/aiir) [](https://github.com/invariant-systems-ai/aiir)

## 为什么？ 在大多数公司，AI 编写了 30–50% 的新代码。Copilot、ChatGPT、Claude、Cursor —— 所有这些都通过 `git commit` 提交，却没有系统性的记录来区分哪些是人写的，哪些是机器生成的。 您的审计员会问：*“哪些 commits 涉及了 AI 工具？您能展示审计追踪记录吗？”* 然后是：*“在发布之前，您是否根据策略验证了每一个 release？”* | 谁在询问 | 他们需要什么 | |----------|---------------| | **SOC 2 / ISO 27001 auditor** | 每个 commit 中声明的 AI 参与情况的防篡改记录 | | **EU AI Act compliance** | 带有 AI 标记的 commits 的透明度证据 + 已验证的发布证明 | | **Insurance underwriter** | 每个 release 中声明的 AI 参与情况的策略评估验证 | | **GRC / supply-chain security** | 兼容 SLSA 的 Verification Summary Attestation (VSA) | | **Engineering leadership** | “我们跟踪声明的 AI 参与情况 *并* 验证每一个 release” —— 附带加密收据 | AIIR 回答了这两个问题。为每个 commit **生成**收据。根据策略**验证** releases。将结果作为机器可读的 VSA 进行**证明**。一个工具。零依赖。Apache 2.0。 ## 什么是收据？ ``` ┌─ Receipt: g1-a3f8b2c1d4e5f6a7b8c9d0e1... │ Commit: c4dec85630 │ Subject: feat: add new auth middleware │ Author: Jane Dev │ Files: 4 changed │ AI: YES (copilot) │ Hash: sha256:7f3a... │ Time: 2026-03-06T09:48:59Z └────────────────────────────────────────── ``` 每个 commit 都会获得一个**内容寻址**的收据 —— 一个 JSON 对象，记录了提交了*什么*，*谁*写的，以及*是否涉及 AI*。更改一个字符？哈希值就会失效。这就是**完整性**（篡改检测）。 为了实现**真实性**（证明*谁*生成了收据），请启用 Sigstore 无密钥签名 —— 请参阅下方的 [Sigstore signing](#sigstore-signing)。如果不签名，收据只能证明内部一致性，而不能证明来源 —— 任何能在同一个 commit 上运行 `aiir` 的人都可以生成等效的收据。 ## 工作原理 —— 验证流水线 AIIR 在三个层面上运行，与现代供应链安全架构相匹配： ``` git commit ↓ AIIR receipt (content-addressed, per-commit) ↓ Sigstore signing (OIDC identity, transparency log) ↓ Policy evaluation (org rules, AI-usage thresholds) ↓ Verification Summary Attestation (in-toto Statement v1) ↓ CI gate (PASS / FAIL — enforceable via branch protection) ``` 这与 [SLSA](https://slsa.dev)、[Sigstore](https://sigstore.dev) 和 [in-toto](https://in-toto.io) 直接对齐 —— 即 npm、PyPI、Kubernetes 和 Linux 内核使用的同一技术栈。 **对于开发者**：将 `aiir` 添加到您的 CI 中，对每个 PR 进行通过/失败检查。 **对于安全团队**：获取作为签名证明的策略评估验证结果。 **对于审计员**：查询 JSONL 账本或 VSA 制品 —— 每个声明都是加密可验证的。 ## 试用 ``` pip install aiir cd your-repo aiir --pretty ``` 就是这样。您的上一次 commit 现在在 `.aiir/receipts.jsonl` 中有了一个收据 —— 这是一个防篡改的 JSONL 账本，会自动索引和去重。再次运行：同一个 commit，零重复。零依赖。Python 3.9+。 ### 验证收据 收据是内容寻址的 —— 更改一个字节，哈希值就会失效： ``` aiir --verify .aiir/receipts.jsonl --explain ``` 请参阅 [Tamper Detection](docs/tamper-detection.md) 以详细了解当收据被修改时会发生什么。 ### 验证 release 根据策略评估所有收据并生成 [Verification Summary Attestation](https://slsa.dev/verification_summary) (VSA)： ``` aiir --verify-release --policy strict --emit-vsa ``` AIIR 充当**验证者** —— 它标识自己（`https://invariantsystems.io/verifiers/aiir`），命名策略，评估每个收据，计算 commit 覆盖率，并作为 [in-toto Statement v1](https://in-toto.io/Statement/v1) 发出签名的 PASS/FAIL 决策。下游的 CI 门禁、审计员和 GRC 平台无需重新评估收据即可使用该 VSA。 ## 每个平台。一个命令。 ### 🤖 MCP Tool —— 让您的 AI 代劳 任何支持 MCP 的 AI 助手（Claude、Copilot、Cursor、Continue、Cline、Windsurf）都可以发现并使用 AIIR 作为工具。添加到您的 MCP 配置中： ``` { "mcpServers": { "aiir": { "command": "aiir-mcp-server", "args": ["--stdio"] } } } ``` 现在您的 AI 助手会在编写代码后自动生成收据。它会说：*“我刚为您提交了代码。让我生成一个 AIIR 收据。”* ### 💻 CLI —— 自己运行 ``` # 为最后一次提交开具 Receipt (自动保存到 .aiir/receipts.jsonl) aiir --pretty # 为整个 PR 分支开具 Receipt aiir --range origin/main..HEAD --pretty # 仅 AI 编写的提交，保存到目录 (CI 模式) aiir --ai-only --output .receipts/ # 打印 JSON 到 stdout 用于管道传输 (绕过 ledger) aiir --json | jq .receipt_id # 用于流式传输/管道传输的 JSON Lines 输出 aiir --range HEAD~5..HEAD --jsonl | jq .receipt_id # 自定义 ledger 位置 aiir --ledger .audit/ # 验证 Receipt — 带有人类可读的解释 aiir --verify receipt.json --explain # 将 Receipt 包装在 in-toto Statement v1 envelope 中 (兼容 SLSA) aiir --range HEAD~3..HEAD --in-toto --output .receipts/ # 签名 + 包装以实现完整的供应链证明 aiir --sign --in-toto --output .receipts/ # 附加代理证明 metadata (Copilot, Cursor, Claude 等) aiir --agent-tool copilot --agent-model gpt-4o --agent-context ide # 为新项目初始化 .aiir/ 目录 aiir --init # scaffolds receipts.jsonl, index, config, .gitignore aiir --init --policy strict # also creates policy.json # 审查 Receipts — 证明提交已被审查的人工认证 aiir --review HEAD # defaults to "approved" aiir --review abc123 --review-outcome rejected --review-comment "needs refactor" # Commit trailers — 将 AIIR metadata 附加到 git commit 消息中 aiir --trailer # prints AIIR-Receipt, AIIR-Type, AIIR-AI, AIIR-Verified # Policy engine — 初始化并强制执行组织范围的规则 aiir --policy-init strict # creates .aiir/policy.json aiir --check --policy strict # CI gate: fail if policy violated aiir --check --max-ai-percent 50 # fail if >50% commits are AI-authored # 根据 Policy 验证整个版本，生成 VSA aiir --verify-release --receipts .aiir/receipts.jsonl --emit-vsa --policy strict # Ledger 实用工具 aiir --stats # dashboard of ledger statistics aiir --badge # shields.io badge Markdown aiir --export backup.json # portable JSON bundle # 隐私 — 从 Receipts 中省略文件路径 aiir --redact-files --namespace acme-corp # 原生 GitLab CI 模式 (MR 评论, dotenv 输出) aiir --gitlab-ci --output .receipts/ # 用于 Security Dashboard 的 GitLab SAST 报告 aiir --gitlab-ci --gl-sast-report ``` ### ⚙️ GitHub Action —— 在 CI 中自动化 ``` # .github/workflows/aiir.yml — 签名 Receipts (默认) name: AIIR on: push: tags-ignore: ['**'] # Don't receipt tag pushes (receipts the whole history) pull_request: permissions: id-token: write # Required for Sigstore keyless signing contents: read checks: write # P0: aiir/verify Check Run on every PR pull-requests: write # P3: automatic receipt summary comment on PRs jobs: receipt: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: invariant-systems-ai/aiir@v1 with: output-dir: .receipts/ ``` 签名**默认开启** —— 每个收据都会获得一个 Sigstore bundle（Fulcio 证书 + Rekor 透明日志条目）。 设置 `output-dir` 后，Artifacts 会自动上传。

Unsigned (opt out of signing, no permissions needed)

``` name: AIIR on: push: tags-ignore: ['**'] pull_request: jobs: receipt: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: invariant-systems-ai/aiir@v1 with: sign: false ```

### 🪝 pre-commit Hook —— 本地为每个 commit 生成收据 ``` # .pre-commit-config.yaml repos: - repo: https://github.com/invariant-systems-ai/aiir rev: v1.2.4 hooks: - id: aiir ``` 在 **post-commit** 阶段运行（在您的 commit 创建之后，因为它需要 commit SHA 来生成收据）。使用参数自定义： ``` - id: aiir args: ["--ai-only", "--output", ".receipts"] ``` ### 🦊 GitLab CI —— 为 merge requests 和 pushes 生成收据 **CI/CD Catalog component**（推荐 —— [browse in Catalog](https://gitlab.com/explore/catalog/invariant-systems/aiir)）： ``` # .gitlab-ci.yml — 单行 include: - component: gitlab.com/invariant-systems/aiir/receipt@1 inputs: stage: test ``` 所有输入都是可选的且有类型限制： | Input | Type | Default | Description | |-------|------|---------|-------------| | `stage` | string | `test` | Pipeline stage | | `version` | string | `1.2.4` | AIIR version from PyPI | | `ai-only` | boolean | `false` | Only receipt AI-authored commits | | `output-dir` | string | `.aiir-receipts` | Artifact output directory | | `artifact-expiry` | string | `90 days` | Artifact retention | | `sign` | boolean | `true` | Sigstore keyless signing (GitLab OIDC) | | `gl-sast-report` | boolean | `false` | Generate SAST report for Security Dashboard | | `approval-threshold` | number | `0` | AI% threshold for extra MR approvals (0 = off) | | `extra-args` | string | `""` | Additional CLI flags | **Legacy include**（仍然有效 —— 无需 Catalog）： ``` include: - remote: 'https://raw.githubusercontent.com/invariant-systems-ai/aiir/v1.2.4/templates/gitlab-ci.yml' ``` **Self-hosted GitLab?** 镜像仓库并使用 `project:` 代替： ``` include: - project: 'your-group/aiir' ref: 'v1.2.4' file: '/templates/gitlab-ci.yml' ``` 通过 pipeline 变量自定义：`AIIR_VERSION`、`AIIR_AI_ONLY`、`AIIR_EXTRA_ARGS`、`AIIR_ARTIFACT_EXPIRY`。完整模板请参阅 [templates/gitlab-ci.yml](templates/gitlab-ci.yml)。 ### 🐳 Docker —— 在任何地方运行 ``` # 为当前 Repo 开具 Receipt (将其挂载进来) docker run --rm -v "$(pwd):/repo" -w /repo invariantsystems/aiir --pretty # 仅 AI，保存 Receipts docker run --rm -v "$(pwd):/repo" -w /repo invariantsystems/aiir --ai-only --output .receipts/ ``` 适用于任何支持容器步骤的 CI/CD 系统 —— Tekton、Buildkite、Drone、Woodpecker 等。 ### 更多 CI/CD 平台

Bitbucket Pipelines

``` # bitbucket-pipelines.yml pipelines: default: - step: name: AIIR Receipt image: python:3.11 script: - pip install aiir - aiir --pretty --output .receipts/ artifacts: - .receipts/** ``` 支持 PR 的完整模板：[templates/bitbucket-pipelines.yml](templates/bitbucket-pipelines.yml)

Azure DevOps

``` # azure-pipelines.yml steps: - task: UsePythonVersion@0 inputs: { versionSpec: '3.11' } - script: pip install aiir && aiir --pretty --output .receipts/ displayName: 'Generate AIIR receipt' - publish: .receipts/ artifact: aiir-receipts ``` 支持 PR/CI 检测的完整模板：[templates/azure-pipelines.yml](templates/azure-pipelines.yml)

CircleCI

``` # .circleci/config.yml jobs: receipt: docker: - image: cimg/python:3.11 steps: - checkout - run: pip install aiir && aiir --pretty --output .receipts/ - store_artifacts: path: .receipts ``` 完整模板：[templates/circleci/config.yml](templates/circleci/config.yml)

Jenkins

``` // Jenkinsfile pipeline { agent { docker { image 'python:3.11' } } stages { stage('AIIR Receipt') { steps { sh 'pip install aiir && aiir --pretty --output .receipts/' archiveArtifacts artifacts: '.receipts/**' } } } } ``` 完整模板：[templates/jenkins/Jenkinsfile](templates/jenkins/Jenkinsfile)

## 检测内容 AIIR 检测 commit 元数据中的三类信号： ### 声明的 AI 辅助 由人类或工具明确归因于 AI 参与的 commits。 | Signal | Examples | |--------|----------| | **Copilot** | `Co-authored-by: Copilot`, `Co-authored-by: GitHub Copilot` | | **ChatGPT** | `Generated by ChatGPT`, `Co-authored-by: ChatGPT` | | **Claude** | `Generated by Claude`, `Co-authored-by: Claude` | | **Cursor** | `Generated by Cursor`, `Co-authored-by: Cursor` | | **Amazon Q / CodeWhisperer** | `amazon q`, `codewhisperer`, `Co-authored-by: Amazon Q` | | **Devin** | `Co-authored-by: Devin`, `devin[bot]` | | **Gemini** | `gemini code assist`, `google gemini`, `gemini[bot]` | | **GitLab Duo** | `gitlab duo`, `duo code suggestions`, `duo chat`, `duo enterprise`, `Co-authored-by: gitlab duo` | | **Tabnine** | `tabnine` in commit metadata | | **Aider** | `aider:` prefix in commit messages | | **Generic markers** | `AI-generated`, `LLM-generated`, `machine-generated` | | **Git trailers** | `Generated-by:`, `AI-assisted:`, `Tool:` git trailers | ### 自动化 / bot 活动 由 CI bots 和自动化依赖工具进行的 commits。这些*不是*生成式 AI 辅助 —— 它们表示自动化（非人类）的创作。 | Signal | Examples | |--------|----------| | **Dependabot** | `dependabot[bot]` as author | | **Renovate** | `renovate[bot]` as author | | **Snyk** | `snyk-bot` as author | | **CodeRabbit** | `coderabbit[bot]` as author | | **GitHub Actions** | `github-actions[bot]` as author | | **GitLab Bot** | `gitlab-bot` as author | | **DeepSource** | `deepsource[bot]` as author |

检测范围和局限性

AI 检测使用 `heuristic_v2` —— 匹配 commit 元数据信号。 **能检测到的：** - 带有 `Co-authored-by: Copilot` 或类似 trailers 的 commits - Bot 创作的 commits（Dependabot, Renovate）—— 单独分类为 `bot` - 显式的 AI 标记（`AI-generated`, `Generated by ChatGPT` 等） **不能检测到的：** - Copilot 内联补全（默认无元数据痕迹） - ChatGPT/Claude 复制粘贴且未注明出处 - Squash-merged 的 AI 分支且带有干净的消息 - 修改过并移除了 AI trailers 的 commits 这是设计使然 —— AIIR 对*已声明*的内容开具收据，而不是对隐藏的内容。收据证明的是所记录内容的完整性，而非 AI 参与的完整性。

## 深入了解

Ledger — .aiir/ directory

默认情况下，`aiir` 将收据追加到本地 JSONL 账本： ``` .aiir/ ├── receipts.jsonl # One receipt per line (append-only) └── index.json # Auto-maintained lookup index ``` **为什么用账本？** - **一个文件即可提交** —— `git add .aiir/` 就是您的完整审计追踪 - **自动去重** —— 在同一个 commit 上重新运行 `aiir` 是无操作的 - **对 Git 友好** —— 仅追加的 JSONL 意味着干净的差异和简单的 `git blame` - **可查询** —— `jq`、`grep` 和 `wc -l` 都可以自然工作 **index.json** 跟踪每个 commit SHA、收据计数和作者细分： ``` { "version": 1, "receipt_count": 42, "ai_commit_count": 7, "bot_commit_count": 3, "ai_percentage": 16.7, "unique_authors": 5, "first_receipt": "2026-03-01T10:00:00Z", "latest_timestamp": "2026-03-06T09:48:59Z", "commits": { "c4dec85630...": { "receipt_id": "g1-a3f8...", "ai": true, "bot": false, "authorship_class": "ai_assisted", "author": "jane@example.com" }, "e7b1a9f203...": { "receipt_id": "g1-b2c1...", "ai": false, "bot": true, "authorship_class": "bot", "author": "dependabot[bot]" } } } ``` **输出模式：** | Flag | Behaviour | |------|-----------| | *(none)* | Append to `.aiir/receipts.jsonl` (default) | | `--ledger .audit/` | Append to custom ledger directory | | `--json` | Print JSON to stdout — no ledger write | | `--jsonl` | Print JSON Lines to stdout — no ledger write* | | `--output dir/` | Write individual files to `dir/` — no ledger write* | | `--pretty` | Human-readable summary to stderr (combines with any mode) | \* 显式添加 `--ledger` 会覆盖并写入**两个**目的地。 **提示**：将 `.aiir/` 添加到您的仓库。它将成为每个已开具收据的 commit 的永久、可审计、仅追加的记录。

收据格式

每个收据都是一个内容寻址的 JSON 文档： ``` { "type": "aiir.commit_receipt", "schema": "aiir/commit_receipt.v1", "receipt_id": "g1-a3f8b2c1d4e5f6a7b8c9d0e1f2a3b4", "content_hash": "sha256:7f3a...", "timestamp": "2026-03-06T09:48:59Z", "commit": { "sha": "c4dec85630232666aba81b6588894a11d07e5d18", "author": { "name": "Jane Dev", "email": "jane@example.com" }, "subject": "feat: add receipt generation to CI", "diff_hash": "sha256:b2c1...", "files_changed": 4 }, "ai_attestation": { "is_ai_authored": true, "signals_detected": ["message_match:co-authored-by: copilot"], "signal_count": 1, "is_bot_authored": false, "bot_signals_detected": [], "bot_signal_count": 0, "authorship_class": "ai_assisted", "detection_method": "heuristic_v2" }, "extensions": {} } ``` **内容寻址** = `receipt_id` 派生自收据规范 JSON 的 SHA-256。更改任何字段 → 哈希值更改 → 收据无效。

GitHub Action — inputs & outputs

### Inputs | Input | Description | Default | |-------|-------------|---------| | `ai-only` | Only receipt AI-authored commits | `false` | | `commit-range` | Specific commit range (e.g., `main..HEAD`) | Auto-detected from event | | `output-dir` | Directory to write receipt JSON files | *(prints to log)* | | `sign` | Sign receipts with Sigstore | `true` | ### Outputs | Output | Description | |--------|-------------| | `receipt_count` | Number of receipts generated | | `ai_commit_count` | Number of AI-authored commits detected | | `receipts_json` | Full JSON array of all receipts (set to `"OVERFLOW"` if >1 MB) | | `receipts_overflow` | `"true"` when `receipts_json` exceeded 1 MB and was truncated | ### 示例：带有 AI 摘要的 PR 评论 ``` name: AI Audit Trail on: pull_request jobs: receipt: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: invariant-systems-ai/aiir@v1 id: receipt with: output-dir: .receipts/ - name: Comment on PR if: steps.receipt.outputs.ai_commit_count > 0 uses: actions/github-script@v7 with: script: | const count = '${{ steps.receipt.outputs.ai_commit_count }}'; const total = '${{ steps.receipt.outputs.receipt_count }}'; github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: `🔐 **AIIR**: ${total} commits receipted, ${count} AI-authored.\n\nReceipts uploaded as build artifacts.` }); ``` ### 示例：强制执行 Receipt Policy ``` name: Require AI Receipts on: pull_request jobs: receipt-gate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: invariant-systems-ai/aiir@v1 id: receipt - name: Enforce receipt policy if: steps.receipt.outputs.ai_commit_count > 0 run: | echo "✅ ${{ steps.receipt.outputs.ai_commit_count }} AI commits receipted" ```

Sigstore signing

可选择使用 [Sigstore](https://sigstore.dev) 无密钥签名对收据进行签名，以实现加密不可否认性： ``` name: AIIR (Signed) on: push: tags-ignore: ['**'] pull_request: permissions: id-token: write contents: read jobs: receipt: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: invariant-systems-ai/aiir@v1 with: output-dir: .receipts/ sign: true ``` 每个收据都会获得一个附带的 `.sigstore` bundle： - **Fulcio certificate** —— 证明签名者 OIDC 身份的短期证书 - **Rekor transparency log** —— 防篡改的公共记录 - **Signature** —— 加密绑定 本地验证： ``` # 基础：检查签名是否有效 (任意签名者) aiir --verify receipt.json --verify-signature # 推荐：绑定到特定的 CI identity 以实现不可否认性 aiir --verify receipt.json --verify-signature \ --signer-identity "https://github.com/myorg/myrepo/.github/workflows/aiir.yml@refs/heads/main" \ --signer-issuer "https://token.actions.githubusercontent.com" ``` 安装签名支持：`pip install aiir[sign]`

MCP server details

AIIR MCP server 暴露七个工具： | Tool | Description | |------|-------------| | `aiir_receipt` | Generate receipts for commit(s). Accepts `commit`, `range`, `ai_only`, `pretty`. | | `aiir_verify` | Verify a receipt file's integrity. Accepts `file` path. | | `aiir_stats` | Ledger statistics: receipt count, AI percentage, unique authors. | | `aiir_explain` | Human-readable explanation of verification results. | | `aiir_policy_check` | Check ledger against org AI-usage policy thresholds. | | `aiir_verify_release` | Release-scoped verification — evaluate receipts against policy, emit VSA. | | `aiir_gitlab_summary` | GitLab-flavored Markdown summary for Duo Chat, MR comments, and CI. | **Install globally:** ``` pip install aiir ``` **Claude Desktop** (`claude_desktop_config.json`): ``` { "mcpServers": { "aiir": { "command": "aiir-mcp-server", "args": ["--stdio"] } } } ``` **VS Code / Copilot** (`.vscode/mcp.json`): ``` { "servers": { "aiir": { "command": "aiir-mcp-server", "args": ["--stdio"] } } } ``` **Cursor** (`.cursor/mcp.json`): ``` { "mcpServers": { "aiir": { "command": "aiir-mcp-server", "args": ["--stdio"] } } } ``` **Continue** (`.continue/mcpServers/aiir.yaml`): ``` name: AIIR version: 0.0.1 schema: v1 mcpServers: - name: aiir command: aiir-mcp-server args: - --stdio ``` Or copy any JSON MCP config (e.g., from Claude Desktop) into `.continue/mcpServers/mcp.json` — Continue auto-discovers it. **Cline** (open MCP Servers panel → add to `cline_mcp_settings.json`): ``` { "mcpServers": { "aiir": { "command": "aiir-mcp-server", "args": ["--stdio"] } } } ``` **Windsurf** (`~/.codeium/windsurf/mcp_config.json`): ``` { "mcpServers": { "aiir": { "command": "aiir-mcp-server", "args": ["--stdio"] } } } ``` 服务器使用与 CLI 相同的零依赖核心。不需要额外的包。

Release verification & VSA

根据策略验证整个 release 并生成机器可读的 [Verification Summary Attestation (VSA)](https://slsa.dev/verification_summary)： ``` # 根据严格的 Policy 验证 Receipts，生成 VSA aiir --verify-release --receipts .aiir/receipts.jsonl --policy strict --emit-vsa # VSA 的自定义 subject (例如，OCI image digest) aiir --verify-release --receipts .aiir/receipts.jsonl \ --subject 'oci://ghcr.io/myorg/app@sha256:abc123...' --emit-vsa aiir-vsa.intoto.jsonl ``` VSA 是一个 [in-toto Statement v1](https://in-toto.io/Statement/v1)，带有 `https://slsa.dev/verification_summary/v1` 谓词，记录了： - **Verifier identity** —— 谁运行了检查 - **Policy digest** —— 被评估策略的 SHA-256 - **Coverage metrics** —— commit 覆盖率百分比，AI/bot/human 细分 - **Pass/fail result** —— 每个收据和聚合评估 策略预设：`strict`（硬性失败，需要签名，最大 50% AI）、`balanced`（软性失败，建议签名）、`permissive`（仅警告）。通过 `.aiir/policy.json` 自定义。

Policy engine

在 CI 中强制执行组织 AI 使用策略： ``` # 从预设初始化 Policy 文件 aiir --policy-init strict # creates .aiir/policy.json aiir --policy-init balanced aiir --policy-init permissive # 针对 Ledger 运行 Policy 检查 aiir --check --policy strict # 快速关卡：如果 AI 编写的百分比超过阈值则失败 aiir --check --max-ai-percent 50 ``` 三个预设： | Preset | Enforcement | Signing | Max AI % | Use case | |--------|-------------|---------|----------|----------| | `strict` | Hard-fail | Required | 50% | Regulated industries, SOC 2, EU AI Act | | `balanced` | Soft-fail | Recommended | 80% | Most teams — catches issues without blocking | | `permissive` | Warn-only | Optional | 100% | Early adoption, experimentation | 每个收据的检查：签名状态、来源仓库、作者类别、模式有效性。 聚合检查：AI commit 百分比上限。 将 `.aiir/policy.json` 提交到您的仓库，以便每个贡献者和 CI 运行都使用相同的规则。

Agent attestation

附加上下文元数据以识别哪个 AI 工具生成了一个 commit： ``` aiir --agent-tool copilot --agent-model gpt-4o --agent-context ide aiir --agent-tool cursor --agent-model claude-sonnet-4-20250514 --agent-context ide aiir --agent-tool claude-code --agent-context cli ``` 存储在 `extensions.agent_attestation` 中（不属于内容哈希的一部分 —— 添加或更改 agent 元数据不会使收据无效）： ``` { "extensions": { "agent_attestation": { "tool_id": "copilot", "model_class": "gpt-4o", "run_context": "ide" } } } ``` 六个允许列表中的键：`tool_id`、`model_class`、`session_id`、`run_context`、`tool_version`、`confidence`。所有值都经过清理（字符串强制转换，200 字符上限）。

in-toto Statement wrapping

将收据包装在标准的 [in-toto Statement v1](https://in-toto.io/Statement/v1) 信封中，以兼容供应链证明生态系统： ``` # 将 Receipt 包装在 in-toto envelope 中 aiir --in-toto --output .receipts/ # 结合签名以实现完整证明 aiir --sign --in-toto --output .receipts/ ``` 谓词类型为 `https://aiir.dev/commit_receipt/v1`。主体通过仓库 URL 和 SHA 识别 git commit。这使得 AIIR 收据原生适用于： - **SLSA** 验证者 - **Sigstore** policy-controller - **Kyverno** / **OPA/Gatekeeper** 准入策略 - **Tekton Chains** 供应链安全

检测内部机制

完整的 STRIDE 分析、DREAD 评分和攻击树请参阅 [THREAT_MODEL.md](THREAT_MODEL.md)。 同形异义字检测使用完整的 [Unicode TR39 confusable map](https://www.unicode.org/reports/tr39/) —— 跨 69 个脚本（Cyrillic、Greek、Armenian、Cherokee、Coptic、Lisu、Warang Citi、Mathematical 等）的 669 个单码点 → ASCII 映射。结合 NFKC 规范化，这涵盖了 Unicode 联盟记录的所有单字符同形异义字。不涵盖多字符易混淆序列 —— 请参阅威胁模型中的 S-02。

## 验证点 以下所有内容都是可验证的。没有隐藏在登录后的推荐信 —— 只有您可以自己审计的公开制品。 | Proof | What it proves | Verify it | |-------|---------------|-----------| | **This repo receipts itself** | Dogfood — AIIR generates its own receipts on every push to `main` | `for f in .receipts/*.json; do aiir --verify "$f"; done` | | **1600+ tests, 100% coverage** | Every release passes Python 3.9–3.13 × Ubuntu/macOS/Windows | [CI runs](https://github.com/invariant-systems-ai/aiir/actions/workflows/ci.yml) | | **25 conformance test vectors** | Third-party implementors can verify their hashing against ours | [schemas/test_vectors.json](schemas/test_vectors.json) | | **Public threat model** | Full STRIDE/DREAD analysis — we show attackers what we defend against | [THREAT_MODEL.md](THREAT_MODEL.md) | | **SLSA provenance on every release** | PyPI wheel has a verifiable build attestation | `gh attestation verify aiir-*.whl --repo invariant-systems-ai/aiir` | | **OpenSSF Scorecard** | Automated security health assessment (branch protection, SAST, signing) | [Scorecard](https://scorecard.dev/viewer/?uri=github.com/invariant-systems-ai/aiir) | | **CycloneDX SBOM on every release** | Machine-readable bill of materials attached to every GitHub Release | [Latest release](https://github.com/invariant-systems-ai/aiir/releases/latest) → `aiir-sbom.cdx.json` | | **Zero dependencies** | Nothing to compromise — `pip show aiir` shows `Requires:` empty | `pip install aiir && pip show aiir` | | **Browser verifier** | Client-side receipt verification — no upload, no account, no server | [invariantsystems.io/verify](https://invariantsystems.io/verify) | [dogfood CI workflow](.github/workflows/dogfood.yml) 在每次推送到 `main` 时生成收据， 并将它们提交回 `.receipts/`。在本地，[pre-commit hook](.pre-commit-config.yaml) 在 `post-commit` 阶段为每个 commit 开具收据。 ## 安全性 广泛的 [security controls](THREAT_MODEL.md)。1600+ 测试。零依赖。 请参阅 [SECURITY.md](SECURITY.md)、[THREAT_MODEL.md](THREAT_MODEL.md) 和 [Tamper Detection](docs/tamper-detection.md)。 ### 信任层级 收据存在于三个信任级别。根据您的用例选择合适的级别： | Tier | What you get | Use when | |------|-------------|----------| | **Unsigned** (`sign: false`) | Tamper-evident — hash integrity detects modification, but anyone can recreate a matching receipt from the same commit | Local development, smoke testing, internal audit trails | | **Signed** (`sign: true`, default) | Tamper-proof — Sigstore signature binds the *entire* receipt (including extensions) to an OIDC identity via a transparency log | CI/CD compliance, SOC 2 evidence, regulatory audit | | **Enveloped** (in-toto Statement) | Signed + wrapped in a supply-chain attestation envelope with explicit subject and predicate binding | SLSA provenance, cross-system verification, EU AI Act evidence packages | ## 规范与模式 AIIR 为第三方实现者发布正式规范和机器可读模式： | Document | Purpose | |----------|---------| | [SPEC.md](SPEC.md) | Normative specification — canonical JSON, content addressing, verification algorithm (RFC 2119) | | [schemas/commit_receipt.v1.schema.json](schemas/commit_receipt.v1.schema.json) | JSON Schema (draft 2020-12) for `aiir/commit_receipt.v1` | | [schemas/verification_summary.v1.schema.json](schemas/verification_summary.v1.schema.json) | JSON Schema for the Verification Summary Attestation (VSA) predicate | | [schemas/test_vectors.json](schemas/test_vectors.json) | 25 conformance test vectors with precomputed hashes | | [THREAT_MODEL.md](THREAT_MODEL.md) | STRIDE/DREAD threat model with comprehensive security controls | | [docs/tamper-detection.md](docs/tamper-detection.md) | Walkthrough — what happens when a receipt is modified | ## 关于 由 [Invariant Systems, Inc.](https://invariantsystems.io) 构建 **License**: Apache-2.0 — See [LICENSE](LICENSE) **Trademarks**: "AIIR", "AI Integrity Receipts", and "Invariant Systems" are trademarks of Invariant Systems, Inc. See [TRADEMARK.md](TRADEMARK.md). **Signed releases**: Every PyPI release is published using [Trusted Publishers](https://docs.pypi.org/trusted-publishers/) (OIDC) — no static API tokens. The GitHub Actions workflow authenticates to PyPI via short-lived OIDC tokens issued by GitHub's identity provider. This means: - **No secrets to leak** — publishing credentials are ephemeral - **Verifiable provenance** — each release is tied to a specific GitHub Actions run, commit SHA, and workflow file - **Tamper-resistant pipeline** — the publish environment is protected by GitHub's deployment protection rules The [publish workflow](.github/workflows/publish.yml) runs: tag push → full test suite → build → OIDC publish → verify on PyPI. **Enterprise**: The AIIR open-source library is and will remain free under Apache-2.0. Invariant Systems may offer additional products and services (hosted verification, enterprise dashboards, SLA-backed APIs) under separate terms.

标签：AI安全, AI辅助编程, Chat Copilot, DevSecOps, DNS 反向解析, GitHub Actions, Git提交, Python, SBOM, SLSA, VSA验证, 上游代理, 代码完整性, 代码签名, 可验证性, 威胁情报, 密码学收据, 开发者工具, 文档安全, 无后门, 溯源, 硬件无关, 网络安全, 自动笔记, 跌倒检测, 软件开发工具包, 软件物料清单, 逆向工具, 隐私保护, 零依赖