sigstore-a2a

# sigstore-a2a

> ⚠️ **Warning:** Prototype code - not for production use. Code is not reviewed and has not undergone a security audit.

A Python library and CLI tool for keyless signing of A2A (Agent-to-Agent) AgentCards using
[Sigstore](https://sigstore.dev/) and [SLSA](https://slsa.dev/) provenance attestations.

## Overview

This library enables verifiable supply chain security for A2A agents by providing:

- **Keyless signing** of A2A Agent Cards using Sigstore's infrastructure
- **SLSA provenance generation** to link Agent Cards to their source repositories and build workflows
- **Identity verification** to establish trust in agent origins
- **Discovery integration** for serving signed Agent Cards at well-known endpoints

## Requirements

- Python 3.11+
- UV package manager (recommended) or pip

## Installation

```bash
# Install from source using UV (recommended)
git clone https://github.com/sigstore/sigstore-a2a
cd sigstore-a2a
uv sync --prerelease=allow

# Alternative: Install from source using pip
pip install -e .
```

## Getting Started

### Signing in CI/CD

The library uses ambient OIDC credentials from CI/CD environments like GitHub Actions to perform keyless signing. This creates a verifiable link between your Agent Card and the source code repository:

```bash
# Sign an Agent Card using CI/CD OIDC credentials
sigstore-a2a sign agent-card.json --output signed-agent-card.json

# Sign with explicit repository binding
sigstore-a2a sign agent-card.json --repository $GITHUB_REPOSITORY

# Verify with repository constraint
sigstore-a2a verify signed-agent-card.json --repository owner/repo
```

### Library Usage

```python
from sigstore-a2a.signer import AgentCardSigner
from sigstore-a2a.verifier import AgentCardVerifier
from sigstore-a2a.provenance import ProvenanceBuilder

# Signing (requires OIDC credentials from CI/CD)
signer = AgentCardSigner()
provenance_builder = ProvenanceBuilder()

provenance = provenance_builder.build_provenance("agent-card.json")
signed_card = signer.sign_agent_card("agent-card.json", provenance_bundle=provenance)

# Verify a signed Agent Card
verifier = AgentCardVerifier()
result = verifier.verify_signed_card(signed_card)

if result.valid:
    print(f"Valid signature from {result.identity}")
else:
    print(f"Invalid signature: {result.errors}")
```

## Agent Card Structure

Agent Cards are extended with cryptographic verification material:

```json
{
  "agentCard": {
    "protocolVersion": "0.2.9",
    "name": "Example Agent",
    "description": "An example AI agent",
    "url": "https://example.com/agent",
    "version": "1.0.0",
    "capabilities": {...},
    "skills": [...]
  },
  "verificationMaterial": {
    "signatureBundle": {
      "signature": "base64-encoded-signature",
      "certificate": "-----BEGIN CERTIFICATE-----...",
      "transparencyLogEntry": {...},
      "timestamp": "2024-01-01T00:00:00Z"
    },
    "provenanceBundle": {
      "provenance": {
        "subject": [...],
        "runDetails": {...},
        "buildDefinition": {...}
      }
    }
  }
}
```

## GitHub Actions Integration

Setting up automated Agent Card signing in GitHub Actions creates a secure and auditable process for publishing AI agents. The workflow below demonstrates how to integrate sigstore-a2a into your CI/CD pipeline, ensuring that every Agent Card published from your repository carries cryptographic proof of its origin.

The key to this integration is the OIDC (OpenID Connect) token that GitHub Actions provides. This token contains claims about the repository, workflow, and actor that triggered the build, which Sigstore embeds into the signing certificate. This creates an immutable link between your Agent Card and its source code.

```yaml
name: Build and Sign Agent Card
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

permissions:
  id-token: write  # Required for Sigstore OIDC token
  contents: read   # Required to checkout repository

jobs:
  sign-agent-card:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install UV package manager
        run: |
          curl -LsSf https://astral.sh/uv/install.sh | sh
          echo "$HOME/.cargo/bin" >> $GITHUB_PATH

      - name: Install sigstore-a2a
        run: |
          uv sync --prerelease=allow

      - name: Sign Agent Card
        env:
          UV_PRERELEASE: allow
        run: |
          uv run sigstore-a2a sign agent-card.json \
            --output signed-agent-card.json \
            --repository ${{ github.repository }}

      - name: Verify signature locally
        env:
          UV_PRERELEASE: allow
        run: |
          uv run sigstore-a2a verify signed-agent-card.json \
            --repository ${{ github.repository }} \
            --workflow "${{ github.workflow }}"

      - name: Upload signed Agent C

... (truncated)