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:
@@ -0,0 +1,25 @@
|
||||
# Excititor Mirror Connector Charter
|
||||
|
||||
## Mission
|
||||
Ingest StellaOps VEX mirror bundles into Excititor, converting them into immutable VEX observations without applying consensus or suppression. The connector must honour the Aggregation-Only Contract, maintain provenance, and support offline replay and incremental updates.
|
||||
|
||||
## Scope
|
||||
- Code in `StellaOps.Excititor.Connectors.StellaOpsMirror`.
|
||||
- Bundle validation (signatures, manifests, Merkle roots) and cursor management.
|
||||
- Integration with Excititor storage and Surface/VEX Lens consumers.
|
||||
- Test fixtures demonstrating deterministic ingest across bundle versions.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/architecture.md`
|
||||
- `docs/ingestion/aggregation-only-contract.md`
|
||||
- `docs/modules/excititor/operations/mirror.md` (if available; otherwise coordinate with Docs to add details)
|
||||
- `docs/modules/airgap/airgap-mode.md`
|
||||
- `docs/modules/concelier/operations/mirror.md` (shared mirror concepts)
|
||||
|
||||
## Working Agreement
|
||||
1. **Status updates**: set tasks to `DOING`/`DONE` in both `docs/implplan/SPRINTS.md` and local `TASKS.md` when work starts/finishes.
|
||||
2. **Provenance preservation**: record bundle IDs, digests, and time anchors in stored observations; avoid derived fields.
|
||||
3. **Deterministic replay**: ensure repeated imports of the same bundle produce identical documents; handle supersedes and delta bundles gracefully.
|
||||
4. **Offline readiness**: no external network calls; provide clear errors for invalid or stale bundles.
|
||||
5. **Testing**: maintain mirror fixtures covering full/delta bundles, supersedes chains, and failure cases.
|
||||
6. **Documentation**: coordinate updates to mirror connector docs and release notes when behaviour or configuration changes.
|
||||
@@ -1,25 +1,36 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
ASP.NET Minimal API surface for Excititor ingest, provider administration, reconciliation, export, and verification flows.
|
||||
## Scope
|
||||
- Program bootstrap, DI wiring for connectors/normalizers/export/attestation/policy/storage.
|
||||
- HTTP endpoints `/excititor/*` with authentication, authorization scopes, request validation, and deterministic responses.
|
||||
- Job orchestration bridges for Worker hand-off (when co-hosted) and offline-friendly configuration.
|
||||
- Observability (structured logs, metrics, tracing) aligned with StellaOps conventions.
|
||||
## Participants
|
||||
- StellaOps.Cli sends `excititor` verbs to this service via token-authenticated HTTPS.
|
||||
- Worker receives scheduled jobs and uses shared infrastructure via common DI extensions.
|
||||
- Authority service provides tokens; WebService enforces scopes before executing operations.
|
||||
## Interfaces & contracts
|
||||
- DTOs for ingest/export requests, run metadata, provider management.
|
||||
- Background job interfaces for ingest/resume/reconcile triggering.
|
||||
- Health/status endpoints exposing pull/export history and current policy revision.
|
||||
## In/Out of scope
|
||||
In: HTTP hosting, request orchestration, DI composition, auth/authorization, logging.
|
||||
Out: long-running ingestion loops (Worker), export rendering (Export module), connector implementations.
|
||||
## Observability & security expectations
|
||||
- Enforce bearer token scopes, enforce audit logging (request/response correlation IDs, provider IDs).
|
||||
- Emit structured events for ingest runs, export invocations, attestation references.
|
||||
- Provide built-in counters/histograms for latency and throughput.
|
||||
## Tests
|
||||
- Minimal API contract/unit tests and integration harness will live in `../StellaOps.Excititor.WebService.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
ASP.NET Minimal API surface for Excititor ingest, provider administration, reconciliation, export, and verification flows.
|
||||
## Scope
|
||||
- Program bootstrap, DI wiring for connectors/normalizers/export/attestation/policy/storage.
|
||||
- HTTP endpoints `/excititor/*` with authentication, authorization scopes, request validation, and deterministic responses.
|
||||
- Job orchestration bridges for Worker hand-off (when co-hosted) and offline-friendly configuration.
|
||||
- Observability (structured logs, metrics, tracing) aligned with StellaOps conventions.
|
||||
## Participants
|
||||
- StellaOps.Cli sends `excititor` verbs to this service via token-authenticated HTTPS.
|
||||
- Worker receives scheduled jobs and uses shared infrastructure via common DI extensions.
|
||||
- Authority service provides tokens; WebService enforces scopes before executing operations.
|
||||
## Interfaces & contracts
|
||||
- DTOs for ingest/export requests, run metadata, provider management.
|
||||
- Background job interfaces for ingest/resume/reconcile triggering.
|
||||
- Health/status endpoints exposing pull/export history and current policy revision.
|
||||
## In/Out of scope
|
||||
In: HTTP hosting, request orchestration, DI composition, auth/authorization, logging.
|
||||
Out: long-running ingestion loops (Worker), export rendering (Export module), connector implementations.
|
||||
## Observability & security expectations
|
||||
- Enforce bearer token scopes, enforce audit logging (request/response correlation IDs, provider IDs).
|
||||
- Emit structured events for ingest runs, export invocations, attestation references.
|
||||
- Provide built-in counters/histograms for latency and throughput.
|
||||
## Tests
|
||||
- Minimal API contract/unit tests and integration harness will live in `../StellaOps.Excititor.WebService.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,23 +1,34 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Background processing host coordinating scheduled pulls, retries, reconciliation, verification, and cache maintenance for Excititor.
|
||||
## Scope
|
||||
- Hosted service (Worker Service) wiring timers/queues for provider pulls and reconciliation cycles.
|
||||
- Resume token management, retry policies, and failure quarantines for connectors.
|
||||
- Re-verification of stored attestations and cache garbage collection routines.
|
||||
- Operational metrics and structured logging for offline-friendly monitoring.
|
||||
## Participants
|
||||
- Triggered by WebService job requests or internal schedules to run connector pulls.
|
||||
- Collaborates with Storage.Mongo repositories and Attestation verification utilities.
|
||||
- Emits telemetry consumed by observability stack and CLI status queries.
|
||||
## Interfaces & contracts
|
||||
- Scheduler abstractions, provider run controllers, retry/backoff strategies, and queue processors.
|
||||
- Hooks for policy revision changes and cache GC thresholds.
|
||||
## In/Out of scope
|
||||
In: background orchestration, job lifecycle management, observability for worker operations.
|
||||
Out: HTTP endpoint definitions, domain modeling, connector-specific parsing logic.
|
||||
## Observability & security expectations
|
||||
- Publish metrics for pull latency, failure counts, retry depth, cache size, and verification outcomes.
|
||||
- Log correlation IDs & provider IDs; avoid leaking secret config values.
|
||||
## Tests
|
||||
- Worker orchestration tests, timer controls, and retry behavior will live in `../StellaOps.Excititor.Worker.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
Background processing host coordinating scheduled pulls, retries, reconciliation, verification, and cache maintenance for Excititor.
|
||||
## Scope
|
||||
- Hosted service (Worker Service) wiring timers/queues for provider pulls and reconciliation cycles.
|
||||
- Resume token management, retry policies, and failure quarantines for connectors.
|
||||
- Re-verification of stored attestations and cache garbage collection routines.
|
||||
- Operational metrics and structured logging for offline-friendly monitoring.
|
||||
## Participants
|
||||
- Triggered by WebService job requests or internal schedules to run connector pulls.
|
||||
- Collaborates with Storage.Mongo repositories and Attestation verification utilities.
|
||||
- Emits telemetry consumed by observability stack and CLI status queries.
|
||||
## Interfaces & contracts
|
||||
- Scheduler abstractions, provider run controllers, retry/backoff strategies, and queue processors.
|
||||
- Hooks for policy revision changes and cache GC thresholds.
|
||||
## In/Out of scope
|
||||
In: background orchestration, job lifecycle management, observability for worker operations.
|
||||
Out: HTTP endpoint definitions, domain modeling, connector-specific parsing logic.
|
||||
## Observability & security expectations
|
||||
- Publish metrics for pull latency, failure counts, retry depth, cache size, and verification outcomes.
|
||||
- Log correlation IDs & provider IDs; avoid leaking secret config values.
|
||||
## Tests
|
||||
- Worker orchestration tests, timer controls, and retry behavior will live in `../StellaOps.Excititor.Worker.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,23 +1,34 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Builds and verifies in-toto/DSSE attestations for Excititor exports and integrates with Rekor v2 transparency logs.
|
||||
## Scope
|
||||
- Attestation envelope builders, signing workflows (keyless/keyed), and predicate model definitions.
|
||||
- Rekor v2 client implementation (submit, verify, poll inclusion) with retry/backoff policies.
|
||||
- Verification utilities reused by Worker for periodic revalidation.
|
||||
- Configuration bindings for signer identity, Rekor endpoints, and offline bundle operation.
|
||||
## Participants
|
||||
- Export module calls into this layer to generate attestations after export artifacts are produced.
|
||||
- WebService and Worker consume verification helpers to ensure stored envelopes remain valid.
|
||||
- CLI `excititor verify` leverages verification services through WebService endpoints.
|
||||
## Interfaces & contracts
|
||||
- `IExportAttestor`, `ITransparencyLogClient`, predicate DTOs, and verification result records.
|
||||
- Extension methods to register attestation services in DI across WebService/Worker.
|
||||
## In/Out of scope
|
||||
In: attestation creation, verification, Rekor integration, signer configuration.
|
||||
Out: export artifact generation, storage persistence, CLI interaction layers.
|
||||
## Observability & security expectations
|
||||
- Structured logs for signing/verification with envelope digest, Rekor URI, and latency; never log private keys.
|
||||
- Metrics for attestation successes/failures and Rekor submission durations.
|
||||
## Tests
|
||||
- Unit tests and integration stubs (with fake Rekor) will live in `../StellaOps.Excititor.Attestation.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
Builds and verifies in-toto/DSSE attestations for Excititor exports and integrates with Rekor v2 transparency logs.
|
||||
## Scope
|
||||
- Attestation envelope builders, signing workflows (keyless/keyed), and predicate model definitions.
|
||||
- Rekor v2 client implementation (submit, verify, poll inclusion) with retry/backoff policies.
|
||||
- Verification utilities reused by Worker for periodic revalidation.
|
||||
- Configuration bindings for signer identity, Rekor endpoints, and offline bundle operation.
|
||||
## Participants
|
||||
- Export module calls into this layer to generate attestations after export artifacts are produced.
|
||||
- WebService and Worker consume verification helpers to ensure stored envelopes remain valid.
|
||||
- CLI `excititor verify` leverages verification services through WebService endpoints.
|
||||
## Interfaces & contracts
|
||||
- `IExportAttestor`, `ITransparencyLogClient`, predicate DTOs, and verification result records.
|
||||
- Extension methods to register attestation services in DI across WebService/Worker.
|
||||
## In/Out of scope
|
||||
In: attestation creation, verification, Rekor integration, signer configuration.
|
||||
Out: export artifact generation, storage persistence, CLI interaction layers.
|
||||
## Observability & security expectations
|
||||
- Structured logs for signing/verification with envelope digest, Rekor URI, and latency; never log private keys.
|
||||
- Metrics for attestation successes/failures and Rekor submission durations.
|
||||
## Tests
|
||||
- Unit tests and integration stubs (with fake Rekor) will live in `../StellaOps.Excititor.Attestation.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,22 +1,33 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Defines shared connector infrastructure for Excititor, including base contexts, result contracts, configuration binding, and helper utilities reused by all connector plug-ins.
|
||||
## Scope
|
||||
- `IVexConnector` context implementation, raw store helpers, verification hooks, and telemetry utilities.
|
||||
- Configuration primitives (YAML parsing, secrets handling guidelines) and options validation.
|
||||
- Connector lifecycle helpers for retries, paging, `.well-known` discovery, and resume markers.
|
||||
- Documentation for connector packaging, plugin manifest metadata, and DI registration (see `docs/dev/30_EXCITITOR_CONNECTOR_GUIDE.md` and `docs/dev/templates/excititor-connector/`).
|
||||
## Participants
|
||||
- All Excititor connector projects reference this module to obtain base classes and context services.
|
||||
- WebService/Worker instantiate connectors via plugin loader leveraging abstractions defined here.
|
||||
## Interfaces & contracts
|
||||
- Connector context, result, and telemetry interfaces; `VexConnectorDescriptor`, `VexConnectorBase`, options binder/validators, authentication helpers.
|
||||
- Utility classes for HTTP clients, throttling, and deterministic logging.
|
||||
## In/Out of scope
|
||||
In: shared abstractions, helper utilities, configuration binding, documentation for connector authors.
|
||||
Out: provider-specific logic (implemented in individual connector modules), storage persistence, HTTP host code.
|
||||
## Observability & security expectations
|
||||
- Provide structured logging helpers, correlation IDs, and metrics instrumentation toggles for connectors.
|
||||
- Enforce redaction of secrets in logs and config dumps.
|
||||
## Tests
|
||||
- Abstraction/unit tests will live in `../StellaOps.Excititor.Connectors.Abstractions.Tests`, covering default behaviors and sample harness.
|
||||
# AGENTS
|
||||
## Role
|
||||
Defines shared connector infrastructure for Excititor, including base contexts, result contracts, configuration binding, and helper utilities reused by all connector plug-ins.
|
||||
## Scope
|
||||
- `IVexConnector` context implementation, raw store helpers, verification hooks, and telemetry utilities.
|
||||
- Configuration primitives (YAML parsing, secrets handling guidelines) and options validation.
|
||||
- Connector lifecycle helpers for retries, paging, `.well-known` discovery, and resume markers.
|
||||
- Documentation for connector packaging, plugin manifest metadata, and DI registration (see `docs/dev/30_EXCITITOR_CONNECTOR_GUIDE.md` and `docs/dev/templates/excititor-connector/`).
|
||||
## Participants
|
||||
- All Excititor connector projects reference this module to obtain base classes and context services.
|
||||
- WebService/Worker instantiate connectors via plugin loader leveraging abstractions defined here.
|
||||
## Interfaces & contracts
|
||||
- Connector context, result, and telemetry interfaces; `VexConnectorDescriptor`, `VexConnectorBase`, options binder/validators, authentication helpers.
|
||||
- Utility classes for HTTP clients, throttling, and deterministic logging.
|
||||
## In/Out of scope
|
||||
In: shared abstractions, helper utilities, configuration binding, documentation for connector authors.
|
||||
Out: provider-specific logic (implemented in individual connector modules), storage persistence, HTTP host code.
|
||||
## Observability & security expectations
|
||||
- Provide structured logging helpers, correlation IDs, and metrics instrumentation toggles for connectors.
|
||||
- Enforce redaction of secrets in logs and config dumps.
|
||||
## Tests
|
||||
- Abstraction/unit tests will live in `../StellaOps.Excititor.Connectors.Abstractions.Tests`, covering default behaviors and sample harness.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,23 +1,34 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector responsible for ingesting Cisco CSAF VEX advisories and handing raw documents to normalizers with Cisco-specific metadata.
|
||||
## Scope
|
||||
- Discovery of Cisco CSAF collection endpoints, authentication (when required), and pagination routines.
|
||||
- HTTP retries/backoff, checksum verification, and document deduplication before storage.
|
||||
- Mapping Cisco advisory identifiers, product hierarchies, and severity hints into connector metadata.
|
||||
- Surfacing provider trust configuration aligned with policy expectations.
|
||||
## Participants
|
||||
- Worker drives scheduled pulls; WebService may trigger manual runs.
|
||||
- CSAF normalizer consumes raw documents to emit claims.
|
||||
- Policy module references connector trust hints (e.g., Cisco signing identities).
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector` using shared abstractions for HTTP/resume handling.
|
||||
- Provides options for API tokens, rate limits, and concurrency.
|
||||
## In/Out of scope
|
||||
In: data fetching, provider metadata, retry controls, raw document persistence.
|
||||
Out: normalization/export, attestation, Mongo wiring (handled in other modules).
|
||||
## Observability & security expectations
|
||||
- Log fetch batches with document counts/durations; mask credentials.
|
||||
- Emit metrics for rate-limit hits, retries, and quarantine events.
|
||||
## Tests
|
||||
- Unit tests plus HTTP harness fixtures will live in `../StellaOps.Excititor.Connectors.Cisco.CSAF.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector responsible for ingesting Cisco CSAF VEX advisories and handing raw documents to normalizers with Cisco-specific metadata.
|
||||
## Scope
|
||||
- Discovery of Cisco CSAF collection endpoints, authentication (when required), and pagination routines.
|
||||
- HTTP retries/backoff, checksum verification, and document deduplication before storage.
|
||||
- Mapping Cisco advisory identifiers, product hierarchies, and severity hints into connector metadata.
|
||||
- Surfacing provider trust configuration aligned with policy expectations.
|
||||
## Participants
|
||||
- Worker drives scheduled pulls; WebService may trigger manual runs.
|
||||
- CSAF normalizer consumes raw documents to emit claims.
|
||||
- Policy module references connector trust hints (e.g., Cisco signing identities).
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector` using shared abstractions for HTTP/resume handling.
|
||||
- Provides options for API tokens, rate limits, and concurrency.
|
||||
## In/Out of scope
|
||||
In: data fetching, provider metadata, retry controls, raw document persistence.
|
||||
Out: normalization/export, attestation, Mongo wiring (handled in other modules).
|
||||
## Observability & security expectations
|
||||
- Log fetch batches with document counts/durations; mask credentials.
|
||||
- Emit metrics for rate-limit hits, retries, and quarantine events.
|
||||
## Tests
|
||||
- Unit tests plus HTTP harness fixtures will live in `../StellaOps.Excititor.Connectors.Cisco.CSAF.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,23 +1,34 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector for Microsoft Security Response Center (MSRC) CSAF advisories, handling authenticated downloads, throttling, and raw document persistence.
|
||||
## Scope
|
||||
- MSRC API onboarding (AAD client credentials), metadata discovery, and CSAF listing retrieval.
|
||||
- Download pipeline with retry/backoff, checksum validation, and document deduplication.
|
||||
- Mapping MSRC-specific identifiers (CVE, ADV, KB) and remediation guidance into connector metadata.
|
||||
- Emitting trust metadata (AAD issuer, signing certificates) for policy weighting.
|
||||
## Participants
|
||||
- Worker schedules MSRC pulls honoring rate limits; WebService may trigger manual runs for urgent updates.
|
||||
- CSAF normalizer processes retrieved documents into claims.
|
||||
- Policy subsystem references connector trust hints for consensus scoring.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector`, requires configuration options for tenant/client/secret or managed identity.
|
||||
- Uses shared HTTP helpers, resume markers, and telemetry from Abstractions module.
|
||||
## In/Out of scope
|
||||
In: authenticated fetching, raw document storage, metadata mapping, retry logic.
|
||||
Out: normalization/export, attestation, storage implementations (handled elsewhere).
|
||||
## Observability & security expectations
|
||||
- Log request batches, rate-limit responses, and token refresh events without leaking secrets.
|
||||
- Track metrics for documents fetched, retries, and failure categories.
|
||||
## Tests
|
||||
- Connector tests with mocked MSRC endpoints and AAD token flow will live in `../StellaOps.Excititor.Connectors.MSRC.CSAF.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector for Microsoft Security Response Center (MSRC) CSAF advisories, handling authenticated downloads, throttling, and raw document persistence.
|
||||
## Scope
|
||||
- MSRC API onboarding (AAD client credentials), metadata discovery, and CSAF listing retrieval.
|
||||
- Download pipeline with retry/backoff, checksum validation, and document deduplication.
|
||||
- Mapping MSRC-specific identifiers (CVE, ADV, KB) and remediation guidance into connector metadata.
|
||||
- Emitting trust metadata (AAD issuer, signing certificates) for policy weighting.
|
||||
## Participants
|
||||
- Worker schedules MSRC pulls honoring rate limits; WebService may trigger manual runs for urgent updates.
|
||||
- CSAF normalizer processes retrieved documents into claims.
|
||||
- Policy subsystem references connector trust hints for consensus scoring.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector`, requires configuration options for tenant/client/secret or managed identity.
|
||||
- Uses shared HTTP helpers, resume markers, and telemetry from Abstractions module.
|
||||
## In/Out of scope
|
||||
In: authenticated fetching, raw document storage, metadata mapping, retry logic.
|
||||
Out: normalization/export, attestation, storage implementations (handled elsewhere).
|
||||
## Observability & security expectations
|
||||
- Log request batches, rate-limit responses, and token refresh events without leaking secrets.
|
||||
- Track metrics for documents fetched, retries, and failure categories.
|
||||
## Tests
|
||||
- Connector tests with mocked MSRC endpoints and AAD token flow will live in `../StellaOps.Excititor.Connectors.MSRC.CSAF.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,23 +1,34 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector for OCI registry OpenVEX attestations, discovering images, downloading attestations, and projecting statements into raw storage.
|
||||
## Scope
|
||||
- OCI registry discovery, authentication (cosign OIDC/key), and ref resolution for provided image digests/tags.
|
||||
- Fetching DSSE envelopes, verifying signatures (delegated to Attestation module), and persisting raw statements.
|
||||
- Mapping OCI manifest metadata (repository, digest, subject) to connector provenance.
|
||||
- Managing offline bundles that seed attestations without registry access.
|
||||
## Participants
|
||||
- Worker schedules polls for configured registries/images; WebService supports manual refresh.
|
||||
- OpenVEX normalizer consumes statements to create claims.
|
||||
- Attestation module is reused to verify upstream envelopes prior to storage.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector` with options for image list, auth, parallelism, and offline file seeds.
|
||||
- Utilizes shared abstractions for retries, telemetry, and resume markers.
|
||||
## In/Out of scope
|
||||
In: OCI interaction, attestation retrieval, verification trigger, raw persistence.
|
||||
Out: normalization/export, policy evaluation, storage implementation.
|
||||
## Observability & security expectations
|
||||
- Log image references, attestation counts, verification outcomes; redact credentials.
|
||||
- Emit metrics for attestation reuse ratio, verification duration, and failures.
|
||||
## Tests
|
||||
- Connector tests with mock OCI registry/attestation responses will live in `../StellaOps.Excititor.Connectors.OCI.OpenVEX.Attest.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector for OCI registry OpenVEX attestations, discovering images, downloading attestations, and projecting statements into raw storage.
|
||||
## Scope
|
||||
- OCI registry discovery, authentication (cosign OIDC/key), and ref resolution for provided image digests/tags.
|
||||
- Fetching DSSE envelopes, verifying signatures (delegated to Attestation module), and persisting raw statements.
|
||||
- Mapping OCI manifest metadata (repository, digest, subject) to connector provenance.
|
||||
- Managing offline bundles that seed attestations without registry access.
|
||||
## Participants
|
||||
- Worker schedules polls for configured registries/images; WebService supports manual refresh.
|
||||
- OpenVEX normalizer consumes statements to create claims.
|
||||
- Attestation module is reused to verify upstream envelopes prior to storage.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector` with options for image list, auth, parallelism, and offline file seeds.
|
||||
- Utilizes shared abstractions for retries, telemetry, and resume markers.
|
||||
## In/Out of scope
|
||||
In: OCI interaction, attestation retrieval, verification trigger, raw persistence.
|
||||
Out: normalization/export, policy evaluation, storage implementation.
|
||||
## Observability & security expectations
|
||||
- Log image references, attestation counts, verification outcomes; redact credentials.
|
||||
- Emit metrics for attestation reuse ratio, verification duration, and failures.
|
||||
## Tests
|
||||
- Connector tests with mock OCI registry/attestation responses will live in `../StellaOps.Excititor.Connectors.OCI.OpenVEX.Attest.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,23 +1,34 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector for Oracle CSAF advisories, including CPU and other bulletin releases, projecting documents into raw storage for normalization.
|
||||
## Scope
|
||||
- Discovery of Oracle CSAF catalogue, navigation of quarterly CPU bundles, and delta detection.
|
||||
- HTTP fetch with retry/backoff, checksum validation, and deduplication across revisions.
|
||||
- Mapping Oracle advisory metadata (CPU ID, component families) into connector context.
|
||||
- Publishing trust metadata (PGP keys/cosign options) aligned with policy expectations.
|
||||
## Participants
|
||||
- Worker orchestrates regular pulls respecting Oracle publication cadence; WebService offers manual triggers.
|
||||
- CSAF normalizer processes raw documents to claims.
|
||||
- Policy engine leverages trust metadata and provenance hints.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector` using shared abstractions for HTTP/resume and telemetry.
|
||||
- Configuration options for CPU schedule, credentials (if required), and offline snapshot ingestion.
|
||||
## In/Out of scope
|
||||
In: fetching, metadata mapping, raw persistence, trust hints.
|
||||
Out: normalization, storage internals, export/attestation flows.
|
||||
## Observability & security expectations
|
||||
- Log CPU release windows, document counts, and fetch durations; redact any secrets.
|
||||
- Emit metrics for deduped vs new documents and quarantine rates.
|
||||
## Tests
|
||||
- Harness tests with mocked Oracle catalogues will live in `../StellaOps.Excititor.Connectors.Oracle.CSAF.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector for Oracle CSAF advisories, including CPU and other bulletin releases, projecting documents into raw storage for normalization.
|
||||
## Scope
|
||||
- Discovery of Oracle CSAF catalogue, navigation of quarterly CPU bundles, and delta detection.
|
||||
- HTTP fetch with retry/backoff, checksum validation, and deduplication across revisions.
|
||||
- Mapping Oracle advisory metadata (CPU ID, component families) into connector context.
|
||||
- Publishing trust metadata (PGP keys/cosign options) aligned with policy expectations.
|
||||
## Participants
|
||||
- Worker orchestrates regular pulls respecting Oracle publication cadence; WebService offers manual triggers.
|
||||
- CSAF normalizer processes raw documents to claims.
|
||||
- Policy engine leverages trust metadata and provenance hints.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector` using shared abstractions for HTTP/resume and telemetry.
|
||||
- Configuration options for CPU schedule, credentials (if required), and offline snapshot ingestion.
|
||||
## In/Out of scope
|
||||
In: fetching, metadata mapping, raw persistence, trust hints.
|
||||
Out: normalization, storage internals, export/attestation flows.
|
||||
## Observability & security expectations
|
||||
- Log CPU release windows, document counts, and fetch durations; redact any secrets.
|
||||
- Emit metrics for deduped vs new documents and quarantine rates.
|
||||
## Tests
|
||||
- Harness tests with mocked Oracle catalogues will live in `../StellaOps.Excititor.Connectors.Oracle.CSAF.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,25 +1,36 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector for Red Hat CSAF VEX feeds, fetching provider metadata, CSAF documents, and projecting them into raw storage for normalization.
|
||||
## Scope
|
||||
- Discovery via `/.well-known/csaf/provider-metadata.json`, scheduling windows, and ETag-aware HTTP fetches.
|
||||
- `RedHatProviderMetadataLoader` handles `.well-known` metadata with caching, schema validation, and offline snapshots.
|
||||
- `RedHatCsafConnector` consumes ROLIE feeds to fetch incremental CSAF documents, honours `context.Since`, and streams raw advisories to storage.
|
||||
- Mapping Red Hat CSAF specifics (product tree aliases, RHSA identifiers, revision history) into raw documents.
|
||||
- Emitting structured telemetry and resume markers for incremental pulls.
|
||||
- Supplying Red Hat-specific trust overrides and provenance hints to normalization.
|
||||
## Participants
|
||||
- Worker schedules pulls using this connector; WebService triggers ad-hoc runs.
|
||||
- CSAF normalizer consumes fetched documents to produce claims.
|
||||
- Policy/consensus rely on Red Hat trust metadata captured here.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector` with Red Hat-specific options (parallelism, token auth if configured).
|
||||
- Uses abstractions from `StellaOps.Excititor.Connectors.Abstractions` for HTTP/resume helpers.
|
||||
## In/Out of scope
|
||||
In: data acquisition, HTTP retries, raw document persistence, provider metadata population.
|
||||
Out: normalization, storage internals, attestation, general connector abstractions (covered elsewhere).
|
||||
## Observability & security expectations
|
||||
- Log provider metadata URL, revision ids, fetch durations; redact tokens.
|
||||
- Emit counters for documents fetched, skipped (304), quarantined.
|
||||
## Tests
|
||||
- Connector harness tests (mock HTTP) and resume regression cases will live in `../StellaOps.Excititor.Connectors.RedHat.CSAF.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector for Red Hat CSAF VEX feeds, fetching provider metadata, CSAF documents, and projecting them into raw storage for normalization.
|
||||
## Scope
|
||||
- Discovery via `/.well-known/csaf/provider-metadata.json`, scheduling windows, and ETag-aware HTTP fetches.
|
||||
- `RedHatProviderMetadataLoader` handles `.well-known` metadata with caching, schema validation, and offline snapshots.
|
||||
- `RedHatCsafConnector` consumes ROLIE feeds to fetch incremental CSAF documents, honours `context.Since`, and streams raw advisories to storage.
|
||||
- Mapping Red Hat CSAF specifics (product tree aliases, RHSA identifiers, revision history) into raw documents.
|
||||
- Emitting structured telemetry and resume markers for incremental pulls.
|
||||
- Supplying Red Hat-specific trust overrides and provenance hints to normalization.
|
||||
## Participants
|
||||
- Worker schedules pulls using this connector; WebService triggers ad-hoc runs.
|
||||
- CSAF normalizer consumes fetched documents to produce claims.
|
||||
- Policy/consensus rely on Red Hat trust metadata captured here.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector` with Red Hat-specific options (parallelism, token auth if configured).
|
||||
- Uses abstractions from `StellaOps.Excititor.Connectors.Abstractions` for HTTP/resume helpers.
|
||||
## In/Out of scope
|
||||
In: data acquisition, HTTP retries, raw document persistence, provider metadata population.
|
||||
Out: normalization, storage internals, attestation, general connector abstractions (covered elsewhere).
|
||||
## Observability & security expectations
|
||||
- Log provider metadata URL, revision ids, fetch durations; redact tokens.
|
||||
- Emit counters for documents fetched, skipped (304), quarantined.
|
||||
## Tests
|
||||
- Connector harness tests (mock HTTP) and resume regression cases will live in `../StellaOps.Excititor.Connectors.RedHat.CSAF.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,23 +1,34 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector targeting SUSE Rancher VEX Hub feeds, ingesting hub events and translating them into raw documents for normalization.
|
||||
## Scope
|
||||
- Hub discovery, authentication, and subscription handling for Rancher VEX updates.
|
||||
- HTTP/WebSocket (if provided) ingestion, checkpoint tracking, and deduplication.
|
||||
- Mapping Rancher-specific status fields and product identifiers into connector metadata.
|
||||
- Integration with offline bundles to allow snapshot imports.
|
||||
## Participants
|
||||
- Worker manages scheduled syncs using this connector; WebService can trigger manual reconcile pulls.
|
||||
- Normalizers convert retrieved documents via CSAF/OpenVEX workflows depending on payload.
|
||||
- Policy module uses trust metadata produced here for weight evaluation.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector` with options for hub URL, credentials, and poll intervals.
|
||||
- Uses shared abstractions for resume markers and telemetry.
|
||||
## In/Out of scope
|
||||
In: hub connectivity, message processing, raw persistence, provider metadata.
|
||||
Out: normalization/export tasks, storage layer implementation, attestation.
|
||||
## Observability & security expectations
|
||||
- Log subscription IDs, batch sizes, and checkpoint updates while redacting secrets.
|
||||
- Emit metrics for messages processed, lag, and retries.
|
||||
## Tests
|
||||
- Connector harness tests with simulated hub responses will live in `../StellaOps.Excititor.Connectors.SUSE.RancherVEXHub.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector targeting SUSE Rancher VEX Hub feeds, ingesting hub events and translating them into raw documents for normalization.
|
||||
## Scope
|
||||
- Hub discovery, authentication, and subscription handling for Rancher VEX updates.
|
||||
- HTTP/WebSocket (if provided) ingestion, checkpoint tracking, and deduplication.
|
||||
- Mapping Rancher-specific status fields and product identifiers into connector metadata.
|
||||
- Integration with offline bundles to allow snapshot imports.
|
||||
## Participants
|
||||
- Worker manages scheduled syncs using this connector; WebService can trigger manual reconcile pulls.
|
||||
- Normalizers convert retrieved documents via CSAF/OpenVEX workflows depending on payload.
|
||||
- Policy module uses trust metadata produced here for weight evaluation.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector` with options for hub URL, credentials, and poll intervals.
|
||||
- Uses shared abstractions for resume markers and telemetry.
|
||||
## In/Out of scope
|
||||
In: hub connectivity, message processing, raw persistence, provider metadata.
|
||||
Out: normalization/export tasks, storage layer implementation, attestation.
|
||||
## Observability & security expectations
|
||||
- Log subscription IDs, batch sizes, and checkpoint updates while redacting secrets.
|
||||
- Emit metrics for messages processed, lag, and retries.
|
||||
## Tests
|
||||
- Connector harness tests with simulated hub responses will live in `../StellaOps.Excititor.Connectors.SUSE.RancherVEXHub.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,23 +1,34 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector for Ubuntu CSAF advisories (USN VEX data), managing discovery, incremental pulls, and raw document persistence.
|
||||
## Scope
|
||||
- Ubuntu CSAF metadata discovery, release channel awareness, and pagination handling.
|
||||
- HTTP client with retries/backoff, checksum validation, and deduplication.
|
||||
- Mapping Ubuntu identifiers (USN numbers, package metadata) into connector metadata for downstream policy.
|
||||
- Emitting trust configuration (GPG fingerprints, cosign options) for policy weighting.
|
||||
## Participants
|
||||
- Worker schedules regular pulls; WebService can initiate manual ingest/resume.
|
||||
- CSAF normalizer converts raw documents into claims.
|
||||
- Policy engine leverages connector-supplied trust metadata.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector`, using shared abstractions for HTTP/resume markers and telemetry.
|
||||
- Provides options for release channels (stable/LTS) and offline seed bundles.
|
||||
## In/Out of scope
|
||||
In: data fetching, metadata mapping, raw persistence, trust hints.
|
||||
Out: normalization/export, storage internals, attestation.
|
||||
## Observability & security expectations
|
||||
- Log release window fetch metrics, rate limits, and deduplication stats; mask secrets.
|
||||
- Emit counters for newly ingested vs unchanged USNs and quota usage.
|
||||
## Tests
|
||||
- Connector tests with mocked Ubuntu CSAF endpoints will live in `../StellaOps.Excititor.Connectors.Ubuntu.CSAF.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
Connector for Ubuntu CSAF advisories (USN VEX data), managing discovery, incremental pulls, and raw document persistence.
|
||||
## Scope
|
||||
- Ubuntu CSAF metadata discovery, release channel awareness, and pagination handling.
|
||||
- HTTP client with retries/backoff, checksum validation, and deduplication.
|
||||
- Mapping Ubuntu identifiers (USN numbers, package metadata) into connector metadata for downstream policy.
|
||||
- Emitting trust configuration (GPG fingerprints, cosign options) for policy weighting.
|
||||
## Participants
|
||||
- Worker schedules regular pulls; WebService can initiate manual ingest/resume.
|
||||
- CSAF normalizer converts raw documents into claims.
|
||||
- Policy engine leverages connector-supplied trust metadata.
|
||||
## Interfaces & contracts
|
||||
- Implements `IVexConnector`, using shared abstractions for HTTP/resume markers and telemetry.
|
||||
- Provides options for release channels (stable/LTS) and offline seed bundles.
|
||||
## In/Out of scope
|
||||
In: data fetching, metadata mapping, raw persistence, trust hints.
|
||||
Out: normalization/export, storage internals, attestation.
|
||||
## Observability & security expectations
|
||||
- Log release window fetch metrics, rate limits, and deduplication stats; mask secrets.
|
||||
- Emit counters for newly ingested vs unchanged USNs and quota usage.
|
||||
## Tests
|
||||
- Connector tests with mocked Ubuntu CSAF endpoints will live in `../StellaOps.Excititor.Connectors.Ubuntu.CSAF.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,26 +1,37 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Domain source of truth for VEX statements, consensus rollups, and trust policy orchestration across all Excititor services.
|
||||
## Scope
|
||||
- Records for raw document metadata, normalized claims, consensus projections, and export descriptors.
|
||||
- Policy + weighting engine that projects provider trust tiers into consensus status outcomes.
|
||||
- Connector, normalizer, export, and attestation contracts shared by WebService, Worker, and plug-ins.
|
||||
- Deterministic hashing utilities (query signatures, artifact digests, attestation subjects).
|
||||
## Participants
|
||||
- Excititor WebService uses the models to persist ingress/egress payloads and to perform consensus mutations.
|
||||
- Excititor Worker executes reconciliation and verification routines using policy helpers defined here.
|
||||
- Export/Attestation modules depend on record definitions for envelopes and manifest payloads.
|
||||
## Interfaces & contracts
|
||||
- `IVexConnector`, `INormalizer`, `IExportEngine`, `ITransparencyLogClient`, `IArtifactStore`, and policy abstractions for consensus resolution.
|
||||
- Value objects for provider metadata, VexClaim, VexConsensusEntry, ExportManifest, QuerySignature.
|
||||
- Deterministic comparer utilities and stable JSON serialization helpers for tests and cache keys.
|
||||
## In/Out of scope
|
||||
In: domain invariants, policy evaluation helpers, deterministic serialization, shared abstractions.
|
||||
Out: Mongo persistence implementations, HTTP endpoints, background scheduling, concrete connector logic.
|
||||
## Observability & security expectations
|
||||
- Avoid secret handling; provide structured logging extension methods for consensus decisions.
|
||||
- Emit correlation identifiers and query signatures without embedding PII.
|
||||
- Ensure deterministic logging order to keep reproducibility guarantees intact.
|
||||
## Tests
|
||||
- Unit coverage lives in `../StellaOps.Excititor.Core.Tests` (to be scaffolded) focusing on consensus, policy gates, and serialization determinism.
|
||||
- Golden fixtures must rely on canonical JSON snapshots produced via stable serializers.
|
||||
# AGENTS
|
||||
## Role
|
||||
Domain source of truth for VEX statements, consensus rollups, and trust policy orchestration across all Excititor services.
|
||||
## Scope
|
||||
- Records for raw document metadata, normalized claims, consensus projections, and export descriptors.
|
||||
- Policy + weighting engine that projects provider trust tiers into consensus status outcomes.
|
||||
- Connector, normalizer, export, and attestation contracts shared by WebService, Worker, and plug-ins.
|
||||
- Deterministic hashing utilities (query signatures, artifact digests, attestation subjects).
|
||||
## Participants
|
||||
- Excititor WebService uses the models to persist ingress/egress payloads and to perform consensus mutations.
|
||||
- Excititor Worker executes reconciliation and verification routines using policy helpers defined here.
|
||||
- Export/Attestation modules depend on record definitions for envelopes and manifest payloads.
|
||||
## Interfaces & contracts
|
||||
- `IVexConnector`, `INormalizer`, `IExportEngine`, `ITransparencyLogClient`, `IArtifactStore`, and policy abstractions for consensus resolution.
|
||||
- Value objects for provider metadata, VexClaim, VexConsensusEntry, ExportManifest, QuerySignature.
|
||||
- Deterministic comparer utilities and stable JSON serialization helpers for tests and cache keys.
|
||||
## In/Out of scope
|
||||
In: domain invariants, policy evaluation helpers, deterministic serialization, shared abstractions.
|
||||
Out: Mongo persistence implementations, HTTP endpoints, background scheduling, concrete connector logic.
|
||||
## Observability & security expectations
|
||||
- Avoid secret handling; provide structured logging extension methods for consensus decisions.
|
||||
- Emit correlation identifiers and query signatures without embedding PII.
|
||||
- Ensure deterministic logging order to keep reproducibility guarantees intact.
|
||||
## Tests
|
||||
- Unit coverage lives in `../StellaOps.Excititor.Core.Tests` (to be scaffolded) focusing on consensus, policy gates, and serialization determinism.
|
||||
- Golden fixtures must rely on canonical JSON snapshots produced via stable serializers.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,23 +1,34 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Produces deterministic VEX export artifacts, coordinates cache lookups, and bridges artifact storage with attestation generation.
|
||||
## Scope
|
||||
- Export orchestration pipeline: query signature resolution, cache lookup, snapshot building, attestation handoff.
|
||||
- Format-neutral builder interfaces consumed by format-specific plug-ins.
|
||||
- Artifact store abstraction wiring (S3/MinIO/filesystem) with offline-friendly packaging.
|
||||
- Export metrics/logging and deterministic manifest emission.
|
||||
## Participants
|
||||
- WebService invokes the export engine to service `/excititor/export` requests.
|
||||
- Attestation module receives built artifacts through this layer for signing.
|
||||
- Worker reuses caching and artifact utilities for scheduled exports and GC routines.
|
||||
## Interfaces & contracts
|
||||
- `IExportEngine`, `IExportSnapshotBuilder`, cache provider interfaces, and artifact store adapters.
|
||||
- Hook points for format plug-ins (JSON, JSONL, OpenVEX, CSAF, ZIP bundle).
|
||||
## In/Out of scope
|
||||
In: orchestration, caching, artifact store interactions, manifest metadata.
|
||||
Out: format-specific serialization (lives in Formats.*), policy evaluation (Policy), HTTP presentation (WebService).
|
||||
## Observability & security expectations
|
||||
- Emit cache hit/miss counters, export durations, artifact sizes, and attestation timing logs.
|
||||
- Ensure no sensitive tokens/URIs are logged.
|
||||
## Tests
|
||||
- Engine orchestration tests, cache behavior, and artifact lifecycle coverage will live in `../StellaOps.Excititor.Export.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
Produces deterministic VEX export artifacts, coordinates cache lookups, and bridges artifact storage with attestation generation.
|
||||
## Scope
|
||||
- Export orchestration pipeline: query signature resolution, cache lookup, snapshot building, attestation handoff.
|
||||
- Format-neutral builder interfaces consumed by format-specific plug-ins.
|
||||
- Artifact store abstraction wiring (S3/MinIO/filesystem) with offline-friendly packaging.
|
||||
- Export metrics/logging and deterministic manifest emission.
|
||||
## Participants
|
||||
- WebService invokes the export engine to service `/excititor/export` requests.
|
||||
- Attestation module receives built artifacts through this layer for signing.
|
||||
- Worker reuses caching and artifact utilities for scheduled exports and GC routines.
|
||||
## Interfaces & contracts
|
||||
- `IExportEngine`, `IExportSnapshotBuilder`, cache provider interfaces, and artifact store adapters.
|
||||
- Hook points for format plug-ins (JSON, JSONL, OpenVEX, CSAF, ZIP bundle).
|
||||
## In/Out of scope
|
||||
In: orchestration, caching, artifact store interactions, manifest metadata.
|
||||
Out: format-specific serialization (lives in Formats.*), policy evaluation (Policy), HTTP presentation (WebService).
|
||||
## Observability & security expectations
|
||||
- Emit cache hit/miss counters, export durations, artifact sizes, and attestation timing logs.
|
||||
- Ensure no sensitive tokens/URIs are logged.
|
||||
## Tests
|
||||
- Engine orchestration tests, cache behavior, and artifact lifecycle coverage will live in `../StellaOps.Excititor.Export.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,23 +1,34 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Normalize CSAF VEX profile documents into Excititor claims and provide CSAF export adapters.
|
||||
## Scope
|
||||
- CSAF ingestion helpers: provider metadata parsing, document revision handling, vulnerability/action mappings.
|
||||
- Normalizer implementation fulfilling `INormalizer` for CSAF sources (Red Hat, Cisco, SUSE, MSRC, Oracle, Ubuntu).
|
||||
- Export adapters producing CSAF-compliant output slices from consensus data.
|
||||
- Schema/version compatibility checks (CSAF 2.0 profile validation).
|
||||
## Participants
|
||||
- Connectors deliver raw CSAF documents to this module for normalization.
|
||||
- Export module leverages adapters when producing CSAF exports.
|
||||
- Policy engine consumes normalized justification/status fields for gating.
|
||||
## Interfaces & contracts
|
||||
- Parser/normalizer classes, helper utilities for `product_tree`, `vulnerabilities`, and `notes`.
|
||||
- Export writer interfaces for per-provider/per-product CSAF packaging.
|
||||
## In/Out of scope
|
||||
In: CSAF parsing/normalization/export, schema validation, mapping to canonical claims.
|
||||
Out: HTTP fetching (connectors), storage persistence, attestation logic.
|
||||
## Observability & security expectations
|
||||
- Emit structured diagnostics when CSAF documents fail schema validation, including source URI and revision.
|
||||
- Provide counters for normalization outcomes (status distribution, justification coverage).
|
||||
## Tests
|
||||
- Fixture-driven parsing/export tests will live in `../StellaOps.Excititor.Formats.CSAF.Tests` using real CSAF samples.
|
||||
# AGENTS
|
||||
## Role
|
||||
Normalize CSAF VEX profile documents into Excititor claims and provide CSAF export adapters.
|
||||
## Scope
|
||||
- CSAF ingestion helpers: provider metadata parsing, document revision handling, vulnerability/action mappings.
|
||||
- Normalizer implementation fulfilling `INormalizer` for CSAF sources (Red Hat, Cisco, SUSE, MSRC, Oracle, Ubuntu).
|
||||
- Export adapters producing CSAF-compliant output slices from consensus data.
|
||||
- Schema/version compatibility checks (CSAF 2.0 profile validation).
|
||||
## Participants
|
||||
- Connectors deliver raw CSAF documents to this module for normalization.
|
||||
- Export module leverages adapters when producing CSAF exports.
|
||||
- Policy engine consumes normalized justification/status fields for gating.
|
||||
## Interfaces & contracts
|
||||
- Parser/normalizer classes, helper utilities for `product_tree`, `vulnerabilities`, and `notes`.
|
||||
- Export writer interfaces for per-provider/per-product CSAF packaging.
|
||||
## In/Out of scope
|
||||
In: CSAF parsing/normalization/export, schema validation, mapping to canonical claims.
|
||||
Out: HTTP fetching (connectors), storage persistence, attestation logic.
|
||||
## Observability & security expectations
|
||||
- Emit structured diagnostics when CSAF documents fail schema validation, including source URI and revision.
|
||||
- Provide counters for normalization outcomes (status distribution, justification coverage).
|
||||
## Tests
|
||||
- Fixture-driven parsing/export tests will live in `../StellaOps.Excititor.Formats.CSAF.Tests` using real CSAF samples.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,22 +1,33 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Normalize CycloneDX VEX documents and expose serialization utilities for CycloneDX-based exports.
|
||||
## Scope
|
||||
- Parsing of CycloneDX VEX statements (`analysis.state`, `justification`, `impact`) into canonical claims.
|
||||
- Utilities to align SBOM references (components, services) with policy expectations.
|
||||
- Export builders that emit CycloneDX-compliant VEX bundles or augment existing SBOMs.
|
||||
- Validation against CycloneDX schema versions and namespace compatibility.
|
||||
## Participants
|
||||
- Connectors ingesting CycloneDX VEX or SBOM attestations send documents here for normalization.
|
||||
- Export module uses serializers to produce CycloneDX JSON/JSONL as requested.
|
||||
- Policy/consensus logic depends on status/justification mapping provided here.
|
||||
## Interfaces & contracts
|
||||
- Normalizer implementations, component reference mapping helpers, export serializers.
|
||||
- Schema validation adaptor for offline mode and fixture-driven testing.
|
||||
## In/Out of scope
|
||||
In: CycloneDX parsing, normalization, export writing, schema validation.
|
||||
Out: Connector transport, storage, attestation; these rely on other modules.
|
||||
## Observability & security expectations
|
||||
- Log schema mismatches with document digest and component references; avoid logging proprietary component details where possible.
|
||||
## Tests
|
||||
- Unit and fixture tests will live in `../StellaOps.Excititor.Formats.CycloneDX.Tests`, covering normalization and serialization determinism.
|
||||
# AGENTS
|
||||
## Role
|
||||
Normalize CycloneDX VEX documents and expose serialization utilities for CycloneDX-based exports.
|
||||
## Scope
|
||||
- Parsing of CycloneDX VEX statements (`analysis.state`, `justification`, `impact`) into canonical claims.
|
||||
- Utilities to align SBOM references (components, services) with policy expectations.
|
||||
- Export builders that emit CycloneDX-compliant VEX bundles or augment existing SBOMs.
|
||||
- Validation against CycloneDX schema versions and namespace compatibility.
|
||||
## Participants
|
||||
- Connectors ingesting CycloneDX VEX or SBOM attestations send documents here for normalization.
|
||||
- Export module uses serializers to produce CycloneDX JSON/JSONL as requested.
|
||||
- Policy/consensus logic depends on status/justification mapping provided here.
|
||||
## Interfaces & contracts
|
||||
- Normalizer implementations, component reference mapping helpers, export serializers.
|
||||
- Schema validation adaptor for offline mode and fixture-driven testing.
|
||||
## In/Out of scope
|
||||
In: CycloneDX parsing, normalization, export writing, schema validation.
|
||||
Out: Connector transport, storage, attestation; these rely on other modules.
|
||||
## Observability & security expectations
|
||||
- Log schema mismatches with document digest and component references; avoid logging proprietary component details where possible.
|
||||
## Tests
|
||||
- Unit and fixture tests will live in `../StellaOps.Excititor.Formats.CycloneDX.Tests`, covering normalization and serialization determinism.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,21 +1,32 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Provides OpenVEX statement normalization and export writers for lightweight attestation-oriented outputs.
|
||||
## Scope
|
||||
- Parse OpenVEX documents/attestations into canonical claims with provenance metadata.
|
||||
- Utilities to merge multiple OpenVEX statements and resolve conflicts for consensus ingestion.
|
||||
- Export writer emitting OpenVEX envelopes from consensus data with deterministic ordering.
|
||||
- Optional SBOM linkage helpers referencing component digests or PURLs.
|
||||
## Participants
|
||||
- OCI/OpenVEX connector and other attest-based sources depend on this module for normalization.
|
||||
- Export module uses writers for `--format openvex` requests.
|
||||
- Attestation layer references emitted statements to populate predicate subjects.
|
||||
## Interfaces & contracts
|
||||
- Normalizer classes implementing `INormalizer`, reducer utilities to consolidate OpenVEX events, export serializer.
|
||||
## In/Out of scope
|
||||
In: OpenVEX parsing, normalization, export serialization, helper utilities.
|
||||
Out: OCI registry access, policy evaluation, attestation signing (handled by other modules).
|
||||
## Observability & security expectations
|
||||
- Log normalization anomalies with subject digest and justification mapping while respecting offline constraints.
|
||||
## Tests
|
||||
- Snapshot-driven normalization/export tests will be placed in `../StellaOps.Excititor.Formats.OpenVEX.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
Provides OpenVEX statement normalization and export writers for lightweight attestation-oriented outputs.
|
||||
## Scope
|
||||
- Parse OpenVEX documents/attestations into canonical claims with provenance metadata.
|
||||
- Utilities to merge multiple OpenVEX statements and resolve conflicts for consensus ingestion.
|
||||
- Export writer emitting OpenVEX envelopes from consensus data with deterministic ordering.
|
||||
- Optional SBOM linkage helpers referencing component digests or PURLs.
|
||||
## Participants
|
||||
- OCI/OpenVEX connector and other attest-based sources depend on this module for normalization.
|
||||
- Export module uses writers for `--format openvex` requests.
|
||||
- Attestation layer references emitted statements to populate predicate subjects.
|
||||
## Interfaces & contracts
|
||||
- Normalizer classes implementing `INormalizer`, reducer utilities to consolidate OpenVEX events, export serializer.
|
||||
## In/Out of scope
|
||||
In: OpenVEX parsing, normalization, export serialization, helper utilities.
|
||||
Out: OCI registry access, policy evaluation, attestation signing (handled by other modules).
|
||||
## Observability & security expectations
|
||||
- Log normalization anomalies with subject digest and justification mapping while respecting offline constraints.
|
||||
## Tests
|
||||
- Snapshot-driven normalization/export tests will be placed in `../StellaOps.Excititor.Formats.OpenVEX.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,23 +1,34 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
Centralizes policy configuration, provider trust weights, and justification guardrails applied to Excititor consensus decisions.
|
||||
## Scope
|
||||
- Policy models for tier weighting, provider overrides, justification allowlists, and conflict escalation.
|
||||
- Configuration binding helpers (YAML/JSON) and validation of operator-supplied policy bundles.
|
||||
- Evaluation services that expose policy revisions and change tracking to WebService/Worker.
|
||||
- Documentation anchors for policy schema and upgrade guidance.
|
||||
## Participants
|
||||
- WebService consumes policy bindings to authorize ingest/export operations and to recompute consensus.
|
||||
- Worker schedules reconciliation runs using policy revisions from this module.
|
||||
- CLI exposes policy inspection commands based on exported descriptors.
|
||||
## Interfaces & contracts
|
||||
- `IVexPolicyProvider`, `IVexPolicyEvaluator`, and immutable policy snapshot value objects.
|
||||
- Validation diagnostics APIs surfacing structured errors and warnings for operators.
|
||||
## In/Out of scope
|
||||
In: policy schema definition, binding/validation, evaluation utilities, audit logging helpers.
|
||||
Out: persistence/migrations, HTTP exposure, connector-specific trust logic (lives in Core/Connectors).
|
||||
## Observability & security expectations
|
||||
- Emit structured events on policy load/update with revision IDs, but do not log full sensitive policy documents.
|
||||
- Maintain deterministic error ordering for reproducible diagnostics.
|
||||
## Tests
|
||||
- Policy fixtures and regression coverage will live in `../StellaOps.Excititor.Policy.Tests` once scaffolded; leverage snapshot comparisons for YAML bindings.
|
||||
# AGENTS
|
||||
## Role
|
||||
Centralizes policy configuration, provider trust weights, and justification guardrails applied to Excititor consensus decisions.
|
||||
## Scope
|
||||
- Policy models for tier weighting, provider overrides, justification allowlists, and conflict escalation.
|
||||
- Configuration binding helpers (YAML/JSON) and validation of operator-supplied policy bundles.
|
||||
- Evaluation services that expose policy revisions and change tracking to WebService/Worker.
|
||||
- Documentation anchors for policy schema and upgrade guidance.
|
||||
## Participants
|
||||
- WebService consumes policy bindings to authorize ingest/export operations and to recompute consensus.
|
||||
- Worker schedules reconciliation runs using policy revisions from this module.
|
||||
- CLI exposes policy inspection commands based on exported descriptors.
|
||||
## Interfaces & contracts
|
||||
- `IVexPolicyProvider`, `IVexPolicyEvaluator`, and immutable policy snapshot value objects.
|
||||
- Validation diagnostics APIs surfacing structured errors and warnings for operators.
|
||||
## In/Out of scope
|
||||
In: policy schema definition, binding/validation, evaluation utilities, audit logging helpers.
|
||||
Out: persistence/migrations, HTTP exposure, connector-specific trust logic (lives in Core/Connectors).
|
||||
## Observability & security expectations
|
||||
- Emit structured events on policy load/update with revision IDs, but do not log full sensitive policy documents.
|
||||
- Maintain deterministic error ordering for reproducible diagnostics.
|
||||
## Tests
|
||||
- Policy fixtures and regression coverage will live in `../StellaOps.Excititor.Policy.Tests` once scaffolded; leverage snapshot comparisons for YAML bindings.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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,24 +1,35 @@
|
||||
# AGENTS
|
||||
## Role
|
||||
MongoDB persistence layer for Excititor raw documents, claims, consensus snapshots, exports, and cache metadata.
|
||||
## Scope
|
||||
- Collection schemas, Bson class maps, repositories, and transactional write patterns for ingest/export flows.
|
||||
- GridFS integration for raw source documents and artifact metadata persistence.
|
||||
- Migrations, index builders, and bootstrap routines aligned with offline-first deployments.
|
||||
- Deterministic query helpers used by WebService, Worker, and Export modules.
|
||||
## Participants
|
||||
- WebService invokes repositories to store ingest runs, recompute consensus, and register exports.
|
||||
- Worker relies on repositories for resume markers, retry queues, and cache GC flows.
|
||||
- Export/Attestation modules pull stored claims/consensus data for snapshot building.
|
||||
## Interfaces & contracts
|
||||
- Repository abstractions (`IVexRawStore`, `IVexClaimStore`, `IVexConsensusStore`, `IVexExportStore`, `IVexCacheIndex`) and migration host interfaces.
|
||||
- Diagnostics hooks providing collection health metrics and schema validation results.
|
||||
## In/Out of scope
|
||||
In: MongoDB data access, migrations, transactional semantics, schema documentation.
|
||||
Out: domain modeling (Core), policy evaluation (Policy), HTTP surfaces (WebService).
|
||||
## Observability & security expectations
|
||||
- Emit structured logs for collection/migration events including revision ids and elapsed timings.
|
||||
- Expose health metrics (counts, queue backlog) and publish to OpenTelemetry when enabled.
|
||||
- Ensure no raw secret material is logged; mask tokens/URLs in diagnostics.
|
||||
## Tests
|
||||
- Integration fixtures (Mongo runner) and schema regression tests will reside in `../StellaOps.Excititor.Storage.Mongo.Tests`.
|
||||
# AGENTS
|
||||
## Role
|
||||
MongoDB persistence layer for Excititor raw documents, claims, consensus snapshots, exports, and cache metadata.
|
||||
## Scope
|
||||
- Collection schemas, Bson class maps, repositories, and transactional write patterns for ingest/export flows.
|
||||
- GridFS integration for raw source documents and artifact metadata persistence.
|
||||
- Migrations, index builders, and bootstrap routines aligned with offline-first deployments.
|
||||
- Deterministic query helpers used by WebService, Worker, and Export modules.
|
||||
## Participants
|
||||
- WebService invokes repositories to store ingest runs, recompute consensus, and register exports.
|
||||
- Worker relies on repositories for resume markers, retry queues, and cache GC flows.
|
||||
- Export/Attestation modules pull stored claims/consensus data for snapshot building.
|
||||
## Interfaces & contracts
|
||||
- Repository abstractions (`IVexRawStore`, `IVexClaimStore`, `IVexConsensusStore`, `IVexExportStore`, `IVexCacheIndex`) and migration host interfaces.
|
||||
- Diagnostics hooks providing collection health metrics and schema validation results.
|
||||
## In/Out of scope
|
||||
In: MongoDB data access, migrations, transactional semantics, schema documentation.
|
||||
Out: domain modeling (Core), policy evaluation (Policy), HTTP surfaces (WebService).
|
||||
## Observability & security expectations
|
||||
- Emit structured logs for collection/migration events including revision ids and elapsed timings.
|
||||
- Expose health metrics (counts, queue backlog) and publish to OpenTelemetry when enabled.
|
||||
- Ensure no raw secret material is logged; mask tokens/URLs in diagnostics.
|
||||
## Tests
|
||||
- Integration fixtures (Mongo runner) and schema regression tests will reside in `../StellaOps.Excititor.Storage.Mongo.Tests`.
|
||||
|
||||
## Required Reading
|
||||
- `docs/modules/excititor/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.
|
||||
|
||||
Reference in New Issue
Block a user