Charon/.github/skills/security-slsa-provenance.SKILL.md

---
# agentskills.io specification v1.0
name: "security-slsa-provenance"
version: "1.0.0"
description: "Generate and verify SLSA provenance attestations for build transparency"
author: "Charon Project"
license: "MIT"
tags:
  - "security"
  - "slsa"
  - "provenance"
  - "supply-chain"
  - "attestation"
compatibility:
  os:
    - "linux"
    - "darwin"
  shells:
    - "bash"
requirements:
  - name: "slsa-verifier"
    version: ">=2.6.0"
    optional: false
    install_url: "https://github.com/slsa-framework/slsa-verifier"
  - name: "jq"
    version: ">=1.6"
    optional: false
  - name: "gh"
    version: ">=2.62.0"
    optional: true
    description: "GitHub CLI (for downloading attestations)"
environment_variables:
  - name: "SLSA_LEVEL"
    description: "Minimum SLSA level required (1, 2, 3)"
    default: "2"
    required: false
parameters:
  - name: "action"
    type: "string"
    description: "Action to perform (generate, verify, inspect)"
    required: true
  - name: "target"
    type: "string"
    description: "Docker image, file path, or provenance file"
    required: true
  - name: "source_uri"
    type: "string"
    description: "Source repository URI (for verification)"
    required: false
    default: ""
outputs:
  - name: "provenance_file"
    type: "file"
    description: "Generated provenance attestation (JSON)"
  - name: "verification_result"
    type: "stdout"
    description: "Verification status and details"
  - name: "exit_code"
    type: "number"
    description: "0 if successful, non-zero otherwise"
metadata:
  category: "security"
  subcategory: "supply-chain"
  execution_time: "fast"
  risk_level: "low"
  ci_cd_safe: true
  requires_network: true
  idempotent: true
exit_codes:
  0: "Operation successful"
  1: "Operation failed or verification mismatch"
  2: "Missing dependencies or invalid parameters"
---

# Security: SLSA Provenance

Generate and verify SLSA (Supply-chain Levels for Software Artifacts) provenance attestations for build transparency and supply chain security.

## Overview

SLSA provenance provides verifiable metadata about how an artifact was built, including the source repository, build platform, dependencies, and build parameters. This skill generates provenance documents, verifies them against policy, and inspects provenance metadata.

SLSA Level 2+ compliance ensures that:
- Builds are executed on isolated, ephemeral systems
- Provenance is generated automatically by the build platform
- Provenance is tamper-proof and cryptographically verifiable

## Features

- Generate SLSA provenance for local artifacts
- Verify provenance against source repository
- Inspect provenance metadata
- Check SLSA level compliance
- Support Docker images and file artifacts
- Parse and display provenance in human-readable format

## Prerequisites

- slsa-verifier 2.6.0 or higher
- jq 1.6 or higher
- gh (GitHub CLI) 2.62.0 or higher (for downloading attestations)
- GitHub account (for downloading remote attestations)

## Usage

### Verify Docker Image Provenance

```bash
# Download and verify provenance from GitHub
.github/skills/scripts/skill-runner.sh security-slsa-provenance \
  verify ghcr.io/user/charon:latest github.com/user/charon
```

### Verify Local Provenance File

```bash
# Verify a local provenance file against an artifact
.github/skills/scripts/skill-runner.sh security-slsa-provenance \
  verify ./dist/charon-linux-amd64 github.com/user/charon provenance.json
```

### Inspect Provenance Metadata

```bash
# Parse and display provenance details
.github/skills/scripts/skill-runner.sh security-slsa-provenance \
  inspect provenance.json
```

### Generate Provenance (Local Development)

```bash
# Generate provenance for a local artifact
# Note: Real provenance should be generated by CI/CD
.github/skills/scripts/skill-runner.sh security-slsa-provenance \
  generate ./dist/charon-linux-amd64
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| action    | string | Yes    | -       | Action: generate, verify, inspect |
| target    | string | Yes    | -       | Docker image, file path, or provenance file |
| source_uri | string | No    | ""      | Source repository URI (github.com/user/repo) |
| provenance_file | string | No | "" | Path to provenance file (for verify action) |

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| SLSA_LEVEL | No | 2 | Minimum SLSA level required (1, 2, 3) |

## Actions

### generate

Generates a basic SLSA provenance document for a local artifact. **Note**: This is for development/testing only. Production provenance must be generated by a trusted build platform (GitHub Actions, Cloud Build, etc.).

**Usage**:
```bash
security-slsa-provenance generate <artifact-path>
```

**Output**: `provenance-<artifact>.json`

### verify

Verifies a provenance document against an artifact and source repository. Checks:
- Provenance signature is valid
- Artifact digest matches provenance
- Source URI matches expected repository
- SLSA level meets minimum requirements

**Usage**:
```bash
# Verify Docker image (downloads attestation automatically)
security-slsa-provenance verify <image> <source-uri>

# Verify local file with provenance file
security-slsa-provenance verify <artifact> <source-uri> <provenance-file>
```

### inspect

Parses and displays provenance metadata in human-readable format. Shows:
- SLSA level
- Builder identity
- Source repository
- Build parameters
- Materials (dependencies)
- Build invocation

**Usage**:
```bash
security-slsa-provenance inspect <provenance-file>
```

## Outputs

### Generate Action
- `provenance-<artifact>.json`: Generated provenance document

### Verify Action
- Exit code 0: Verification successful
- Exit code 1: Verification failed
- stdout: Verification details and reasons

### Inspect Action
- Human-readable provenance metadata
- SLSA level and builder information
- Source and build details

## Examples

### Example 1: Verify Docker Image from GitHub

```bash
$ .github/skills/scripts/skill-runner.sh security-slsa-provenance \
  verify ghcr.io/user/charon:v1.0.0 github.com/user/charon

[INFO] Verifying SLSA provenance for ghcr.io/user/charon:v1.0.0
[SLSA] Downloading provenance from GitHub...
[SLSA] Found provenance attestation
[SLSA] Verifying provenance signature...
[SLSA] Signature valid
[SLSA] Checking source URI...
[SLSA] Source: github.com/user/charon ✓
[SLSA] Builder: https://github.com/slsa-framework/slsa-github-generator
[SLSA] SLSA Level: 3 ✓
[SUCCESS] Provenance verification passed
```

### Example 2: Verify Release Binary

```bash
$ .github/skills/scripts/skill-runner.sh security-slsa-provenance \
  verify ./dist/charon-linux-amd64 github.com/user/charon provenance-release.json

[INFO] Verifying SLSA provenance for ./dist/charon-linux-amd64
[SLSA] Reading provenance from provenance-release.json
[SLSA] Verifying provenance signature...
[SLSA] Signature valid
[SLSA] Checking artifact digest...
[SLSA] Digest matches ✓
[SLSA] Source URI: github.com/user/charon ✓
[SLSA] SLSA Level: 2 ✓
[SUCCESS] Provenance verification passed
```

### Example 3: Inspect Provenance Details

```bash
$ .github/skills/scripts/skill-runner.sh security-slsa-provenance \
  inspect provenance-release.json

[PROVENANCE] SLSA Provenance Details
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SLSA Level: 3
Builder: https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@v2.1.0

Source Repository:
  URI: github.com/user/charon
  Digest: sha1:abc123def456...
  Ref: refs/tags/v1.0.0

Build Information:
  Invoked by: github.com/user/charon/.github/workflows/docker-build.yml@refs/heads/main
  Started: 2026-01-10T12:00:00Z
  Finished: 2026-01-10T12:05:32Z

Materials:
  - github.com/user/charon@sha1:abc123def456...

Subject:
  Name: ghcr.io/user/charon
  Digest: sha256:789abc...
```

### Example 4: CI/CD Integration (GitHub Actions)

```yaml
- name: Download SLSA Verifier
  run: |
    curl -sLO https://github.com/slsa-framework/slsa-verifier/releases/download/v2.6.0/slsa-verifier-linux-amd64
    sudo install slsa-verifier-linux-amd64 /usr/local/bin/slsa-verifier

- name: Verify Image Provenance
  run: |
    .github/skills/scripts/skill-runner.sh security-slsa-provenance \
      verify ghcr.io/${{ github.repository }}:${{ github.sha }} \
      github.com/${{ github.repository }}
```

## SLSA Levels

### Level 1
- Build process is documented
- Provenance is generated
- **Not cryptographically verifiable**

### Level 2 (Recommended Minimum)
- Build on ephemeral, isolated system
- Provenance generated by build platform
- Provenance is signed and verifiable
- **This skill enforces Level 2 minimum by default**

### Level 3
- Source and build platform are strongly hardened
- Audit logs are retained
- Hermetic, reproducible builds
- **Recommended for production releases**

## Provenance Structure

A SLSA provenance document contains:

```json
{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    {
      "name": "ghcr.io/user/charon",
      "digest": { "sha256": "..." }
    }
  ],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "buildType": "https://github.com/slsa-framework/slsa-github-generator/...",
      "externalParameters": {
        "source": { "uri": "git+https://github.com/user/charon@refs/tags/v1.0.0" }
      },
      "internalParameters": {},
      "resolvedDependencies": [...]
    },
    "runDetails": {
      "builder": { "id": "https://github.com/slsa-framework/..." },
      "metadata": {
        "invocationId": "...",
        "startedOn": "2026-01-10T12:00:00Z",
        "finishedOn": "2026-01-10T12:05:32Z"
      }
    }
  }
}
```

## Error Handling

### Common Issues

**slsa-verifier not installed**:
```bash
Error: slsa-verifier command not found
Solution: Install from https://github.com/slsa-framework/slsa-verifier
Quick install: go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@latest
```

**Provenance not found**:
```bash
Error: No provenance found for image
Solution: Ensure the image was built with SLSA provenance generation enabled
```

**Source URI mismatch**:
```bash
Error: Source URI mismatch
Expected: github.com/user/charon
Found: github.com/attacker/charon
Solution: Verify you're using the correct image/artifact
```

**SLSA level too low**:
```bash
Error: SLSA level 1 does not meet minimum requirement of 2
Solution: Rebuild artifact with SLSA Level 2+ generator
```

**Invalid provenance signature**:
```bash
Error: Failed to verify provenance signature
Solution: Provenance may be tampered or corrupted - do not trust artifact
```

## Exit Codes

- **0**: Operation successful
- **1**: Operation failed or verification mismatch
- **2**: Missing dependencies or invalid parameters

## Related Skills

- [security-verify-sbom](./security-verify-sbom.SKILL.md) - Verify SBOM and scan vulnerabilities
- [security-sign-cosign](./security-sign-cosign.SKILL.md) - Sign artifacts with Cosign

## Notes

- **Production provenance MUST be generated by trusted build platform**
- Local provenance generation is for testing only
- SLSA Level 2 is the minimum recommended for production
- Level 3 provides strongest guarantees but requires hermetic builds
- Provenance verification requires network access to download attestations
- GitHub attestations are public and verifiable by anyone
- Provenance documents are immutable once generated

## Security Considerations

- Never trust artifacts without verified provenance
- Always verify source URI matches expected repository
- Require SLSA Level 2+ for production deployments
- Provenance tampering indicates compromised supply chain
- Provenance signature must be verified before trusting metadata
- Local provenance generation bypasses security guarantees
- Use SLSA-compliant build platforms (GitHub Actions, Cloud Build, etc.)

---

**Last Updated**: 2026-01-10
**Maintained by**: Charon Project
**Source**: slsa-framework/slsa-verifier
**Documentation**: https://slsa.dev/