2eb6852d34
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
- Implement `SbomIngestServiceCollectionExtensionsTests` to verify the SBOM ingestion pipeline exports snapshots correctly. - Create `SbomIngestTransformerTests` to ensure the transformation produces expected nodes and edges, including deduplication of license nodes and normalization of timestamps. - Add `SbomSnapshotExporterTests` to test the export functionality for manifest, adjacency, nodes, and edges. - Introduce `VexOverlayTransformerTests` to validate the transformation of VEX nodes and edges. - Set up project file for the test project with necessary dependencies and configurations. - Include JSON fixture files for testing purposes.
103 lines
6.5 KiB
Markdown
103 lines
6.5 KiB
Markdown
> **Imposed rule:** Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.
|
||
|
||
# Advisory AI Overview
|
||
|
||
_Updated: 2025-11-03 • Owner: Docs Guild & Advisory AI Guild • Status: Draft_
|
||
|
||
Advisory AI is the retrieval-augmented assistant that synthesises Conseiller (advisory) and Excititor (VEX) evidence, Policy Engine context, and SBOM insights into explainable outputs. It operates under the Aggregation-Only Contract (AOC): no derived intelligence alters or mutates raw facts, and every generated recommendation is paired with verifiable provenance.
|
||
|
||
## 1. Value proposition
|
||
|
||
- **Summaries on demand** – deterministically produce advisory briefs that highlight impact, exploitability, and mitigation steps with paragraph-level citations.
|
||
- **Conflict explainers** – reconcile diverging VEX statements by exposing supplier trust metadata, confidence weights, and precedence logic.
|
||
- **Remediation planning** – merge SBOM timelines, dependency paths, and policy thresholds to propose actionable remediation plans tailored to the requesting tenant.
|
||
- **Offline parity** – the same workflows execute in air-gapped deployments using local inference profiles; cache artefacts can be exported as DSSE bundles for audits.
|
||
|
||
## 2. Architectural highlights
|
||
|
||
| Layer | Responsibilities | Key dependencies |
|
||
|-------|------------------|------------------|
|
||
| Retrievers | Fetch deterministic advisory/VEX/SBOM context, guardrail inputs, policy digests. | Conseiller, Excititor, SBOM Service, Policy Engine |
|
||
| Orchestrator | Builds `AdvisoryTaskPlan` objects (summary/conflict/remediation) with budgets and cache keys. | Deterministic toolset (AIAI-31-003), Authority scopes |
|
||
| Guardrails | Enforce redaction, structured prompts, citation validation, injection defence, and DSSE sealing. | Security Guild guardrail library |
|
||
| Outputs | Persist cache entries (hash + context manifest), expose via API/CLI/Console, emit telemetry. | Mongo cache store, Export Center, Observability stack |
|
||
|
||
See `docs/modules/advisory-ai/architecture.md` for deep technical diagrams and sequence flows.
|
||
|
||
## 3. Guardrails & compliance
|
||
|
||
1. **Aggregation-only** – only raw facts from authorised sources are consumed; no on-the-fly enrichment beyond deterministic tooling.
|
||
2. **Citation-first** – every sentence referencing external evidence must cite a canonical paragraph/statement identifier.
|
||
3. **Content filters** – redaction, policy-based profanity filters, and prompt allowlists are applied before model invocation.
|
||
4. **Deterministic cache** – outputs are stored with `inputDigest` and `outputHash`; force-refresh regenerates the same output unless upstream evidence changes.
|
||
5. **Audit & scope** – Authority scopes (`advisory-ai:view|operate|admin`) plus `aoc:verify` are mandatory; audit events (`advisory_ai.output.generated`, etc.) flow to the Authority ledger.
|
||
|
||
## 4. Supported personas & surfaces
|
||
|
||
| Persona | Typical role | Access |
|
||
|---------|--------------|--------|
|
||
| **Operations engineer** | Reviews summaries/remediation recommendations during incident triage. | Console + `advisory-ai:view` |
|
||
| **Platform engineer** | Automates remediation planning via CI/CD or CLI. | CLI + API + `advisory-ai:operate` |
|
||
| **Security/Compliance** | Audits guardrail decisions, exports outputs for evidence lockers. | API/Export Center + `advisory-ai:view` |
|
||
| **Service owner** | Tunes profiles, remote inference settings, and rate limits. | Authority admin + `advisory-ai:admin` |
|
||
|
||
Surfaces:
|
||
- **Console**: dashboard widgets (pending in CONSOLE-AIAI backlog) render cached summaries and conflicts.
|
||
- **CLI**: `stella advise run <task>` (AIAI-31-004C) for automation scripts.
|
||
- **API**: `/v1/advisory-ai/*` endpoints documented in `docs/advisory-ai/api.md`.
|
||
|
||
## 5. Data sources & provenance
|
||
|
||
- **Advisories** – Conseiller raw observations (CSAF/OSV) with paragraph anchors and supersedes chains.
|
||
- **VEX statements** – Excititor VEX observations plus trust weights provided by VEX Lens.
|
||
- **SBOM context** – SBOM Service timelines and dependency graphs (requires AIAI-31-002 completion).
|
||
- **Policy** – Policy Engine explain traces, waivers, and risk ratings used to contextualise responses.
|
||
- **Runtime posture** – Optional Zastava signals (exposure, admission status) when available.
|
||
|
||
All sources are referenced via content hashes (`content_hash`, `statement_id`, `timeline_entry_id`) ensuring reproducibility.
|
||
|
||
## 6. Profiles & deployment options
|
||
|
||
| Profile | Location | Notes |
|
||
|---------|----------|-------|
|
||
| `default` / `fips-local` | On-prem GPU/CPU | Packaged with Offline Kit; FIPS-approved crypto.
|
||
| `gost-local` | Sovereign clusters | GOST-compliant crypto & model pipeline.
|
||
| `cloud-openai` | Remote (optional) | Disabled by default; requires tenant consent and policy alignment.
|
||
| Custom profiles | Operator-defined | Managed via Authority `advisory-ai` admin APIs and documented policy bundles.
|
||
|
||
Offline deployments mirror prompts, guardrails, and weights within Offline Kits. Remote profiles must pass through Authority consent enforcement and strict allowlists.
|
||
|
||
## 7. Observability & SLOs
|
||
|
||
Metrics (pre-registered in Observability backlog):
|
||
- `advisory_ai_requests_total{tenant,task,profile}`
|
||
- `advisory_ai_latency_seconds_bucket`
|
||
- `advisory_ai_guardrail_blocks_total`
|
||
- `advisory_ai_cache_hits_total`
|
||
|
||
Suggested SLOs (subject to Observability sprint sign-off):
|
||
- P95 latency ≤ 3s for local profiles, ≤ 8s for remote profiles.
|
||
- Guardrail block rate < 1% (investigate above threshold).
|
||
- Cache hit ratio ≥ 60% for repeated advisory requests per tenant.
|
||
|
||
## 8. Roadmap & dependencies
|
||
|
||
| Area | Key tasks |
|
||
|------|----------|
|
||
| API delivery | DOCS-AIAI-31-003 (completed), AIAI-31-004A (service wiring), AIAI-31-006 (public endpoints). |
|
||
| Guardrails | AIAI-31-005, Security Guild reviews, DSSE provenance wiring (AIAI-31-004B). |
|
||
| CLI & Console | AIAI-31-004C (CLI), CONSOLE-AIAI tasks (dashboards, widgets). |
|
||
| Docs | DOCS-AIAI-31-002 (architecture deep-dive), DOCS-AIAI-31-004 (console guide), DOCS-AIAI-31-005 (CLI guide). |
|
||
|
||
## 9. Checklist
|
||
|
||
- [ ] SBOM context retriever (AIAI-31-002) completed and tested across ecosystems.
|
||
- [ ] Guardrail library integrated and security-reviewed.
|
||
- [ ] Authority scopes and consent toggles validated in staging.
|
||
- [ ] Telemetry dashboard reviewed with Observability guild.
|
||
- [ ] Offline kit bundle includes prompts, guardrail configs, local profile weights.
|
||
|
||
---
|
||
|
||
_For questions or contributions, contact the Advisory AI Guild (Slack #guild-advisory-ai) and tag Docs Guild reviewers._
|