stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
daa6a4ae8ce372f398c450eeaaafcd079ca5ea46
git.stella-ops.org/src/StellaOps.Scanner.Core/AGENTS.md
master daa6a4ae8c
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Build Test Deploy / build-test (push) Has been cancelled
Details
Build Test Deploy / authority-container (push) Has been cancelled
Details
Build Test Deploy / docs (push) Has been cancelled
Details
Build Test Deploy / deploy (push) Has been cancelled
Details
up
2025-10-19 10:38:55 +03:00

2.3 KiB
Raw Blame History

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.