Initial Commit
This commit is contained in:
138
packages/security-stack/security/slsa/README.md
Normal file
138
packages/security-stack/security/slsa/README.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# @suaveplan/slsa - SLSA L1-L2 supply-chain security: provenance, SBOM, DSSE attestations, Sigstore Rekor transparency-log client, policy evaluation, OTel audit events
|
||||
|
||||
## Summary
|
||||
|
||||
SLSA L1-L2 supply-chain security for Suaveplan. Generates and
|
||||
verifies in-toto / SLSA v1.0 provenance, CycloneDX 1.5 SBOMs, DSSE
|
||||
attestation envelopes, and RFC 6962 Sigstore Rekor transparency-log
|
||||
proofs. Every capability emits structured OTel span events and raises
|
||||
typed `SlsaError` subclasses with stable error codes.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [assessment](./src/assessment/assessment.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [assessment](./src/assessment/assessment.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [dsse](./src/attestation/dsse/dsse.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [dsse](./src/attestation/dsse/dsse.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [errors](./src/errors/slsa-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [slsa-error](./src/errors/slsa-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [otel](./src/otel/slsa-otel.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [slsa-otel](./src/otel/slsa-otel.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [policy](./src/policy/policy.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [policy](./src/policy/policy.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [provenance](./src/provenance/provenance.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [canonical-json](./src/provenance/canonical-json.md) — Produces a byte-stable, lexicographically-ordered JSON encoding for provenance statements, SBOM documents, and DSSE pay…
|
||||
- [digest](./src/provenance/digest.md) — Single canonical entry point for SHA-256 digest computation inside the SLSA package. Deliberately routes through `@suav…
|
||||
- [provenance](./src/provenance/provenance.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [inclusion-proof](./src/rekor/inclusion-proof.md) — Verifies an RFC 6962 Merkle inclusion proof as returned by Sigstore Rekor. Given a leaf (the canonical body a Rekor ent…
|
||||
- [rekor-client](./src/rekor/rekor-client.md) — Minimal Sigstore Rekor REST client for the two upload shapes Suaveplan cares about: `hashedrekord` v0.0.1 (when logging…
|
||||
- [sbom](./src/sbom/sbom.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [sbom](./src/sbom/sbom.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [schemas](./src/schemas/parse.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [parse](./src/schemas/parse.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [verification](./src/verification/verification.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
- [checks](./src/verification/checks.md) — Individual, stateless verification rules that consume a provenance statement plus policy inputs and return a structured…
|
||||
- [verification](./src/verification/verification.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
||||
<!-- end:auto-docs --> - [assessment](./src/assessment/assessment.md) — <!-- begin:auto-docs --> _(no submodules)_- [dsse](./src/attestation/dsse/dsse.md) — <!-- begin:auto-docs --> _(no submodules)_- [dsse](./src/attestation/dsse/dsse.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/slsa-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [slsa-error](./src/errors/slsa-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/slsa-otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [slsa-otel](./src/otel/slsa-otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [policy](./src/policy/policy.md) — <!-- begin:auto-docs --> _(no submodules)_- [policy](./src/policy/policy.md) — <!-- begin:auto-docs --> _(no submodules)_- [provenance](./src/provenance/provenance.md) — <!-- begin:auto-docs --> _(no submodules)_- [canonical-json](./src/provenance/canonical-json.md) — Produces a byte-stable, lexicographically-ordered JSON encoding for provenance statements, SBOM documents, and DSSE pay…
|
||||
- [digest](./src/provenance/digest.md) — Single canonical entry point for SHA-256 digest computation inside the SLSA package. Deliberately routes through `@suav…
|
||||
- [provenance](./src/provenance/provenance.md) — <!-- begin:auto-docs --> _(no submodules)_- [inclusion-proof](./src/rekor/inclusion-proof.md) — Verifies an RFC 6962 Merkle inclusion proof as returned by Sigstore Rekor. Given a leaf (the canonical body a Rekor ent…
|
||||
- [rekor-client](./src/rekor/rekor-client.md) — Minimal Sigstore Rekor REST client for the two upload shapes Suaveplan cares about: `hashedrekord` v0.0.1 (when logging…
|
||||
- [sbom](./src/sbom/sbom.md) — <!-- begin:auto-docs --> _(no submodules)_- [sbom](./src/sbom/sbom.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [parse](./src/schemas/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [verification](./src/verification/verification.md) — <!-- begin:auto-docs --> _(no submodules)_- [checks](./src/verification/checks.md) — Individual, stateless verification rules that consume a provenance statement plus policy inputs and return a structured…
|
||||
- [verification](./src/verification/verification.md) — <!-- begin:auto-docs --> _(no submodules)_- [assessment](./src/assessment/assessment.md) — <!-- begin:auto-docs --> _(no submodules)_- [dsse](./src/attestation/dsse/dsse.md) — <!-- begin:auto-docs --> _(no submodules)_- [dsse](./src/attestation/dsse/dsse.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/slsa-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [slsa-error](./src/errors/slsa-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/slsa-otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [slsa-otel](./src/otel/slsa-otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [policy](./src/policy/policy.md) — <!-- begin:auto-docs --> _(no submodules)_- [policy](./src/policy/policy.md) — <!-- begin:auto-docs --> _(no submodules)_- [provenance](./src/provenance/provenance.md) — <!-- begin:auto-docs --> _(no submodules)_- [canonical-json](./src/provenance/canonical-json.md) — Produces a byte-stable, lexicographically-ordered JSON encoding for provenance statements, SBOM documents, and DSSE pay…
|
||||
- [digest](./src/provenance/digest.md) — Single canonical entry point for SHA-256 digest computation inside the SLSA package. Deliberately routes through `@suav…
|
||||
- [provenance](./src/provenance/provenance.md) — <!-- begin:auto-docs --> _(no submodules)_- [inclusion-proof](./src/rekor/inclusion-proof.md) — Verifies an RFC 6962 Merkle inclusion proof as returned by Sigstore Rekor. Given a leaf (the canonical body a Rekor ent…
|
||||
- [rekor-client](./src/rekor/rekor-client.md) — Minimal Sigstore Rekor REST client for the two upload shapes Suaveplan cares about: `hashedrekord` v0.0.1 (when logging…
|
||||
- [sbom](./src/sbom/sbom.md) — <!-- begin:auto-docs --> _(no submodules)_- [sbom](./src/sbom/sbom.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [parse](./src/schemas/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [verification](./src/verification/verification.md) — <!-- begin:auto-docs --> _(no submodules)_- [checks](./src/verification/checks.md) — Individual, stateless verification rules that consume a provenance statement plus policy inputs and return a structured…
|
||||
- [verification](./src/verification/verification.md) — <!-- begin:auto-docs --> _(no submodules)_- [assessment](./src/assessment/assessment.md) — <!-- begin:auto-docs --> _(no submodules)_- [dsse](./src/attestation/dsse/dsse.md) — <!-- begin:auto-docs --> _(no submodules)_- [dsse](./src/attestation/dsse/dsse.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/slsa-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [slsa-error](./src/errors/slsa-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/slsa-otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [slsa-otel](./src/otel/slsa-otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [policy](./src/policy/policy.md) — <!-- begin:auto-docs --> _(no submodules)_- [policy](./src/policy/policy.md) — <!-- begin:auto-docs --> _(no submodules)_- [provenance](./src/provenance/provenance.md) — <!-- begin:auto-docs --> _(no submodules)_- [canonical-json](./src/provenance/canonical-json.md) — Produces a byte-stable, lexicographically-ordered JSON encoding for provenance statements, SBOM documents, and DSSE pay…
|
||||
- [digest](./src/provenance/digest.md) — Single canonical entry point for SHA-256 digest computation inside the SLSA package. Deliberately routes through `@suav…
|
||||
- [provenance](./src/provenance/provenance.md) — <!-- begin:auto-docs --> _(no submodules)_- [inclusion-proof](./src/rekor/inclusion-proof.md) — Verifies an RFC 6962 Merkle inclusion proof as returned by Sigstore Rekor. Given a leaf (the canonical body a Rekor ent…
|
||||
- [rekor-client](./src/rekor/rekor-client.md) — Minimal Sigstore Rekor REST client for the two upload shapes Suaveplan cares about: `hashedrekord` v0.0.1 (when logging…
|
||||
- [sbom](./src/sbom/sbom.md) — <!-- begin:auto-docs --> _(no submodules)_- [sbom](./src/sbom/sbom.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [parse](./src/schemas/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [verification](./src/verification/verification.md) — <!-- begin:auto-docs --> _(no submodules)_- [checks](./src/verification/checks.md) — Individual, stateless verification rules that consume a provenance statement plus policy inputs and return a structured…
|
||||
- [verification](./src/verification/verification.md) — <!-- begin:auto-docs --> _(no submodules)_- [assessment](./src/assessment/assessment.md) — <!-- begin:auto-docs --> _(no submodules)_- [dsse](./src/attestation/dsse/dsse.md) — <!-- begin:auto-docs --> _(no submodules)_ - [dsse](./src/attestation/dsse/dsse.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/slsa-error.md) — <!-- begin:auto-docs --> _(no submodules)_ - [slsa-error](./src/errors/slsa-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [otel](./src/otel/slsa-otel.md) — <!-- begin:auto-docs --> _(no submodules)_ - [slsa-otel](./src/otel/slsa-otel.md) — <!-- begin:auto-docs --> _(no submodules)_- [policy](./src/policy/policy.md) — <!-- begin:auto-docs --> _(no submodules)_ - [policy](./src/policy/policy.md) — <!-- begin:auto-docs --> _(no submodules)_- [provenance](./src/provenance/provenance.md) — <!-- begin:auto-docs --> _(no submodules)_ - [canonical-json](./src/provenance/canonical-json.md) — Produces a byte-stable, lexicographically-ordered JSON encoding for provenance statements, SBOM documents, and DSSE pay…
|
||||
- [digest](./src/provenance/digest.md) — Single canonical entry point for SHA-256 digest computation inside the SLSA package. Deliberately routes through `@suav…
|
||||
- [provenance](./src/provenance/provenance.md) — <!-- begin:auto-docs --> _(no submodules)_- [inclusion-proof](./src/rekor/inclusion-proof.md) — Verifies an RFC 6962 Merkle inclusion proof as returned by Sigstore Rekor. Given a leaf (the canonical body a Rekor ent…
|
||||
- [rekor-client](./src/rekor/rekor-client.md) — Minimal Sigstore Rekor REST client for the two upload shapes Suaveplan cares about: `hashedrekord` v0.0.1 (when logging…
|
||||
- [sbom](./src/sbom/sbom.md) — <!-- begin:auto-docs --> _(no submodules)_ - [sbom](./src/sbom/sbom.md) — <!-- begin:auto-docs --> _(no submodules)_- [schemas](./src/schemas/parse.md) — <!-- begin:auto-docs --> _(no submodules)_ - [parse](./src/schemas/parse.md) — <!-- begin:auto-docs --> _(no submodules)_- [verification](./src/verification/verification.md) — <!-- begin:auto-docs --> _(no submodules)_ - [checks](./src/verification/checks.md) — Individual, stateless verification rules that consume a provenance statement plus policy inputs and return a structured…
|
||||
- [verification](./src/verification/verification.md) — <!-- begin:auto-docs --> _(no submodules)_
|
||||
## Install
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/slsa
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts
|
||||
import {
|
||||
assessSlsaLevel,
|
||||
generateProvenance,
|
||||
generateSbom,
|
||||
RekorClient,
|
||||
verifyProvenance,
|
||||
wrapInDsse,
|
||||
} from "@suaveplan/slsa";
|
||||
|
||||
const statement = generateProvenance({
|
||||
packageName: "@suaveplan/utils",
|
||||
packageVersion: "1.2.3",
|
||||
artifactDigest: "abc123...",
|
||||
sourceCommit: "deadbeef...",
|
||||
sourceRepo: "https://gitlab.fq.io/suaveplan/project",
|
||||
sourceRef: "refs/heads/main",
|
||||
builderId: "https://gitlab.fq.io/suaveplan/project/-/runners/1",
|
||||
buildInvocationId: "ci-12345",
|
||||
buildStartedOn: new Date().toISOString(),
|
||||
});
|
||||
|
||||
const result = verifyProvenance(statement, {
|
||||
trustedBuilders: ["https://gitlab.fq.io/suaveplan/project/-/runners/*"],
|
||||
expectedSourceRepo: "https://gitlab.fq.io/suaveplan/project",
|
||||
});
|
||||
|
||||
const sbom = generateSbom({
|
||||
packageName: "@suaveplan/utils",
|
||||
packageVersion: "1.2.3",
|
||||
dependencies: { lodash: "4.17.21" },
|
||||
});
|
||||
|
||||
const envelope = wrapInDsse(statement, signatures);
|
||||
const rekor = new RekorClient();
|
||||
const entry = await rekor.uploadIntoto(envelope);
|
||||
|
||||
console.log(assessSlsaLevel({ ...environment, hasRekorInclusion: true }).level);
|
||||
```
|
||||
|
||||
## Modules
|
||||
|
||||
- [`errors/slsa-error`](./src/errors/slsa-error.md) — typed error hierarchy
|
||||
- stable `SLSA_*` code registry.
|
||||
- [`otel/slsa-otel`](./src/otel/slsa-otel.md) — OTel audit-event adapter.
|
||||
- [`schemas/parse`](./src/schemas/parse.md) — Zod-validated JSON parsers.
|
||||
- [`provenance/canonical-json`](./src/provenance/canonical-json.md) —
|
||||
deterministic JSON encoder.
|
||||
- [`provenance/digest`](./src/provenance/digest.md) — SHA-256 helper over
|
||||
`@suaveplan/crypto-hash`.
|
||||
- [`provenance/provenance`](./src/provenance/provenance.md) — in-toto /
|
||||
SLSA v1.0 statement generator.
|
||||
- [`verification/checks`](./src/verification/checks.md) — individual
|
||||
verification rules.
|
||||
- [`verification/verification`](./src/verification/verification.md) —
|
||||
policy-driven verifier.
|
||||
- [`sbom/sbom`](./src/sbom/sbom.md) — CycloneDX 1.5 SBOM generator.
|
||||
- [`assessment/assessment`](./src/assessment/assessment.md) — SLSA L0-L3
|
||||
environment assessor.
|
||||
- [`attestation/dsse/dsse`](./src/attestation/dsse/dsse.md) — DSSE PAE,
|
||||
envelope wrapper, ed25519 verification.
|
||||
- [`rekor/inclusion-proof`](./src/rekor/inclusion-proof.md) — RFC 6962
|
||||
Merkle inclusion proof verification.
|
||||
- [`rekor/rekor-client`](./src/rekor/rekor-client.md) — Sigstore Rekor
|
||||
REST client.
|
||||
- [`policy/policy`](./src/policy/policy.md) — composite policy evaluator.
|
||||
|
||||
## Status
|
||||
|
||||
- Tests: 170 passing (13 files).
|
||||
- Coverage: 99.2% statements, 100% functions, 99.44% lines, 95.15% branches.
|
||||
- Typecheck, lint, and build all green.
|
||||
|
||||
Reference in New Issue
Block a user