feat: implement comprehensive supply chain security with cryptographic verification and documentation

2026-01-10 03:39:25 +00:00
parent 8bcfe28709
commit b2d5418d67
5 changed files with 1124 additions and 3 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+### Added
+
+- **Supply Chain Security**: Comprehensive supply chain security implementation with cryptographic verification (PR #XXX)
+  - **Cosign Signatures**: All container images cryptographically signed with keyless Sigstore Cosign
+  - **SLSA Provenance**: SLSA Level 3 compliant build provenance attestation for verifiable builds
+  - **SBOM Generation**: Software Bill of Materials in SPDX format for all releases
+  - **Transparency Log**: All signatures recorded in public Rekor transparency log
+  - **VS Code Integration**: Three new agent skills for developers:
+    - `security-verify-sbom`: Verify SBOM contents and check for vulnerabilities
+    - `security-sign-cosign`: Sign container images with Cosign
+    - `security-slsa-provenance`: Generate SLSA provenance attestation
+  - **Automated Verification**: Tasks integrated into development workflow
+  - **Documentation**: Complete user and developer guides for verification and usage
+  - See [Supply Chain Security User Guide](docs/guides/supply-chain-security-user-guide.md) for verification instructions
+  - See [Supply Chain Security Developer Guide](docs/guides/supply-chain-security-developer-guide.md) for development workflow
+
 ### Verified

 - **React 19 Compatibility:** Confirmed React 19.2.3 works correctly with lucide-react@0.562.0
--- a/README.md
+++ b/README.md
@@ -66,7 +66,11 @@ Free SSL certificates that request, install, and renew themselves. Your sites ge

 Web Application Firewall, rate limiting, geographic blocking, access control lists, and intrusion detection via CrowdSec. Protection that "just works."

-### 🔗 **Smart Proxy Headers**
+### <EFBFBD> **Supply Chain Security**
+
+Verifiable builds with cryptographic signatures, SLSA provenance attestation, and comprehensive SBOMs. Verify what you run with transparent, tamper-proof evidence.
+
+### <20>🔗 **Smart Proxy Headers**

 Automatically adds standard headers (X-Real-IP, X-Forwarded-Proto, etc.) so your backend applications see real client IPs, enforce HTTPS correctly, and log accurately—with full backward compatibility for existing hosts.

@@ -264,8 +268,7 @@ All JSON templates support these variables:
 ## Getting Help

 **[📖 Full Documentation](https://wikid82.github.io/charon/)** — Everything explained simply
-**[🚀 5-Minute Guide](https://wikid82.github.io/charon/getting-started)** — Your first website up and running
-**[<EFBFBD> Troubleshooting](docs/troubleshooting/)** — Common issues and solutions
+**[🚀 5-Minute Guide](https://wikid82.github.io/charon/getting-started)** — Your first website up and running**[🔐 Supply Chain Security](docs/guides/supply-chain-security-user-guide.md)** — Verify signatures and build provenance**[<EFBFBD> Troubleshooting](docs/troubleshooting/)** — Common issues and solutions
 **[<EFBFBD>💬 Ask Questions](https://github.com/Wikid82/charon/discussions)** — Friendly community help
 **[🐛 Report Problems](https://github.com/Wikid82/charon/issues)** — Something broken? Let us know

--- a/SECURITY.md
+++ b/SECURITY.md
@@ -183,6 +183,107 @@ services:

 ---

+## Supply Chain Security
+
+Charon implements comprehensive supply chain security measures to ensure the integrity and authenticity of releases. Every release includes cryptographic signatures, SLSA provenance attestation, and Software Bill of Materials (SBOM).
+
+### Verification Commands
+
+#### Verify Container Image Signature
+
+All official Charon images are signed with Sigstore Cosign:
+
+```bash
+# Install cosign (if not already installed)
+curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64
+sudo mv cosign-linux-amd64 /usr/local/bin/cosign
+sudo chmod +x /usr/local/bin/cosign
+
+# Verify image signature
+cosign verify \
+  --certificate-identity-regexp='https://github.com/Wikid82/charon' \
+  --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
+  ghcr.io/wikid82/charon:latest
+```
+
+Successful verification output confirms:
+- The image was built by GitHub Actions
+- The build came from the official Charon repository
+- The image has not been tampered with since signing
+
+#### Verify SLSA Provenance
+
+SLSA (Supply-chain Levels for Software Artifacts) provenance provides tamper-proof evidence of how the software was built:
+
+```bash
+# Install slsa-verifier (if not already installed)
+curl -LO https://github.com/slsa-framework/slsa-verifier/releases/latest/download/slsa-verifier-linux-amd64
+sudo mv slsa-verifier-linux-amd64 /usr/local/bin/slsa-verifier
+sudo chmod +x /usr/local/bin/slsa-verifier
+
+# Download provenance from release assets
+curl -LO https://github.com/Wikid82/charon/releases/latest/download/provenance.json
+
+# Verify provenance
+slsa-verifier verify-artifact \
+  --provenance-path provenance.json \
+  --source-uri github.com/Wikid82/charon \
+  ./backend/charon-binary
+```
+
+#### Inspect Software Bill of Materials (SBOM)
+
+Every release includes a comprehensive SBOM in SPDX format:
+
+```bash
+# Download SBOM from release assets
+curl -LO https://github.com/Wikid82/charon/releases/latest/download/sbom.spdx.json
+
+# View SBOM contents
+cat sbom.spdx.json | jq .
+
+# Check for known vulnerabilities (requires Grype)
+grype sbom:sbom.spdx.json
+```
+
+### Transparency Log (Rekor)
+
+All signatures are recorded in the public Sigstore Rekor transparency log, providing an immutable audit trail:
+
+- **Search the log**: <https://search.sigstore.dev/>
+- **Query by image**: Search for `ghcr.io/wikid82/charon`
+- **View entry details**: Each entry includes commit SHA, workflow run, and signing timestamp
+
+### Automated Verification in CI/CD
+
+Integrate supply chain verification into your deployment pipeline:
+
+```yaml
+# Example GitHub Actions workflow
+- name: Verify Charon Image
+  run: |
+    cosign verify \
+      --certificate-identity-regexp='https://github.com/Wikid82/charon' \
+      --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
+      ghcr.io/wikid82/charon:${{ env.VERSION }}
+```
+
+### What's Protected
+
+- **Container Images**: All `ghcr.io/wikid82/charon:*` images are signed
+- **Release Binaries**: Backend binaries include provenance attestation
+- **Build Process**: SLSA Level 3 compliant build provenance
+- **Dependencies**: Complete SBOM including all direct and transitive dependencies
+
+### Learn More
+
+- **[User Guide](docs/guides/supply-chain-security-user-guide.md)**: Step-by-step verification instructions
+- **[Developer Guide](docs/guides/supply-chain-security-developer-guide.md)**: Integration into development workflow
+- **[Sigstore Documentation](https://docs.sigstore.dev/)**: Technical details on signing and verification
+- **[SLSA Framework](https://slsa.dev/)**: Supply chain security framework overview
+
+---
+
 ## Security Audits & Scanning

 ### Automated Scanning
--- a/docs/guides/supply-chain-security-developer-guide.md
+++ b/docs/guides/supply-chain-security-developer-guide.md
@@ -0,0 +1,667 @@
+# Supply Chain Security - Developer Guide
+
+## Overview
+
+This guide explains how to use Charon's supply chain security tools during development, testing, and release preparation. It covers the three agent skills, when to use them, and how they integrate into your workflow.
+
+---
+
+## Table of Contents
+
+1. [Quick Reference](#quick-reference)
+2. [Agent Skills Overview](#agent-skills-overview)
+3. [Development Workflow](#development-workflow)
+4. [Testing and Validation](#testing-and-validation)
+5. [Release Process](#release-process)
+6. [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick Reference
+
+### Available VS Code Tasks
+
+```bash
+# Verify SBOM and scan for vulnerabilities
+Task: "Security: Verify SBOM"
+
+# Sign a container image with Cosign
+Task: "Security: Sign with Cosign"
+
+# Generate SLSA provenance for a binary
+Task: "Security: Generate SLSA Provenance"
+
+# Run all supply chain checks
+Task: "Security: Full Supply Chain Audit"
+```
+
+### Direct Skill Invocation
+
+```bash
+# From project root
+.github/skills/scripts/skill-runner.sh security-verify-sbom [image]
+.github/skills/scripts/skill-runner.sh security-sign-cosign [type] [target]
+.github/skills/scripts/skill-runner.sh security-slsa-provenance [action] [target]
+```
+
+---
+
+## Agent Skills Overview
+
+### 1. security-verify-sbom
+
+**Purpose:** Verify SBOM contents and scan for vulnerabilities
+
+**Usage:**
+```bash
+# Verify container image SBOM
+.github/skills/scripts/skill-runner.sh security-verify-sbom docker charon:local
+
+# Verify directory SBOM
+.github/skills/scripts/skill-runner.sh security-verify-sbom dir ./backend
+
+# Verify file SBOM
+.github/skills/scripts/skill-runner.sh security-verify-sbom file ./backend/main
+```
+
+**What it does:**
+1. Generates SBOM using Syft (if not exists)
+2. Validates SBOM format (SPDX JSON)
+3. Scans for vulnerabilities using Grype
+4. Reports findings with severity levels
+
+**When to use:**
+- Before committing dependency updates
+- After building new images
+- Before releases
+- During security audits
+
+**Output:**
+- SBOM file (SPDX JSON format)
+- Vulnerability report
+- Summary of critical/high findings
+
+### 2. security-sign-cosign
+
+**Purpose:** Sign container images or binaries with Cosign
+
+**Usage:**
+```bash
+# Sign Docker image
+.github/skills/scripts/skill-runner.sh security-sign-cosign docker charon:local
+
+# Sign binary file
+.github/skills/scripts/skill-runner.sh security-sign-cosign file ./backend/main
+
+# Sign OCI artifact
+.github/skills/scripts/skill-runner.sh security-sign-cosign oci ghcr.io/wikid82/charon:latest
+```
+
+**What it does:**
+1. Verifies target exists
+2. Signs with Cosign (keyless or with key)
+3. Records signature in Rekor transparency log
+4. Generates verification commands
+
+**When to use:**
+- After building local test images
+- Before pushing to registry
+- During release preparation
+- For artifact attestation
+
+**Requirements:**
+- Cosign installed (`make install-cosign`)
+- Docker running (for image signing)
+- Network access (for Rekor)
+
+### 3. security-slsa-provenance
+
+**Purpose:** Generate and verify SLSA provenance attestation
+
+**Usage:**
+```bash
+# Generate provenance for binary
+.github/skills/scripts/skill-runner.sh security-slsa-provenance generate ./backend/main
+
+# Verify provenance
+.github/skills/scripts/skill-runner.sh security-slsa-provenance verify ./backend/main provenance.json
+
+# Validate provenance format
+.github/skills/scripts/skill-runner.sh security-slsa-provenance validate provenance.json
+```
+
+**What it does:**
+1. Collects build metadata (commit, branch, timestamp)
+2. Generates SLSA provenance document
+3. Signs provenance with Cosign
+4. Verifies provenance integrity
+
+**When to use:**
+- After building release binaries
+- Before publishing releases
+- For compliance requirements
+- To prove build reproducibility
+
+**Output:**
+- `provenance.json` - SLSA provenance attestation
+- Verification status
+- Build metadata
+
+---
+
+## Development Workflow
+
+### Daily Development
+
+#### 1. Dependency Updates
+
+When updating dependencies:
+
+```bash
+# 1. Update dependencies
+cd backend && go get -u ./...
+cd ../frontend && npm update
+
+# 2. Build and test
+make build-all
+make test-all
+
+# 3. Verify SBOM (check for new vulnerabilities)
+.github/skills/scripts/skill-runner.sh security-verify-sbom docker charon:local
+```
+
+**Review output:**
+- ✅ No critical/high vulnerabilities → Proceed
+- ⚠️ Vulnerabilities found → Review, patch, or document
+
+#### 2. Local Testing
+
+Before committing:
+
+```bash
+# 1. Build local image
+docker build -t charon:dev .
+
+# 2. Generate and verify SBOM
+.github/skills/scripts/skill-runner.sh security-verify-sbom docker charon:dev
+
+# 3. Sign image (optional, for testing)
+.github/skills/scripts/skill-runner.sh security-sign-cosign docker charon:dev
+```
+
+#### 3. Pre-Commit Checks
+
+Add to your pre-commit routine:
+
+```bash
+# .git/hooks/pre-commit (or pre-commit config)
+#!/bin/bash
+set -e
+
+echo "🔍 Running supply chain checks..."
+
+# Build
+make build-all
+
+# Verify SBOM
+.github/skills/scripts/skill-runner.sh security-verify-sbom dir ./backend
+
+# Check for critical vulnerabilities
+if grep -i "critical" sbom-scan-output.txt; then
+    echo "❌ Critical vulnerabilities found! Review before committing."
+    exit 1
+fi
+
+echo "✅ Supply chain checks passed"
+```
+
+### Pull Request Workflow
+
+#### As a Developer
+
+```bash
+# 1. Build and test locally
+make build-all
+make test-all
+
+# 2. Run full supply chain audit
+# (Uses the composite VS Code task)
+# Run via VS Code: Ctrl+Shift+P → "Tasks: Run Task" → "Security: Full Supply Chain Audit"
+
+# 3. Document findings in PR description
+# - SBOM changes (new dependencies)
+# - Vulnerability scan results
+# - Signature verification status
+```
+
+#### As a Reviewer
+
+Verify supply chain artifacts:
+
+```bash
+# 1. Checkout PR branch
+git fetch origin pull/123/head:pr-123
+git checkout pr-123
+
+# 2. Build
+make build-all
+
+# 3. Verify SBOM
+.github/skills/scripts/skill-runner.sh security-verify-sbom docker charon:local
+
+# 4. Check for regressions
+# - New vulnerabilities introduced?
+# - Unexpected dependency changes?
+# - SBOM completeness?
+```
+
+**Review checklist:**
+- [ ] SBOM includes all new dependencies
+- [ ] No new critical/high vulnerabilities
+- [ ] Dependency licenses compatible
+- [ ] Security documentation updated
+
+---
+
+## Testing and Validation
+
+### Unit Testing Supply Chain Skills
+
+```bash
+# Test SBOM generation
+.github/skills/scripts/skill-runner.sh security-verify-sbom dir ./backend
+test -f sbom.spdx.json || echo "❌ SBOM not generated"
+
+# Test signing (requires Cosign)
+docker build -t charon:test .
+.github/skills/scripts/skill-runner.sh security-sign-cosign docker charon:test
+echo $? # Should be 0 for success
+
+# Test provenance generation
+go build -o main ./backend/cmd/charon
+.github/skills/scripts/skill-runner.sh security-slsa-provenance generate ./main
+test -f provenance.json || echo "❌ Provenance not generated"
+```
+
+### Integration Testing
+
+Create a test script:
+
+```bash
+#!/bin/bash
+# test-supply-chain.sh
+set -e
+
+echo "🔧 Building test image..."
+docker build -t charon:integration-test .
+
+echo "🔍 Verifying SBOM..."
+.github/skills/scripts/skill-runner.sh security-verify-sbom docker charon:integration-test
+
+echo "✍️ Signing image..."
+.github/skills/scripts/skill-runner.sh security-sign-cosign docker charon:integration-test
+
+echo "🔐 Verifying signature..."
+cosign verify \
+  --certificate-identity-regexp='.*' \
+  --certificate-oidc-issuer='.*' \
+  charon:integration-test || echo "⚠️ Verification expected to fail for local image"
+
+echo "📄 Generating provenance..."
+.github/skills/scripts/skill-runner.sh security-slsa-provenance generate ./backend/main
+
+echo "✅ All supply chain tests passed!"
+```
+
+Run in CI/CD:
+
+```yaml
+# .github/workflows/test.yml
+- name: Test Supply Chain
+  run: |
+    chmod +x test-supply-chain.sh
+    ./test-supply-chain.sh
+```
+
+### Validation Checklist
+
+Before marking a feature complete:
+
+- [ ] SBOM generation works for all artifacts
+- [ ] Signing works for images and binaries
+- [ ] Provenance generation includes correct metadata
+- [ ] Verification commands documented
+- [ ] CI/CD integration tested
+- [ ] Error handling validated
+- [ ] Documentation updated
+
+---
+
+## Release Process
+
+### Pre-Release Checklist
+
+#### 1. Version Bump and Tag
+
+```bash
+# Update version
+echo "v1.0.0" > VERSION
+
+# Commit and tag
+git add VERSION
+git commit -m "chore: bump version to v1.0.0"
+git tag -a v1.0.0 -m "Release v1.0.0"
+```
+
+#### 2. Build Release Artifacts
+
+```bash
+# Build backend binary
+cd backend
+go build -ldflags="-s -w -X main.Version=v1.0.0" -o charon-linux-amd64 ./cmd/charon
+
+# Build frontend
+cd ../frontend
+npm run build
+
+# Build Docker image
+cd ..
+docker build -t charon:v1.0.0 .
+```
+
+#### 3. Generate Supply Chain Artifacts
+
+```bash
+# Generate SBOM for image
+.github/skills/scripts/skill-runner.sh security-verify-sbom docker charon:v1.0.0
+mv sbom.spdx.json sbom-v1.0.0.spdx.json
+
+# Generate SBOM for binary
+.github/skills/scripts/skill-runner.sh security-verify-sbom file ./backend/charon-linux-amd64
+mv sbom.spdx.json sbom-binary-v1.0.0.spdx.json
+
+# Generate provenance for binary
+.github/skills/scripts/skill-runner.sh security-slsa-provenance generate ./backend/charon-linux-amd64
+mv provenance.json provenance-v1.0.0.json
+
+# Sign binary
+.github/skills/scripts/skill-runner.sh security-sign-cosign file ./backend/charon-linux-amd64
+```
+
+#### 4. Push and Sign Image
+
+```bash
+# Tag image for registry
+docker tag charon:v1.0.0 ghcr.io/wikid82/charon:v1.0.0
+docker tag charon:v1.0.0 ghcr.io/wikid82/charon:latest
+
+# Push to registry
+docker push ghcr.io/wikid82/charon:v1.0.0
+docker push ghcr.io/wikid82/charon:latest
+
+# Sign images
+.github/skills/scripts/skill-runner.sh security-sign-cosign oci ghcr.io/wikid82/charon:v1.0.0
+.github/skills/scripts/skill-runner.sh security-sign-cosign oci ghcr.io/wikid82/charon:latest
+```
+
+#### 5. Verify Release Artifacts
+
+```bash
+# Verify image signature
+cosign verify \
+  --certificate-identity-regexp='https://github.com/Wikid82/charon' \
+  --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
+  ghcr.io/wikid82/charon:v1.0.0
+
+# Verify provenance
+slsa-verifier verify-artifact \
+  --provenance-path provenance-v1.0.0.json \
+  --source-uri github.com/Wikid82/charon \
+  ./backend/charon-linux-amd64
+
+# Scan SBOM
+grype sbom:sbom-v1.0.0.spdx.json
+```
+
+#### 6. Create GitHub Release
+
+Upload these files as release assets:
+- `charon-linux-amd64` - Binary
+- `charon-linux-amd64.sig` - Binary signature
+- `sbom-v1.0.0.spdx.json` - Image SBOM
+- `sbom-binary-v1.0.0.spdx.json` - Binary SBOM
+- `provenance-v1.0.0.json` - SLSA provenance
+
+Release notes should include:
+- Verification commands
+- Link to user guide
+- Known vulnerabilities (if any)
+
+### Automated Release (GitHub Actions)
+
+The release process is automated via GitHub Actions. The workflow:
+
+1. Triggers on version tags (`v*`)
+2. Builds artifacts
+3. Generates SBOMs and provenance
+4. Signs with Cosign (keyless)
+5. Pushes to registry
+6. Creates GitHub release with assets
+
+See `.github/workflows/release.yml` for implementation.
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### "syft: command not found"
+
+**Solution:**
+```bash
+make install-syft
+# Or manually:
+curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
+```
+
+#### "cosign: command not found"
+
+**Solution:**
+```bash
+make install-cosign
+# Or manually:
+curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64
+sudo mv cosign-linux-amd64 /usr/local/bin/cosign
+sudo chmod +x /usr/local/bin/cosign
+```
+
+#### "grype: command not found"
+
+**Solution:**
+```bash
+make install-grype
+# Or manually:
+curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin
+```
+
+#### SBOM Generation Fails
+
+**Possible causes:**
+- Docker image doesn't exist
+- Directory/file path incorrect
+- Syft version incompatible
+
+**Debug:**
+```bash
+# Check image exists
+docker images | grep charon
+
+# Test Syft manually
+syft docker:charon:local -o spdx-json
+
+# Check Syft version
+syft version
+```
+
+#### Signing Fails with "no ambient OIDC credentials"
+
+**Cause:** Cosign keyless signing requires OIDC authentication (GitHub Actions, Google Cloud, etc.)
+
+**Solutions:**
+1. Use key-based signing for local development:
+   ```bash
+   cosign generate-key-pair
+   cosign sign --key cosign.key charon:local
+   ```
+
+2. Set up OIDC provider (GitHub Actions example):
+   ```yaml
+   permissions:
+     id-token: write
+     packages: write
+   ```
+
+3. Use environment variables:
+   ```bash
+   export COSIGN_EXPERIMENTAL=1
+   ```
+
+#### Provenance Verification Fails
+
+**Possible causes:**
+- Provenance file doesn't match binary
+- Binary was modified after provenance generation
+- Wrong source URI
+
+**Debug:**
+```bash
+# Check binary hash
+sha256sum ./backend/charon-linux-amd64
+
+# Check hash in provenance
+cat provenance.json | jq -r '.subject[0].digest.sha256'
+
+# Hashes should match
+```
+
+### Performance Optimization
+
+#### SBOM Generation is Slow
+
+**Optimization:**
+```bash
+# Cache SBOM between runs
+SBOM_FILE="sbom-$(git rev-parse --short HEAD).spdx.json"
+if [ ! -f "$SBOM_FILE" ]; then
+    syft docker:charon:local -o spdx-json > "$SBOM_FILE"
+fi
+```
+
+#### Large Image Scans Timeout
+
+**Solution:**
+```bash
+# Increase timeout
+export GRYPE_CHECK_FOR_APP_UPDATE=false
+export GRYPE_DB_AUTO_UPDATE=false
+grype --timeout 10m docker:charon:local
+```
+
+### Debugging
+
+Enable verbose logging:
+
+```bash
+# For skill scripts
+export SKILL_DEBUG=1
+.github/skills/scripts/skill-runner.sh security-verify-sbom docker charon:local
+
+# For Syft
+export SYFT_LOG_LEVEL=debug
+syft docker:charon:local
+
+# For Cosign
+export COSIGN_LOG_LEVEL=debug
+cosign sign charon:local
+
+# For Grype
+export GRYPE_LOG_LEVEL=debug
+grype docker:charon:local
+```
+
+---
+
+## Best Practices
+
+### Security
+
+1. **Never commit private keys**: Use keyless signing or store keys securely
+2. **Verify before sign**: Always verify artifacts before signing
+3. **Use specific versions**: Pin tool versions in CI/CD
+4. **Rotate keys regularly**: If using key-based signing
+5. **Monitor transparency logs**: Check Rekor for unexpected signatures
+
+### Development
+
+1. **Generate SBOM early**: Run during development, not just before release
+2. **Automate verification**: Add to CI/CD and pre-commit hooks
+3. **Document vulnerabilities**: Track known issues in SECURITY.md
+4. **Test locally**: Verify skills work on developer machines
+5. **Update dependencies**: Keep tools (Syft, Cosign, Grype) current
+
+### CI/CD
+
+1. **Cache tools**: Cache tool installations between runs
+2. **Parallel execution**: Run SBOM generation and signing in parallel
+3. **Fail fast**: Exit early on critical vulnerabilities
+4. **Artifact retention**: Store SBOMs and provenance as artifacts
+5. **Release automation**: Fully automate release signing and verification
+
+---
+
+## Additional Resources
+
+### Documentation
+
+- [User Guide](supply-chain-security-user-guide.md) - End-user verification
+- [SECURITY.md](../../SECURITY.md) - Security policy and contacts
+- [Skill Implementation](../.github/skills/security-supply-chain/) - Skill source code
+
+### External Resources
+
+- [Sigstore Documentation](https://docs.sigstore.dev/)
+- [SLSA Framework](https://slsa.dev/)
+- [Syft Documentation](https://github.com/anchore/syft)
+- [Grype Documentation](https://github.com/anchore/grype)
+- [Cosign Documentation](https://docs.sigstore.dev/cosign/overview/)
+
+### Tools
+
+- [Sigstore Rekor Search](https://search.sigstore.dev/)
+- [SPDX Online Tools](https://tools.spdx.org/)
+- [Supply Chain Security Best Practices](https://slsa.dev/spec/v1.0/requirements)
+
+---
+
+## Support
+
+### Getting Help
+
+- **Questions**: [GitHub Discussions](https://github.com/Wikid82/charon/discussions)
+- **Bug Reports**: [GitHub Issues](https://github.com/Wikid82/charon/issues)
+- **Security**: [Security Advisory](https://github.com/Wikid82/charon/security/advisories)
+
+### Contributing
+
+Found a bug or want to improve the supply chain security implementation?
+
+1. Open an issue describing the problem
+2. Submit a PR with fixes/improvements
+3. Update tests and documentation
+4. Run full supply chain audit before submitting
+
+---
+
+**Last Updated**: January 10, 2026
+**Version**: 1.0
--- a/docs/guides/supply-chain-security-user-guide.md
+++ b/docs/guides/supply-chain-security-user-guide.md
@@ -0,0 +1,334 @@
+# Supply Chain Security - User Guide
+
+## Overview
+
+Charon implements comprehensive supply chain security measures to ensure you can verify the authenticity and integrity of every release. This guide shows you how to verify signatures, check build provenance, and inspect Software Bill of Materials (SBOM).
+
+## Why Supply Chain Security Matters
+
+When you download and run software, you're trusting that:
+- The software came from the legitimate source
+- It hasn't been tampered with during distribution
+- The build process was secure and reproducible
+- You know exactly what dependencies are included
+
+Supply chain attacks are increasingly common. Charon's verification tools help you confirm what you're running is exactly what the developers built.
+
+---
+
+## Quick Start: Verify a Release
+
+### Prerequisites
+
+Install verification tools (one-time setup):
+
+```bash
+# Install Cosign (for signature verification)
+curl -LO https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64
+sudo mv cosign-linux-amd64 /usr/local/bin/cosign
+sudo chmod +x /usr/local/bin/cosign
+
+# Install slsa-verifier (for provenance verification)
+curl -LO https://github.com/slsa-framework/slsa-verifier/releases/latest/download/slsa-verifier-linux-amd64
+sudo mv slsa-verifier-linux-amd64 /usr/local/bin/slsa-verifier
+sudo chmod +x /usr/local/bin/slsa-verifier
+
+# Install Grype (optional, for SBOM vulnerability scanning)
+curl -sSfL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b /usr/local/bin
+```
+
+### Verify Container Image (Recommended)
+
+Verify the Charon container image before running it:
+
+```bash
+cosign verify \
+  --certificate-identity-regexp='https://github.com/Wikid82/charon' \
+  --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
+  ghcr.io/wikid82/charon:latest
+```
+
+**Expected Output:**
+```
+Verification for ghcr.io/wikid82/charon:latest --
+The following checks were performed on each of these signatures:
+  - The cosign claims were validated
+  - Existence of the claims in the transparency log was verified offline
+  - The code-signing certificate was verified using trusted certificate authority certificates
+```
+
+---
+
+## Detailed Verification Steps
+
+### 1. Verify Image Signature with Cosign
+
+**What it does:** Confirms the image was signed by the Charon project and hasn't been modified.
+
+**Command:**
+```bash
+cosign verify \
+  --certificate-identity-regexp='https://github.com/Wikid82/charon' \
+  --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
+  ghcr.io/wikid82/charon:v1.0.0
+```
+
+**What to check:**
+- ✅ "Verification for ... --" message appears
+- ✅ Certificate identity matches `https://github.com/Wikid82/charon`
+- ✅ OIDC issuer is `https://token.actions.githubusercontent.com`
+- ✅ No errors or warnings
+
+**Troubleshooting:**
+- **Error: "no matching signatures"** → The image may not be signed, or you have the wrong tag
+- **Error: "certificate identity doesn't match"** → The image may be compromised or unofficial
+- **Error: "OIDC issuer doesn't match"** → The signing process didn't use GitHub Actions
+
+### 2. Verify SLSA Provenance
+
+**What it does:** Proves the software was built by the official GitHub Actions workflow from the official repository.
+
+**Step 1: Download provenance**
+```bash
+curl -LO https://github.com/Wikid82/charon/releases/download/v1.0.0/provenance.json
+```
+
+**Step 2: Download the binary**
+```bash
+curl -LO https://github.com/Wikid82/charon/releases/download/v1.0.0/charon-linux-amd64
+```
+
+**Step 3: Verify provenance**
+```bash
+slsa-verifier verify-artifact \
+  --provenance-path provenance.json \
+  --source-uri github.com/Wikid82/charon \
+  charon-linux-amd64
+```
+
+**Expected Output:**
+```
+Verified signature against tlog entry index XXXXX at URL: https://rekor.sigstore.dev/api/v1/log/entries/...
+Verified build using builder https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@refs/tags/v1.9.0 at commit SHA256:...
+PASSED: Verified SLSA provenance
+```
+
+**What to check:**
+- ✅ "PASSED: Verified SLSA provenance"
+- ✅ Builder is the official SLSA generator
+- ✅ Source URI matches `github.com/Wikid82/charon`
+- ✅ Entry is recorded in Rekor transparency log
+
+**Troubleshooting:**
+- **Error: "artifact hash doesn't match"** → The binary may have been tampered with
+- **Error: "source URI doesn't match"** → The build came from an unofficial repository
+- **Error: "invalid provenance"** → The provenance file may be corrupted
+
+### 3. Inspect Software Bill of Materials (SBOM)
+
+**What it does:** Shows all dependencies included in Charon, allowing you to check for known vulnerabilities.
+
+**Step 1: Download SBOM**
+```bash
+curl -LO https://github.com/Wikid82/charon/releases/download/v1.0.0/sbom.spdx.json
+```
+
+**Step 2: View SBOM contents**
+```bash
+# Pretty-print the SBOM
+cat sbom.spdx.json | jq .
+
+# List all packages
+cat sbom.spdx.json | jq -r '.packages[].name' | sort
+```
+
+**Step 3: Check for vulnerabilities**
+```bash
+# Requires Grype (see prerequisites)
+grype sbom:sbom.spdx.json
+```
+
+**Expected Output:**
+```
+NAME                 INSTALLED           VULNERABILITY   SEVERITY
+github.com/caddyserver/caddy/v2  v2.11.0    (no vulnerabilities found)
+...
+```
+
+**What to check:**
+- ✅ SBOM contains expected packages (Go modules, npm packages)
+- ✅ Package versions match release notes
+- ✅ No critical or high-severity vulnerabilities
+- ⚠️ Known acceptable vulnerabilities are documented in SECURITY.md
+
+**Troubleshooting:**
+- **High/Critical vulnerabilities found** → Check SECURITY.md for known issues and mitigation status
+- **SBOM format error** → Download may be corrupted, try again
+- **Missing packages** → SBOM may be incomplete, report as an issue
+
+---
+
+## Verify in Your CI/CD Pipeline
+
+Integrate verification into your deployment workflow:
+
+### GitHub Actions Example
+
+```yaml
+name: Deploy Charon
+on:
+  push:
+    branches: [main]
+
+jobs:
+  verify-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Cosign
+        uses: sigstore/cosign-installer@v3
+
+      - name: Verify Charon Image
+        run: |
+          cosign verify \
+            --certificate-identity-regexp='https://github.com/Wikid82/charon' \
+            --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
+            ghcr.io/wikid82/charon:latest
+
+      - name: Deploy
+        if: success()
+        run: |
+          docker-compose pull
+          docker-compose up -d
+```
+
+### Docker Compose with Pre-Pull Verification
+
+```bash
+#!/bin/bash
+set -e
+
+IMAGE="ghcr.io/wikid82/charon:latest"
+
+echo "🔍 Verifying image signature..."
+cosign verify \
+  --certificate-identity-regexp='https://github.com/Wikid82/charon' \
+  --certificate-oidc-issuer='https://token.actions.githubusercontent.com' \
+  "$IMAGE"
+
+echo "✅ Signature verified!"
+echo "🚀 Pulling and starting Charon..."
+docker-compose pull
+docker-compose up -d
+
+echo "✅ Charon started successfully"
+```
+
+---
+
+## Transparency and Audit Trail
+
+### Sigstore Rekor Transparency Log
+
+All signatures are recorded in the public Rekor transparency log:
+
+1. **Visit**: <https://search.sigstore.dev/>
+2. **Search**: Enter `ghcr.io/wikid82/charon` or a specific tag
+3. **View Entry**: Click on an entry to see:
+   - Signing timestamp
+   - Git commit SHA
+   - GitHub Actions workflow run ID
+   - Certificate details
+
+**Why this matters:** The transparency log provides an immutable, public record of all signatures. If a compromise occurs, it can be detected by comparing signatures against the log.
+
+### GitHub Release Assets
+
+Each release includes:
+- `provenance.json` - SLSA provenance attestation
+- `sbom.spdx.json` - Software Bill of Materials
+- `*.sig` - Cosign signature files (for binaries)
+- `charon-*` - Release binaries
+
+**Download from**: <https://github.com/Wikid82/charon/releases>
+
+---
+
+## Security Best Practices
+
+### Before Deploying
+1. ✅ Always verify signatures before first deployment
+2. ✅ Check SBOM for known vulnerabilities
+3. ✅ Verify provenance for critical environments
+4. ✅ Pin to specific version tags (not `latest`)
+
+### During Operations
+1. ✅ Set up automated verification in CI/CD
+2. ✅ Monitor SECURITY.md for vulnerability updates
+3. ✅ Subscribe to GitHub release notifications
+4. ✅ Re-verify after any manual image pulls
+
+### For Production Environments
+1. ✅ Require signature verification before deployment
+2. ✅ Use admission controllers (e.g., Kyverno, OPA) to enforce verification
+3. ✅ Maintain audit logs of verified deployments
+4. ✅ Scan SBOM against private vulnerability databases
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+#### "cosign: command not found"
+**Solution:** Install Cosign (see Prerequisites section)
+
+#### "Error: no matching signatures"
+**Possible causes:**
+- Image tag doesn't exist
+- Image was pulled before signing implementation
+- Using an unofficial image source
+
+**Solution:** Use official images from `ghcr.io/wikid82/charon` with tags v1.0.0 or later
+
+#### "Error: certificate identity doesn't match"
+**Possible causes:**
+- Image is from an unofficial source
+- Image may be compromised
+
+**Solution:** Only use images from the official repository. Report suspicious images.
+
+#### "slsa-verifier: verification failed"
+**Possible causes:**
+- Provenance file doesn't match the binary
+- Binary was modified after signing
+- Wrong provenance file downloaded
+
+**Solution:** Re-download both provenance and binary from the same release
+
+#### Grype shows vulnerabilities
+**Solution:**
+1. Check SECURITY.md for known issues
+2. Review vulnerability severity and exploitability
+3. Check if patches are available in newer releases
+4. Report new vulnerabilities via GitHub Security Advisory
+
+### Getting Help
+
+- **Documentation**: [Developer Guide](supply-chain-security-developer-guide.md)
+- **Security Issues**: <https://github.com/Wikid82/charon/security/advisories>
+- **Questions**: <https://github.com/Wikid82/charon/discussions>
+- **Bug Reports**: <https://github.com/Wikid82/charon/issues>
+
+---
+
+## Additional Resources
+
+- **[Sigstore Documentation](https://docs.sigstore.dev/)** - Learn about keyless signing
+- **[SLSA Framework](https://slsa.dev/)** - Supply chain security levels
+- **[SPDX Specification](https://spdx.dev/)** - SBOM format details
+- **[Rekor Transparency Log](https://docs.sigstore.dev/rekor/overview/)** - Audit trail documentation
+
+---
+
+**Last Updated**: January 10, 2026
+**Version**: 1.0