audit, advisories and doctors/setup work
This commit is contained in:
master
@@ -0,0 +1,76 @@
|
||||
# Controlled Conversational Interface for Stella Ops
|
||||
|
||||
**Status:** ANALYZED - Sprints Created
|
||||
**Date:** 2026-01-13
|
||||
**Type:** Product Advisory (Advisory AI / Assistant)
|
||||
|
||||
## Executive Summary
|
||||
- Provide an "Ask Stella" conversational interface that is evidence-first and policy-gated.
|
||||
- Enforce guardrails: no secret exfiltration, token and rate budgets, audited actions.
|
||||
- Keep offline parity: local models, deterministic citations, no external calls.
|
||||
|
||||
## New Topics vs Existing Work
|
||||
- Chat Gateway with quotas, scrubber, and policy checks before tool use.
|
||||
- Sanctioned tool registry (read-only default) with explicit confirmation for actions.
|
||||
- Immutable audit log of prompts, redactions, tool calls, and model fingerprints.
|
||||
- CLI parity: `stella advise "<question>" --evidence --no-action`.
|
||||
- Policy lattice for tool permissions and action approvals.
|
||||
|
||||
## Safe Default Architecture
|
||||
- **Chat Gateway (API):** Authority auth, quotas (user/org), scrubber, policy check, action confirmation.
|
||||
- **Local LLM Orchestrator:** tool schema only, no free-form shell, deterministic defaults.
|
||||
- **Sanctioned Plugins:** read-only by default; action tools require confirmation + policy allow.
|
||||
- **Audit Log:** Postgres system of record; optional DSSE signatures; Valkey for ephemeral cache.
|
||||
|
||||
## Minimal Plugin Surface (v1)
|
||||
- Read-only tools: `vex.query`, `sbom.read`, `scanner.findings.topk`.
|
||||
- Explain tools: `explain.finding`, `prioritize`, `suggest.fix` (no execution).
|
||||
- Action tools (opt-in): `scanner.rescan`, `orchestrator.create.ticket` (require confirmation + policy allow).
|
||||
|
||||
## Policy and Safety Requirements
|
||||
- No secrets ever: vault metadata only, scrubber strips tokens/keys/ASN, entropy filter, allowlist.
|
||||
- Budgets: tokens, requests/min, tool invocations/day per user/org.
|
||||
- Tool least-privilege: separate roles per plugin, read vs write paths.
|
||||
- Offline-ready: local models only; no external calls.
|
||||
- Deterministic windows: low temperature for factual responses; narrow expansions for drafts.
|
||||
|
||||
## Data Contracts (Sketch)
|
||||
- Tool I/O is JSON with stable schemas.
|
||||
- Each tool result includes `object_ref`, `hash`, and `evidence[]`.
|
||||
|
||||
Example tool response:
|
||||
```json
|
||||
{
|
||||
"tool": "vex.query",
|
||||
"object_ref": "vex:issuer:sha256:abc123",
|
||||
"hash": "sha256:deadbeef...",
|
||||
"evidence": [
|
||||
{ "type": "vex", "ref": "vex:issuer:sha256:abc123" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Example Flow (Why a CVE still appears)
|
||||
1. Gateway scrubs input -> orchestrator calls `vex.query`, `sbom.read`, `reachability.graph.query`.
|
||||
2. Policy check allows read-only tools.
|
||||
3. Response cites evidence (attestation, diff sig, VEX status, reachability).
|
||||
|
||||
## First Cut (1 Week)
|
||||
1. Gateway: auth, quotas, scrubber, audit log.
|
||||
2. Orchestrator: three read-only plugins (`vex.query`, `sbom.read`, `scanner.findings.topk`).
|
||||
3. Advisor UI panel with citations; CLI `stella advise` (no action by default).
|
||||
4. Policy v0: deny all actions; allow read-only tools in a sample namespace.
|
||||
5. One curated intent: "Explain why this CVE still appears" with evidence chain.
|
||||
|
||||
## Defaults to Apply
|
||||
- Hybrid reachability posture (graph DSSE required; edge-bundle DSSE optional).
|
||||
- Deterministic outputs only.
|
||||
- Offline-friendly operation with frozen feeds.
|
||||
|
||||
## De-duplication
|
||||
Extends (not supersedes):
|
||||
- `docs-archived/product/advisories/26-Dec-2025 - AI Assistant as Proof-Carrying Evidence Engine.md`
|
||||
- `docs-archived/product/advisories/30-Dec-2025 - Evidence-Gated AI Explanations.md`
|
||||
- `docs-archived/product/advisories/26-Dec-2025 - AI Surfacing UX Patterns.md`
|
||||
|
||||
Overlap: evidence-grounded outputs, UI patterns. New content: chat gateway quotas, tool sanctions, audit log schema, CLI parity, policy lattice for tool access.
|
||||
@@ -0,0 +1,105 @@
|
||||
# Advisory - Release Orchestrator Doctor Self Service
|
||||
|
||||
**Date:** 2026-01-13
|
||||
**Status:** Draft
|
||||
**Scope:** Release Orchestrator, Doctor CLI/UI, Integration Hub
|
||||
**Supersedes/Extends:** None
|
||||
|
||||
## Summary
|
||||
- Doctor is a self-service diagnostics runner for integrations and modules.
|
||||
- Auto-discover what is installed, run deterministic checks, explain failures, and print exact fix commands.
|
||||
- Output includes JSONL evidence logs and an optional DSSE signed summary for audits.
|
||||
|
||||
## Goals
|
||||
- Auto-discover checks via installed packs and plugins.
|
||||
- Deterministic results with explicit evidence and root causes.
|
||||
- CLI-first remediation; UI mirrors commands verbatim.
|
||||
- Offline friendly by default (local JSONL; outbound telemetry opt-in only).
|
||||
|
||||
## Extension Points
|
||||
|
||||
### Core
|
||||
- Doctor runner: CLI `stella doctor run` and UI "Doctor" panel.
|
||||
- Evidence log: JSONL report plus DSSE summary.
|
||||
- Remediation printer: `how_to_fix.commands[]` for every check.
|
||||
|
||||
### SCM (GitLab/GitHub/Gitea)
|
||||
- Webhook reachability, secret token, event list (push/tag/release).
|
||||
- Branch policies: protected branches, required reviews/status checks.
|
||||
- PAT/OIDC auth scopes: verify least-privilege tokens.
|
||||
- Repo access: bot user/CI user has required permissions.
|
||||
|
||||
### Registry + SBOM Ingestion
|
||||
- OCI endpoints reachable; auth works (robot accounts supported).
|
||||
- Push/pull for test artifact; verify manifest + attestation (Rekor mirror if present).
|
||||
- SBOM/VEX ingestion path working (CycloneDX/SPDX sample accept).
|
||||
|
||||
### Secrets/Vault
|
||||
- Vault URL/TLS/PKI valid; AppRole/JWT/OIDC login succeeds.
|
||||
- KV engine mounted and policy grants read/list where expected.
|
||||
- Expiring secrets alert (Doctor warns and prints rotation command).
|
||||
|
||||
### LDAP / Authority
|
||||
- Bind works (SASL/StartTLS/LDAPS); search base + filter validated.
|
||||
- Attribute mapping sanity (uid/email/groups to roles).
|
||||
- Test user roundtrip: resolve -> login -> role computed.
|
||||
|
||||
### Migrations
|
||||
- Pending DB migrations detected; simulate -> apply dry-run hash.
|
||||
- Rollback path available; print safe apply order for multi-service stacks.
|
||||
|
||||
### Policy Engine / Gates
|
||||
- Sample policy pack loads; failing sample emits deterministic proof.
|
||||
- Gate wiring: pre-deploy blocks on criticals; override requires reason + signature.
|
||||
|
||||
### Telemetry (Optional, Air-Gap Safe)
|
||||
- Local JSONL only by default; outbound disabled unless opted in.
|
||||
|
||||
## Declarative Doctor Packs
|
||||
Doctor packs can be declared as YAML manifests and executed by the CLI or service.
|
||||
- Location: `plugins/doctor/*.yaml`
|
||||
- Discovery: `spec.discovery.when` uses env or file checks.
|
||||
- Check execution: `run.exec`, `parse.expect`, `parse.expectJson`.
|
||||
- Remediation: `how_to_fix.commands[]` printed verbatim.
|
||||
|
||||
Sample manifest:
|
||||
- `docs/benchmarks/doctor/doctor-plugin-release-orchestrator-gitlab.yaml`
|
||||
|
||||
Short snippet:
|
||||
```yaml
|
||||
apiVersion: stella.ops/doctor.v1
|
||||
kind: DoctorPlugin
|
||||
metadata:
|
||||
name: doctor-release-orchestrator-gitlab
|
||||
spec:
|
||||
discovery:
|
||||
when:
|
||||
- env: GITLAB_URL
|
||||
```
|
||||
|
||||
## CLI Scaffolding (Stable Names)
|
||||
```bash
|
||||
# Run all checks for orchestrator integrations
|
||||
stella doctor run --pack orchestrator --format table
|
||||
|
||||
# Run GitLab pack, JSON for agents
|
||||
stella doctor run --plugin doctor-release-orchestrator-gitlab --format json > out.json
|
||||
|
||||
# Execute proposed fixes interactively (dry-run by default)
|
||||
stella doctor fix --from out.json --apply
|
||||
```
|
||||
|
||||
## UI Contract
|
||||
- Doctor page lists packs -> plugins -> checks.
|
||||
- Each check shows status, evidence, Copy Fix Commands, and Run Fix (guarded by `doctor.fix.enabled=true`).
|
||||
- Export: Download DSSE Report and Download JSON.
|
||||
|
||||
## Open TODOs
|
||||
- Add `plugins/doctor/*.yaml` for GitLab, GitHub, Gitea, Harbor/OCI, Vault, LDAP.
|
||||
- Implement `stella doctor run|fix` with the `parse.expect/expectJson` contract.
|
||||
- Wire UI to read the same JSON schema and render commands verbatim.
|
||||
- Ship two sample SBOMs (CycloneDX 1.6 + SPDX 3.0.1) under `samples/`.
|
||||
|
||||
## References
|
||||
- `docs/doctor/doctor-capabilities.md`
|
||||
- `docs/modules/release-orchestrator/modules/integration-hub.md`
|
||||
Reference in New Issue
Block a user