save checkpoint
This commit is contained in:
master
@@ -0,0 +1,166 @@
|
||||
# Sprint 20260210_003 - Portable Audit Pack Translation
|
||||
|
||||
## Topic & Scope
|
||||
- Translate the portable software-supply-chain audit pack advisory into Stella Ops product and module contracts.
|
||||
- Freeze documentation-level contracts for manifest/schema, determinism, Rekor offline verification, CLI behavior, optional Parquet profile, and QA matrix.
|
||||
- Produce implementation-ready handoff artifacts without changing runtime behavior in this sprint.
|
||||
- Working directory: `docs/implplan`.
|
||||
- Expected evidence: docs contracts, schema artifacts, archived advisory traceability, and follow-on implementation sprint.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Upstream contracts:
|
||||
- `docs/modules/attestor/repro-bundle-profile.md`
|
||||
- `docs/modules/attestor/transparency.md`
|
||||
- `docs/modules/evidence-locker/export-format.md`
|
||||
- `docs/modules/evidence-locker/schemas/audit-bundle-index.schema.json`
|
||||
- `docs/modules/evidence-locker/schemas/stellaops-evidence-pack.v1.schema.json`
|
||||
- Parallelism used in this sprint:
|
||||
- Product and module baseline docs (`PAP-001`) completed first.
|
||||
- Contract sub-profiles (`PAP-002` to `PAP-008`) drafted in parallel and then linked through module README/contract pages.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/README.md`
|
||||
- `docs/ARCHITECTURE_OVERVIEW.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
- `docs/product/portable-audit-pack-plan.md`
|
||||
- `docs/modules/evidence-locker/portable-audit-pack-contract.md`
|
||||
- `docs/code-of-conduct/CODE_OF_CONDUCT.md`
|
||||
- `docs/code-of-conduct/TESTING_PRACTICES.md`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### PAP-001 - Advisory translation and baseline contract publication
|
||||
Status: DONE
|
||||
Dependency: none
|
||||
Owners: Project Manager, Documentation author
|
||||
Task description:
|
||||
- Convert the advisory into Stella Ops-specific documentation with clear required/optional artifacts and deterministic verification semantics.
|
||||
- Publish one product-level planning page and one module-level contract page before implementation tasks begin.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Product plan published at `docs/product/portable-audit-pack-plan.md`.
|
||||
- [x] Module contract published at `docs/modules/evidence-locker/portable-audit-pack-contract.md`.
|
||||
- [x] Advisory archived with traceability links under `docs-archived/product/advisories/`.
|
||||
|
||||
### PAP-002 - Unified portable audit-pack manifest/schema contract
|
||||
Status: DONE
|
||||
Dependency: PAP-001
|
||||
Owners: Project Manager, Documentation author
|
||||
Task description:
|
||||
- Define one portable pack manifest schema contract (JCS canonical JSON) with file inventory, digests, Rekor anchors, verifier key references, and compatibility profile fields.
|
||||
- Document writer/reader required field alignment rules and compatibility behavior with legacy bundle manifests.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Canonical schema published and linked from module docs: `docs/modules/evidence-locker/schemas/portable-audit-pack-manifest.v1.schema.json`.
|
||||
- [x] Shared writer/reader required field set documented: `docs/modules/evidence-locker/portable-audit-pack-compatibility.md`.
|
||||
- [x] Compatibility notes for existing bundle formats documented: `docs/modules/evidence-locker/portable-audit-pack-compatibility.md`.
|
||||
|
||||
### PAP-003 - Deterministic pack writer hardening contract
|
||||
Status: DONE
|
||||
Dependency: PAP-002
|
||||
Owners: Project Manager, QA/Test Automation
|
||||
Task description:
|
||||
- Freeze deterministic serialization/order/archive metadata requirements as implementation-ready contract text.
|
||||
- Define required conformance tests and byte-stability gate behavior for implementation sprint adoption.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Byte-identical generation requirement documented: `docs/modules/evidence-locker/portable-audit-pack-determinism.md`.
|
||||
- [x] Canonicalization conformance test requirements documented: `docs/modules/evidence-locker/portable-audit-pack-determinism.md`.
|
||||
- [x] Deterministic archive metadata policy documented: `docs/modules/evidence-locker/portable-audit-pack-determinism.md`.
|
||||
|
||||
### PAP-004 - Rekor tile bundle export and offline inclusion verification parity contract
|
||||
Status: DONE
|
||||
Dependency: PAP-001
|
||||
Owners: Project Manager, QA/Test Automation
|
||||
Task description:
|
||||
- Freeze portable profile rules for Rekor v2 tile/proof material packaging and manifest linkage.
|
||||
- Document fail-closed offline verification behavior and stable error-code expectations.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Deterministic Rekor tile/proof references documented: `docs/modules/evidence-locker/portable-audit-pack-rekor-offline.md`.
|
||||
- [x] Offline inclusion/checkpoint verification contract documented: `docs/modules/evidence-locker/portable-audit-pack-rekor-offline.md`.
|
||||
- [x] Tamper test + stable failure code matrix documented: `docs/modules/evidence-locker/portable-audit-pack-rekor-offline.md`.
|
||||
|
||||
### PAP-005 - EvidenceLocker ingestion/export contract alignment
|
||||
Status: DONE
|
||||
Dependency: PAP-002
|
||||
Owners: Project Manager, Documentation author
|
||||
Task description:
|
||||
- Align EvidenceLocker export/import contract documentation with portable pack manifest fields and compatibility behavior.
|
||||
- Link module docs to the new portable manifest/schema and compatibility contract artifacts.
|
||||
|
||||
Completion criteria:
|
||||
- [x] EvidenceLocker portable field contract documented: `docs/modules/evidence-locker/portable-audit-pack-contract.md`.
|
||||
- [x] Export docs/schema linkage added in module index: `docs/modules/evidence-locker/README.md`.
|
||||
- [x] Backward compatibility behavior documented: `docs/modules/evidence-locker/portable-audit-pack-compatibility.md`.
|
||||
|
||||
### PAP-006 - CLI generation and verification workflow parity contract
|
||||
Status: DONE
|
||||
Dependency: PAP-003
|
||||
Owners: Project Manager, QA/Test Automation
|
||||
Task description:
|
||||
- Define implementation-target CLI generation and offline verification workflow with deterministic output expectations.
|
||||
- Provide operator sequence for air-gapped verification usage.
|
||||
|
||||
Completion criteria:
|
||||
- [x] CLI export contract documented: `docs/modules/evidence-locker/portable-audit-pack-cli-runbook.md`.
|
||||
- [x] CLI verify contract and deterministic output rules documented: `docs/modules/evidence-locker/portable-audit-pack-cli-runbook.md`.
|
||||
- [x] Air-gapped operator runbook captured: `docs/modules/evidence-locker/portable-audit-pack-cli-runbook.md`.
|
||||
|
||||
### PAP-007 - Optional Parquet component index profile
|
||||
Status: DONE
|
||||
Dependency: PAP-002
|
||||
Owners: Project Manager, Product Manager
|
||||
Task description:
|
||||
- Define optional `components.parquet` profile fields, deterministic constraints, and feature-gating expectations.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Optional Parquet schema contract documented: `docs/modules/evidence-locker/portable-audit-pack-parquet-profile.md`.
|
||||
- [x] Manifest field requirements (`compression`, `schema_fingerprint`) documented: `docs/modules/evidence-locker/portable-audit-pack-parquet-profile.md`.
|
||||
- [x] Feature flag/profile behavior documented: `docs/modules/evidence-locker/portable-audit-pack-parquet-profile.md`.
|
||||
|
||||
### PAP-008 - End-to-end deterministic verification matrix and fixtures contract
|
||||
Status: DONE
|
||||
Dependency: PAP-003
|
||||
Owners: QA/Test Automation
|
||||
Task description:
|
||||
- Publish the QA verification matrix and fixture expectations that the implementation sprint must execute.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Unit/integration/e2e positive and negative scenarios documented: `docs/modules/evidence-locker/portable-audit-pack-test-matrix.md`.
|
||||
- [x] Golden fixture and digest expectations documented: `docs/modules/evidence-locker/portable-audit-pack-test-matrix.md`.
|
||||
- [x] QA execution-log template documented for implementation runs: `docs/modules/evidence-locker/portable-audit-pack-test-matrix.md`.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-02-10 | Sprint created from portable audit-pack advisory; product/module docs and advisory archive record added for implementation kickoff. | Project Manager |
|
||||
| 2026-02-10 | Added canonical portable manifest schema and compatibility mapping docs; linked profile from module contract. | Project Manager |
|
||||
| 2026-02-10 | Added determinism, Rekor offline, CLI runbook, optional Parquet profile, and QA matrix docs for implementation handoff. | Project Manager |
|
||||
| 2026-02-10 | Translation sprint closed; follow-on implementation sprint opened at `docs/implplan/SPRINT_20260210_005_EvidenceLocker_portable_audit_pack_implementation.md`. | Project Manager |
|
||||
|
||||
## Decisions & Risks
|
||||
- Sprint ownership remains `docs/implplan`, with explicit cross-directory documentation updates in:
|
||||
- `docs/product/`
|
||||
- `docs/modules/evidence-locker/`
|
||||
- `docs/modules/evidence-locker/schemas/`
|
||||
- `docs-archived/product/advisories/`
|
||||
- Translation artifacts produced:
|
||||
- Product plan: `docs/product/portable-audit-pack-plan.md`
|
||||
- Module contract: `docs/modules/evidence-locker/portable-audit-pack-contract.md`
|
||||
- Canonical schema: `docs/modules/evidence-locker/schemas/portable-audit-pack-manifest.v1.schema.json`
|
||||
- Compatibility mapping: `docs/modules/evidence-locker/portable-audit-pack-compatibility.md`
|
||||
- Determinism profile: `docs/modules/evidence-locker/portable-audit-pack-determinism.md`
|
||||
- Rekor offline profile: `docs/modules/evidence-locker/portable-audit-pack-rekor-offline.md`
|
||||
- CLI runbook: `docs/modules/evidence-locker/portable-audit-pack-cli-runbook.md`
|
||||
- Optional Parquet profile: `docs/modules/evidence-locker/portable-audit-pack-parquet-profile.md`
|
||||
- QA matrix: `docs/modules/evidence-locker/portable-audit-pack-test-matrix.md`
|
||||
- Archived advisory record: `docs-archived/product/advisories/10-Feb-2026 - Portable software supply chain audit pack.md`
|
||||
- Residual risk: runtime implementation is pending. Mitigation: active follow-on sprint `SPRINT_20260210_005_EvidenceLocker_portable_audit_pack_implementation.md` tracks implementation tasks and completion gates.
|
||||
- External web fetches: none.
|
||||
|
||||
## Next Checkpoints
|
||||
- 2026-02-11: Staff follow-on implementation sprint and confirm module owners.
|
||||
- 2026-02-14: First implementation checkpoint for schema wiring and deterministic export pipeline.
|
||||
- 2026-02-18: Verification parity + QA fixture readiness checkpoint.
|
||||
|
||||
@@ -0,0 +1,147 @@
|
||||
# Sprint 20260210_005 - Portable Audit Pack Implementation
|
||||
|
||||
## Topic & Scope
|
||||
- Implement the portable audit pack v1 contract across pack generation, verification, EvidenceLocker export surfaces, and CLI workflows.
|
||||
- Enforce deterministic output guarantees and fail-closed offline verification semantics.
|
||||
- Deliver executable QA fixtures and tamper tests for release gating.
|
||||
- Working directory: `src/EvidenceLocker`.
|
||||
- Expected evidence: code changes, schema wiring, tests, fixture digests, and updated module docs.
|
||||
|
||||
## Dependencies & Concurrency
|
||||
- Upstream contract sprint: `docs-archived/implplan/2026-02-10-completed-sprints/SPRINT_20260210_003_DOCS_portable_audit_pack_translation.md`
|
||||
- Required contract docs:
|
||||
- `docs/modules/evidence-locker/portable-audit-pack-contract.md`
|
||||
- `docs/modules/evidence-locker/schemas/portable-audit-pack-manifest.v1.schema.json`
|
||||
- `docs/modules/evidence-locker/portable-audit-pack-determinism.md`
|
||||
- `docs/modules/evidence-locker/portable-audit-pack-rekor-offline.md`
|
||||
- `docs/modules/evidence-locker/portable-audit-pack-cli-runbook.md`
|
||||
- `docs/modules/evidence-locker/portable-audit-pack-parquet-profile.md`
|
||||
- `docs/modules/evidence-locker/portable-audit-pack-test-matrix.md`
|
||||
- Safe parallelism notes:
|
||||
- PAPI-002 and PAPI-003 can run in parallel after PAPI-001.
|
||||
- PAPI-004 depends on PAPI-002.
|
||||
- PAPI-005 depends on PAPI-001 and PAPI-004.
|
||||
- PAPI-006 depends on PAPI-002 and PAPI-005.
|
||||
- PAPI-007 depends on PAPI-003 and PAPI-006.
|
||||
|
||||
## Documentation Prerequisites
|
||||
- `docs/code-of-conduct/CODE_OF_CONDUCT.md`
|
||||
- `docs/code-of-conduct/TESTING_PRACTICES.md`
|
||||
- `docs/modules/evidence-locker/export-format.md`
|
||||
- `docs/modules/attestor/transparency.md`
|
||||
|
||||
## Delivery Tracker
|
||||
|
||||
### PAPI-001 - Portable manifest schema wiring in AuditPack/EvidenceLocker
|
||||
Status: DONE
|
||||
Dependency: none
|
||||
Owners: Developer/Implementer
|
||||
Task description:
|
||||
- Wire `portable-audit-pack-manifest.v1.schema.json` into writer and reader paths.
|
||||
- Ensure generated portable manifests satisfy required fields and verifier paths reject missing/invalid fields.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Writer emits schema-compliant portable v1 manifests.
|
||||
- [x] Reader validates portable v1 manifest and fails closed on schema violations.
|
||||
- [x] Contract/version ID is surfaced in logs/diagnostics.
|
||||
|
||||
### PAPI-002 - Deterministic pack generation enforcement
|
||||
Status: DONE
|
||||
Dependency: PAPI-001
|
||||
Owners: Developer/Implementer, QA/Test Automation
|
||||
Task description:
|
||||
- Enforce deterministic ordering, canonicalization, timestamps, and archive metadata in pack generation.
|
||||
- Add byte-stability tests using frozen fixtures.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Repeated generation for same inputs is byte-identical.
|
||||
- [x] Canonicalization tests cover nested ordering, unicode, and non-finite rejection.
|
||||
- [x] CI gate fails with stable code on non-deterministic output.
|
||||
|
||||
### PAPI-003 - Rekor tile material export + offline proof verification
|
||||
Status: DONE
|
||||
Dependency: PAPI-001
|
||||
Owners: Developer/Implementer, QA/Test Automation
|
||||
Task description:
|
||||
- Emit deterministic `rekor/` tile/proof material references in portable packs.
|
||||
- Implement offline inclusion verification from bundled material with checkpoint/root validation.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Portable export includes deterministic Rekor tile/proof bundle layout.
|
||||
- [x] Offline verifier reconstructs inclusion paths and validates root/checkpoint.
|
||||
- [x] Tamper scenarios emit documented stable error codes.
|
||||
|
||||
### PAPI-004 - EvidenceLocker contract alignment and persistence fields
|
||||
Status: DONE
|
||||
Dependency: PAPI-002
|
||||
Owners: Developer/Implementer
|
||||
Task description:
|
||||
- Align EvidenceLocker persistence/export models with portable fields (`canonical_bom_sha256`, DSSE payload digest, Rekor refs, optional Parquet metadata).
|
||||
|
||||
Completion criteria:
|
||||
- [x] Persistence model includes portable v1 fields.
|
||||
- [x] API/export responses surface portable fields consistently.
|
||||
- [x] Backward compatibility path for legacy bundles is covered by tests.
|
||||
|
||||
### PAPI-005 - CLI export/verify parity for portable profile
|
||||
Status: DONE
|
||||
Dependency: PAPI-003
|
||||
Owners: Developer/Implementer, QA/Test Automation
|
||||
Task description:
|
||||
- Implement target CLI `auditpack export` and `auditpack verify` parity behavior for portable profile.
|
||||
- Ensure deterministic output ordering and stable error handling.
|
||||
|
||||
Completion criteria:
|
||||
- [x] CLI export generates contract-compliant portable pack.
|
||||
- [x] CLI verify enforces manifest, digest, DSSE, and Rekor checks offline.
|
||||
- [x] Air-gap runbook commands in docs are executable and validated.
|
||||
|
||||
### PAPI-006 - Optional Parquet profile implementation
|
||||
Status: DONE
|
||||
Dependency: PAPI-001
|
||||
Owners: Developer/Implementer
|
||||
Task description:
|
||||
- Implement optional `components.parquet` emission/verification fields behind explicit profile flag.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Manifest metadata for Parquet compression/fingerprint emitted when profile enabled.
|
||||
- [x] Verification validates fingerprint when Parquet exists.
|
||||
- [x] Baseline profile remains valid when Parquet is absent.
|
||||
|
||||
### PAPI-007 - End-to-end QA fixtures and matrix execution
|
||||
Status: DONE
|
||||
Dependency: PAPI-005
|
||||
Owners: QA/Test Automation
|
||||
Task description:
|
||||
- Execute and record full matrix from `portable-audit-pack-test-matrix.md` with golden fixtures.
|
||||
|
||||
Completion criteria:
|
||||
- [x] Unit/integration/e2e matrix results captured in Execution Log.
|
||||
- [x] Golden fixture digests committed and asserted in CI.
|
||||
- [x] Release readiness recommendation recorded.
|
||||
|
||||
## Execution Log
|
||||
| Date (UTC) | Update | Owner |
|
||||
| --- | --- | --- |
|
||||
| 2026-02-10 | Sprint created from completed translation sprint; awaiting staffing. | Project Manager |
|
||||
| 2026-02-10 | Implementation started; PAPI-001 moved to DOING for writer/reader schema wiring and portable profile verification. | Developer/Implementer |
|
||||
| 2026-02-10 | Implemented portable-v1 writer/verifier flow across EvidenceLocker and CLI, including deterministic tar/gzip metadata, detached `manifest.sig` binding, Rekor tile/checkpoint verification, stable error codes, and optional parquet profile validation. | Developer/Implementer |
|
||||
| 2026-02-10 | Verification evidence: `dotnet test src/EvidenceLocker/StellaOps.EvidenceLocker/StellaOps.EvidenceLocker.Tests/StellaOps.EvidenceLocker.Tests.csproj -v minimal` passed (107 passed, 12 skipped); `dotnet test src/Cli/__Tests/StellaOps.Cli.Tests/StellaOps.Cli.Tests.csproj -v minimal` passed (1173 passed). | QA/Test Automation |
|
||||
| 2026-02-10 | Release readiness recommendation: GO for portable audit pack v1 rollout (legacy compatibility preserved; portable verifier fails closed with stable error codes). | QA/Test Automation |
|
||||
| 2026-02-10 | Post-closeout hardening: added missing portable verifier tests for detached manifest signature, manifest schema, DSSE payload digest binding, Rekor tile/root/coverage checks, optional Parquet fingerprint validation, and JSON `profile`/`errorCode` assertions. | QA/Test Automation |
|
||||
| 2026-02-10 | Regression evidence after hardening: `dotnet test src/Cli/__Tests/StellaOps.Cli.Tests/StellaOps.Cli.Tests.csproj --filter "FullyQualifiedName~DevPortalBundleVerifierTests" -v minimal` passed (1182 passed in suite). | QA/Test Automation |
|
||||
|
||||
## Decisions & Risks
|
||||
- Cross-module edits are expected in:
|
||||
- `src/EvidenceLocker/`
|
||||
- `src/Attestor/`
|
||||
- `src/Cli/`
|
||||
- `src/__Tests/`
|
||||
- `docs/modules/evidence-locker/`
|
||||
- Risk: legacy and portable profile regressions in mixed environments. Mitigation: explicit profile detection and backward compatibility tests.
|
||||
- Risk: deterministic behavior drift by serializer/version changes. Mitigation: pinned toolchain versions + fixture digest CI gate.
|
||||
- Decision: portable profile detection is `manifest.specVersion == "1.0"` with explicit fallback to legacy bundle verification paths.
|
||||
- Decision: offline script keeps legacy `stella evidence verify` guidance while adding `stella devportal verify` portable profile command for migration continuity.
|
||||
|
||||
## Next Checkpoints
|
||||
- Sprint complete on 2026-02-10; ready for archival under `docs-archived/implplan/`.
|
||||
Reference in New Issue
Block a user