<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: implementing-software-provenance
description: >-
  Implement software provenance tracking using SLSA framework, in-toto
  attestations, and Sigstore. Generate verifiable build provenance that proves
  where, when, and how software artifacts were produced.
domain: cybersecurity
subdomain: supply-chain-security
tags:
  - slsa
  - provenance
  - in-toto
  - sigstore
  - build-integrity
  - attestation
  - software-transparency
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1195.002"]
---

# Implementing Software Provenance

## Overview

Software provenance answers "who built this, from what source, using what build
process?" — critical for supply chain trust. The SLSA framework defines four
levels of provenance assurance. This skill covers generating, signing, and
verifying build provenance using SLSA GitHub generators, in-toto attestations,
and Sigstore tooling.

Mode: `[MODE: ARCHITECT]` — Design provenance pipelines; `[MODE: BLUE]` — Verify artifact provenance.

## Prerequisites

| Requirement | Details |
|---|---|
| slsa-verifier (`go install github.com/slsa-framework/slsa-verifier/v2/cli/slsa-verifier@latest`) | Required |
| cosign (`brew install cosign`) | Required |
| in-toto CLI (`pip install in-toto`) | Required |
| GitHub Actions (for SLSA GitHub Generator) | Required |

## Key Concepts

### SLSA Provenance Generation (GitHub Actions)

```yaml
name: SLSA Provenance
on:
  push:
    tags: ['v*']

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      digest: ${{ steps.hash.outputs.digest }}
    steps:
      - uses: actions/checkout@v4
      - name: Build artifact
        run: |
          go build -o app ./cmd/app
          tar czf app.tar.gz app
      - name: Generate hash
        id: hash
        run: |
          echo "digest=$(sha256sum app.tar.gz | base64 -w0)" >> "$GITHUB_OUTPUT"
      - uses: actions/upload-artifact@v4
        with:
          name: app
          path: app.tar.gz

  provenance:
    needs: build
    permissions:
      actions: read
      id-token: write
      contents: write
    uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v2.0.0
    with:
      base64-subjects: "${{ needs.build.outputs.digest }}"
      upload-assets: true
```

### Provenance Verification

```bash
# Verify SLSA provenance
slsa-verifier verify-artifact app.tar.gz \
  --provenance-path provenance.intoto.jsonl \
  --source-uri github.com/org/repo \
  --source-tag v1.2.3

# Verify container image provenance
slsa-verifier verify-image ghcr.io/org/app:v1.2.3 \
  --source-uri github.com/org/repo

# Inspect provenance content
cat provenance.intoto.jsonl | jq -r '.payload' | base64 -d | jq '.'
```

### in-toto Attestations

```bash
# Create layout (defines expected build steps)
in-toto-run --step-name build --products app.tar.gz -- make build

# Verify supply chain
in-toto-verify --layout layout.json --layout-keys key.pub
```

## Workflow

### Step 1: Generate Provenance Metadata

```bash
node scripts/agent.js --action generate --artifact app.tar.gz --builder github-actions --output /tmp/provenance.json
```

### Step 2: Verify Artifact Provenance

```bash
node scripts/agent.js --action verify --artifact app.tar.gz --provenance /tmp/provenance.json --source github.com/org/repo --output /tmp/verification.json
```

### Step 3: Assess SLSA Level

```bash
node scripts/agent.js --action assess --provenance /tmp/provenance.json --output /tmp/slsa-level.json
```

## Detection

```yaml
title: Software Provenance Detection
id: 9a935c0a-9421-4b4b-a1fa-75d60c106624
status: experimental
description: Detects suspicious activity related to implementing software provenance techniques in supply chain security context
logsource:
  category: process_creation
  product: linux
detection:
  selection:
    CommandLine: "*implementing*software*"
  condition: selection
level: medium
tags:
  - attack.t1195.002
  - attack.initial_access
falsepositives:
  - Package manager performing routine dependency resolution
```


**Detection Opportunities**

| Indicator | Source | Detection Logic |
|---|---|---|
| Software Provenance Detection | linux/process_creation | Sigma rule (medium) |
| ATT&CK Coverage | MITRE ATT&CK | T1195.002 |

## Verification

- [ ] Build provenance generated for every release artifact
- [ ] Provenance signed by build platform (not developer keys)
- [ ] SLSA Level 2+ achieved (hosted build, signed provenance)
- [ ] slsa-verifier passes for all published artifacts
- [ ] Provenance includes source repository, commit, and builder identity
- [ ] Container images have attached provenance attestations

## References

- [SLSA Framework](https://slsa.dev/)
- [SLSA GitHub Generator](https://github.com/slsa-framework/slsa-github-generator)
- [in-toto Specification](https://in-toto.io/)
- [Sigstore Documentation](https://docs.sigstore.dev/)
- [SLSA Verifier](https://github.com/slsa-framework/slsa-verifier)
