Update AGENTS.md files across multiple modules to standardize task status update instructions and introduce a new document for Secret Leak Detection operations.
- Modified task status update instructions in AGENTS.md files to refer to corresponding sprint files as `/docs/implplan/SPRINT_*.md` instead of `docs/implplan/SPRINTS.md`.
- Added a comprehensive document for Secret Leak Detection operations detailing scope, prerequisites, rule bundle lifecycle, enabling the analyzer, policy patterns, observability, troubleshooting, and references.
@@ -10,7 +10,7 @@ The `stella` CLI is the operator-facing Swiss army knife for scans, exports, pol
- [Task board](./TASKS.md)
## How to get started
1. Open ../../implplan/SPRINTS.md and locate the stories referencing this module.
1. Open sprint file `/docs/implplan/SPRINT_*.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.
@@ -27,7 +27,7 @@ The `stella` CLI is the operator-facing Swiss army knife for scans, exports, pol
-`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.
- 1. Update task status to `DOING`/`DONE` in both correspoding sprint file `/docs/implplan/SPRINT_*.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.
| CLI-DOCS-0001 | TODO | Docs Guild | Validate that ./README.md aligns with the latest release notes. | See ./AGENTS.md |
| CLI-OPS-0001 | TODO | Ops Guild | Review runbooks/observability assets after next sprint demo. | Sync outcomes back to ../../TASKS.md |
| CLI-ENG-0001 | TODO | Module Team | Cross-check implementation plan milestones against ../../implplan/SPRINTS.md. | Update status via ./AGENTS.md workflow |
| CLI-ENG-0001 | TODO | Module Team | Cross-check implementation plan milestones against `/docs/implplan/SPRINT_*.md`. | Update status via ./AGENTS.md workflow |
> **Audience:** DevEx engineers, operators, and CI authors integrating the `stella` CLI with Aggregation-Only Contract (AOC) workflows.
> **Scope:** Command synopsis, options, exit codes, and offline considerations for `stella sources ingest --dry-run` and `stella aoc verify` as introduced in Sprint19.
# CLI AOC Commands Reference
> **Audience:** DevEx engineers, operators, and CI authors integrating the `stella` CLI with Aggregation-Only Contract (AOC) workflows.
> **Scope:** Command synopsis, options, exit codes, and offline considerations for `stella sources ingest --dry-run` and `stella aoc verify` as introduced in Sprint19.
Both commands are designed to enforce the AOC guardrails documented in the [aggregation-only reference](../../../ingestion/aggregation-only-contract.md) and the [architecture overview](../architecture.md). They consume Authority-issued tokens with tenant scopes and never mutate ingestion stores.
-`vex:read` for Excititor sources (optional but required for VEX checks).
-`aoc:verify` to invoke guard verification endpoints.
-`tenant:select` if your deployment uses tenant switching.
- Connectivity: direct access to Concelier/Excititor APIs or Offline Kit snapshot (see §4).
- Environment: set `STELLA_AUTHORITY_URL`, `STELLA_TENANT`, and export a valid OpTok via `stella auth login` or existing token cache.
---
## 2·`stella sources ingest --dry-run`
### 2.1Synopsis
```bash
stella sources ingest --dry-run \
--source <source-key> \
--input <path-or-uri> \
[--tenant <tenant-id>]\
[--format json|table]\
[--no-color]\
[--output <file>]
```
### 2.2Description
Previews an ingestion write without touching MongoDB. The command loads an upstream advisory or VEX document, computes the would-write payload, runs it through the `AOCWriteGuard`, and reports any forbidden fields, provenance gaps, or idempotency issues. Use it during connector development, CI validation, or while triaging incidents.
| `--input <path-or-uri>` | Path to local CSAF/OSV/VEX file or HTTPS URI. CLI normalises transport (gzip/base64) before guard evaluation. |
| `--tenant <tenant-id>` | Overrides default tenant for multi-tenant deployments. Mandatory when `STELLA_TENANT` is not set. |
| `--format json|table` | Output format. `table` (default) prints summary with highlighted violations; `json` emits machine-readable report (see below). |
| `--no-color` | Disables ANSI colour output for CI logs. |
| `--output <file>` | Writes the JSON report to file while still printing human-readable summary to stdout. |
### 2.4Output schema (JSON)
```json
{
"source":"redhat",
"tenant":"default",
"guardVersion":"1.0.0",
"status":"ok",
"document":{
"contentHash":"sha256:…",
"supersedes":null,
"provenance":{
"signature":{"format":"pgp","present":true}
}
},
"violations":[]
}
```
When violations exist, `status` becomes `error` and `violations` contains entries with `code` (`ERR_AOC_00x`), a short `message`, and JSON Pointer `path` values indicating offending fields.
| `70` | Transport error (network, auth, malformed input). |
> Exit codes map directly to the `ERR_AOC_00x` table for scripting consistency. Multiple violations yield the highest-priority code (e.g., 11 takes precedence over 14).
- Use `--input` paths pointing to Offline Kit snapshots (`offline-kit/advisories/*.json`).
- Provide `--tenant` explicitly if the offline bundle contains multiple tenants.
- The command does not attempt network access when given a file path.
- Store reports with `--output` to include in transfer packages for policy review.
---
## 3·`stella aoc verify`
### 3.1Synopsis
```bash
stella aoc verify \
[--since <iso8601|duration>]\
[--limit <count>]\
[--sources <list>]\
[--codes <ERR_AOC_00x,...>]\
[--format table|json]\
[--export <file>]\
[--tenant <tenant-id>]\
[--no-color]
```
### 3.2Description
Replays the AOC guard against stored raw documents. By default it checks all advisories and VEX statements ingested in the last 24hours for the active tenant, reporting totals, top violation codes, and sample documents. Use it in CI pipelines, scheduled verifications, or during incident response.
### 3.3Options
| Option | Description |
|--------|-------------|
| `--since <value>` | Verification window. Accepts ISO8601 timestamp (`2025-10-25T12:00:00Z`) or duration (`48h`, `7d`). Defaults to `24h`. |
| `--limit <count>` | Maximum number of violations to display (per code). `0` means show all. Defaults to `20`. |
| `--sources <list>` | Comma-separated list of sources (`redhat,ubuntu,osv`). Filters both advisories and VEX entries. |
| `--codes <list>` | Restricts output to specific `ERR_AOC_00x` codes. Useful for regression tracking. |
| `--format table|json` | `table` (default) prints summary plus top violations; `json` outputs machine-readable report identical to the `/aoc/verify` API. |
| `--export <file>` | Writes the JSON report to disk (useful for audits/offline uploads). |
| `--tenant <tenant-id>` | Overrides tenant context. Required for cross-tenant verifications when run by platform operators. |
| `--no-color` | Disables ANSI colours. |
`table` mode prints a summary showing the active tenant, evaluated window, counts of checked advisories/VEX statements, the active limit, total writes/violations, and whether the page was truncated. Status is colour-coded as `ok`, `violations`, or `truncated`. When violations exist the detail table lists the code, total occurrences, first sample document (`source` + `documentId` + `contentHash`), and JSON pointer path.
### 3.4Report structure (JSON)
```json
{
"tenant":"default",
"window":{
"from":"2025-10-25T12:00:00Z",
"to":"2025-10-26T12:00:00Z"
},
"checked":{
"advisories":482,
"vex":75
},
"violations":[
{
"code":"ERR_AOC_001",
"count":2,
"examples":[
{
"source":"redhat",
"documentId":"advisory_raw:redhat:RHSA-2025:1",
"contentHash":"sha256:…",
"path":"/content/raw/cvss"
}
]
}
],
"metrics":{
"ingestion_write_total":557,
"aoc_violation_total":2
},
"truncated":false
}
```
### 3.5Exit codes
| Exit code | Meaning |
|-----------|---------|
| `0` | Verification succeeded with zero violations. |
| `11…17` | Same mapping as §2.5 when violations are detected. Highest-priority code returned. |
| `18` | Verification ran but results truncated (limit reached) – treat as warning; rerun with higher `--limit`. |
- Schedule with `cron` or platform scheduler and fail the job when exit code ≥11.
- Pair with `stella sources ingest --dry-run` for pre-flight validation before re-enabling a paused source.
- Push JSON exports to observability pipelines for historical tracking of violation counts.
### 3.8Offline notes
- Works against Offline Kit Mongo snapshots when CLI is pointed at the local API gateway included in the bundle.
- When fully disconnected, run against exported `aoc verify` reports generated on production and replay them using `--format json --export` (automation recipe above).
- Include verification output in compliance packages alongside Offline Kit manifests.
---
## 4·Global exit-code reference
| Code | Summary |
|------|---------|
| `0` | Success / no violations. |
| `11` | `ERR_AOC_001`– Forbidden field present. |
Use these codes in CI to map outcomes to build statuses or alert severities.
---
## 4·`stella vuln observations` (Overlay paging)
`stella vuln observations` lists raw advisory observations for downstream overlays (Graph Explorer, Policy simulations, Console). Large tenants can now page through results deterministically.
| Option | Description |
|--------|-------------|
| `--limit <count>` | Caps the number of observations returned in a single call. Defaults to `200`; values above `500` are clamped server-side. |
| `--cursor <token>` | Opaque continuation token produced by the previous page (`nextCursor` in JSON output). Pass it back to resume iteration. |
Additional notes:
- Table mode prints a hint when `hasMore` is `true`:
`[yellow]More observations available. Continue with --cursor <token>[/]`.
- JSON mode returns `nextCursor` and `hasMore` alongside the observation list so automation can loop until `hasMore` is `false`.
- Supplying a non-positive limit falls back to the default (`200`). Invalid/expired cursors yield `400 Bad Request`; restart without `--cursor` to begin a fresh iteration.
-`vex:read` for Excititor sources (optional but required for VEX checks).
-`aoc:verify` to invoke guard verification endpoints.
-`tenant:select` if your deployment uses tenant switching.
- Connectivity: direct access to Concelier/Excititor APIs or Offline Kit snapshot (see §4).
- Environment: set `STELLA_AUTHORITY_URL`, `STELLA_TENANT`, and export a valid OpTok via `stella auth login` or existing token cache.
---
## 2·`stella sources ingest --dry-run`
### 2.1Synopsis
```bash
stella sources ingest --dry-run \
--source <source-key> \
--input <path-or-uri> \
[--tenant <tenant-id>]\
[--format json|table]\
[--no-color]\
[--output <file>]
```
### 2.2Description
Previews an ingestion write without touching MongoDB. The command loads an upstream advisory or VEX document, computes the would-write payload, runs it through the `AOCWriteGuard`, and reports any forbidden fields, provenance gaps, or idempotency issues. Use it during connector development, CI validation, or while triaging incidents.
| `--input <path-or-uri>` | Path to local CSAF/OSV/VEX file or HTTPS URI. CLI normalises transport (gzip/base64) before guard evaluation. |
| `--tenant <tenant-id>` | Overrides default tenant for multi-tenant deployments. Mandatory when `STELLA_TENANT` is not set. |
| `--format json|table` | Output format. `table` (default) prints summary with highlighted violations; `json` emits machine-readable report (see below). |
| `--no-color` | Disables ANSI colour output for CI logs. |
| `--output <file>` | Writes the JSON report to file while still printing human-readable summary to stdout. |
### 2.4Output schema (JSON)
```json
{
"source":"redhat",
"tenant":"default",
"guardVersion":"1.0.0",
"status":"ok",
"document":{
"contentHash":"sha256:…",
"supersedes":null,
"provenance":{
"signature":{"format":"pgp","present":true}
}
},
"violations":[]
}
```
When violations exist, `status` becomes `error` and `violations` contains entries with `code` (`ERR_AOC_00x`), a short `message`, and JSON Pointer `path` values indicating offending fields.
| `70` | Transport error (network, auth, malformed input). |
> Exit codes map directly to the `ERR_AOC_00x` table for scripting consistency. Multiple violations yield the highest-priority code (e.g., 11 takes precedence over 14).
- Use `--input` paths pointing to Offline Kit snapshots (`offline-kit/advisories/*.json`).
- Provide `--tenant` explicitly if the offline bundle contains multiple tenants.
- The command does not attempt network access when given a file path.
- Store reports with `--output` to include in transfer packages for policy review.
---
## 3·`stella aoc verify`
### 3.1Synopsis
```bash
stella aoc verify \
[--since <iso8601|duration>]\
[--limit <count>]\
[--sources <list>]\
[--codes <ERR_AOC_00x,...>]\
[--format table|json]\
[--export <file>]\
[--tenant <tenant-id>]\
[--no-color]
```
### 3.2Description
Replays the AOC guard against stored raw documents. By default it checks all advisories and VEX statements ingested in the last 24hours for the active tenant, reporting totals, top violation codes, and sample documents. Use it in CI pipelines, scheduled verifications, or during incident response.
### 3.3Options
| Option | Description |
|--------|-------------|
| `--since <value>` | Verification window. Accepts ISO8601 timestamp (`2025-10-25T12:00:00Z`) or duration (`48h`, `7d`). Defaults to `24h`. |
| `--limit <count>` | Maximum number of violations to display (per code). `0` means show all. Defaults to `20`. |
| `--sources <list>` | Comma-separated list of sources (`redhat,ubuntu,osv`). Filters both advisories and VEX entries. |
| `--codes <list>` | Restricts output to specific `ERR_AOC_00x` codes. Useful for regression tracking. |
| `--format table|json` | `table` (default) prints summary plus top violations; `json` outputs machine-readable report identical to the `/aoc/verify` API. |
| `--export <file>` | Writes the JSON report to disk (useful for audits/offline uploads). |
| `--tenant <tenant-id>` | Overrides tenant context. Required for cross-tenant verifications when run by platform operators. |
| `--no-color` | Disables ANSI colours. |
`table` mode prints a summary showing the active tenant, evaluated window, counts of checked advisories/VEX statements, the active limit, total writes/violations, and whether the page was truncated. Status is colour-coded as `ok`, `violations`, or `truncated`. When violations exist the detail table lists the code, total occurrences, first sample document (`source` + `documentId` + `contentHash`), and JSON pointer path.
### 3.4Report structure (JSON)
```json
{
"tenant":"default",
"window":{
"from":"2025-10-25T12:00:00Z",
"to":"2025-10-26T12:00:00Z"
},
"checked":{
"advisories":482,
"vex":75
},
"violations":[
{
"code":"ERR_AOC_001",
"count":2,
"examples":[
{
"source":"redhat",
"documentId":"advisory_raw:redhat:RHSA-2025:1",
"contentHash":"sha256:…",
"path":"/content/raw/cvss"
}
]
}
],
"metrics":{
"ingestion_write_total":557,
"aoc_violation_total":2
},
"truncated":false
}
```
### 3.5Exit codes
| Exit code | Meaning |
|-----------|---------|
| `0` | Verification succeeded with zero violations. |
| `11…17` | Same mapping as §2.5 when violations are detected. Highest-priority code returned. |
| `18` | Verification ran but results truncated (limit reached) – treat as warning; rerun with higher `--limit`. |
- Schedule with `cron` or platform scheduler and fail the job when exit code ≥11.
- Pair with `stella sources ingest --dry-run` for pre-flight validation before re-enabling a paused source.
- Push JSON exports to observability pipelines for historical tracking of violation counts.
### 3.8Offline notes
- Works against Offline Kit Mongo snapshots when CLI is pointed at the local API gateway included in the bundle.
- When fully disconnected, run against exported `aoc verify` reports generated on production and replay them using `--format json --export` (automation recipe above).
- Include verification output in compliance packages alongside Offline Kit manifests.
---
## 4·Global exit-code reference
| Code | Summary |
|------|---------|
| `0` | Success / no violations. |
| `11` | `ERR_AOC_001`– Forbidden field present. |
Use these codes in CI to map outcomes to build statuses or alert severities.
---
## 4·`stella vuln observations` (Overlay paging)
`stella vuln observations` lists raw advisory observations for downstream overlays (Graph Explorer, Policy simulations, Console). Large tenants can now page through results deterministically.
| Option | Description |
|--------|-------------|
| `--limit <count>` | Caps the number of observations returned in a single call. Defaults to `200`; values above `500` are clamped server-side. |
| `--cursor <token>` | Opaque continuation token produced by the previous page (`nextCursor` in JSON output). Pass it back to resume iteration. |
Additional notes:
- Table mode prints a hint when `hasMore` is `true`:
`[yellow]More observations available. Continue with --cursor <token>[/]`.
- JSON mode returns `nextCursor` and `hasMore` alongside the observation list so automation can loop until `hasMore` is `false`.
- Supplying a non-positive limit falls back to the default (`200`). Invalid/expired cursors yield `400 Bad Request`; restart without `--cursor` to begin a fresh iteration.
- [ ] Usage documented for both table and JSON formats.
@@ -317,10 +317,8 @@ All publish/promote operations require interactive identities with `policy:publi
---
*Last updated: 2025-11-03 (Sprint100).*
## 13. Authority configuration quick reference
| Setting | Purpose | How to set |
|---------|---------|------------|
| `StellaOps:Authority:OperatorReason` | Incident/change description recorded with `orch:operate` tokens. | CLI flag `--Authority:OperatorReason=...` or env `STELLAOPS_ORCH_REASON`. |
@@ -332,4 +330,61 @@ All publish/promote operations require interactive identities with `policy:publi
| `StellaOps:Authority:Scope` | Default scope string requested during `stella auth login`. | CLI flag `--Authority:Scope=\"packs.read packs.run\"` or env `STELLAOPS_AUTHORITY_SCOPE`; see `docs/modules/cli/guides/packs-profiles.md` for common Task Pack profiles. |
> Tokens requesting `orch:operate` fail with `invalid_request` unless both operator values are present. `orch:quota` tokens require `quota_reason` (≤256 chars) and accept an optional `quota_ticket` (≤128 chars). `orch:backfill` tokens require both `backfill_reason` (≤256 chars) and `backfill_ticket` (≤128 chars). Avoid embedding secrets in any value.
---
## 14·`stella excititor verify`
### 14.1Synopsis
```bash
stella excititor verify \
[--export-id <id>]\
[--digest <sha256>]\
[--attestation <path>]\
[--verbose]
```
At least one of `--export-id`, `--digest`, or `--attestation` must be supplied.
### 14.2Description
Submits an artifact, digest, or attestation bundle to the Attestor service for verification. The command is available once the non-core plugin pack is installed (default in production CLI builds). It validates DSSE envelopes, Rekor proofs, and export digests without requiring operators to call Attestor APIs directly.
### 14.3Options
| Option | Description |
|--------|-------------|
| `--export-id <id>` | Verify a previously issued Excititor export by identifier. |
| `--digest <sha256>` | Expected SHA-256 digest of the artifact or attestation payload. Added to the verification payload for additional integrity checks. |
| `--attestation <path>` | Path to a DSSE or in-toto bundle. The CLI base64-encodes the file and streams it to Attestor for verification. |
| `--verbose` | Enables debug logging. |
> **Behaviour:** When `--attestation` is used the CLI loads the file into memory, encodes it as base64, and delegates verification to Attestor. Verification fails fast if the file cannot be read.
### 14.4Secret rule bundle workflow
To confirm the signed secret-leak rule bundle before enabling the analyzer:
```bash
exportSTELLA_ATTESTOR_URL=https://attestor.internal.example # or Offline Kit mirror
- Sync with cross-cutting teams noted in ../../implplan/SPRINTS.md.
- Sync with cross-cutting teams noted in `/docs/implplan/SPRINT_*.md`.
- Update this plan whenever scope, dependencies, or guardrails change.
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
master