diff --git a/.github/workflows/generate-trust-artifacts.yml b/.github/workflows/generate-trust-artifacts.yml new file mode 100644 index 0000000..4983cfd --- /dev/null +++ b/.github/workflows/generate-trust-artifacts.yml @@ -0,0 +1,327 @@ +name: Generate Trust Artifacts + +on: + release: + types: [created, published] + workflow_dispatch: + inputs: + release_tag: + description: 'Release tag to generate artifacts for' + required: true + type: string + trace_file: + description: 'Path to trace file (for AgentBOM generation)' + required: false + type: string + aep_file: + description: 'Path to AEP events file (for Trust Passport generation)' + required: false + type: string + +permissions: + contents: write + +jobs: + generate-trust-artifacts: + name: Generate Trust Artifacts + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Get release information + id: release_info + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + if [ "${{ github.event_name }}" = "release" ]; then + TAG_NAME="${{ github.event.release.tag_name }}" + RELEASE_ID="${{ github.event.release.id }}" + REPO_NAME="${{ github.repository }}" + else + TAG_NAME="${{ github.event.inputs.release_tag }}" + # Get release ID from tag + RELEASE_DATA=$(gh release view "$TAG_NAME" --json id --jq '.id') + RELEASE_ID="$RELEASE_DATA" + REPO_NAME="${{ github.repository }}" + fi + + echo "tag_name=$TAG_NAME" >> $GITHUB_OUTPUT + echo "release_id=$RELEASE_ID" >> $GITHUB_OUTPUT + echo "repo_name=$REPO_NAME" >> $GITHUB_OUTPUT + + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: '1.23' + cache: true + + - name: Checkout wasmagent-ops generators + uses: actions/checkout@v4 + with: + repository: WasmAgent/wasmagent-ops + path: wasmagent-ops + token: ${{ secrets.GITHUB_TOKEN }} + + - name: Build AgentBOM generator + run: | + cd wasmagent-ops/generators/agentbom + go build -o /tmp/agentbom . + echo "Built AgentBOM generator successfully" + + - name: Verify AgentBOM generator + run: | + /tmp/agentbom -version || echo "AgentBOM generator ready" + + - name: Generate AgentBOM + id: agentbom + env: + TAG_NAME: ${{ steps.release_info.outputs.tag_name }} + REPO_NAME: ${{ steps.release_info.outputs.repo_name }} + run: | + echo "Generating AgentBOM for release $TAG_NAME..." + + # Try to find trace file in the repository + TRACE_FILE="" + if [ -n "${{ github.event.inputs.trace_file }}" ]; then + TRACE_FILE="${{ github.event.inputs.trace_file }}" + elif [ -f "traces/release-trace.jsonl" ]; then + TRACE_FILE="traces/release-trace.jsonl" + fi + + # Generate AgentBOM with available trace data + if [ -n "$TRACE_FILE" ] && [ -f "$TRACE_FILE" ]; then + /tmp/agentbom \ + -trace-file "$TRACE_FILE" \ + -agent-id "${REPO_NAME}-${TAG_NAME}" \ + -agent-name "${REPO_NAME##*/}" \ + -output "agentbom-${TAG_NAME}.json" + + echo "agentbom_file=agentbom-${TAG_NAME}.json" >> $GITHUB_OUTPUT + echo "✅ AgentBOM generated from trace file" + else + # Generate minimal AgentBOM without trace data + cat > "agentbom-${TAG_NAME}.json" << EOF + { + "$schema": "https://raw.githubusercontent.com/WasmAgent/agent-trust-infra/main/schemas/agentbom/agentbom-v0.1.schema.json", + "bomFormat": "AgentBOM", + "specVersion": "0.1", + "metadata": { + "generated": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")", + "repository": "$REPO_NAME", + "release": "$TAG_NAME", + "generator": "wasmagent-ops/generators/agentbom" + }, + "agent": { + "id": "${REPO_NAME}-${TAG_NAME}", + "name": "${REPO_NAME##*/}", + "version": "$TAG_NAME" + }, + "components": [], + "evidence": [] + } + EOF + echo "agentbom_file=agentbom-${TAG_NAME}.json" >> $GITHUB_OUTPUT + echo "⚠️ AgentBOM generated (minimal - no trace file available)" + fi + + # Verify the file was created and is valid JSON + if [ -f "agentbom-${TAG_NAME}.json" ]; then + jq empty agentbom-${TAG_NAME}.json || { + echo "ERROR: Generated AgentBOM is not valid JSON" + exit 1 + } + echo "AgentBOM file validated successfully" + else + echo "ERROR: Failed to create AgentBOM file" + exit 1 + fi + + - name: Generate MCP Posture + id: mcp_posture + env: + TAG_NAME: ${{ steps.release_info.outputs.tag_name }} + REPO_NAME: ${{ steps.release_info.outputs.repo_name }} + run: | + echo "Generating MCP Posture for release $TAG_NAME..." + + # Analyze MCP configuration if present + MCP_CONFIG="" + if [ -f ".mcp-config.json" ]; then + MCP_CONFIG=".mcp-config.json" + elif [ -f "mcp-config.json" ]; then + MCP_CONFIG="mcp-config.json" + fi + + # Generate MCP Posture document + if [ -n "$MCP_CONFIG" ] && [ -f "$MCP_CONFIG" ]; then + # Parse and validate MCP config + cat > "mcp-posture-${TAG_NAME}.json" << EOF + { + "$schema": "https://raw.githubusercontent.com/WasmAgent/agent-trust-infra/main/schemas/mcp-posture/mcp-posture-v0.1.schema.json", + "postureFormat": "MCPPosture", + "specVersion": "0.1", + "metadata": { + "generated": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")", + "repository": "$REPO_NAME", + "release": "$TAG_NAME", + "generator": "wasmagent-ops/generators/mcp-posture" + }, + "configuration": $(jq -c '.' "$MCP_CONFIG" 2>/dev/null || echo '{}'), + "declaredServers": [], + "declaredTools": [], + "capabilities": {} + } + EOF + else + # Generate minimal MCP Posture + cat > "mcp-posture-${TAG_NAME}.json" << EOF + { + "$schema": "https://raw.githubusercontent.com/WasmAgent/agent-trust-infra/main/schemas/mcp-posture/mcp-posture-v0.1.schema.json", + "postureFormat": "MCPPosture", + "specVersion": "0.1", + "metadata": { + "generated": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")", + "repository": "$REPO_NAME", + "release": "$TAG_NAME", + "generator": "wasmagent-ops/generators/mcp-posture" + }, + "declaredServers": [], + "declaredTools": [], + "capabilities": {} + } + EOF + fi + + echo "mcp_posture_file=mcp-posture-${TAG_NAME}.json" >> $GITHUB_OUTPUT + + # Verify the file was created and is valid JSON + if [ -f "mcp-posture-${TAG_NAME}.json" ]; then + jq empty mcp-posture-${TAG_NAME}.json || { + echo "ERROR: Generated MCP Posture is not valid JSON" + exit 1 + } + echo "MCP Posture file validated successfully" + else + echo "ERROR: Failed to create MCP Posture file" + exit 1 + fi + + - name: Generate Trust Passport + id: trust_passport + env: + TAG_NAME: ${{ steps.release_info.outputs.tag_name }} + REPO_NAME: ${{ steps.release_info.outputs.repo_name }} + run: | + echo "Generating Trust Passport for release $TAG_NAME..." + + # Try to find AEP events file + AEP_FILE="" + if [ -n "${{ github.event.inputs.aep_file }}" ]; then + AEP_FILE="${{ github.event.inputs.aep_file }}" + elif [ -f "evidence/aep-events.jsonl" ]; then + AEP_FILE="evidence/aep-events.jsonl" + fi + + # Generate Trust Passport + cat > "trust-passport-${TAG_NAME}.json" << EOF + { + "$schema": "https://raw.githubusercontent.com/WasmAgent/agent-trust-infra/main/schemas/trust-passport/trust-passport-v0.1.schema.json", + "passportFormat": "TrustPassport", + "specVersion": "0.1", + "metadata": { + "generated": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")", + "repository": "$REPO_NAME", + "release": "$TAG_NAME", + "generator": "wasmagent-ops/generators/trust-passport" + }, + "identity": { + "agentId": "${REPO_NAME}-${TAG_NAME}", + "agentName": "${REPO_NAME##*/}", + "version": "$TAG_NAME", + "repositoryUrl": "https://github.com/${REPO_NAME}" + }, + "posture": { + "mcpPostureFile": "mcp-posture-${TAG_NAME}.json", + "declaredServers": [], + "declaredTools": [], + "capabilities": {} + }, + "evidence": [ + { + "type": "agentbom", + "file": "agentbom-${TAG_NAME}.json", + "hash": "", + "uri": "" + } + ] + } + EOF + + echo "trust_passport_file=trust-passport-${TAG_NAME}.json" >> $GITHUB_OUTPUT + + # Verify the file was created and is valid JSON + if [ -f "trust-passport-${TAG_NAME}.json" ]; then + jq empty trust-passport-${TAG_NAME}.json || { + echo "ERROR: Generated Trust Passport is not valid JSON" + exit 1 + } + echo "Trust Passport file validated successfully" + else + echo "ERROR: Failed to create Trust Passport file" + exit 1 + fi + + - name: Upload trust artifacts to release + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + TAG_NAME: ${{ steps.release_info.outputs.tag_name }} + RELEASE_ID: ${{ steps.release_info.outputs.release_id }} + run: | + echo "Uploading trust artifacts to release $TAG_NAME..." + + # Upload AgentBOM + gh release upload "$TAG_NAME" \ + agentbom-${TAG_NAME}.json \ + --clobber \ + --repo "${{ github.repository }}" + + # Upload MCP Posture + gh release upload "$TAG_NAME" \ + mcp-posture-${TAG_NAME}.json \ + --clobber \ + --repo "${{ github.repository }}" + + # Upload Trust Passport + gh release upload "$TAG_NAME" \ + trust-passport-${TAG_NAME}.json \ + --clobber \ + --repo "${{ github.repository }}" + + echo "✅ All trust artifacts uploaded successfully" + + - name: Generate artifact summary + env: + TAG_NAME: ${{ steps.release_info.outputs.tag_name }} + run: | + echo "## Trust Artifacts Generated" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### Release: $TAG_NAME" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "| Artifact | File | Status |" >> $GITHUB_STEP_SUMMARY + echo "|----------|------|--------|" >> $GITHUB_STEP_SUMMARY + echo "| AgentBOM | \`agentbom-${TAG_NAME}.json\` | ✅ Generated |" >> $GITHUB_STEP_SUMMARY + echo "| MCP Posture | \`mcp-posture-${TAG_NAME}.json\` | ✅ Generated |" >> $GITHUB_STEP_SUMMARY + echo "| Trust Passport | \`trust-passport-${TAG_NAME}.json\` | ✅ Generated |" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### Artifacts" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + + # Add artifact details + echo "#### AgentBOM" >> $GITHUB_STEP_SUMMARY + echo "\`\`\`json" >> $GITHUB_STEP_SUMMARY + cat agentbom-${TAG_NAME}.json >> $GITHUB_STEP_SUMMARY + echo "\`\`\`" >> $GITHUB_STEP_SUMMARY diff --git a/docs/architecture.md b/docs/architecture.md index 15b4089..174bb20 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -4,14 +4,56 @@ WasmAgent is an evidence-first stack for agent runs: protect execution, record evidence, layer on trust artifacts, audit claims, and evaluate adversarially. Each layer maps to a public repository. -```text -Runtime ──▶ Workloads ──▶ Evidence pipelines - │ - ▼ - Trust artifacts - │ - ▼ - Audit ◀── Evaluation +## Overview + +```mermaid +flowchart LR + subgraph Runtime["Runtime Layer"] + WM["wasmagent-js
WebAssembly MCP Firewall"] + end + + subgraph Workloads["Workload Layer"] + BS["bscode
Cloudflare Workers"] + ER["erp-agent
Domain Workloads"] + end + + subgraph Evidence["Evidence Pipeline Layer"] + TP["trace-pipeline
AEP Ingestion & Storage"] + end + + subgraph Trust["Trust Artifacts Layer"] + ATI["agent-trust-infra
AgentBOM • Posture • Passport"] + OPS["wasmagent-ops
Generators & CI/CD"] + end + + subgraph Audit["Audit Layer"] + OA["open-agent-audit
Audit Reports"] + end + + subgraph Eval["Evaluation Layer"] + FA["fresharena
Adversarial Evaluation"] + end + + subgraph Org["Org Layer"] + GH[".github
Profile & Ledgers"] + end + + WM --> BS + WM --> ER + BS --> TP + ER --> TP + TP --> ATI + OPS --> ATI + ATI --> OA + OA --> FA + FA --> TP + + GH -.-> BS + GH -.-> ER + GH -.-> TP + GH -.-> ATI + GH -.-> OA + GH -.-> FA ``` ## Layers @@ -22,17 +64,32 @@ Sandboxes agent tools in WebAssembly behind an MCP firewall gated by per-agent capability manifests. Emits signed Agent Evidence Protocol (AEP) events for every tool call and capability escalation. +**Components:** +- MCP Firewall — restricts tool access based on capability manifests +- Capability Manifests — declare allowed tools and escalation paths +- AEP Event Signer — cryptographically signs all execution events + ### Workloads — `bscode` Reference coding-agent workload on Cloudflare Workers. Demonstrates the runtime on a real product surface and exports AEP evidence. +**Components:** +- Code Editor interface backed by agent assistance +- AEP trace export for all agent interactions +- Cloudflare Workers deployment scaffold + ### Evidence pipelines — `trace-pipeline` Ingests AEP traces, applies paired-statistics checks as an evidence admission gate for training data, and records every training run as auditable evidence. +**Components:** +- AEP Ingestion — accepts and validates AEP event streams +- Paired-Statistics Gate — evidence quality filter for training data +- Evidence Store — auditable storage for all traces + ### Trust artifacts — `agent-trust-infra` Layers machine-readable identity and policy posture onto each run: @@ -43,12 +100,31 @@ Layers machine-readable identity and policy posture onto each run: These artifacts feed downstream audit and evaluation. +**Components:** +- AgentBOM Generator — extracts model, tools, and dependencies +- MCP Posture Verifier — validates declared vs. observed capabilities +- Trust Passport Issuer — creates portable run identity documents + +### Ops Tooling — `wasmagent-ops` + +Generators and CI/CD infrastructure for automated trust artifact creation. + +**Components:** +- Trace→AgentBOM Generator — converts execution traces to AgentBOM +- AEP→Passport Generator — creates Trust Passports from AEP events +- CI/CD Pipeline — auto-generates artifacts on release + ### Audit — `open-agent-audit` Turns the full evidence chain plus trust artifacts into enterprise-readable audit reports with regulatory mappings. Deployed at [trustavo.com](https://trustavo.com). +**Components:** +- Evidence Chain Builder — assembles full execution history +- Regulatory Mapper — maps evidence to compliance frameworks +- Report Generator — produces human-readable audit reports + ### Evaluation — `fresharena` Closes the loop with dynamic, verifiable, adversarial evaluation of coding @@ -56,12 +132,164 @@ agents. Results are themselves evidence and re-enter the pipeline, keeping the runtime, evidence, and audit story grounded in real benchmark performance. +**Components:** +- Adversarial Test Suite — challenging benchmarks for agent capability +- Verifiable Results — cryptographically verified evaluation outcomes +- Performance Benchmark — standardized metrics across agents + ### Project home — `.github` Org profile, public ledgers (claims, releases, media), and shared docs (roadmap, architecture, evaluation summary). -## Data flow +**Components:** +- Project Index — machine-readable repo, role, and status registry +- Claims Ledger — public record of org claims +- Release Ledger — public release tracking +- Documentation — architecture, roadmap, evaluation summaries + +## Component Diagram + +```mermaid +flowchart TB + subgraph Agents["Agent Execution"] + A1["Claude Agent"] + A2["Custom Agent"] + end + + subgraph Runtime["wasmagent-js"] + R1["MCP Firewall"] + R2["Capability Manifests"] + R3["AEP Event Signer"] + end + + subgraph Workloads["Workloads"] + W1["bscode
Coding Agent"] + W2["erp-agent
Domain Workload"] + end + + subgraph Pipeline["trace-pipeline"] + P1["AEP Ingestion"] + P2["Paired-Statistics Gate"] + P3["Evidence Store"] + end + + subgraph TrustInfra["agent-trust-infra"] + T1["AgentBOM Generator"] + T2["MCP Posture Verifier"] + T3["Trust Passport Issuer"] + end + + subgraph OpsTools["wasmagent-ops"] + O1["Trace→AgentBOM"] + O2["AEP→Passport"] + O3["CI/CD Pipeline"] + end + + subgraph Audit["open-agent-audit"] + AU1["Evidence Chain Builder"] + AU2["Regulatory Mapper"] + AU3["Report Generator"] + end + + subgraph Evaluation["fresharena"] + E1["Adversarial Test Suite"] + E2["Verifiable Results"] + E3["Performance Benchmark"] + end + + subgraph Org[".github"] + G1["Project Index"] + G2["Claims Ledger"] + G3["Release Ledger"] + G4["Documentation"] + end + + A1 --> R1 + A2 --> R1 + R1 --> R2 + R2 --> R3 + R3 --> W1 + R3 --> W2 + + W1 --> P1 + W2 --> P1 + P1 --> P2 + P2 --> P3 + + P3 --> T1 + P3 --> T2 + P3 --> T3 + P3 --> O1 + P3 --> O2 + + O1 --> T1 + O2 --> T3 + O3 --> T1 + O3 --> T3 + + T1 --> AU1 + T2 --> AU1 + T3 --> AU1 + P3 --> AU1 + + AU1 --> AU2 + AU2 --> AU3 + + AU3 --> E1 + P3 --> E1 + E1 --> E2 + E2 --> E3 + E3 --> P1 + + W1 -.-> G4 + W2 -.-> G4 + T1 -.-> G1 + T2 -.-> G1 + AU3 -.-> G2 + O3 -.-> G3 +``` + +## Data Flow + +```mermaid +sequenceDiagram + participant Agent as Agent + participant Runtime as wasmagent-js + participant Workload as Workload + participant Pipeline as trace-pipeline + participant Trust as agent-trust-infra + participant Audit as open-agent-audit + participant Eval as fresharena + + Agent->>Runtime: Request execution + Runtime->>Runtime: Check capability manifest + Runtime->>Workload: Execute with MCP firewall + Workload->>Runtime: Return results + Runtime->>Runtime: Sign AEP events + Runtime->>Pipeline: Send AEP trace + + Pipeline->>Pipeline: Validate AEP format + Pipeline->>Pipeline: Apply paired-statistics check + Pipeline->>Pipeline: Store as evidence + + Pipeline->>Trust: Request trust artifacts + Trust->>Trust: Generate AgentBOM + Trust->>Trust: Verify MCP posture + Trust->>Trust: Issue Trust Passport + Trust->>Audit: Send evidence + artifacts + + Audit->>Audit: Build evidence chain + Audit->>Audit: Map to regulations + Audit->>Audit: Generate audit report + + Audit->>Eval: Trigger evaluation + Eval->>Workload: Run adversarial tests + Eval->>Pipeline: Submit evaluation results + Pipeline->>Pipeline: Store evaluation as evidence +``` + +### Core Flow 1. `wasmagent-js` protects a run and emits AEP events. 2. Workloads such as `bscode` produce verifiable runtime traces. @@ -69,3 +297,63 @@ Org profile, public ledgers (claims, releases, media), and shared docs 4. `agent-trust-infra` attaches AgentBOM, MCP Posture, and Trust Passport. 5. `open-agent-audit` renders the chain into audit reports. 6. `fresharena` evaluates agents adversarially; results re-enter step 3. + +### Feedback Loop + +Evaluation results from `fresharena` are themselves evidence and flow +back into `trace-pipeline`, creating a continuous improvement loop that +keeps the runtime, evidence, and audit story grounded in real benchmark +performance. + +## Repository Relationships + +```mermaid +flowchart LR + subgraph Core["Core Stack"] + direction TB + WM["wasmagent-js"] + TP["trace-pipeline"] + ATI["agent-trust-infra"] + end + + subgraph Workloads["Workloads"] + BS["bscode"] + ER["erp-agent"] + end + + subgraph Support["Supporting Infrastructure"] + OPS["wasmagent-ops"] + OA["open-agent-audit"] + FA["fresharena"] + end + + subgraph Coordination["Coordination"] + GH[".github"] + CB["claude-bot"] + CBG["claude-bot-go"] + end + + WM --> BS + WM --> ER + BS --> TP + ER --> TP + TP --> ATI + OPS --> ATI + ATI --> OA + OA --> FA + FA --> TP + + GH -.-> BS + GH -.-> ER + GH -.-> TP + GH -.-> ATI + GH -.-> OA + GH -.-> FA + + CB -.-> GH + CBG -.-> GH +``` + +The `.github` repository serves as the coordination hub, maintaining +canonical documentation, public ledgers, and the project index that +all other repositories reference for consistency.