stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
8bbfe4d2d2248c3e93122c82828eb819a9dbcc71
git.stella-ops.org/src/Excititor/AGENTS.md
master 8bbfe4d2d2 feat(rate-limiting): Implement core rate limiting functionality with configuration, decision-making, metrics, middleware, and service registration 
- Add RateLimitConfig for configuration management with YAML binding support.
- Introduce RateLimitDecision to encapsulate the result of rate limit checks.
- Implement RateLimitMetrics for OpenTelemetry metrics tracking.
- Create RateLimitMiddleware for enforcing rate limits on incoming requests.
- Develop RateLimitService to orchestrate instance and environment rate limit checks.
- Add RateLimitServiceCollectionExtensions for dependency injection registration.
2025-12-17 18:02:37 +02:00

4.6 KiB
Raw Blame History

Excititor · AGENTS Charter (Air-Gap & Trust Connectors)

Module Scope & Working Directory

  • Working directory: src/Excititor/** (WebService, Worker, __Libraries, __Tests, connectors, scripts). No cross-module edits unless explicitly noted in sprint Decisions & Risks.
  • Mission (current sprint): air-gap parity for evidence chunks, trust connector wiring, and attestation verification aligned to Evidence Locker contract.

Roles

  • Backend engineer (ASP.NET Core / Postgres): chunk ingestion/export, attestation verifier, trust connector.
  • Air-Gap/Platform engineer: sealed-mode switches, offline bundles, deterministic cache/path handling.
  • QA automation: WebApplicationFactory + Postgres or in-memory fixtures for chunk APIs, attestations, and trust connector; deterministic ordering/hashes.
  • Docs/Schema steward: keep chunk API, attestation plan, and trust connector docs in sync with behavior; update schemas and samples.

Required Reading (treat as read before DOING)

  • docs/README.md
  • docs/07_HIGH_LEVEL_ARCHITECTURE.md
  • docs/modules/platform/architecture-overview.md
  • docs/modules/excititor/architecture.md
  • docs/modules/excititor/attestation-plan.md
  • docs/modules/excititor/operations/chunk-api-user-guide.md
  • docs/modules/excititor/schemas/vex-chunk-api.yaml
  • docs/modules/evidence-locker/attestation-contract.md
  • docs/product-advisories/14-Dec-2025 - Smart-Diff Technical Reference.md (for VEX emission contracts)

VEX Emission Contracts (Sprint 3500)

The Excititor module handles VEX candidate emission for Smart-Diff:

Namespace

  • StellaOps.Excititor.VexEmission - VEX candidate generation

Key Types

  • VexCandidateEmitter - Generates VEX candidate statements
  • VexCandidate - A VEX statement candidate for review
  • VexEmissionRule - Rule matching for VEX emission
  • IVexCandidateRepository - Storage for VEX candidates

VEX Emission Triggers

Trigger Description VEX Status
sink_unreachable Vulnerability requires sink not present not_affected candidate
entry_unreachable Vulnerable entry point unreachable not_affected candidate
api_absent Vulnerable API not called not_affected candidate
package_removed Vulnerable package removed fixed candidate
version_upgraded Package upgraded past fix version fixed candidate
patch_applied Security patch detected fixed candidate

VEX Candidate Workflow

  1. Smart-Diff detects reachability flip or package change
  2. VexCandidateEmitter evaluates emission rules
  3. Matching rules generate VexCandidate with justification
  4. Candidates stored via IVexCandidateRepository
  5. Candidates surfaced in triage UI for review/approval

Integration Points

  • Scanner SmartDiff triggers VEX emission on reachability changes
  • Candidates stored with SmartDiffPredicate reference for traceability
  • Approved candidates become formal VEX statements via Attestor

Working Agreements

  • Determinism: canonical JSON ordering; stable pagination; UTC ISO-8601 timestamps; sort chunk edges deterministically.
  • Offline-first: default sealed-mode must not reach external networks; connectors obey allowlist; feature flags default safe.
  • Attestation: DSSE/Envelope per contract; always include tenant/source identifiers; validation fixtures required.
  • Tenant safety: enforce tenant headers/guards on every API; no cross-tenant leakage.
  • Logging/metrics: structured logs; meters under StellaOps.Excititor.*; tag tenant, source, result.
  • Cross-module edits: require sprint note; otherwise, stay within Excititor working dir.

Testing Rules

  • Prefer Postgres integration or in-memory fixtures; avoid network.
  • API tests in StellaOps.Excititor.WebService.Tests; worker/connectors in StellaOps.Excititor.Worker.Tests; shared fixtures in __Tests.
  • Tests must assert determinism (ordering/hashes), tenant enforcement, and sealed-mode behavior.

Delivery Discipline

  • Update sprint tracker status (TODO → DOING → DONE/BLOCKED) for each task; mirror changes in Execution Log and Decisions & Risks.
  • When changing contracts (API/attestation schemas), update docs and samples and link from sprint Decisions & Risks.
  • If a decision is needed, mark the task BLOCKED and record the decision ask—do not pause work.

Tooling/Env Notes

  • .NET 10 with preview features enabled; Postgres or in-memory storage only (Mongo/BSON removed).
  • Signing/verifier hooks rely on Evidence Locker contract fixtures under docs/modules/evidence-locker/.
  • Sealed-mode tests should run with EXCITITOR_SEALED=1 (env var) to enforce offline code paths.