71 lines
4.7 KiB
Markdown
71 lines
4.7 KiB
Markdown
# Advisory AI CLI Usage (DOCS-AIAI-31-005)
|
|
|
|
_Updated: 2025-11-24 · Owners: Docs Guild · DevEx/CLI Guild · Sprint 0111_
|
|
|
|
This guide shows how to drive Advisory AI from the StellaOps CLI using the `advise run` verb, with deterministic fixtures published on 2025-11-19 (`CLI-VULN-29-001`, `CLI-VEX-30-001`). It is designed for CI/offline use and mirrors the guardrail/policy contracts captured in `docs/advisory-ai/guardrails-and-evidence.md` and `docs/policy/assistant-parameters.md`.
|
|
|
|
## Prerequisites
|
|
- CLI binary from Sprint 205 (`stella`), logged in with scopes `advisory-ai:operate` + `aoc:verify`.
|
|
- Base URL pointed at Advisory AI gateway: `export STELLAOPS_ADVISORYAI_URL=https://advisory-ai.internal` (falls back to main backend base address when unset).
|
|
- Evidence fixtures available locally (offline friendly):
|
|
- `out/console/guardrails/cli-vuln-29-001/sample-vuln-output.ndjson` (SHA256 `e5aecfba5cee8d412408fb449f12fa4d5bf0a7cb7e5b316b99da3b9019897186`).
|
|
- `out/console/guardrails/cli-vuln-29-001/sample-sbom-context.json` (SHA256 `421af53f9eeba6903098d292fbd56f98be62ea6130b5161859889bf11d699d18`).
|
|
- `out/console/guardrails/cli-vex-30-001/sample-vex-output.ndjson` (SHA256 `2b11b1e2043c2ec1b0cb832c29577ad1c5cbc3fbd0b379b0ca0dee46c1bc32f6`).
|
|
- Policy hash pinned: set `ADVISORYAI__POLICYVERSION=2025.11.19` (or the bundle hash shipped in the Offline Kit).
|
|
|
|
## Quickstart
|
|
```bash
|
|
stella advise run summary \
|
|
--advisory-key csaf:redhat:RHSA-2025:1001 \
|
|
--artifact-id registry.stella-ops.internal/runtime/api \
|
|
--policy-version "$ADVISORYAI__POLICYVERSION" \
|
|
--profile fips-local \
|
|
--timeout 30 \
|
|
--json
|
|
```
|
|
- Use `--timeout 0` for cache-only probes in CI; add `--force-refresh` to bypass cache.
|
|
- `--profile cloud-openai` remains disabled unless tenant consent is recorded in Authority; guardrails reject with exit code 12 when disabled.
|
|
- Guardrail fixtures (`sample-vuln-output.ndjson`, `sample-vex-output.ndjson`, `sample-sbom-context.json`) live in Offline Kits and feed the backend self-tests; the CLI fetches evidence from backend services automatically.
|
|
|
|
## Exit codes
|
|
| Code | Meaning | Notes |
|
|
| --- | --- | --- |
|
|
| 0 | Success (hit or miss; output cached or freshly generated) | Includes `outputHash` and citations. |
|
|
| 2 | Validation error (missing advisory key, bad profile) | Mirrors HTTP 400.
|
|
| 3 | Context unavailable (SBOM/LNM/policy missing) | Mirrors HTTP 409 `advisory.contextUnavailable`.
|
|
| 4 | Guardrail block (PII, citation gap, prompt too large) | Mirrors HTTP 422 `advisory.guardrail.blocked`.
|
|
| 5 | Timeout waiting for output | Respect `--timeout` in seconds (0 = no wait). |
|
|
| 12 | Remote profile disabled | Returned when `cloud-openai` is selected without consent. |
|
|
| 7 | Transport/auth failure | Network/TLS/token issues. |
|
|
|
|
## Scripting patterns
|
|
- **Cache-only probes (CI smoke):** `stella advise run summary --advisory-key ... --timeout 0 --json > cache.json` (fails fast if evidence missing).
|
|
- **Batch mode:** pipe advisory keys: `cat advisories.txt | xargs -n1 -I{} stella advise run summary --advisory-key {} --timeout 0 --json`.
|
|
- **Profile gating:** set `--profile fips-local` for offline; use `--profile cloud-openai` only after Authority consent and when `ADVISORYAI__INFERENCE__MODE=Remote`.
|
|
- **Policy pinning:** always pass `--policy-version` (matches Offline Kit bundle hash); outputs include the policy hash in `context.planCacheKey`.
|
|
|
|
## Sample output (trimmed)
|
|
```json
|
|
{
|
|
"taskType": "Summary",
|
|
"profile": "fips-local",
|
|
"generatedAt": "2025-11-24T00:00:00Z",
|
|
"outputHash": "sha256:cafe...babe",
|
|
"citations": [{"index":1,"kind":"advisory","sourceId":"concelier:csaf:redhat:RHSA-2025:1001:paragraph:12"}],
|
|
"context": {
|
|
"planCacheKey": "adv-summary:csaf:redhat:RHSA-2025:1001:fips-local",
|
|
"sbom": {"artifactId":"registry.stella-ops.internal/runtime/api","versionTimeline":8,"dependencyPaths":5}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Offline kit notes
|
|
- Copy the three CLI guardrail artefact bundles and their `hashes.sha256` files into `offline-kit/advisory-ai/fixtures/` and record them in `SHA256SUMS`.
|
|
- Set `ADVISORYAI__SBOM__BASEADDRESS` to the SBOM Service endpoint packaged in the kit; leave unset to fall back to `NullSbomContextClient` (Advisory AI will still respond deterministically with context counts set to 0).
|
|
- Keep `profiles.catalog.json` and `prompts.manifest` hashes aligned with the guardrail pack referenced in the Offline Kit manifest.
|
|
|
|
## Troubleshooting
|
|
- `contextUnavailable`: ensure SBOM service is reachable or provide `--sbom-context` fixture; verify LNM linkset IDs and hashes.
|
|
- `guardrail.blocked`: check blocked phrase list (`docs/policy/assistant-parameters.md`) and payload size; remove PII or reduce SBOM clamps.
|
|
- `timeout`: raise `--timeout` or run cache-only mode to avoid long waits in CI.
|