SLSA.md

SLSA Compliance for telemetry-kit

Status: SLSA Level 2 Target: SLSA Level 3 Last Updated: 2025-01-22

---

Table of Contents

• What is SLSA?
• Current Compliance
• SLSA Level 2 (Current)
• SLSA Level 3 (Planned)
• Build Provenance
• Verification
• Supply Chain Threats
• Roadmap

---

What is SLSA?

SLSA (Supply-chain Levels for Software Artifacts) is a security framework to protect software supply chains from tampering, unauthorized changes, and malicious code injection.

Goals:

• Prevent unauthorized modifications to source code
• Ensure integrity of build process
• Provide verifiable provenance for artifacts
• Enable consumers to verify artifact authenticity

Levels:

• Level 1: Documentation of build process
• Level 2: Tamper-resistant build service
• Level 3: Hardened build platforms
• Level 4: Highest level of auditability (two-party review)

---

Current Compliance

SLSA Level 2 ✅

Requirement	Status	Implementation
Version controlled source	✅	GitHub repository
Generated provenance	✅	GitHub Actions attestations
Build service	✅	GitHub Actions
Automated build	✅	CI/CD pipeline
Provenance available	✅	Signed attestations

SLSA Level 3 (In Progress)

Requirement	Status	Implementation
Hardened build platform	🔄	GitHub Actions (trusted)
Non-falsifiable provenance	🔄	Sigstore integration planned
Isolated builds	✅	Ephemeral GitHub runners
Parameterless builds	🔄	Working towards
Hermetic builds	❌	Planned for v2.0

---

SLSA Level 2 (Current)

Requirements Met

1. Version Controlled Source ✅

Requirement: Source code is version controlled with history.

Implementation:

• Git repository: https://github.com/ibrahimcesar/telemetry-kit
• All changes tracked in version control
• Signed commits encouraged (not required)
• Branch protection on main:
  • Pull request required
  • Status checks must pass
  • No direct pushes

Verification:

# Clone repository
git clone https://github.com/ibrahimcesar/telemetry-kit
cd telemetry-kit

# Verify history
git log --oneline

# Check for signed commits
git log --show-signature

2. Generated Provenance ✅

Requirement: Provenance is automatically generated for each release.

Implementation:

• GitHub Actions workflows generate SLSA provenance
• Provenance includes:
  • Source commit SHA
  • Build parameters
  • Builder identity
  • Build timestamp
• Stored as GitHub attestations

Verification:

# Download release
gh release download v0.2.0

# Verify attestation (requires gh CLI v2.40+)
gh attestation verify telemetry-kit-*.tar.gz \
  --owner ibrahimcesar

3. Build Service ✅

Requirement: Builds are performed by a hosted build service.

Implementation:

• Service: GitHub Actions
• Runners: GitHub-hosted (Ubuntu latest)
• Isolation: Each build runs in fresh VM
• Logging: Full build logs available
• Reproducibility: Same inputs → same outputs

Build Configuration: .github/workflows/release.yml

4. Build as Code ✅

Requirement: Build process is defined as code in version control.

Implementation:

# .github/workflows/release.yml
name: Release
on:
  push:
    tags:
      - 'v*'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write  # For SLSA provenance
      attestations: write

    steps:
      - uses: actions/checkout@v4

      - name: Build
        run: cargo build --release

      - name: Generate provenance
        uses: actions/attest-build-provenance@v1
        with:
          subject-path: 'target/release/telemetry-kit'

---

SLSA Level 3 (Planned)

Additional Requirements

1. Hardened Build Platform 🔄

Requirement: Build platform prevents tampering by build process.

Current State:

• GitHub Actions provides isolation ✅
• Ephemeral runners prevent persistence ✅
• No access to secrets from forks ✅

Planned Improvements:

• Custom runners with enhanced security
• Restricted network access during builds
• Immutable build containers

2. Non-falsifiable Provenance 🔄

Requirement: Provenance cannot be forged by build process itself.

Current State:

• GitHub Actions signs provenance ✅
• Attestations stored externally ✅

Planned Improvements:

• Sigstore integration: Sign with Rekor transparency log
• Cosign signatures: Verify artifacts with cosign
• Public transparency: All signatures publicly verifiable

Example (planned):

# Sign with cosign
cosign sign-blob \
  --bundle telemetry-kit.bundle \
  target/release/telemetry-kit

# Verify signature
cosign verify-blob \
  --bundle telemetry-kit.bundle \
  --certificate-identity=https://github.com/ibrahimcesar/telemetry-kit/.github/workflows/release.yml@refs/heads/main \
  --certificate-oidc-issuer=https://token.actions.githubusercontent.com \
  target/release/telemetry-kit

3. Isolated Builds ✅

Requirement: Builds cannot access secrets or network.

Current State:

• Each build runs in fresh VM ✅
• Secrets not available to build steps ✅
• Network access restricted (partially)

Verification:

# Build step has no secret access
- name: Build
  run: cargo build --release
  # No 'env:' with secrets
  # No 'with: secrets'

4. Parameterless Builds 🔄

Requirement: Build doesn't accept user-controlled parameters.

Current State:

• Tag triggers build ✅
• No manual workflow_dispatch ✅
• Build parameters from git only ✅

Improvement Needed:

• Remove version from Cargo.toml
• Derive version from git tag
• Zero external parameters

5. Hermetic Builds ❌

Requirement: All dependencies declared and fetched from known sources.

Planned for v2.0:

• Vendor all dependencies
• Cargo.lock pinning (already done ✅)
• Offline build capability
• Reproducible builds

---

Build Provenance

What is Provenance?

Provenance is metadata about how an artifact was built:

• What: Source repository and commit
• When: Build timestamp
• Where: Build platform (GitHub Actions)
• Who: Builder identity (GitHub)
• How: Build recipe (.github/workflows/release.yml)

Provenance Format

We use the in-toto SLSA Provenance format (v1.0):

{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [
    {
      "name": "telemetry-kit",
      "digest": {
        "sha256": "abc123..."
      }
    }
  ],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "buildType": "https://github.com/actions/...",
      "externalParameters": {
        "workflow": {
          "ref": "refs/tags/v0.2.0",
          "repository": "https://github.com/ibrahimcesar/telemetry-kit"
        }
      }
    },
    "runDetails": {
      "builder": {
        "id": "https://github.com/actions/runner"
      },
      "metadata": {
        "invocationId": "https://github.com/ibrahimcesar/telemetry-kit/actions/runs/..."
      }
    }
  }
}

Accessing Provenance

Via GitHub CLI:

# List attestations for a release
gh attestation list \
  --owner ibrahimcesar \
  --repo telemetry-kit \
  --limit 10

# Download specific attestation
gh attestation download \
  --repo ibrahimcesar/telemetry-kit \
  --digest-alg sha256 \
  --digest abc123...

Via API:

# Get attestations
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/repos/ibrahimcesar/telemetry-kit/attestations/sha256:abc123

---

Verification

For crates.io Users

# Install from crates.io
cargo install telemetry-kit

# Verify checksum matches GitHub release
sha256sum $(which telemetry-kit)

# Compare with GitHub release checksum
curl -sL https://github.com/ibrahimcesar/telemetry-kit/releases/download/v0.2.0/checksums.txt

For Binary Users

# Download release
wget https://github.com/ibrahimcesar/telemetry-kit/releases/download/v0.2.0/telemetry-kit-linux-x86_64.tar.gz

# Verify checksum
sha256sum telemetry-kit-linux-x86_64.tar.gz

# Verify attestation
gh attestation verify telemetry-kit-linux-x86_64.tar.gz \
  --owner ibrahimcesar \
  --repo telemetry-kit

For Source Users

# Clone repository
git clone https://github.com/ibrahimcesar/telemetry-kit
cd telemetry-kit

# Verify tag signature (if signed)
git tag -v v0.2.0

# Build from source
cargo build --release

# Verify build is reproducible
cargo clean
cargo build --release
sha256sum target/release/telemetry-kit

---

Supply Chain Threats

Threats We Mitigate

Threat	Mitigation	SLSA Level
Compromised source repo	Branch protection, 2FA required	L2
Malicious dependencies	cargo-deny, cargo-audit	L2
Tampered build process	Immutable workflow files	L2
Man-in-the-middle attacks	HTTPS, TLS certificate pinning	L1
Compromised build environment	Ephemeral GitHub runners	L3
Forged provenance	GitHub-signed attestations	L3 (partial)

Threats We're Working On

Threat	Status	Target
Dependency confusion	🔄 Planning	L3
Typosquatting	🔄 Monitoring	L2
Compromised maintainer account	✅ 2FA enforced	L2
Build parameter injection	🔄 Hardening	L3
Time-of-check to time-of-use (TOCTOU)	❌ Future	L4

Known Limitations

❌ Not Yet Addressed:

• Hermetic builds (dependencies fetched at build time)
• Reproducible builds (timestamps in binaries)
• Post-build tampering (waiting for Sigstore)
• Supply chain attacks on build tools (cargo, rustc)

---

Roadmap

Q1 2025 - SLSA Level 2 Complete ✅

• GitHub Actions for builds
• Provenance generation
• Branch protection
• Automated releases
• Checksums published

Q2 2025 - SLSA Level 3

• Sigstore integration
  • Sign releases with cosign
  • Upload to Rekor transparency log
  • Verify in CI/CD
• Hardened builds
  • Network isolation
  • Read-only filesystems
  • Minimal base images
• Parameterless builds
  • Version from git tags only
  • No manual workflow triggers

Q3 2025 - Enhanced Security

• Reproducible builds
  • Fixed timestamps
  • Hermetic dependencies
  • Vendored crates
• SBOM generation
  • CycloneDX format
  • Dependency graph
  • License compliance
• Vulnerability scanning
  • Automated Dependabot PRs
  • Trivy container scanning
  • OSV.dev integration

Q4 2025 - SLSA Level 4 (Aspirational)

• Two-party review
• Mandatory code review
• Signed commits required
• Build reproducibility verified
• Complete audit trail

---

Dependencies

Trusted Publishers

We trust these crates.io publishers:

• tokio - Tokio team (verified)
• serde - Serde team (verified)
• reqwest - Sean McArthur (verified)
• rusqlite - John Gallagher (verified)

Dependency Verification

# Audit dependencies for vulnerabilities
cargo audit

# Check dependency licenses
cargo deny check licenses

# Review dependency authors
cargo supply-chain publishers

# Check for unmaintained crates
cargo outdated

Cargo.lock

We commit Cargo.lock to ensure deterministic builds:

# Verify dependencies match lock
cargo verify-project

# Check for inconsistencies
cargo tree

---

Contributing to SLSA Compliance

For Contributors

Before Submitting PRs:

• Sign your commits: git config --global commit.gpgsign true
• Run security checks: cargo audit && cargo deny check
• No secrets in code: git-secrets --scan

In Pull Requests:

• Add new dependencies to deny.toml allowlist
• Update SBOM if dependencies change
• Note security implications in PR description

For Maintainers

Before Merging:

• Review dependency changes carefully
• Check for suspicious code patterns
• Verify CI passes all security checks
• Ensure provenance will be generated

Release Process:

• Tag with GPG-signed tag
• Wait for automated build
• Verify attestation is generated
• Test installation from crates.io

---

References

SLSA Documentation

• SLSA Levels
• SLSA Requirements
• Provenance Format

Tools & Services

• GitHub Attestations
• Sigstore
• in-toto
• cargo-audit
• cargo-deny

Standards

• SLSA Specification v1.0
• in-toto Specification
• The Update Framework (TUF)

---

Contact

Questions about SLSA compliance?

• Email: security@ibrahimcesar.com
• GitHub: https://github.com/ibrahimcesar/telemetry-kit/security
• Discussions: https://github.com/ibrahimcesar/telemetry-kit/discussions

---

Document Version: 1.0 Last Updated: 2025-01-22 SLSA Level: 2 (working towards 3)