first commit

docs/security-stack/security/slsa/src/assessment/assessment.md

@@ -0,0 +1,73 @@
+# assessment
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Evaluates the build environment against SLSA Build track levels L0-L3 and
+returns a structured `SlsaAssessment`. Intended for CI dashboards, publish
+gates, and compliance audits so teams can see in plain language which
+controls are in place and which are missing. The assessor is pure: it
+takes signals via `AssessmentEnvironment` and has no side effects, so it
+can be fed synthetic input in tests.
+
+## Features
+
+- L0-L3 progression matching the SLSA Build specification.
+- Rekor inclusion is an optional L3 gate — when `hasRekorInclusion` is
+  `undefined` it is ignored; when `false` it blocks L3 even if all other
+  controls are met.
+- Parallel `met` / `unmet` string lists for dashboard rendering.
+- `detectEnvironment()` reads `process.env` to auto-populate the signals
+  from the SLSA convention variables (`SLSA_*`, `CI`, `GITLAB_CI`,
+  `GITHUB_ACTIONS`).
+
+## Usage: Basic Example
+
+```ts
+import { assessSlsaLevel } from "@suaveplan/slsa";
+
+const result = assessSlsaLevel({
+  isCI: true,
+  hasProvenance: true,
+  hasIsolatedBuild: false,
+  hasHardenedProvenance: false,
+  ciOnlyPublish: true,
+  hasSbom: true,
+  hasDigestVerification: true,
+  hasVersionControl: true,
+});
+
+console.log(result.level); // "L2"
+```
+
+## Usage: Advanced Example
+
+```ts
+import { assessSlsaLevel, detectEnvironment } from "@suaveplan/slsa";
+
+const env = { ...detectEnvironment(), hasRekorInclusion: await verifyLogs() };
+const result = assessSlsaLevel(env);
+
+if (result.level !== "L3") {
+  log.warn({ missing: result.unmet }, "publish blocked below L3");
+  process.exit(1);
+}
+```
+
+## API Reference
+
+- `assessSlsaLevel(env: AssessmentEnvironment): SlsaAssessment` — returns
+  `{ level, met, unmet }`.
+- `detectEnvironment(): AssessmentEnvironment` — reads `SLSA_*` + CI env
+  vars. `hasVersionControl` is hard-wired to `true` because the project
+  is Git-backed.
+
+## Implementation Notes
+
+`hasRekorInclusion` has three states: `undefined` (ignored), `true` (L3
+eligible), `false` (L3 blocked). This lets callers opt in to the Rekor
+gate without forcing it on every existing pipeline. The level-determination
+logic cascades — L3 implies L2 implies L1 — so adding additional L3
+constraints only requires appending to the L3 conjunction.