sigstore/sigstore-a2a
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.
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
SecurityREADME.md
Originalsigstore-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 succeededagent_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 schemacertificate: 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: writepermission 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
digitalSignaturein KeyUsage - Certificate must have
codeSigningin 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