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

audit, advisories and doctors/setup work

Browse Source
This commit is contained in:
master
2026-01-13 18:53:39 +02:00
parent 9ca7cb183e
commit d7be6ba34b
811 changed files with 54242 additions and 4056 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/doctor/README.md
View File

@@ -27,11 +27,15 @@ stella doctor --category database
# Export report for support
stella doctor export --output diagnostic-bundle.zip
# Apply safe fixes from a report (dry-run by default)
stella doctor fix --from doctor-report.json --apply
```
### UI
Navigate to `/ops/doctor` in the Stella Ops console to access the interactive Doctor Dashboard.
Fix actions are exposed in the UI and mirror CLI commands; destructive steps are never executed by Doctor.
### API

31
docs/doctor/cli-reference.md
View File

@@ -16,9 +16,10 @@ stella doctor [options]
| Option | Short | Type | Default | Description |
|--------|-------|------|---------|-------------|
| `--format` | `-f` | enum | `text` | Output format: `text`, `json`, `markdown` |
| `--format` | `-f` | enum | `text` | Output format: `text`, `table`, `json`, `markdown` |
| `--quick` | `-q` | flag | false | Run only quick checks (tagged `quick`) |
| `--full` | | flag | false | Run all checks including slow/intensive |
| `--pack` | | string[] | all | Filter by pack name (manifest grouping) |
| `--category` | `-c` | string[] | all | Filter by category |
| `--plugin` | `-p` | string[] | all | Filter by plugin ID |
| `--check` | | string | | Run single check by ID |
@@ -71,6 +72,34 @@ stella doctor --verbose
stella doctor --timeout 60s --parallel 2
```
### stella doctor fix
Apply non-destructive fixes from a Doctor report.
```bash
stella doctor fix --from report.json [--apply]
```
#### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--from` | path | required | Path to JSON report with `how_to_fix` commands |
| `--apply` | flag | false | Execute fixes (default is dry-run preview) |
Doctor only executes non-destructive commands. If a fix requires a destructive
change, it is printed as manual guidance and not executed by Doctor.
#### Examples
```bash
# Preview fixes (dry-run)
stella doctor fix --from doctor-report.json
# Apply safe fixes
stella doctor fix --from doctor-report.json --apply
```
### stella doctor export
Generate a diagnostic bundle for support.

116
docs/doctor/doctor-capabilities.md
View File

@@ -48,6 +48,7 @@ The Doctor capability provides comprehensive self-service diagnostics for Stella
3. **Zero Docs Familiarity** - Users can diagnose and fix without reading documentation
4. **Evidence-Based Diagnostics** - All checks collect and report evidence
5. **Multi-Surface Consistency** - Same check engine powers CLI, UI, and API
6. **Non-Destructive Fixes** - Doctor never executes destructive actions; fix commands must be safe and idempotent
### 1.4 Surfaces
@@ -749,7 +750,32 @@ public class DoctorPluginLoader
}
```
### 4.5 Plugin Directory Structure
### 4.5 Declarative Doctor Packs (YAML)
Doctor packs provide declarative checks that wrap CLI commands and parsing rules.
They complement compiled plugins and are loaded from `plugins/doctor/*.yaml` (plus optional override directories).
Short example:
```yaml
apiVersion: stella.ops/doctor.v1
kind: DoctorPlugin
metadata:
name: doctor-release-orchestrator-gitlab
spec:
discovery:
when:
- env: GITLAB_URL
```
Full sample: `docs/benchmarks/doctor/doctor-plugin-release-orchestrator-gitlab.yaml`
Key fields:
- `spec.discovery.when`: env/file existence gates.
- `checks[].run.exec`: command to execute (must be deterministic).
- `checks[].parse.expect` or `checks[].parse.expectJson`: pass/fail rules.
- `checks[].how_to_fix.commands[]`: exact fix commands printed verbatim.
### 4.6 Plugin Directory Structure
```
src/
@@ -770,7 +796,7 @@ src/
│ └── StellaOps.Doctor.Plugin.Observability/
```
### 4.6 Plugin Configuration
### 4.7 Plugin Configuration
Plugins read configuration from the standard config hierarchy:
@@ -807,7 +833,7 @@ Doctor:
- "secret/data/stellaops/certificates"
```
### 4.7 Security Model
### 4.8 Security Model
#### Secret Redaction
@@ -853,7 +879,7 @@ Doctor checks require specific scopes:
| `doctor:export` | Export diagnostic reports |
| `admin:system` | Access system-level checks |
### 4.8 Versioning Strategy
### 4.9 Versioning Strategy
- **Engine version:** Semantic versioning (e.g., `1.0.0`)
- **Plugin version:** Independent semantic versioning
@@ -880,16 +906,24 @@ if (plugin.MinEngineVersion > DoctorEngine.Version)
**Proposed Location:** `src/Cli/StellaOps.Cli/Commands/DoctorCommandGroup.cs`
```bash
stella doctor [options]
stella doctor run [options]
stella doctor list [options]
stella doctor fix --from report.json [--apply]
```
Note: `stella doctor` remains shorthand for `stella doctor run` for compatibility.
`stella doctor fix` executes only non-destructive commands. Any destructive step
must be presented as manual guidance and is not eligible for `--apply`.
### 5.2 Options and Flags
| Option | Short | Type | Default | Description |
|--------|-------|------|---------|-------------|
| `--format` | `-f` | enum | `text` | Output format: `text`, `json`, `markdown` |
| `--format` | `-f` | enum | `text` | Output format: `text`, `table`, `json`, `markdown` |
| `--quick` | `-q` | flag | false | Run only quick checks (tagged `quick`) |
| `--full` | | flag | false | Run all checks including slow/intensive |
| `--pack` | | string[] | all | Filter by pack name (manifest grouping) |
| `--category` | `-c` | string[] | all | Filter by category: `core`, `database`, `service-graph`, `integration`, `security`, `observability` |
| `--plugin` | `-p` | string[] | all | Filter by plugin ID (e.g., `scm.github`) |
| `--check` | | string | | Run single check by ID |
@@ -901,6 +935,16 @@ stella doctor [options]
| `--verbose` | `-v` | flag | false | Include detailed evidence in output |
| `--tenant` | | string | | Tenant context for multi-tenant checks |
#### Fix Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--from` | path | required | Path to JSON report with `how_to_fix` commands |
| `--apply` | flag | false | Execute fixes (default is dry-run preview) |
Only commands marked safe and non-destructive are eligible for `--apply`.
Destructive changes must be printed as manual steps and executed by the operator outside Doctor.
### 5.3 Exit Codes
| Code | Meaning |
@@ -915,9 +959,12 @@ stella doctor [options]
### 5.4 Usage Examples
```bash
# Quick health check (default)
# Quick health check (alias)
stella doctor
# Run all checks explicitly
stella doctor run
# Full diagnostic
stella doctor --full
@@ -933,6 +980,12 @@ stella doctor --check check.database.migrations.pending
# JSON output for CI/CD
stella doctor --format json --severity fail,warn
# Run orchestrator pack with table output
stella doctor run --pack orchestrator --format table
# Apply fixes from a JSON report (dry-run unless --apply)
stella doctor fix --from out.json --apply
# Export markdown report
stella doctor --full --format markdown --export doctor-report.md
@@ -1133,7 +1186,13 @@ src/app/features/doctor/
+------------------------------------------------------------------+
```
### 6.5 Real-Time Updates
### 6.5 Pack Navigation and Fix Actions
- Navigation hierarchy: packs -> plugins -> checks.
- Each check shows status, evidence, Copy Fix Commands, and Run Fix (disabled unless `doctor.fix.enabled=true`).
- Export actions: Download JSON and Download DSSE summary.
### 6.6 Real-Time Updates
- **Polling:** Auto-refresh option (every 30s/60s/5m)
- **SSE:** Live check progress during execution
@@ -1287,6 +1346,9 @@ GET /api/v1/doctor/run/dr_20260112_143052_abc123
}
```
Results also expose a `how_to_fix` object for automation. It is a simplified alias of
the richer `remediation` model and includes `commands[]` printed verbatim.
### 7.3 SSE Stream
```http
@@ -1311,10 +1373,28 @@ event: run-completed
data: {"runId":"dr_20260112_143052_abc123","summary":{"passed":44,"warnings":2,"failed":1}}
```
### 7.4 Evidence Logs and Attestations
Doctor runs emit a JSONL evidence log and optional DSSE summary for audit trails.
By default, JSONL is local only and deterministic; outbound telemetry is opt-in.
- JSONL path: `artifacts/doctor/doctor-run-<runId>.ndjson` (configurable).
- DSSE summary: `artifacts/doctor/doctor-run-<runId>.dsse.json` (optional).
- Evidence records include `doctor_command` to capture the operator-invoked command.
DSSE summaries assume operator execution and must include the same command note.
Example JSONL line:
```json
{"runId":"dr_20260112_143052_abc123","doctor_command":"stella doctor run --format json","checkId":"check.database.connectivity","severity":"pass","executedAt":"2026-01-12T14:30:52Z","how_to_fix":{"commands":[]}}
```
---
## 8. Remediation Command Patterns
Remediation should favor the best operator experience: short, copy/paste friendly
commands with minimal steps and clear verification guidance.
### 8.1 Standard Output Format
Every failed check produces remediation in this structure:
@@ -1345,6 +1425,20 @@ Every failed check produces remediation in this structure:
{command to re-run this specific check}
```
### 8.1.1 JSON Remediation Structure
The JSON output MUST include a `how_to_fix` object for agent consumption. It can be
derived from `remediation.steps` and preserves command order.
```json
"how_to_fix": {
"summary": "Apply baseline branch policy",
"commands": [
"stella orchestrator scm apply-branch-policy --preset strict"
]
}
```
### 8.2 Placeholder Conventions
When commands require user-specific values:
@@ -1363,10 +1457,12 @@ When commands require user-specific values:
### 8.3 Safety Notes
Commands that modify data include safety guidance:
Doctor fix executes only non-destructive commands. If a fix requires a change
that modifies data, Doctor must present it as manual guidance with explicit
safety notes and never execute it.
```
Fix Steps:
Manual Steps (not executed by Doctor):
# SAFETY: This operation modifies the database. Create a backup first.
# 1. Backup database (REQUIRED before proceeding)