# Build Attestations and SLSA Provenance

## Overview

All releases of European Parliament MCP Server include cryptographic attestations and SLSA Level 3 provenance, providing verifiable proof of build integrity and supply chain security.

## Current Attestation Status

**As of 2026-02-27 — pre-v1.0 status (package version 0.8.2)**

| Security Control | Status | Details |
|-----------------|--------|---------|
| npm audit vulnerabilities | ✅ 0 | No known vulnerabilities in dependency tree |
| SLSA Level 3 | ✅ Achieved | Cryptographic provenance on all releases |
| License compliance | ✅ Passing | All dependencies comply with the license allowlist |
| Test suite | ✅ Passing | See docs/test-results/results.json for up-to-date test metrics |
| SAST (CodeQL) | ✅ Enabled | Automated scanning on every PR and push |
| Secret scanning | ✅ Enabled | GitHub native secret detection |
| Dependabot | ✅ Enabled | Automated dependency update PRs |
| Sigstore signing | ✅ Enabled | npm package and GitHub release artifacts |
| SHA-pinned actions | ✅ Enforced | All critical GitHub Actions pinned to commit SHA (SLSA actions use vetted version tags) |

### Dependency Vulnerability Status (2026-02-27)

| Package | Version | Vulnerabilities | Status |
|---------|---------|----------------|--------|
| @modelcontextprotocol/sdk | 1.27.1 | 0 | ✅ Clean |
| lru-cache | 11.2.6 | 0 | ✅ Clean |
| undici | 7.22.0 | 0 | ✅ Clean |
| zod | 4.3.6 | 0 | ✅ Clean |

> **Note:** High-severity vulnerabilities in `rollup` (GHSA-mw96-cpmx-2vgc) and `minimatch` (GHSA-3ppc-4f35-3m26, GHSA-7r86-cg39-jmmj, GHSA-23c5-xmqv-rm74) were remediated prior to the v1.0 release by updating transitive dependencies.

## SLSA Level 3 Compliance

This project achieves SLSA Level 3 by meeting the following requirements:

### Build Level Requirements
- ✅ **Hermetic builds** - Builds run in isolated GitHub Actions runners
- ✅ **Retained provenance** - Build provenance stored with each release
- ✅ **Non-falsifiable** - Cryptographically signed by GitHub's Sigstore
- ✅ **Auditable** - Complete build logs available
- ✅ **Scripted build** - Automated via GitHub Actions

### Source Level Requirements
- ✅ **Version controlled** - Source in GitHub
- ✅ **Two-person reviewed** - Required PR reviews
- ✅ **Retained history** - Git history preserved

### Provenance Requirements
- ✅ **Available** - Provenance in every release
- ✅ **Authenticated** - Signed with Sigstore
- ✅ **Service generated** - Generated by GitHub Actions
- ✅ **Non-falsifiable** - Tamper-proof signatures
- ✅ **Dependencies complete** - SBOM includes all dependencies

## Verifying Attestations

### Prerequisites
```bash
# Install GitHub CLI
gh auth login

# Or use gh CLI version 2.40.0+
gh version
```

### Verify Build Provenance
```bash
# Download release artifacts
gh release download v1.0.0 --repo Hack23/European-Parliament-MCP-Server

# Verify build attestation
gh attestation verify european-parliament-mcp-server.tar.gz \
  --owner Hack23 \
  --repo European-Parliament-MCP-Server

# Expected output:
✓ Verification succeeded!

sha256:abc123... was attested by:
REPO                                PREDICATE_TYPE               WORKFLOW
Hack23/European-Parliament-MCP-Server  https://slsa.dev/provenance/v1  .github/workflows/slsa-provenance.yml@refs/tags/v1.0.0
```

### Verify npm Package Provenance
```bash
# View provenance for published package
npm view european-parliament-mcp-server dist.attestations

# Verify npm package
npm audit signatures
```

### Verify Checksums
```bash
# Verify artifact integrity
sha256sum -c checksums.txt
```

## Attestation Contents

Each attestation includes:

- **Subject** - Artifact name and SHA256 hash
- **Predicate Type** - `https://slsa.dev/provenance/v1`
- **Builder** - GitHub Actions workflow
- **Build Definition** - Complete build parameters
- **Run Details** - Workflow run metadata
- **External Parameters** - Repository, ref, workflow
- **Internal Parameters** - Build environment details
- **Resolved Dependencies** - All build-time dependencies

## SLSA Provenance Structure

```json
{
  "_type": "https://in-toto.io/Statement/v1",
  "subject": [{
    "name": "european-parliament-mcp-server.tar.gz",
    "digest": {"sha256": "abc123..."}
  }],
  "predicateType": "https://slsa.dev/provenance/v1",
  "predicate": {
    "buildDefinition": {
      "buildType": "https://slsa.dev/build/v1",
      "externalParameters": {
        "workflow": {
          "ref": "refs/tags/v1.0.0",
          "repository": "https://github.com/Hack23/European-Parliament-MCP-Server"
        }
      },
      "resolvedDependencies": [...]
    },
    "runDetails": {
      "builder": {
        "id": "https://github.com/actions/runner/..."
      },
      "metadata": {
        "invocationId": "...",
        "startedOn": "2026-02-16T..."
      }
    }
  }
}
```

## Security Benefits

### Supply Chain Security
- **Tamper Detection** - Any modification to artifacts invalidates attestation
- **Build Reproducibility** - Complete build environment captured
- **Dependency Tracking** - All build dependencies recorded
- **Source Traceability** - Links artifact to exact source commit

### Compliance
- **ISO 27001:2022** - A.8.30 Supplier relationships
- **NIST CSF 2.0** - SC.5: Integrity verification
- **CIS Controls v8.1** - Control 2.7: Software inventory
- **SLSA Level 3** - Full provenance and attestations

## ISMS Policy Compliance

- [Secure Development Policy - SLSA Requirements](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md)
- [Open Source Policy - Build Integrity](https://github.com/Hack23/ISMS-PUBLIC/blob/main/Open_Source_Policy.md)

## Troubleshooting

### Attestation Verification Failed

If verification fails:
1. Ensure you're using gh CLI 2.40.0+
2. Check artifact hasn't been modified (verify checksum)
3. Confirm you're verifying against correct repository
4. Check GitHub Actions had proper permissions

### Provenance Not Found

If provenance is missing:
1. Verify release was created via GitHub Actions
2. Check workflow had `attestations: write` permission
3. Ensure SLSA workflow completed successfully
4. Check release assets include `provenance.intoto.jsonl`

## References

- [SLSA Framework](https://slsa.dev/)
- [GitHub Attestations](https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)
- [Sigstore](https://www.sigstore.dev/)
- [in-toto Attestation Framework](https://in-toto.io/)