stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity

feat(docs): Add comprehensive documentation for Vexer, Vulnerability Explorer, and Zastava modules

Browse Source 
- Introduced AGENTS.md, README.md, TASKS.md, and implementation_plan.md for Vexer, detailing mission, responsibilities, key components, and operational notes.
- Established similar documentation structure for Vulnerability Explorer and Zastava modules, including their respective workflows, integrations, and observability notes.
- Created risk scoring profiles documentation outlining the core workflow, factor model, governance, and deliverables.
- Ensured all modules adhere to the Aggregation-Only Contract and maintain determinism and provenance in outputs.
This commit is contained in:
master
2025-10-30 00:09:39 +02:00
parent 3154c67978
commit 7b5bdcf4d3
503 changed files with 16136 additions and 54638 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/modules/registry/AGENTS.md Normal file
View File

@@ -0,0 +1,22 @@
# Registry Token Service agent guide
## Mission
The registry module issues scoped pull tokens for mirrored container registries while enforcing plan and licence constraints.
## Key docs
- [Module README](./README.md)
- [Architecture](./architecture.md)
- [Implementation plan](./implementation_plan.md)
- [Task board](./TASKS.md)
## How to get started
1. Open ../../implplan/SPRINTS.md and locate the stories referencing this module.
2. Review ./TASKS.md for local follow-ups and confirm status transitions (TODO → DOING → DONE/BLOCKED).
3. Read the architecture and README for domain context before editing code or docs.
4. Coordinate cross-module changes in the main /AGENTS.md description and through the sprint plan.
## Guardrails
- Honour the Aggregation-Only Contract where applicable (see ../../ingestion/aggregation-only-contract.md).
- Preserve determinism: sort outputs, normalise timestamps (UTC ISO-8601), and avoid machine-specific artefacts.
- Keep Offline Kit parity in mind—document air-gapped workflows for any new feature.
- Update runbooks/observability assets when operational characteristics change.

34
docs/modules/registry/README.md Normal file
View File

@@ -0,0 +1,34 @@
# StellaOps Registry Token Service
The registry module issues scoped pull tokens for mirrored container registries while enforcing plan and licence constraints.
## Responsibilities
- Validate Authority-issued OpToks and tenant scopes before issuance.
- Mint time-bound registry tokens and record issuance ledgers.
- Expose revocation and audit endpoints for security teams.
- Integrate with Offline Kit for deterministic token manifests.
## Key components
- `StellaOps.Registry.TokenService` minimal API host.
- Mongo-backed issuance ledger.
- Tests under `src/Registry/__Tests`.
## Integrations & dependencies
- Authority for identity & scope verification.
- Export Center/Offline Kit for distribution.
- DevOps runbooks for deployment and rotation.
## Operational notes
- Operational guide at ./operations/token-service.md.
- Telemetry dashboards pending (see ../../TASKS.md).
## Related resources
- ./operations/token-service.md
## Backlog references
- DEVOPS-REGISTRY items in ../../TASKS.md (future work).
- Registry automation stories tracked in src/Registry/TASKS.md if present.
## Epic alignment
- **Epic 10 – Export Center:** provide signed, auditable registry token bundles for mirror distribution.
- **Epic 14 – Identity & Tenancy:** enforce tenant-aware scopes, PoE alignment, and revocation policies.

9
docs/modules/registry/TASKS.md Normal file
View File

@@ -0,0 +1,9 @@
# Task board — Registry Token Service
> Local tasks should link back to ./AGENTS.md and mirror status updates into ../../TASKS.md when applicable.
| ID | Status | Owner(s) | Description | Notes |
|----|--------|----------|-------------|-------|
| REGISTRY TOKEN SERVICE-DOCS-0001 | TODO | Docs Guild | Validate that ./README.md aligns with the latest release notes. | See ./AGENTS.md |
| REGISTRY TOKEN SERVICE-OPS-0001 | TODO | Ops Guild | Review runbooks/observability assets after next sprint demo. | Sync outcomes back to ../../TASKS.md |
| REGISTRY TOKEN SERVICE-ENG-0001 | TODO | Module Team | Cross-check implementation plan milestones against ../../implplan/SPRINTS.md. | Update status via ./AGENTS.md workflow |

7
docs/modules/registry/architecture.md Normal file
View File

@@ -0,0 +1,7 @@
# Registry Token Service architecture
> Grounded in the Export Center and Authority module guides, which describe token issuance, provenance, tenant isolation, and offline packaging expectations.
This placeholder summarises the planned architecture for Registry Token Service. Consolidate design details from implementation plans and upcoming epics before coding.
Refer to the module README and implementation plan for immediate context, and update this document once component boundaries and data flows are finalised.

20
docs/modules/registry/implementation_plan.md Normal file
View File

@@ -0,0 +1,20 @@
# Implementation plan — Registry Token Service
## Current objectives
- Maintain deterministic behaviour and offline parity across releases.
- Keep documentation, telemetry, and runbooks aligned with the latest sprint outcomes.
## Workstreams
- Backlog grooming: reconcile open stories in ../../TASKS.md with this module's roadmap.
- Implementation: collaborate with service owners to land feature work defined in SPRINTS/EPIC docs.
- Validation: extend tests/fixtures to preserve determinism and provenance requirements.
## Epic milestones
- **Epic 10 – Export Center:** deliver signed registry token bundles supporting mirror/Offline Kit workflows.
- **Epic 14 – Identity & Tenancy:** integrate tenant-aware scope validation, revocation, and audit trails.
- Track follow-ups in ../../TASKS.md and src/Registry/TASKS.md.
## Coordination
- Review ./AGENTS.md before picking up new work.
- Sync with cross-cutting teams noted in ../../implplan/SPRINTS.md.
- Update this plan whenever scope, dependencies, or guardrails change.

66
docs/modules/registry/operations/token-service.md Normal file
View File

@@ -0,0 +1,66 @@
# Registry Token Service Operations
_Component_: `src/Registry/StellaOps.Registry.TokenService`
The registry token service issues short-lived Docker registry bearer tokens after
validating an Authority OpTok (DPoP/mTLS sender constraint) and the customer’s
plan entitlements. It is fronted by the Docker registry’s `Bearer realm` flow.
## Configuration
Configuration lives in `etc/registry-token.yaml` and can be overridden through
environment variables prefixed with `REGISTRY_TOKEN_`. Key sections:
| Section | Purpose |
| ------- | ------- |
| `authority` | Authority issuer/metadata URL, audience list, and scopes required to request tokens (default `registry.token.issue`). |
| `signing` | JWT issuer, signing key (PEM or PFX), optional key ID, and token lifetime (default five minutes). The repository ships **`etc/registry-signing-sample.pem`** for local testing only – replace it with a private key generated and stored per-environment before going live. |
| `registry` | Registry realm URL and optional allow-list of `service` values accepted from the registry challenge. |
| `plans` | Plan catalogue mapping plan name → repository patterns and allowed actions. Wildcards (`*`) are supported per path segment. |
| `defaultPlan` | Applied when the caller’s token omits `stellaops:plan`. |
| `revokedLicenses` | Blocks issuance when the caller presents a matching `stellaops:license` claim. |
Plan entries must cover every private repository namespace. Actions default to
`pull` if omitted.
## Request flow
1. Docker/OCI client contacts the registry and receives a `401` with
`WWW-Authenticate: Bearer realm=...,service=...,scope=repository:...`.
2. Client acquires an OpTok from Authority (DPoP/mTLS bound) with the
`registry.token.issue` scope.
3. Client calls `GET /token?service=<service>&scope=repository:<name>:<actions>`
against the token service, presenting the OpTok and matching DPoP proof.
4. The service validates the token, plan, and requested scopes, then issues a
JWT containing an `access` claim conforming to the Docker registry spec.
All denial paths return RFC 6750-style problem responses (HTTP 400 for malformed
scopes, 403 for plan or revocation failures).
## Monitoring
The service emits OpenTelemetry metrics via `registry_token_issued_total` and
`registry_token_rejected_total`. Suggested Prometheus alerts:
| Metric | Condition | Action |
|--------|-----------|--------|
| `registry_token_rejected_total` | `increase(...) > 0` over 5 minutes | Investigate plan misconfiguration or licence revocation. |
| `registry_token_issued_total` | Sudden drop compared to baseline | Confirm registry is still challenging with the expected realm/service. |
Enable the built-in `/healthz` endpoint for liveness checks. Authentication and
DPoP failures surface via the service logs (Serilog console output).
## Sample deployment
```bash
dotnet run --project src/Registry/StellaOps.Registry.TokenService \
--urls "http://0.0.0.0:8085"
curl -H "Authorization: Bearer <OpTok>" \
-H "DPoP: $(dpop-proof ...)" \
"http://localhost:8085/token?service=registry.localhost&scope=repository:stella-ops/public/base:pull"
```
Replace `<OpTok>` and `DPoP` with tokens issued by Authority. The response
contains `token`, `expires_in`, and `issued_at` fields suitable for Docker/OCI
clients.