Skip to content
Projects

sigstore/sigstore-a2a has 27 GitHub stars and 6 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-18 17:26 UTC. Last push 2026-11-17.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Sigstore A2A Agent Signing

Security

README.md

Original

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 signing and verifying A2A (Agent-to-Agent) AgentCards using Sigstore keyless signing, EC key signing, or X.509 certificate signing, with optional SLSA provenance attestations.

Overview

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

  • Sigstore keyless signing of A2A Agent Cards using Sigstore's infrastructure (default)
  • EC key signing using elliptic curve private keys (secp256r1, secp384r1, secp521r1)
  • Certificate signing using X.509 certificates with chain-of-trust validation
  • 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

# 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 with an EC Key

For environments where Sigstore OIDC is unavailable, sign with a standard EC private key:

# Generate an EC key pair
openssl ecparam -genkey -name prime256v1 -noout -out private.pem
openssl ec -in private.pem -pubout -out public.pem

# Sign an Agent Card
sigstore-a2a sign key agent-card.json --private-key private.pem

# Verify with the matching public key
sigstore-a2a verify key agent-card.signed.json --public-key public.pem

# Sign with SLSA provenance
sigstore-a2a sign key agent-card.json --private-key private.pem --provenance

Signing with a Certificate

For enterprise environments using X.509 PKI:

# Generate a self-signed code-signing certificate
openssl req -x509 -new -key private.pem -out cert.pem -days 365 \
  -subj "/CN=My Agent Signer" \
  -addext "keyUsage=digitalSignature" \
  -addext "extendedKeyUsage=codeSigning"

# Sign with certificate
sigstore-a2a sign certificate agent-card.json \
  --private-key private.pem --signing-cert cert.pem --cert-chain cert.pem

# Verify with certificate chain
sigstore-a2a verify certificate agent-card.signed.json --cert-chain cert.pem

# Verify with SAN identity pinning
sigstore-a2a verify certificate agent-card.signed.json \
  --cert-chain cert.pem --san-uri spiffe://example.com/agent

Signing with Sigstore (Keyless)

In CI/CD environments with OIDC credentials, Sigstore keyless signing is the default:

# Sign using ambient CI/CD OIDC credentials (default method)
sigstore-a2a sign agent-card.json --use_ambient_credentials

# Verify with identity constraints
sigstore-a2a verify signed-card.json \
  --identity [email protected] \
  --identity_provider https://accounts.google.com

Library Usage

The recommended library API uses the Config builder pattern to select a signing or verification method:

from pathlib import Path
from sigstore_a2a.signing import SigningConfig
from sigstore_a2a.verifying import VerifyingConfig

# --- EC key ---
signed = SigningConfig().use_elliptic_key_signer(private_key=Path("private.pem")).sign_card("agent-card.json")
result = VerifyingConfig().use_elliptic_key_verifier(public_key=Path("public.pem")).verify(signed)

if result.valid:
    print(f"Verified: {result.agent_card.name}")
else:
    print(f"Failed: {result.errors}")

# --- Certificate ---
signed = (
    SigningConfig()
    .use_certificate_signer(
        private_key=Path("private.pem"),
        signing_cert=Path("cert.pem"),
        cert_chain=[Path("ca.pem")],
    )
    .sign_card("agent-card.json")
)
result = VerifyingConfig().use_certificate_verifier(cert_chain=[Path("ca.pem")]).verify(signed)

# --- Sigstore keyless (default if no method selected) ---
signed = SigningConfig().sign_card("agent-card.json")
result = (
    VerifyingConfig()
    .use_sigstore_verifier(identity="[email protected]", oidc_issuer="https://accounts.google.com")
    .verify(signed)
)

# --- Sign to file ---
SigningConfig().use_elliptic_key_signer(private_key=Path("key.pem")).sign("agent-card.json", Path("signed.json"))
result = VerifyingConfig().use_elliptic_key_verifier(public_key=Path("pub.pem")).verify_file("signed.json")

CLI Reference

The CLI uses subcommands under sign and verify to select the signing method. If no method is specified, Sigstore keyless signing is used by default.

sigstore-a2a sign <method> [options] AGENT_CARD
sigstore-a2a verify <method> [options] SIGNED_CARD

sign key

Sign using an EC private key:

sigstore-a2a sign key agent-card.json --private-key key.pem
sigstore-a2a sign key agent-card.json --private-key key.pem -o signed.json
sigstore-a2a sign key agent-card.json --private-key key.pem --provenance
sigstore-a2a sign key agent-card.json --private-key key.pem \
  --provenance --repository owner/repo --commit_sha abc123

sign certificate

Sign using an X.509 certificate and trust chain:

sigstore-a2a sign certificate agent-card.json \
  --private-key key.pem --signing-cert cert.pem --cert-chain ca.pem
sigstore-a2a sign certificate agent-card.json \
  --private-key key.pem --signing-cert cert.pem --cert-chain ca.pem --provenance

sign sigstore

Sign using Sigstore keyless signing (default when no method is given):

# These are equivalent:
sigstore-a2a sign agent-card.json
sigstore-a2a sign sigstore agent-card.json

# With options:
sigstore-a2a sign agent-card.json --use_ambient_credentials
sigstore-a2a sign agent-card.json --staging
sigstore-a2a sign agent-card.json --identity_token "$TOKEN"
sigstore-a2a sign agent-card.json --provenance --repository owner/repo

verify key

Verify using an EC public key:

sigstore-a2a verify key signed-card.json --public-key pubkey.pem

verify certificate

Verify using a certificate chain:

sigstore-a2a verify certificate signed-card.json --cert-chain ca.pem
sigstore-a2a verify certificate signed-card.json \
  --cert-chain ca.pem --san-uri spiffe://example.com/agent

verify sigstore

Verify using Sigstore (default when no method is given):

# These are equivalent:
sigstore-a2a verify signed-card.json \
  --identity [email protected] \
  --identity_provider https://accounts.google.com

sigstore-a2a verify sigstore signed-card.json \
  --identity [email protected] \
  --identity_provider https://accounts.google.com

# With constraints:
sigstore-a2a verify signed-card.json \
  --identity "https://github.com/owner/repo/.github/workflows/ci.yml@refs/heads/main" \
  --identity_provider https://token.actions.githubusercontent.com \
  --repository owner/repo \
  --workflow ci

serve

Serve a signed Agent Card at well-known endpoints:

# Serve with Sigstore verification on startup
sigstore-a2a serve signed-card.json --port 8080

# Serve with EC key verification on startup
sigstore-a2a serve signed-card.json --public-key pubkey.pem

# Serve with certificate chain verification on startup
sigstore-a2a serve signed-card.json --cert-chain ca.pem

# Serve without verification
sigstore-a2a serve signed-card.json --no-verify

trust-instance

Bootstrap trust for a private Sigstore instance:

sigstore-a2a trust-instance root.json --instance https://sigstore.example.com

Agent Card Structure

Signed Agent Cards wrap the original card with cryptographic attestations:

{
  "agentCard": {
    "name": "Example Agent",
    "description": "An example AI agent",
    "version": "1.0.0",
    "supportedInterfaces": [{"url": "https://example.com/agent"}],
    "skills": [...]
  },
  "attestations": {
    "signatureBundle": {
      "mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json",
      "verificationMaterial": { ... },
      "dsseEnvelope": { ... }
    },
    "provenanceBundle": { ... }
  }
}

The signatureBundle uses the Sigstore bundle format for all signing methods (Sigstore keyless, EC key, and certificate).

GitHub Actions Integration

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

permissions:
  id-token: write
  contents: read

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

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install sigstore-a2a
        run: pip install sigstore-a2a

      - name: Sign Agent Card
        run: |
          sigstore-a2a sign sigstore agent-card.json \
            --use_ambient_credentials \
            --provenance \
            --repository ${{ github.repository }} \
            --commit_sha ${{ github.sha }} \
            --output signed-agent-card.json

      - name: Verify signature
        run: |
          sigstore-a2a verify sigstore signed-agent-card.json \
            --identity "https://github.com/${{ github.repository }}/.github/workflows/${{ github.workflow }}.yml@refs/heads/main" \
            --identity_provider https://token.actions.githubusercontent.com \
            --repository ${{ github.repository }}

      - uses: actions/upload-artifact@v4
        with:
          name: signed-agent-card
          path: signed-agent-card.json

API Reference

SigningConfig

from sigstore_a2a.signing import SigningConfig

SigningConfig()
    .use_sigstore_signer(identity_token=None, staging=False, ...)  -> Self
    .use_elliptic_key_signer(private_key: Path, password=None)     -> Self
    .use_certificate_signer(private_key: Path, signing_cert: Path,
                            cert_chain: Iterable[Path] = ())       -> Self
    .sign_card(agent_card, provenance_bundle=None)  -> SignedAgentCard
    .sign(agent_card, output_path: Path, provenance_bundle=None) -> Path

Defaults to Sigstore keyless signing if no use_* method is called.

VerifyingConfig

from sigstore_a2a.verifying import VerifyingConfig

VerifyingConfig()
    .use_sigstore_verifier(identity=None, oidc_issuer=None, ...)  -> Self
    .use_elliptic_key_verifier(public_key: Path)                  -> Self
    .use_certificate_verifier(cert_chain: Iterable[Path] = (),
                              expected_san_uris: Iterable[str] = ()) -> Self
    .verify(signed_card)      -> VerificationResult
    .verify_file(file_path)   -> VerificationResult

Raises ValueError if no use_* method is called (no default).

ECKeyAgentCardSigner

class ECKeyAgentCardSigner:
    def __init__(self, private_key_path: Path, password: bytes | None = None)
    def sign_agent_card(self, agent_card, provenance_bundle=None) -> SignedAgentCard
    def sign_file(self, input_path, output_path=None, provenance_bundle=None) -> Path

Supported curves: secp256r1, secp384r1, secp521r1.

ECKeyAgentCardVerifier

class ECKeyAgentCardVerifier:
    def __init__(self, public_key_path: Path)
    def verify_signed_card(self, signed_card) -> VerificationResult
    def verify_file(self, file_path) -> VerificationResult

CertificateAgentCardSigner

class CertificateAgentCardSigner(ECKeyAgentCardSigner):
    def __init__(self, private_key_path: Path, signing_cert_path: Path,
                 cert_chain_paths: Iterable[Path] = (), password: bytes | None = None)
    def sign_agent_card(self, agent_card, provenance_bundle=None) -> SignedAgentCard
    def sign_file(self, input_path, output_path=None, provenance_bundle=None) -> Path

Validates certificate expiry, key-cert match. Embeds X.509 certificate chain in the bundle.

CertificateAgentCardVerifier

class CertificateAgentCardVerifier:
    def __init__(self, cert_chain_paths: Iterable[Path] = (),
                 expected_san_uris: Iterable[str] = ())
    def verify_signed_card(self, signed_card) -> VerificationResult
    def verify_file(self, file_path) -> VerificationResult

Validates certificate chain (via pyOpenSSL), checks KeyUsage/ExtendedKeyUsage for code signing, and optionally pins SAN URIs (e.g. SPIFFE IDs). Defaults to OS root CAs when no chain is provided.

AgentCardSigner

class AgentCardSigner:
    def __init__(self, identity_token=None, staging=False, trust_config=None,
                 instance=None, client_id=None, client_secret=None,
                 use_ambient_credentials=False)
    def sign_agent_card(self, agent_card, provenance_bundle=None) -> SignedAgentCard
    def sign_file(self, input_path, output_path=None, provenance_bundle=None) -> Path

AgentCardVerifier

class AgentCardVerifier:
    def __init__(self, identity=None, oidc_issuer=None, staging=False,
                 trust_config=None, instance=None)
    def verify_signed_card(self, signed_card, constraints=None) -> VerificationResult
    def verify_file(self, file_path, constraints=None) -> VerificationResult

VerificationResult

  • valid: Whether verification succeeded
  • agent_card: Verified AgentCard (extracted from the authenticated DSSE payload)
  • raw_card_data: Raw predicate dict, preserving fields that may not map to the current protobuf schema
  • certificate: Signing certificate (Sigstore and certificate methods)
  • identity: Extracted identity information (Sigstore only)
  • errors: List of verification errors

ProvenanceBuilder

class ProvenanceBuilder:
    def __init__(self, build_type="https://github.com/actions/workflow@v1")
    def build_provenance(self, agent_card, source_repo=None, commit_sha=None,
                         workflow_ref=None) -> SLSAProvenance

OpenTelemetry Tracing

Optional OpenTelemetry support enables distributed tracing for all sign and verify operations.

Installation

pip install sigstore-a2a[otel]

Usage

When installed with the [otel] extra, tracing is automatically enabled. Configure the exporter via standard OpenTelemetry environment variables:

export OTEL_SERVICE_NAME="sigstore-a2a"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"

sigstore-a2a sign key agent-card.json --private-key key.pem
sigstore-a2a verify key signed.json --public-key pub.pem

Each sign and verify CLI command creates a span with attributes like signing.method, signing.agent_card, verification.method, and verification.signed_card.

Without the [otel] extra, tracing is silently disabled with zero overhead.

Testing with Jaeger

# Start Jaeger
docker run --rm -d --name jaeger -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:latest

# Run the OTel integration test
./scripts/tests/test-otel.sh

# View traces at http://localhost:16686

Troubleshooting

OIDC Token Issues (Sigstore)

In CI/CD environments, ensure:

  • id-token: write permission is set
  • Repository has OIDC enabled
  • Workflow runs in trusted environment

EC Key Issues

  • Key must be an elliptic curve key (RSA and other types are rejected)
  • Supported curves: secp256r1 (P-256), secp384r1 (P-384), secp521r1 (P-521)
  • Key format: PEM encoded

Certificate Issues

  • Certificate must have digitalSignature in KeyUsage
  • Certificate must have codeSigning in ExtendedKeyUsage (TLS-only certificates are rejected)
  • Certificate must not be expired or not-yet-valid
  • Certificate public key must match the private key
  • Certificate format: PEM encoded

License

Apache License 2.0

Related Projects

  • Sigstore - Keyless signing infrastructure
  • SLSA - Supply chain security framework
  • A2A Protocol - Agent-to-Agent communication specification