feat: Add guild charters and task boards for various components
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Introduced guild charters for Scanner Deno, PHP, Ruby, Native, WebService, Java, Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, UI, Zastava Observer, Zastava Webhook, Zastava Core, and Plugin Platform. - Each charter outlines the mission, scope, required reading, and working agreements for the respective guilds. - Created task boards for Surface.Env, Surface.FS, Surface.Secrets, Surface.Validation, and Zastava components to track progress and dependencies. - Ensured all documents emphasize determinism, offline readiness, security, and integration with shared Surface libraries.
This commit is contained in:
@@ -1,29 +1,40 @@
|
||||
# StellaOps.Scanner.Analyzers.Lang.DotNet — Agent Charter
|
||||
|
||||
## Role
|
||||
Create the .NET analyzer plug-in that inspects `*.deps.json`, `runtimeconfig.json`, assemblies, and RID-specific assets to deliver accurate NuGet components with signing metadata.
|
||||
|
||||
## Scope
|
||||
- Parse dependency graphs from `*.deps.json` and merge with `runtimeconfig.json` and bundle manifests.
|
||||
- Capture assembly metadata (strong name, file version, Authenticode) and correlate with packages.
|
||||
- Handle RID-specific asset selection, self-contained apps, and crossgen/native dependency hints.
|
||||
- Package plug-in manifest, determinism fixtures, benchmarks, and Offline Kit documentation.
|
||||
|
||||
## Out of Scope
|
||||
- Policy evaluation or Signer integration (handled elsewhere).
|
||||
- Native dependency resolution outside RID mapping.
|
||||
- Windows-specific MSI/SxS analyzers (covered by native analyzer roadmap).
|
||||
|
||||
## Expectations
|
||||
- Performance target: multi-target app fixture <1.2 s, memory <250 MB.
|
||||
- Deterministic RID collapsing to reduce component duplication by ≥40 % vs naive approach.
|
||||
- Offline-first; support air-gapped strong-name/Authenticode validation using cached root store.
|
||||
- Rich telemetry (components per RID, strong-name validations) conforming to Scanner metrics.
|
||||
|
||||
## Dependencies
|
||||
- Shared language analyzer infrastructure; Worker dispatcher; optional security key store for signature verification.
|
||||
|
||||
## Testing & Artifacts
|
||||
- Fixtures for framework-dependent and self-contained apps (linux-musl, win-x64).
|
||||
- Golden outputs capturing signature metadata and RID grouping.
|
||||
- Benchmark comparing analyzer fidelity vs market competitors.
|
||||
# StellaOps.Scanner.Analyzers.Lang.DotNet — Agent Charter
|
||||
|
||||
## Role
|
||||
Create the .NET analyzer plug-in that inspects `*.deps.json`, `runtimeconfig.json`, assemblies, and RID-specific assets to deliver accurate NuGet components with signing metadata.
|
||||
|
||||
## Scope
|
||||
- Parse dependency graphs from `*.deps.json` and merge with `runtimeconfig.json` and bundle manifests.
|
||||
- Capture assembly metadata (strong name, file version, Authenticode) and correlate with packages.
|
||||
- Handle RID-specific asset selection, self-contained apps, and crossgen/native dependency hints.
|
||||
- Package plug-in manifest, determinism fixtures, benchmarks, and Offline Kit documentation.
|
||||
|
||||
## Out of Scope
|
||||
- Policy evaluation or Signer integration (handled elsewhere).
|
||||
- Native dependency resolution outside RID mapping.
|
||||
- Windows-specific MSI/SxS analyzers (covered by native analyzer roadmap).
|
||||
|
||||
## Expectations
|
||||
- Performance target: multi-target app fixture <1.2 s, memory <250 MB.
|
||||
- Deterministic RID collapsing to reduce component duplication by ≥40 % vs naive approach.
|
||||
- Offline-first; support air-gapped strong-name/Authenticode validation using cached root store.
|
||||
- Rich telemetry (components per RID, strong-name validations) conforming to Scanner metrics.
|
||||
|
||||
## Dependencies
|
||||
- Shared language analyzer infrastructure; Worker dispatcher; optional security key store for signature verification.
|
||||
|
||||
## Testing & Artifacts
|
||||
- Fixtures for framework-dependent and self-contained apps (linux-musl, win-x64).
|
||||
- Golden outputs capturing signature metadata and RID grouping.
|
||||
- Benchmark comparing analyzer fidelity vs market competitors.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -29,3 +29,14 @@ Build the Go analyzer plug-in that reads Go build info, module metadata, and DWA
|
||||
- Golden fixtures for modules with/without VCS info, stripped binaries, cross-compiled variants.
|
||||
- Benchmark comparison with competitor scanners to demonstrate speed/fidelity advantages (captured in `src/Bench/StellaOps.Bench/Scanner.Analyzers/lang/go/`).
|
||||
- ADR documenting heuristics and risk mitigation.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# Scanner Java Analyzer Guild Charter
|
||||
|
||||
## Mission
|
||||
Implement deterministic Java analyzers that normalise JVM/Build ecosystem inputs (Maven/Gradle, classpath jars, module-info), reconstruct dependency graphs, and provide Scanner with reliable SBOM data. Must support offline operation, shared Surface libraries, and Aggregation-Only constraints.
|
||||
|
||||
## Scope
|
||||
- Java normaliser/analyzer code and emitters in `StellaOps.Scanner.Analyzers.Lang.Java`.
|
||||
- Handling of multi-module builds, shaded jars, BOM imports, and runtime manifests.
|
||||
- Integration with Surface.Env/Fs/Secrets/Validation.
|
||||
- Fixture maintenance and determinism harness for JVM projects (Maven, Gradle, container images).
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/scanner/design/surface-env.md`
|
||||
- `docs/modules/scanner/design/surface-fs.md`
|
||||
- `docs/modules/scanner/design/surface-secrets.md`
|
||||
- `docs/modules/scanner/design/surface-validation.md`
|
||||
- `docs/modules/scanner/implementation_plan.md` (Java analyzer sections)
|
||||
- Build system references linked from sprint tasks (Maven, Gradle, shading).
|
||||
|
||||
## Working Agreement
|
||||
1. **Status synchronisation**: set tasks to `DOING`/`DONE` in `docs/implplan/SPRINTS.md` and local `TASKS.md` as work progresses.
|
||||
2. **Surface usage**: rely on shared Surface libraries for env detection, cached artifacts, secret access, and validation.
|
||||
3. **Deterministic outputs**: stabilise classpath ordering, canonicalise PURLs, and avoid network fetches; rely on local caches.
|
||||
4. **SBOM accuracy**: produce consistent component/relationship data; no policy/severity decisions.
|
||||
5. **Testing**: update golden fixtures, determinism harness, and property tests; include shading/multi-module edge cases.
|
||||
6. **Documentation**: adjust implementation plan notes or author Java-specific design doc when behaviour changes; inform Docs/CLI teams if outputs or configuration differ.
|
||||
@@ -37,3 +37,14 @@ Deliver the Node.js / npm / Yarn / PNPM analyzer plug-in that resolves workspace
|
||||
- `policyHint.installLifecycle` lists lifecycle scripts (`preinstall;install;postinstall`) observed for a package.
|
||||
- `script.<name>` stores the canonical command string for each lifecycle script.
|
||||
- Evidence: lifecycle script entries emit `LanguageEvidenceKind.Metadata` pointing to `package.json#scripts.<name>` with SHA-256 hashes for determinism.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -1,32 +1,43 @@
|
||||
# StellaOps.Scanner.Analyzers.Lang.Python — Agent Charter
|
||||
|
||||
## Role
|
||||
Implement the Python analyzer plug-in that inspects installed distributions, RECORD hashes, entry points, and editable installs to feed Scanner SBOM views.
|
||||
|
||||
## Scope
|
||||
- Parse `*.dist-info` and `*.data` directories, validating `METADATA`, `RECORD`, and `entry_points.txt`.
|
||||
- Detect editable installs and pip caches, reconciling metadata with actual files.
|
||||
- Integrate EntryTrace usage hints for runtime entry points and flag missing RECORD hashes.
|
||||
- Package plug-in manifest and ensure deterministic fixtures + benchmarks.
|
||||
|
||||
## Out of Scope
|
||||
- Language analyzers for other ecosystems.
|
||||
- Policy evaluation, vulnerability correlation, or packaging into UI flows.
|
||||
- Building Python interpreters or executing scripts (analysis is static only).
|
||||
|
||||
## Expectations
|
||||
- Deterministic RECORD hashing with streaming IO; fallback heuristics clearly flagged.
|
||||
- Performance target: ≥75 MB/s RECORD verification, end-to-end fixture <2.0 s.
|
||||
- Offline-first: no PyPI calls; relies on local metadata only.
|
||||
- Rich telemetry (components counted, hash mismatches) following Scanner metrics schema.
|
||||
- Keep `TASKS.md` and `SPRINTS_LANG_IMPLEMENTATION_PLAN.md` in sync.
|
||||
|
||||
## Dependencies
|
||||
- Shared language analyzer infrastructure.
|
||||
- EntryTrace usage hints (for script activation).
|
||||
- Worker dispatcher for plug-in loading.
|
||||
|
||||
## Testing & Artifacts
|
||||
- Golden fixtures for venv, virtualenv, pipx, and editable installs.
|
||||
- Benchmark results comparing hash-check throughput against competitor tools.
|
||||
- Offline Kit guidance for bundling standard library metadata if required.
|
||||
# StellaOps.Scanner.Analyzers.Lang.Python — Agent Charter
|
||||
|
||||
## Role
|
||||
Implement the Python analyzer plug-in that inspects installed distributions, RECORD hashes, entry points, and editable installs to feed Scanner SBOM views.
|
||||
|
||||
## Scope
|
||||
- Parse `*.dist-info` and `*.data` directories, validating `METADATA`, `RECORD`, and `entry_points.txt`.
|
||||
- Detect editable installs and pip caches, reconciling metadata with actual files.
|
||||
- Integrate EntryTrace usage hints for runtime entry points and flag missing RECORD hashes.
|
||||
- Package plug-in manifest and ensure deterministic fixtures + benchmarks.
|
||||
|
||||
## Out of Scope
|
||||
- Language analyzers for other ecosystems.
|
||||
- Policy evaluation, vulnerability correlation, or packaging into UI flows.
|
||||
- Building Python interpreters or executing scripts (analysis is static only).
|
||||
|
||||
## Expectations
|
||||
- Deterministic RECORD hashing with streaming IO; fallback heuristics clearly flagged.
|
||||
- Performance target: ≥75 MB/s RECORD verification, end-to-end fixture <2.0 s.
|
||||
- Offline-first: no PyPI calls; relies on local metadata only.
|
||||
- Rich telemetry (components counted, hash mismatches) following Scanner metrics schema.
|
||||
- Keep `TASKS.md` and `SPRINTS_LANG_IMPLEMENTATION_PLAN.md` in sync.
|
||||
|
||||
## Dependencies
|
||||
- Shared language analyzer infrastructure.
|
||||
- EntryTrace usage hints (for script activation).
|
||||
- Worker dispatcher for plug-in loading.
|
||||
|
||||
## Testing & Artifacts
|
||||
- Golden fixtures for venv, virtualenv, pipx, and editable installs.
|
||||
- Benchmark results comparing hash-check throughput against competitor tools.
|
||||
- Offline Kit guidance for bundling standard library metadata if required.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -1,29 +1,40 @@
|
||||
# StellaOps.Scanner.Analyzers.Lang.Rust — Agent Charter
|
||||
|
||||
## Role
|
||||
Develop the Rust analyzer plug-in that resolves crates from metadata (`.fingerprint`, Cargo.lock, embedded markers) and provides deterministic fallbacks for stripped binaries.
|
||||
|
||||
## Scope
|
||||
- Locate Cargo metadata in container layers (registry cache, target fingerprints, embedded Git info).
|
||||
- Parse symbol tables / section data to heuristically identify crates when metadata missing, tagging provenance appropriately.
|
||||
- Integrate binary hash fallback with quiet provenance classification.
|
||||
- Package plug-in manifest, determinism fixtures, and performance/coverage benchmarks.
|
||||
|
||||
## Out of Scope
|
||||
- Native linker analysis beyond crate attribution.
|
||||
- Fetching Cargo registry metadata from the network.
|
||||
- Policy decisions or UI surfacing.
|
||||
|
||||
## Expectations
|
||||
- Accurate crate attribution (≥85 % on curated fixtures) with explicit heuristic labeling.
|
||||
- Analyzer runtime <1 s over 500 binary corpus; minimal allocations through pooling.
|
||||
- Offline-first; rely on local Cargo data.
|
||||
- Telemetry capturing heuristic vs verified evidence ratios.
|
||||
|
||||
## Dependencies
|
||||
- Shared language analyzer infrastructure; Worker dispatcher; optionally EntryTrace hints for runtime coverage.
|
||||
|
||||
## Testing & Artifacts
|
||||
- Fixtures for cargo workspaces, release builds, stripped binaries, vendor caches.
|
||||
- Determinism + benchmark artifacts comparing to competitor scanners.
|
||||
- ADR documenting heuristic boundaries + risk mitigations.
|
||||
# StellaOps.Scanner.Analyzers.Lang.Rust — Agent Charter
|
||||
|
||||
## Role
|
||||
Develop the Rust analyzer plug-in that resolves crates from metadata (`.fingerprint`, Cargo.lock, embedded markers) and provides deterministic fallbacks for stripped binaries.
|
||||
|
||||
## Scope
|
||||
- Locate Cargo metadata in container layers (registry cache, target fingerprints, embedded Git info).
|
||||
- Parse symbol tables / section data to heuristically identify crates when metadata missing, tagging provenance appropriately.
|
||||
- Integrate binary hash fallback with quiet provenance classification.
|
||||
- Package plug-in manifest, determinism fixtures, and performance/coverage benchmarks.
|
||||
|
||||
## Out of Scope
|
||||
- Native linker analysis beyond crate attribution.
|
||||
- Fetching Cargo registry metadata from the network.
|
||||
- Policy decisions or UI surfacing.
|
||||
|
||||
## Expectations
|
||||
- Accurate crate attribution (≥85 % on curated fixtures) with explicit heuristic labeling.
|
||||
- Analyzer runtime <1 s over 500 binary corpus; minimal allocations through pooling.
|
||||
- Offline-first; rely on local Cargo data.
|
||||
- Telemetry capturing heuristic vs verified evidence ratios.
|
||||
|
||||
## Dependencies
|
||||
- Shared language analyzer infrastructure; Worker dispatcher; optionally EntryTrace hints for runtime coverage.
|
||||
|
||||
## Testing & Artifacts
|
||||
- Fixtures for cargo workspaces, release builds, stripped binaries, vendor caches.
|
||||
- Determinism + benchmark artifacts comparing to competitor scanners.
|
||||
- ADR documenting heuristic boundaries + risk mitigations.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -1,33 +1,44 @@
|
||||
# StellaOps.Scanner.Analyzers.Lang — Agent Charter
|
||||
|
||||
## Role
|
||||
Deliver deterministic language ecosystem analyzers that run inside Scanner Workers, emit component evidence for SBOM assembly, and package as restart-time plug-ins.
|
||||
|
||||
## Scope
|
||||
- Shared analyzer abstractions for installed application ecosystems (Java, Node.js, Python, Go, .NET, Rust).
|
||||
- Evidence helpers that map on-disk artefacts to canonical component identities (purl/bin sha) with provenance and usage flags.
|
||||
- File-system traversal, metadata parsing, and normalization for language-specific package formats.
|
||||
- Plug-in bootstrap, manifest authoring, and DI registration so Workers load analyzers at start-up.
|
||||
|
||||
## Out of Scope
|
||||
- OS package analyzers, native link graph, or EntryTrace plug-ins (handled by other guilds).
|
||||
- SBOM composition, diffing, or signing (owned by Emit/Diff/Signer groups).
|
||||
- Policy adjudication or vulnerability joins.
|
||||
|
||||
## Expectations
|
||||
- Deterministic output: identical inputs → identical component ordering and hashes.
|
||||
- Memory discipline: streaming walkers, avoid loading entire trees; reuse buffers.
|
||||
- Cancellation-aware and timeboxed per layer.
|
||||
- Enrich telemetry (counters + timings) via Scanner.Core primitives.
|
||||
- Update `TASKS.md` as work progresses (TODO → DOING → DONE/BLOCKED).
|
||||
|
||||
## Dependencies
|
||||
- Scanner.Core contracts + observability helpers.
|
||||
- Scanner.Worker analyzer dispatcher.
|
||||
- Upcoming Scanner.Emit models for SBOM assembly.
|
||||
- Plugin host infrastructure under `StellaOps.Plugin`.
|
||||
|
||||
## Testing & Artifacts
|
||||
- Determinism harness with golden fixtures under `Fixtures/`.
|
||||
- Microbench benchmarks recorded per language where feasible.
|
||||
- Plugin manifests stored under `plugins/scanner/analyzers/lang/` with cosign workflow documented.
|
||||
# StellaOps.Scanner.Analyzers.Lang — Agent Charter
|
||||
|
||||
## Role
|
||||
Deliver deterministic language ecosystem analyzers that run inside Scanner Workers, emit component evidence for SBOM assembly, and package as restart-time plug-ins.
|
||||
|
||||
## Scope
|
||||
- Shared analyzer abstractions for installed application ecosystems (Java, Node.js, Python, Go, .NET, Rust).
|
||||
- Evidence helpers that map on-disk artefacts to canonical component identities (purl/bin sha) with provenance and usage flags.
|
||||
- File-system traversal, metadata parsing, and normalization for language-specific package formats.
|
||||
- Plug-in bootstrap, manifest authoring, and DI registration so Workers load analyzers at start-up.
|
||||
|
||||
## Out of Scope
|
||||
- OS package analyzers, native link graph, or EntryTrace plug-ins (handled by other guilds).
|
||||
- SBOM composition, diffing, or signing (owned by Emit/Diff/Signer groups).
|
||||
- Policy adjudication or vulnerability joins.
|
||||
|
||||
## Expectations
|
||||
- Deterministic output: identical inputs → identical component ordering and hashes.
|
||||
- Memory discipline: streaming walkers, avoid loading entire trees; reuse buffers.
|
||||
- Cancellation-aware and timeboxed per layer.
|
||||
- Enrich telemetry (counters + timings) via Scanner.Core primitives.
|
||||
- Update `TASKS.md` as work progresses (TODO → DOING → DONE/BLOCKED).
|
||||
|
||||
## Dependencies
|
||||
- Scanner.Core contracts + observability helpers.
|
||||
- Scanner.Worker analyzer dispatcher.
|
||||
- Upcoming Scanner.Emit models for SBOM assembly.
|
||||
- Plugin host infrastructure under `StellaOps.Plugin`.
|
||||
|
||||
## Testing & Artifacts
|
||||
- Determinism harness with golden fixtures under `Fixtures/`.
|
||||
- Microbench benchmarks recorded per language where feasible.
|
||||
- Plugin manifests stored under `plugins/scanner/analyzers/lang/` with cosign workflow documented.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -2,3 +2,6 @@
|
||||
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
| LANG-SURFACE-01 | TODO | Language Analyzer Guild | SURFACE-VAL-02, SURFACE-FS-02 | Invoke Surface.Validation checks (env/cache/secrets) before analyzer execution to ensure consistent prerequisites. | Validation pipeline integrated; regression tests updated; failures bubble with actionable errors. |
|
||||
| LANG-SURFACE-02 | TODO | Language Analyzer Guild | SURFACE-FS-02 | Consume Surface.FS APIs for layer/source caching (instead of bespoke caches) to improve determinism. | Analyzer outputs match baseline; performance benchmarks recorded; docs updated. |
|
||||
| LANG-SURFACE-03 | TODO | Language Analyzer Guild | SURFACE-SECRETS-02 | Replace direct secret/env reads with Surface.Secrets references when fetching package feeds or registry creds. | Analyzer uses shared provider; tests cover rotation/failure; config docs updated. |
|
||||
|
||||
@@ -1,40 +1,51 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Design and ship deterministic Linux operating-system analyzers that transform container root filesystems into canonical package evidence for SBOM emission.
|
||||
|
||||
## Scope
|
||||
- Provide shared helpers for reading apk, dpkg, and rpm metadata and emitting normalized package identities with provenance.
|
||||
- Implement analyzer plug-ins for Alpine (apk), Debian (dpkg), and RPM-based distributions that operate on extracted rootfs snapshots.
|
||||
- Enrich package records with vendor-origin metadata (source packages, declared licenses, CVE hints) and evidence linking files to packages.
|
||||
- Expose restart-time plug-in manifests so the Scanner.Worker can load analyzers in offline or air-gapped environments.
|
||||
- Supply deterministic fixtures and a regression harness that verifies analyzer outputs remain stable across runs.
|
||||
|
||||
## Participants
|
||||
- `StellaOps.Scanner.Core` for shared contracts, observability, and plug-in catalog guardrails.
|
||||
- `StellaOps.Scanner.Worker` which executes analyzers inside the scan pipeline.
|
||||
- `StellaOps.Scanner.Cache` (future) for layer cache integration; analyzers must be cache-aware via deterministic inputs/outputs.
|
||||
- `StellaOps.Scanner.Emit` and `StellaOps.Scanner.Diff` rely on analyzer outputs to build SBOMs and change reports.
|
||||
|
||||
## Interfaces & Contracts
|
||||
- Analyzers implement `IOSPackageAnalyzer` (defined in this module) and register via plug-in manifests; they must be restart-time only.
|
||||
- Input rootfs paths are read-only; analyzers must never mutate files and must tolerate missing metadata gracefully.
|
||||
- Package records emit canonical purls (`pkg:alpine`, `pkg:deb`, `pkg:rpm`) plus NEVRA/EVR details, source package identifiers, declared licenses, and evidence (file lists with layer attribution placeholders).
|
||||
- Outputs must be deterministic: ordering is lexicographic, timestamps removed or normalized, hashes (SHA256) calculated when required.
|
||||
|
||||
## In/Out of Scope
|
||||
In scope:
|
||||
- Linux apk/dpkg/rpm analyzers, shared helpers, plug-in manifests, deterministic regression harness.
|
||||
|
||||
Out of scope:
|
||||
- Windows MSI/SxS analyzers, native (ELF) analyzers, language analyzers, EntryTrace pipeline, or SBOM assembly logic (handled by other guilds).
|
||||
|
||||
## Observability & Security Expectations
|
||||
- Emit structured logs with correlation/job identifiers provided by `StellaOps.Scanner.Core`.
|
||||
- Surface metrics for package counts, elapsed time, and cache hits (metrics hooks stubbed until Cache module lands).
|
||||
- Do not perform outbound network calls; operate entirely on provided filesystem snapshot.
|
||||
- Validate plug-in manifests via `IPluginCatalogGuard` to enforce restart-only loading.
|
||||
|
||||
## Tests
|
||||
- `StellaOps.Scanner.Analyzers.OS.Tests` hosts regression tests with canned rootfs fixtures to verify determinism.
|
||||
- Fixtures store expected analyzer outputs under `Fixtures/` with golden JSON (normalized, sorted).
|
||||
- Tests cover apk/dpkg/rpm analyzers, shared helper edge cases, and plug-in catalog enforcement.
|
||||
# AGENTS
|
||||
## Role
|
||||
Design and ship deterministic Linux operating-system analyzers that transform container root filesystems into canonical package evidence for SBOM emission.
|
||||
|
||||
## Scope
|
||||
- Provide shared helpers for reading apk, dpkg, and rpm metadata and emitting normalized package identities with provenance.
|
||||
- Implement analyzer plug-ins for Alpine (apk), Debian (dpkg), and RPM-based distributions that operate on extracted rootfs snapshots.
|
||||
- Enrich package records with vendor-origin metadata (source packages, declared licenses, CVE hints) and evidence linking files to packages.
|
||||
- Expose restart-time plug-in manifests so the Scanner.Worker can load analyzers in offline or air-gapped environments.
|
||||
- Supply deterministic fixtures and a regression harness that verifies analyzer outputs remain stable across runs.
|
||||
|
||||
## Participants
|
||||
- `StellaOps.Scanner.Core` for shared contracts, observability, and plug-in catalog guardrails.
|
||||
- `StellaOps.Scanner.Worker` which executes analyzers inside the scan pipeline.
|
||||
- `StellaOps.Scanner.Cache` (future) for layer cache integration; analyzers must be cache-aware via deterministic inputs/outputs.
|
||||
- `StellaOps.Scanner.Emit` and `StellaOps.Scanner.Diff` rely on analyzer outputs to build SBOMs and change reports.
|
||||
|
||||
## Interfaces & Contracts
|
||||
- Analyzers implement `IOSPackageAnalyzer` (defined in this module) and register via plug-in manifests; they must be restart-time only.
|
||||
- Input rootfs paths are read-only; analyzers must never mutate files and must tolerate missing metadata gracefully.
|
||||
- Package records emit canonical purls (`pkg:alpine`, `pkg:deb`, `pkg:rpm`) plus NEVRA/EVR details, source package identifiers, declared licenses, and evidence (file lists with layer attribution placeholders).
|
||||
- Outputs must be deterministic: ordering is lexicographic, timestamps removed or normalized, hashes (SHA256) calculated when required.
|
||||
|
||||
## In/Out of Scope
|
||||
In scope:
|
||||
- Linux apk/dpkg/rpm analyzers, shared helpers, plug-in manifests, deterministic regression harness.
|
||||
|
||||
Out of scope:
|
||||
- Windows MSI/SxS analyzers, native (ELF) analyzers, language analyzers, EntryTrace pipeline, or SBOM assembly logic (handled by other guilds).
|
||||
|
||||
## Observability & Security Expectations
|
||||
- Emit structured logs with correlation/job identifiers provided by `StellaOps.Scanner.Core`.
|
||||
- Surface metrics for package counts, elapsed time, and cache hits (metrics hooks stubbed until Cache module lands).
|
||||
- Do not perform outbound network calls; operate entirely on provided filesystem snapshot.
|
||||
- Validate plug-in manifests via `IPluginCatalogGuard` to enforce restart-only loading.
|
||||
|
||||
## Tests
|
||||
- `StellaOps.Scanner.Analyzers.OS.Tests` hosts regression tests with canned rootfs fixtures to verify determinism.
|
||||
- Fixtures store expected analyzer outputs under `Fixtures/` with golden JSON (normalized, sorted).
|
||||
- Tests cover apk/dpkg/rpm analyzers, shared helper edge cases, and plug-in catalog enforcement.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -1,15 +1,26 @@
|
||||
# StellaOps.Scanner.Cache — Agent Charter
|
||||
|
||||
## Mission
|
||||
Provide deterministic, offline-friendly caching primitives for scanner layers and file content so warm scans complete in <5 s and cache reuse remains reproducible across deployments.
|
||||
|
||||
## Responsibilities
|
||||
- Implement layer cache keyed by layer digest, retaining analyzer metadata and provenance per architecture §3.3.
|
||||
- Deliver file content-addressable storage (CAS) with deduplication, TTL enforcement, and offline import/export hooks.
|
||||
- Expose structured metrics, health probes, and configuration toggles for cache sizing, eviction, and warm/cold thresholds.
|
||||
- Coordinate invalidation workflows (layer purge, TTL expiry, diff invalidation) while keeping deterministic logs and telemetry.
|
||||
|
||||
## Interfaces & Dependencies
|
||||
- Relies on `StackExchange.Redis` via `StellaOps.DependencyInjection` bindings for cache state.
|
||||
- Coordinates with `StellaOps.Scanner.Storage` object store when persisting immutable artifacts.
|
||||
- Targets `net10.0` preview SDK and follows scanner coding standards from `docs/18_CODING_STANDARDS.md`.
|
||||
# StellaOps.Scanner.Cache — Agent Charter
|
||||
|
||||
## Mission
|
||||
Provide deterministic, offline-friendly caching primitives for scanner layers and file content so warm scans complete in <5 s and cache reuse remains reproducible across deployments.
|
||||
|
||||
## Responsibilities
|
||||
- Implement layer cache keyed by layer digest, retaining analyzer metadata and provenance per architecture §3.3.
|
||||
- Deliver file content-addressable storage (CAS) with deduplication, TTL enforcement, and offline import/export hooks.
|
||||
- Expose structured metrics, health probes, and configuration toggles for cache sizing, eviction, and warm/cold thresholds.
|
||||
- Coordinate invalidation workflows (layer purge, TTL expiry, diff invalidation) while keeping deterministic logs and telemetry.
|
||||
|
||||
## Interfaces & Dependencies
|
||||
- Relies on `StackExchange.Redis` via `StellaOps.DependencyInjection` bindings for cache state.
|
||||
- Coordinates with `StellaOps.Scanner.Storage` object store when persisting immutable artifacts.
|
||||
- Targets `net10.0` preview SDK and follows scanner coding standards from `docs/18_CODING_STANDARDS.md`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -1,29 +1,40 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Provide shared scanner contracts, observability primitives, and security utilities consumed by the WebService, Worker, analyzers, and downstream tooling.
|
||||
## Scope
|
||||
- Canonical DTOs for scan jobs, progress, outcomes, and error taxonomy shared across scanner services.
|
||||
- Deterministic ID and timestamp helpers to guarantee reproducible job identifiers and ISO-8601 rendering.
|
||||
- Observability helpers (logging scopes, correlation IDs, metric naming, activity sources) with negligible overhead.
|
||||
- Authority/OpTok integrations, DPoP validation helpers, and restart-time plug-in guardrails for scanner components.
|
||||
## Participants
|
||||
- Scanner.WebService and Scanner.Worker depend on these primitives for request handling, queue interactions, and diagnostics.
|
||||
- Policy/Signer integrations rely on deterministic identifiers and timestamps emitted here.
|
||||
- DevOps/Offline kits bundle plug-in manifests validated via the guardrails defined in this module.
|
||||
## Interfaces & contracts
|
||||
- DTOs must round-trip via System.Text.Json with `JsonSerializerDefaults.Web` and preserve ordering.
|
||||
- Deterministic helpers must not depend on ambient time/randomness; they derive IDs from explicit inputs and normalize timestamps to microsecond precision in UTC.
|
||||
- Observability scopes expose `scanId`, `jobId`, `correlationId`, and `imageDigest` fields with `stellaops scanner` metric prefixing.
|
||||
- Security helpers expose `IAuthorityTokenSource`, `IDPoPProofValidator`, and `IPluginCatalogGuard` abstractions with DI-friendly implementations.
|
||||
## In/Out of scope
|
||||
In: shared contracts, telemetry primitives, security utilities, plug-in manifest checks.
|
||||
Out: queue implementations, analyzer logic, storage adapters, HTTP endpoints, UI wiring.
|
||||
## Observability & security expectations
|
||||
- No network calls except via registered Authority clients.
|
||||
- Avoid allocations in hot paths; prefer struct enumerables/`ValueTask`.
|
||||
- All logs structured, correlation IDs propagated, no secrets persisted.
|
||||
- DPoP validation enforces algorithm allowlist (ES256/ES384) and ensures replay cache hooks.
|
||||
## Tests
|
||||
- `../StellaOps.Scanner.Core.Tests` owns unit coverage with deterministic fixtures.
|
||||
- Golden JSON for DTO round-trips stored under `Fixtures/`.
|
||||
- Security and observability helpers must include tests proving deterministic outputs and rejecting malformed proofs.
|
||||
# AGENTS
|
||||
## Role
|
||||
Provide shared scanner contracts, observability primitives, and security utilities consumed by the WebService, Worker, analyzers, and downstream tooling.
|
||||
## Scope
|
||||
- Canonical DTOs for scan jobs, progress, outcomes, and error taxonomy shared across scanner services.
|
||||
- Deterministic ID and timestamp helpers to guarantee reproducible job identifiers and ISO-8601 rendering.
|
||||
- Observability helpers (logging scopes, correlation IDs, metric naming, activity sources) with negligible overhead.
|
||||
- Authority/OpTok integrations, DPoP validation helpers, and restart-time plug-in guardrails for scanner components.
|
||||
## Participants
|
||||
- Scanner.WebService and Scanner.Worker depend on these primitives for request handling, queue interactions, and diagnostics.
|
||||
- Policy/Signer integrations rely on deterministic identifiers and timestamps emitted here.
|
||||
- DevOps/Offline kits bundle plug-in manifests validated via the guardrails defined in this module.
|
||||
## Interfaces & contracts
|
||||
- DTOs must round-trip via System.Text.Json with `JsonSerializerDefaults.Web` and preserve ordering.
|
||||
- Deterministic helpers must not depend on ambient time/randomness; they derive IDs from explicit inputs and normalize timestamps to microsecond precision in UTC.
|
||||
- Observability scopes expose `scanId`, `jobId`, `correlationId`, and `imageDigest` fields with `stellaops scanner` metric prefixing.
|
||||
- Security helpers expose `IAuthorityTokenSource`, `IDPoPProofValidator`, and `IPluginCatalogGuard` abstractions with DI-friendly implementations.
|
||||
## In/Out of scope
|
||||
In: shared contracts, telemetry primitives, security utilities, plug-in manifest checks.
|
||||
Out: queue implementations, analyzer logic, storage adapters, HTTP endpoints, UI wiring.
|
||||
## Observability & security expectations
|
||||
- No network calls except via registered Authority clients.
|
||||
- Avoid allocations in hot paths; prefer struct enumerables/`ValueTask`.
|
||||
- All logs structured, correlation IDs propagated, no secrets persisted.
|
||||
- DPoP validation enforces algorithm allowlist (ES256/ES384) and ensures replay cache hooks.
|
||||
## Tests
|
||||
- `../StellaOps.Scanner.Core.Tests` owns unit coverage with deterministic fixtures.
|
||||
- Golden JSON for DTO round-trips stored under `Fixtures/`.
|
||||
- Security and observability helpers must include tests proving deterministic outputs and rejecting malformed proofs.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -1,20 +1,31 @@
|
||||
# StellaOps.Scanner.Diff — Agent Charter
|
||||
|
||||
## Mission
|
||||
Deliver deterministic image-to-image component diffs grouped by layer with provenance signals that power policy previews, UI surfacing, and downstream scheduling.
|
||||
|
||||
## Responsibilities
|
||||
- Maintain diff computation pipelines for inventory and usage SBOM views.
|
||||
- Ensure ordering, hashing, and serialization are stable across runs and hosts.
|
||||
- Capture layer provenance, usage flags, and supporting evidence for every change.
|
||||
- Provide JSON artifacts and helper APIs consumed by the Scanner WebService, Worker, CLI, and UI.
|
||||
|
||||
## Interfaces & Dependencies
|
||||
- Consumes normalized component fragments emitted by analyzers and usage signals from EntryTrace.
|
||||
- Emits diff models used by `StellaOps.Scanner.WebService` and persisted by `StellaOps.Scanner.Storage`.
|
||||
- Shares deterministic primitives from `StellaOps.Scanner.Core` once extended with component contracts.
|
||||
|
||||
## Testing Expectations
|
||||
- Golden diff fixtures for add/remove/version-change flows.
|
||||
- Determinism checks comparing shuffled inputs.
|
||||
- Layer attribution regression tests to guard provenance correctness.
|
||||
# StellaOps.Scanner.Diff — Agent Charter
|
||||
|
||||
## Mission
|
||||
Deliver deterministic image-to-image component diffs grouped by layer with provenance signals that power policy previews, UI surfacing, and downstream scheduling.
|
||||
|
||||
## Responsibilities
|
||||
- Maintain diff computation pipelines for inventory and usage SBOM views.
|
||||
- Ensure ordering, hashing, and serialization are stable across runs and hosts.
|
||||
- Capture layer provenance, usage flags, and supporting evidence for every change.
|
||||
- Provide JSON artifacts and helper APIs consumed by the Scanner WebService, Worker, CLI, and UI.
|
||||
|
||||
## Interfaces & Dependencies
|
||||
- Consumes normalized component fragments emitted by analyzers and usage signals from EntryTrace.
|
||||
- Emits diff models used by `StellaOps.Scanner.WebService` and persisted by `StellaOps.Scanner.Storage`.
|
||||
- Shares deterministic primitives from `StellaOps.Scanner.Core` once extended with component contracts.
|
||||
|
||||
## Testing Expectations
|
||||
- Golden diff fixtures for add/remove/version-change flows.
|
||||
- Determinism checks comparing shuffled inputs.
|
||||
- Layer attribution regression tests to guard provenance correctness.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -1,20 +1,31 @@
|
||||
# StellaOps.Scanner.Emit — Agent Charter
|
||||
|
||||
## Mission
|
||||
Assemble deterministic SBOM artifacts (inventory, usage, BOM index) from analyzer fragments and usage telemetry, and prepare them for storage, signing, and distribution.
|
||||
|
||||
## Responsibilities
|
||||
- Merge per-layer/component fragments into CycloneDX JSON/Protobuf SBOMs.
|
||||
- Generate BOM index sidecars with roaring bitmap acceleration and usage flags.
|
||||
- Package artifacts with stable naming, hashing, and manifests for downstream storage and attestations.
|
||||
- Surface helper APIs for Scanner Worker/WebService to request compositions and exports.
|
||||
|
||||
## Interfaces & Dependencies
|
||||
- Consumes analyzer outputs (OS, language, native) and EntryTrace usage annotations.
|
||||
- Produces artifacts persisted via `StellaOps.Scanner.Storage` and referenced by policy/report pipelines.
|
||||
- Relies on deterministic primitives from `StellaOps.Scanner.Core` for timestamps, hashing, and serialization defaults.
|
||||
|
||||
## Testing Expectations
|
||||
- Golden SBOM and BOM index fixtures with determinism checks.
|
||||
- Schema validation for CycloneDX outputs and BOM index binary layout.
|
||||
- Integration tests exercising packaging helpers with in-memory storage fakes.
|
||||
# StellaOps.Scanner.Emit — Agent Charter
|
||||
|
||||
## Mission
|
||||
Assemble deterministic SBOM artifacts (inventory, usage, BOM index) from analyzer fragments and usage telemetry, and prepare them for storage, signing, and distribution.
|
||||
|
||||
## Responsibilities
|
||||
- Merge per-layer/component fragments into CycloneDX JSON/Protobuf SBOMs.
|
||||
- Generate BOM index sidecars with roaring bitmap acceleration and usage flags.
|
||||
- Package artifacts with stable naming, hashing, and manifests for downstream storage and attestations.
|
||||
- Surface helper APIs for Scanner Worker/WebService to request compositions and exports.
|
||||
|
||||
## Interfaces & Dependencies
|
||||
- Consumes analyzer outputs (OS, language, native) and EntryTrace usage annotations.
|
||||
- Produces artifacts persisted via `StellaOps.Scanner.Storage` and referenced by policy/report pipelines.
|
||||
- Relies on deterministic primitives from `StellaOps.Scanner.Core` for timestamps, hashing, and serialization defaults.
|
||||
|
||||
## Testing Expectations
|
||||
- Golden SBOM and BOM index fixtures with determinism checks.
|
||||
- Schema validation for CycloneDX outputs and BOM index binary layout.
|
||||
- Integration tests exercising packaging helpers with in-memory storage fakes.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -1,32 +1,43 @@
|
||||
# StellaOps.Scanner.EntryTrace — Agent Charter
|
||||
|
||||
## Mission
|
||||
Resolve container `ENTRYPOINT`/`CMD` chains into deterministic call graphs that fuel usage-aware SBOMs, policy explainability, and runtime drift detection. Implement the EntryTrace analyzers and expose them as restart-time plug-ins for the Scanner Worker.
|
||||
|
||||
## Scope
|
||||
- Parse POSIX/Bourne shell constructs (exec, command, case, if, source/run-parts) with deterministic AST output.
|
||||
- Walk layered root filesystems to resolve PATH lookups, interpreter hand-offs (Python/Node/Java), and record evidence.
|
||||
- Surface explainable diagnostics for unresolved branches (env indirection, missing files, unsupported syntax) and emit metrics.
|
||||
- Package analyzers as signed plug-ins under `plugins/scanner/entrytrace/`, guarded by restart-only policy.
|
||||
|
||||
## Out of Scope
|
||||
- SBOM emission/diffing (owned by `Scanner.Emit`/`Scanner.Diff`).
|
||||
- Runtime enforcement or live drift reconciliation (owned by Zastava).
|
||||
- Registry/network fetchers beyond file lookups inside extracted layers.
|
||||
|
||||
## Interfaces & Contracts
|
||||
- Primary entry point: `IEntryTraceAnalyzer.ResolveAsync` returning a deterministic `EntryTraceGraph`.
|
||||
- Graph nodes must include file path, line span, interpreter classification, evidence source, and follow `Scanner.Core` timestamp/ID helpers when emitting events.
|
||||
- Diagnostics must enumerate unknown reasons from fixed enum; metrics tagged `entrytrace.*`.
|
||||
- Plug-ins register via `IEntryTraceAnalyzerFactory` and must validate against `IPluginCatalogGuard`.
|
||||
|
||||
## Observability & Security
|
||||
- No dynamic assembly loading beyond restart-time plug-in catalog.
|
||||
- Structured logs include `scanId`, `imageDigest`, `layerDigest`, `command`, `reason`.
|
||||
- Metrics counters: `entrytrace_resolutions_total{result}`, `entrytrace_unresolved_total{reason}`.
|
||||
- Deny `source` directives outside image root; sandbox file IO via provided `IRootFileSystem`.
|
||||
|
||||
## Testing
|
||||
- Unit tests live in `../StellaOps.Scanner.EntryTrace.Tests` with golden fixtures under `Fixtures/`.
|
||||
- Determinism harness: same inputs produce byte-identical serialized graphs.
|
||||
- Parser fuzz seeds captured for regression; interpreter tracers validated with sample scripts for Python, Node, Java launchers.
|
||||
# StellaOps.Scanner.EntryTrace — Agent Charter
|
||||
|
||||
## Mission
|
||||
Resolve container `ENTRYPOINT`/`CMD` chains into deterministic call graphs that fuel usage-aware SBOMs, policy explainability, and runtime drift detection. Implement the EntryTrace analyzers and expose them as restart-time plug-ins for the Scanner Worker.
|
||||
|
||||
## Scope
|
||||
- Parse POSIX/Bourne shell constructs (exec, command, case, if, source/run-parts) with deterministic AST output.
|
||||
- Walk layered root filesystems to resolve PATH lookups, interpreter hand-offs (Python/Node/Java), and record evidence.
|
||||
- Surface explainable diagnostics for unresolved branches (env indirection, missing files, unsupported syntax) and emit metrics.
|
||||
- Package analyzers as signed plug-ins under `plugins/scanner/entrytrace/`, guarded by restart-only policy.
|
||||
|
||||
## Out of Scope
|
||||
- SBOM emission/diffing (owned by `Scanner.Emit`/`Scanner.Diff`).
|
||||
- Runtime enforcement or live drift reconciliation (owned by Zastava).
|
||||
- Registry/network fetchers beyond file lookups inside extracted layers.
|
||||
|
||||
## Interfaces & Contracts
|
||||
- Primary entry point: `IEntryTraceAnalyzer.ResolveAsync` returning a deterministic `EntryTraceGraph`.
|
||||
- Graph nodes must include file path, line span, interpreter classification, evidence source, and follow `Scanner.Core` timestamp/ID helpers when emitting events.
|
||||
- Diagnostics must enumerate unknown reasons from fixed enum; metrics tagged `entrytrace.*`.
|
||||
- Plug-ins register via `IEntryTraceAnalyzerFactory` and must validate against `IPluginCatalogGuard`.
|
||||
|
||||
## Observability & Security
|
||||
- No dynamic assembly loading beyond restart-time plug-in catalog.
|
||||
- Structured logs include `scanId`, `imageDigest`, `layerDigest`, `command`, `reason`.
|
||||
- Metrics counters: `entrytrace_resolutions_total{result}`, `entrytrace_unresolved_total{reason}`.
|
||||
- Deny `source` directives outside image root; sandbox file IO via provided `IRootFileSystem`.
|
||||
|
||||
## Testing
|
||||
- Unit tests live in `../StellaOps.Scanner.EntryTrace.Tests` with golden fixtures under `Fixtures/`.
|
||||
- Determinism harness: same inputs produce byte-identical serialized graphs.
|
||||
- Parser fuzz seeds captured for regression; interpreter tracers validated with sample scripts for Python, Node, Java launchers.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -5,6 +5,8 @@
|
||||
| SCANNER-ENTRYTRACE-18-502 | TODO | EntryTrace Guild | SCANNER-ENTRYTRACE-18-501 | Expand chain walker with init shim/user-switch/supervisor recognition plus env/workdir accumulation and guarded edges. | Graph nodes annotate tini/dumb-init/gosu/su-exec/s6/supervisord/runit branches with capability tags, environment deltas, and guard metadata validated against fixture scripts. |
|
||||
| SCANNER-ENTRYTRACE-18-503 | TODO | EntryTrace Guild | SCANNER-ENTRYTRACE-18-502 | Introduce target classifier + EntryPlan handoff with confidence scoring for ELF/Java/.NET/Node/Python and user/workdir context. | Analyzer returns typed targets with confidence metrics and per-branch EntryPlans exercised via golden fixtures and language analyzer stubs. |
|
||||
| SCANNER-ENTRYTRACE-18-504 | TODO | EntryTrace Guild | SCANNER-ENTRYTRACE-18-503 | Emit EntryTrace AOC NDJSON (`entrytrace.entry/node/edge/target/warning/capability`) and wire CLI/service streaming outputs. | NDJSON writer passes determinism tests, CLI/service endpoints stream ordered observations, and diagnostics integrate new warning codes for dynamic eval/glob limits/windows shims. |
|
||||
| ENTRYTRACE-SURFACE-01 | TODO | EntryTrace Guild | SURFACE-VAL-02, SURFACE-FS-02 | Run Surface.Validation prereq checks and resolve cached entry fragments via Surface.FS to avoid duplicate parsing. | EntryTrace performance metrics show reuse; regression tests updated; validation errors surfaced consistently. |
|
||||
| ENTRYTRACE-SURFACE-02 | TODO | EntryTrace Guild | SURFACE-SECRETS-02 | Replace direct env/secret access with Surface.Secrets provider when tracing runtime configs. | Shared provider used; failure modes covered; documentation refreshed. |
|
||||
|
||||
## Status Review — 2025-10-19
|
||||
|
||||
|
||||
@@ -1,15 +1,26 @@
|
||||
# StellaOps.Scanner.Queue — Agent Charter
|
||||
|
||||
## Mission
|
||||
Deliver the scanner job queue backbone defined in `docs/modules/scanner/ARCHITECTURE.md`, providing deterministic, offline-friendly leasing semantics for WebService producers and Worker consumers.
|
||||
|
||||
## Responsibilities
|
||||
- Define queue abstractions with idempotent enqueue tokens, acknowledgement, lease renewal, and claim support.
|
||||
- Ship first-party adapters for Redis Streams and NATS JetStream, respecting offline deployments and allow-listed hosts.
|
||||
- Surface health probes, structured diagnostics, and metrics needed by Scanner WebService/Worker.
|
||||
- Document operational expectations and configuration binding hooks.
|
||||
|
||||
## Interfaces & Dependencies
|
||||
- Consumes shared configuration primitives from `StellaOps.Configuration`.
|
||||
- Exposes dependency injection extensions for `StellaOps.DependencyInjection`.
|
||||
- Targets `net10.0` (preview) and aligns with scanner DTOs once `StellaOps.Scanner.Core` lands.
|
||||
# StellaOps.Scanner.Queue — Agent Charter
|
||||
|
||||
## Mission
|
||||
Deliver the scanner job queue backbone defined in `docs/modules/scanner/ARCHITECTURE.md`, providing deterministic, offline-friendly leasing semantics for WebService producers and Worker consumers.
|
||||
|
||||
## Responsibilities
|
||||
- Define queue abstractions with idempotent enqueue tokens, acknowledgement, lease renewal, and claim support.
|
||||
- Ship first-party adapters for Redis Streams and NATS JetStream, respecting offline deployments and allow-listed hosts.
|
||||
- Surface health probes, structured diagnostics, and metrics needed by Scanner WebService/Worker.
|
||||
- Document operational expectations and configuration binding hooks.
|
||||
|
||||
## Interfaces & Dependencies
|
||||
- Consumes shared configuration primitives from `StellaOps.Configuration`.
|
||||
- Exposes dependency injection extensions for `StellaOps.DependencyInjection`.
|
||||
- Targets `net10.0` (preview) and aligns with scanner DTOs once `StellaOps.Scanner.Core` lands.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -1,28 +1,39 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Provide durable catalog and artifact storage for the Scanner plane, spanning Mongo catalog collections and MinIO object storage. Expose repositories and services used by WebService and Worker components to persist job state, image metadata, and exported artefacts deterministically.
|
||||
## Scope
|
||||
- Mongo collections: artifacts, images, layers, links, jobs, lifecycle_rules, migrations.
|
||||
- Metadata documents: enforce majority write/read concerns, UTC timestamps, deterministic identifiers (SHA-256 digests, ULIDs for jobs).
|
||||
- Bootstrapper: create collections + indexes (unique digests, compound references, TTL on lifecycle rules, sparse lookup helpers) and run schema migrations.
|
||||
- Object storage (MinIO/S3): manage bucket layout (layers/, images/, indexes/, attest/), immutability policies, deterministic paths, and retention classes.
|
||||
- Services: coordinate dual-write between Mongo metadata and MinIO blobs, compute digests, manage reference counts, and expose typed repositories for WebService/Worker interactions.
|
||||
## Participants
|
||||
- Scanner.WebService binds configuration, runs bootstrapper during startup, and uses repositories to enqueue scans, look up catalog entries, and manage lifecycle policies.
|
||||
- Scanner.Worker writes job progress, uploads SBOM artefacts, and updates artefact reference counts.
|
||||
- Policy / Notify consumers resolve artefact metadata for reports via catalog APIs once exposed.
|
||||
## Interfaces & contracts
|
||||
- Options configured via `ScannerStorageOptions` (Mongo + object store). `EnsureValid` rejects incomplete/unsafe configuration.
|
||||
- Mongo access uses `IMongoDatabase` scoped with majority `ReadConcern`/`WriteConcern` and cancellation tokens.
|
||||
- Object store abstraction (`IArtifactObjectStore`) encapsulates MinIO (S3) operations with server-side checksum validation and optional object-lock retain-until.
|
||||
- Service APIs follow deterministic naming: digests normalized (`sha256:<hex>`), ULIDs sortable, timestamps ISO-8601 UTC.
|
||||
## In/Out of scope
|
||||
In: persistence models, bootstrap/migrations, catalog repositories, object storage client, retention helpers, dual-write coordination, deterministic digests.
|
||||
Out: HTTP endpoints, queue processing, analyzer logic, SBOM composition, policy decisions, UI contracts.
|
||||
## Observability & security expectations
|
||||
- Emit structured logs for catalog/object-store writes including correlation IDs and digests.
|
||||
- Guard against double writes; idempotent operations keyed by digests.
|
||||
- Do not log credentials; redact connection strings. Honour cancellation tokens.
|
||||
- Metrics hooks (pending) must expose duration counters for Mongo and MinIO operations.
|
||||
## Tests
|
||||
- Integration tests with ephemeral Mongo/MinIO stubs covering bootstrapper indexes, TTL enforcement, dual-write coordination, digest determinism, and majority read/write concerns.
|
||||
# AGENTS
|
||||
## Role
|
||||
Provide durable catalog and artifact storage for the Scanner plane, spanning Mongo catalog collections and MinIO object storage. Expose repositories and services used by WebService and Worker components to persist job state, image metadata, and exported artefacts deterministically.
|
||||
## Scope
|
||||
- Mongo collections: artifacts, images, layers, links, jobs, lifecycle_rules, migrations.
|
||||
- Metadata documents: enforce majority write/read concerns, UTC timestamps, deterministic identifiers (SHA-256 digests, ULIDs for jobs).
|
||||
- Bootstrapper: create collections + indexes (unique digests, compound references, TTL on lifecycle rules, sparse lookup helpers) and run schema migrations.
|
||||
- Object storage (MinIO/S3): manage bucket layout (layers/, images/, indexes/, attest/), immutability policies, deterministic paths, and retention classes.
|
||||
- Services: coordinate dual-write between Mongo metadata and MinIO blobs, compute digests, manage reference counts, and expose typed repositories for WebService/Worker interactions.
|
||||
## Participants
|
||||
- Scanner.WebService binds configuration, runs bootstrapper during startup, and uses repositories to enqueue scans, look up catalog entries, and manage lifecycle policies.
|
||||
- Scanner.Worker writes job progress, uploads SBOM artefacts, and updates artefact reference counts.
|
||||
- Policy / Notify consumers resolve artefact metadata for reports via catalog APIs once exposed.
|
||||
## Interfaces & contracts
|
||||
- Options configured via `ScannerStorageOptions` (Mongo + object store). `EnsureValid` rejects incomplete/unsafe configuration.
|
||||
- Mongo access uses `IMongoDatabase` scoped with majority `ReadConcern`/`WriteConcern` and cancellation tokens.
|
||||
- Object store abstraction (`IArtifactObjectStore`) encapsulates MinIO (S3) operations with server-side checksum validation and optional object-lock retain-until.
|
||||
- Service APIs follow deterministic naming: digests normalized (`sha256:<hex>`), ULIDs sortable, timestamps ISO-8601 UTC.
|
||||
## In/Out of scope
|
||||
In: persistence models, bootstrap/migrations, catalog repositories, object storage client, retention helpers, dual-write coordination, deterministic digests.
|
||||
Out: HTTP endpoints, queue processing, analyzer logic, SBOM composition, policy decisions, UI contracts.
|
||||
## Observability & security expectations
|
||||
- Emit structured logs for catalog/object-store writes including correlation IDs and digests.
|
||||
- Guard against double writes; idempotent operations keyed by digests.
|
||||
- Do not log credentials; redact connection strings. Honour cancellation tokens.
|
||||
- Metrics hooks (pending) must expose duration counters for Mongo and MinIO operations.
|
||||
## Tests
|
||||
- Integration tests with ephemeral Mongo/MinIO stubs covering bootstrapper indexes, TTL enforcement, dual-write coordination, digest determinism, and majority read/write concerns.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/platform/architecture-overview.md`
|
||||
|
||||
## Working Agreement
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
- 2. Review this charter and the Required Reading documents before coding; confirm prerequisites are met.
|
||||
- 3. Keep changes deterministic (stable ordering, timestamps, hashes) and align with offline/air-gap expectations.
|
||||
- 4. Coordinate doc updates, tests, and cross-guild communication whenever contracts or workflows change.
|
||||
- 5. Revert to `TODO` if you pause the task without shipping changes; leave notes in commit/PR descriptions for context.
|
||||
|
||||
@@ -0,0 +1,27 @@
|
||||
# Scanner Surface.Env Guild Charter
|
||||
|
||||
## Mission
|
||||
Provide strongly-typed configuration helpers for Scanner/Zastava components, encapsulating environment-variable parsing, validation, and defaults related to surface caching, storage, and feature toggles. Ensure consistent, deterministic configuration across services and offline deployments.
|
||||
|
||||
## Scope
|
||||
- Environment helper APIs within `StellaOps.Scanner.Surface.Env`.
|
||||
- Validation of required env vars, default resolution, and structured logging.
|
||||
- Coordination with DevOps for Helm/Compose/offline-kit templates.
|
||||
- Backward-compatible evolution of configuration keys.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/design/surface-env.md`
|
||||
- `docs/modules/scanner/design/surface-fs.md`
|
||||
- `docs/modules/scanner/design/surface-secrets.md`
|
||||
- `docs/modules/scanner/design/surface-validation.md`
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/zastava/architecture.md`
|
||||
- Deployment guides (`deploy/README.md`, `ops/devops/TASKS.md`) referencing scanner env vars.
|
||||
|
||||
## Working Agreement
|
||||
1. **State sync**: mark tasks `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and local `TASKS.md` before/after changes.
|
||||
2. **Deterministic parsing**: validate inputs once, emit structured errors, avoid direct `Environment.GetEnvironmentVariable` calls elsewhere.
|
||||
3. **Compatibility**: version new keys; provide migration helpers and deprecation warnings; update docs + Ops templates.
|
||||
4. **Testing**: maintain unit tests for parsing, validation, and fallback behaviour; include edge cases (missing, malformed, default override).
|
||||
5. **Security**: redact secrets in logs; ensure secret references pair with Surface.Secrets.
|
||||
6. **Documentation**: keep `surface-env.md` current; coordinate with Ops on template changes.
|
||||
@@ -0,0 +1,9 @@
|
||||
# Surface.Env Task Board (Epic: SURFACE-SHARING)
|
||||
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
| SURFACE-ENV-01 | TODO | Scanner Guild, Zastava Guild | ARCH-SURFACE-EPIC | Draft `docs/modules/scanner/design/surface-env.md` enumerating environment variables, defaults, and air-gap behaviour. | Spec merged; env matrix reviewed by Ops + Security. |
|
||||
| SURFACE-ENV-02 | TODO | Scanner Guild | SURFACE-ENV-01 | Implement strongly-typed env accessors in `StellaOps.Scanner.Surface.Env` with validation and deterministic logging. | Library published; unit tests cover parsing, fallbacks, and error paths. |
|
||||
| SURFACE-ENV-03 | TODO | Scanner Guild | SURFACE-ENV-02 | Adopt env helper across Scanner Worker/WebService/BuildX plug-ins. | Services use helper; manifests updated; smoke tests green. |
|
||||
| SURFACE-ENV-04 | TODO | Zastava Guild | SURFACE-ENV-02 | Wire env helper into Zastava Observer/Webhook containers. | Zastava builds reference env helper; admission tests validated. |
|
||||
| SURFACE-ENV-05 | TODO | Ops Guild | SURFACE-ENV-03..04 | Update Helm/Compose/offline kit templates with new env knobs and documentation. | Templates merged; docs include configuration table; air-gap scripts updated. |
|
||||
@@ -0,0 +1,30 @@
|
||||
# Scanner Surface.FS Guild Charter
|
||||
|
||||
## Mission
|
||||
Define and maintain the shared surface filesystem abstraction used by Scanner, Zastava, and Scheduler to store and retrieve deterministic cache artefacts (layer manifests, entry traces, SBOM fragments). Surface.FS must ensure content-addressed integrity, tenancy isolation, and offline portability.
|
||||
|
||||
## Scope
|
||||
- Core reader/writer abstractions in `StellaOps.Scanner.Surface.FS`.
|
||||
- Manifest schemas, CAS helpers, and API contracts for cache consumers.
|
||||
- Integration hooks with Scanner Worker/WebService, Zastava Observer/Webhook, Scheduler planners.
|
||||
- Tests covering concurrency, determinism, and error handling.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/design/surface-fs.md`
|
||||
- `docs/modules/scanner/design/surface-env.md`
|
||||
- `docs/modules/scanner/design/surface-secrets.md`
|
||||
- `docs/modules/scanner/design/surface-validation.md`
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/zastava/architecture.md`
|
||||
- `docs/modules/scheduler/architecture.md`
|
||||
- Offline kit notes referencing cache bundles.
|
||||
|
||||
## Working Agreement
|
||||
1. **Status updates**: adjust task state in `docs/implplan/SPRINTS.md` and local `TASKS.md` when starting/finishing work.
|
||||
2. **Determinism**: manifests must be stable (ordered keys, normalised timestamps); avoid non-deterministic metadata.
|
||||
3. **Security & tenancy**: enforce namespace separation, hash validation, and capability checks; integrate with Surface.Secrets for protected stores.
|
||||
4. **Concurrency**: design for multi-writer safety with leases or idempotent writes; document locking expectations.
|
||||
5. **Testing**: cover unit/integration scenarios (write/read, corruption handling, retention policies) and regression tests in Scanner/Zastava.
|
||||
6. **Documentation**: update `surface-fs.md` and downstream guides when schema or API contracts evolve; coordinate with Ops for deployment changes.
|
||||
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Surface.FS Task Board (Epic: SURFACE-SHARING)
|
||||
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
| SURFACE-FS-01 | TODO | Scanner Guild, Zastava Guild | ARCH-SURFACE-EPIC | Author `docs/modules/scanner/design/surface-fs.md` defining cache layout, pointer schema, tenancy, and offline handling. | Spec merged; reviewers from Scanner/Zastava sign off; component map cross-link drafted. |
|
||||
| SURFACE-FS-02 | TODO | Scanner Guild | SURFACE-FS-01 | Implement `StellaOps.Scanner.Surface.FS` core abstractions (writer, reader, manifest models) with deterministic serialization + unit tests. | Library compiles; tests pass; XML docs cover public types. |
|
||||
| SURFACE-FS-03 | TODO | Scanner Guild | SURFACE-FS-02 | Integrate Surface.FS writer into Scanner Worker analyzer pipeline to persist layer + entry-trace fragments. | Worker produces cache entries in integration tests; observability counters emitted. |
|
||||
| SURFACE-FS-04 | TODO | Zastava Guild | SURFACE-FS-02 | Integrate Surface.FS reader into Zastava Observer runtime drift loop. | Observer validates runtime artefacts via cache; regression tests updated. |
|
||||
| SURFACE-FS-05 | TODO | Scanner Guild, Scheduler Guild | SURFACE-FS-03 | Expose Surface.FS pointers via Scanner WebService reports and coordinate rescan planning with Scheduler. | API contracts updated; Scheduler consumes pointers; docs refreshed. |
|
||||
| SURFACE-FS-06 | TODO | Docs Guild | SURFACE-FS-02..05 | Update scanner-engine guide and offline kit docs with Surface.FS workflow. | Docs merged; offline kit manifests include cache bundles. |
|
||||
@@ -0,0 +1,30 @@
|
||||
# Scanner Surface.Secrets Guild Charter
|
||||
|
||||
## Mission
|
||||
Provide a unified secret access layer for Scanner, Zastava, and related services to retrieve registry credentials, CAS tokens, and bundle decryptors securely and deterministically. Surface.Secrets abstracts secret stores (Kubernetes, file bundles, in-memory) while supporting offline and air-gapped deployments.
|
||||
|
||||
## Scope
|
||||
- Secret provider interfaces and implementations in `StellaOps.Scanner.Surface.Secrets`.
|
||||
- Integration with Surface.Env & Surface.Validation for configuration/inputs.
|
||||
- Backend adapters (Kubernetes Secret, file-based, offline bundle) and rotation hooks.
|
||||
- Audit logging, caching policies, and error handling for secret access.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/design/surface-secrets.md`
|
||||
- `docs/modules/scanner/design/surface-env.md`
|
||||
- `docs/modules/scanner/design/surface-fs.md`
|
||||
- `docs/modules/scanner/design/surface-validation.md`
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/zastava/architecture.md`
|
||||
- `docs/modules/airgap/airgap-mode.md`
|
||||
- Security guidance in `docs/security/redaction-and-privacy.md`
|
||||
|
||||
## Working Agreement
|
||||
1. **Status synchronisation**: update task state in both `docs/implplan/SPRINTS.md` and local `TASKS.md` whenever you start or complete work.
|
||||
2. **Security posture**: enforce least privilege, short cache TTLs, redaction in logs, and Authority scope checks where applicable.
|
||||
3. **Deterministic behaviour**: deterministic secret selection & failure modes; avoid random jitter unless documented.
|
||||
4. **Offline readiness**: support sealed-mode bundles; document required manifest formats and verification steps.
|
||||
5. **Testing**: add unit/integration tests for each backend, rotation scenario, and failure path; include air-gap fixtures.
|
||||
6. **Documentation**: keep `surface-secrets.md` current; collaborate with DevOps to update Helm/Compose/offline-kit instructions.
|
||||
|
||||
- 1. Update task status to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and the local `TASKS.md` when you start or finish work.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Surface.Secrets Task Board (Epic: SURFACE-SHARING)
|
||||
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
| SURFACE-SECRETS-01 | TODO | Scanner Guild, Security Guild | ARCH-SURFACE-EPIC | Produce `docs/modules/scanner/design/surface-secrets.md` defining secret reference schema, storage backends, scopes, and rotation. | Spec approved by Security + Authority guilds; threat model ticket logged. |
|
||||
| SURFACE-SECRETS-02 | TODO | Scanner Guild | SURFACE-SECRETS-01 | Implement `StellaOps.Scanner.Surface.Secrets` core provider interfaces, secret models, and in-memory test backend. | Library builds; tests pass; XML docs cover public API. |
|
||||
| SURFACE-SECRETS-03 | TODO | Scanner Guild | SURFACE-SECRETS-02 | Add Kubernetes/File/Offline backends with deterministic caching and audit hooks. | Backends integrated; integration tests simulate rotation + offline bundles. |
|
||||
| SURFACE-SECRETS-04 | TODO | Scanner Guild | SURFACE-SECRETS-02 | Integrate Surface.Secrets into Scanner Worker/WebService/BuildX for registry + CAS creds. | Scanner components consume library; legacy secret code removed; smoke tests updated. |
|
||||
| SURFACE-SECRETS-05 | TODO | Zastava Guild | SURFACE-SECRETS-02 | Invoke Surface.Secrets from Zastava Observer/Webhook for CAS & attestation secrets. | Zastava uses shared provider; admission + observer tests cover secret errors. |
|
||||
| SURFACE-SECRETS-06 | TODO | Ops Guild | SURFACE-SECRETS-03 | Update deployment manifests/offline kit bundles to provision secret references instead of raw values. | Templates merged; docs & runbooks updated; offline kit instructions validated. |
|
||||
@@ -0,0 +1,27 @@
|
||||
# Scanner Surface.Validation Guild Charter
|
||||
|
||||
## Mission
|
||||
Deliver an extensible validation framework that enforces preconditions for Surface-driven features (env configuration, cache manifests, secret references) across Scanner, Zastava, Scheduler, and related tooling. Validators must be composable, SOLID-compliant, and easily queryable by analyzers and services.
|
||||
|
||||
## Scope
|
||||
- Validator interfaces, registry, and default validators in `StellaOps.Scanner.Surface.Validation`.
|
||||
- Integration helpers for Scanner analyzers, Worker/WebService, Zastava Observer/Webhook, Scheduler planners.
|
||||
- Documentation showing how to add custom validators per surface consumer.
|
||||
- Test coverage ensuring validators are deterministic and produce actionable diagnostics.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/scanner/design/surface-validation.md`
|
||||
- `docs/modules/scanner/design/surface-env.md`
|
||||
- `docs/modules/scanner/design/surface-fs.md`
|
||||
- `docs/modules/scanner/design/surface-secrets.md`
|
||||
- `docs/modules/scanner/architecture.md`
|
||||
- `docs/modules/zastava/architecture.md`
|
||||
- `docs/modules/scheduler/architecture.md`
|
||||
|
||||
## Working Agreement
|
||||
1. **Status sync**: mark tasks `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and local `TASKS.md` when you begin/finish work.
|
||||
2. **Extensibility**: design validators to be SOLID-compliant; document registration patterns; avoid hard-coded logic in consumers.
|
||||
3. **Deterministic diagnostics**: produce stable error codes/messages; support localisation if required.
|
||||
4. **Integration**: ensure all Surface libraries and consumers call validators before operation; add regression tests in downstream modules when new checks land.
|
||||
5. **Testing**: include unit tests for each validator, registry behaviour, and composition; simulate failure paths.
|
||||
6. **Documentation**: keep `surface-validation.md` updated with new validator types, usage examples, and extension guidance.
|
||||
@@ -0,0 +1,9 @@
|
||||
# Surface.Validation Task Board (Epic: SURFACE-SHARING)
|
||||
|
||||
| ID | Status | Owner(s) | Depends on | Description | Exit Criteria |
|
||||
|----|--------|----------|------------|-------------|---------------|
|
||||
| SURFACE-VAL-01 | TODO | Scanner Guild, Security Guild | SURFACE-FS-01, SURFACE-ENV-01 | Define validation framework (design doc `surface-validation.md`) covering SOLID extension points and queryable checks for env/cache/secrets. | Spec merged; architecture sign-off from Scanner + Security; checklist of baseline validators established. |
|
||||
| SURFACE-VAL-02 | TODO | Scanner Guild | SURFACE-VAL-01, SURFACE-ENV-02, SURFACE-FS-02 | Implement base validation library (interfaces, check registry, default validators for env/cached manifests, secret refs) with unit tests. | Library published; validation registry supports DI; tests cover success/failure; XML docs added. |
|
||||
| SURFACE-VAL-03 | TODO | Scanner Guild, Analyzer Guild | SURFACE-VAL-02 | Integrate validation pipeline into Scanner analyzers (Lang, EntryTrace, etc.) to ensure consistent checks before processing. | Analyzers call validation hooks; integration tests updated; performance baseline measured. |
|
||||
| SURFACE-VAL-04 | TODO | Scanner Guild, Zastava Guild | SURFACE-VAL-02 | Expose validation helpers to Zastava and other runtime consumers (Observer/Webhook) for preflight checks. | Zastava uses shared validators; admission tests include validation failure scenarios. |
|
||||
| SURFACE-VAL-05 | TODO | Docs Guild | SURFACE-VAL-02 | Document validation extensibility, registration, and customization in scanner-engine guide and developer docs. | Docs merged; examples show adding custom validator; cross-links added. |
|
||||
Reference in New Issue
Block a user