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

doctor: complete runtime check documentation sprint

Browse Source 
Signed-off-by: master <>
This commit is contained in:
master
2026-03-31 23:26:24 +03:00
parent 404d50bcb7
commit 152c1b1357
54 changed files with 2210 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
docs/modules/doctor/checks/README.md Normal file
View File

@@ -0,0 +1,188 @@
# Doctor Runtime Check Index
## Scope
- Runtime catalog source: `GET /api/v1/doctor/checks` on 2026-03-31.
- Docker compose baseline source: run `dr_20260331_195122_99ff09` captured from the locally running default stack.
- Canonical remediation content lives in `docs/doctor/articles/**`; this index maps the live runtime catalog to those articles.
## Runtime Summary
| Plugin | Checks |
| --- | ---: |
| `stellaops.doctor.attestation` | 3 |
| `stellaops.doctor.binaryanalysis` | 6 |
| `stellaops.doctor.compliance` | 7 |
| `stellaops.doctor.core` | 9 |
| `stellaops.doctor.database` | 8 |
| `stellaops.doctor.docker` | 5 |
| `stellaops.doctor.environment` | 6 |
| `stellaops.doctor.integration` | 16 |
| `stellaops.doctor.observability` | 6 |
| `stellaops.doctor.release` | 6 |
| `stellaops.doctor.scanner` | 7 |
| `stellaops.doctor.security` | 11 |
| `stellaops.doctor.servicegraph` | 6 |
| `stellaops.doctor.verification` | 5 |
## Baseline Legend
- `pass`: expected healthy result in the captured compose baseline.
- `info`: informational only; not a release blocker in the captured baseline.
- `warn`: action needed or recommended; not a hard failure in the captured baseline.
- `fail`: baseline failure observed in the captured runtime.
- `skip`: not applicable in the captured runtime context.
## `stellaops.doctor.attestation`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.attestation.clock.skew` | `warn` | `warn` | [article](../../../doctor/articles/attestor/clock-skew.md) |
| `check.attestation.cosign.keymaterial` | `fail` | `skip` | [article](../../../doctor/articles/attestor/cosign-keymaterial.md) |
| `check.attestation.rekor.connectivity` | `fail` | `skip` | [article](../../../doctor/articles/attestor/rekor-connectivity.md) |
## `stellaops.doctor.binaryanalysis`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.binaryanalysis.buildinfo.cache` | `warn` | `warn` | [article](../../../doctor/articles/binary-analysis/buildinfo-cache.md) |
| `check.binaryanalysis.corpus.kpi.baseline` | `warn` | `warn` | [article](../../../doctor/articles/binary-analysis/kpi-baseline-exists.md) |
| `check.binaryanalysis.corpus.mirror.freshness` | `warn` | `warn` | [article](../../../doctor/articles/binary-analysis/corpus-mirror-freshness.md) |
| `check.binaryanalysis.ddeb.enabled` | `warn` | `warn` | [article](../../../doctor/articles/binary-analysis/ddeb-repo-enabled.md) |
| `check.binaryanalysis.debuginfod.available` | `warn` | `info` | [article](../../../doctor/articles/binary-analysis/debuginfod-availability.md) |
| `check.binaryanalysis.symbol.recovery.fallback` | `warn` | `info` | [article](../../../doctor/articles/binary-analysis/symbol-recovery-fallback.md) |
## `stellaops.doctor.compliance`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.compliance.attestation-signing` | `fail` | `skip` | [article](../../../doctor/articles/compliance/attestation-signing.md) |
| `check.compliance.audit-readiness` | `warn` | `skip` | [article](../../../doctor/articles/compliance/audit-readiness.md) |
| `check.compliance.evidence-integrity` | `fail` | `skip` | [article](../../../doctor/articles/compliance/evidence-integrity.md) |
| `check.compliance.evidence-rate` | `fail` | `skip` | [article](../../../doctor/articles/compliance/evidence-rate.md) |
| `check.compliance.export-readiness` | `warn` | `skip` | [article](../../../doctor/articles/compliance/export-readiness.md) |
| `check.compliance.framework` | `warn` | `skip` | [article](../../../doctor/articles/compliance/framework.md) |
| `check.compliance.provenance-completeness` | `fail` | `skip` | [article](../../../doctor/articles/compliance/provenance-completeness.md) |
## `stellaops.doctor.core`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.core.auth.config` | `warn` | `skip` | [article](../../../doctor/articles/core/auth-config.md) |
| `check.core.config.loaded` | `fail` | `pass` | [article](../../../doctor/articles/core/config-loaded.md) |
| `check.core.config.required` | `fail` | `fail` | [article](../../../doctor/articles/core/config-required.md) |
| `check.core.crypto.available` | `fail` | `pass` | [article](../../../doctor/articles/core/crypto-available.md) |
| `check.core.env.diskspace` | `fail` | `pass` | [article](../../../doctor/articles/core/env-diskspace.md) |
| `check.core.env.memory` | `warn` | `pass` | [article](../../../doctor/articles/core/env-memory.md) |
| `check.core.env.variables` | `warn` | `warn` | [article](../../../doctor/articles/core/env-variables.md) |
| `check.core.services.dependencies` | `fail` | `pass` | [article](../../../doctor/articles/core/services-dependencies.md) |
| `check.core.services.health` | `fail` | `skip` | [article](../../../doctor/articles/core/services-health.md) |
## `stellaops.doctor.database`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.db.connection` | `fail` | `skip` | [article](../../../doctor/articles/postgres/db-connection.md) |
| `check.db.latency` | `fail` | `skip` | [article](../../../doctor/articles/postgres/db-latency.md) |
| `check.db.migrations.failed` | `fail` | `skip` | [article](../../../doctor/articles/postgres/db-migrations-failed.md) |
| `check.db.migrations.pending` | `warn` | `skip` | [article](../../../doctor/articles/postgres/db-migrations-pending.md) |
| `check.db.permissions` | `fail` | `skip` | [article](../../../doctor/articles/postgres/db-permissions.md) |
| `check.db.pool.health` | `fail` | `skip` | [article](../../../doctor/articles/postgres/db-pool-health.md) |
| `check.db.pool.size` | `warn` | `skip` | [article](../../../doctor/articles/postgres/db-pool-size.md) |
| `check.db.schema.version` | `fail` | `skip` | [article](../../../doctor/articles/postgres/db-schema-version.md) |
## `stellaops.doctor.docker`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.docker.apiversion` | `warn` | `skip` | [article](../../../doctor/articles/docker/apiversion.md) |
| `check.docker.daemon` | `fail` | `fail` | [article](../../../doctor/articles/docker/daemon.md) |
| `check.docker.network` | `warn` | `skip` | [article](../../../doctor/articles/docker/network.md) |
| `check.docker.socket` | `fail` | `fail` | [article](../../../doctor/articles/docker/socket.md) |
| `check.docker.storage` | `warn` | `skip` | [article](../../../doctor/articles/docker/storage.md) |
## `stellaops.doctor.environment`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.environment.capacity` | `warn` | `skip` | [article](../../../doctor/articles/environment/environment-capacity.md) |
| `check.environment.connectivity` | `warn` | `skip` | [article](../../../doctor/articles/environment/environment-connectivity.md) |
| `check.environment.deployments` | `warn` | `skip` | [article](../../../doctor/articles/environment/environment-deployment-health.md) |
| `check.environment.drift` | `warn` | `skip` | [article](../../../doctor/articles/environment/environment-drift.md) |
| `check.environment.network.policy` | `warn` | `skip` | [article](../../../doctor/articles/environment/environment-network-policy.md) |
| `check.environment.secrets` | `warn` | `skip` | [article](../../../doctor/articles/environment/environment-secret-health.md) |
## `stellaops.doctor.integration`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.integration.ci.system` | `warn` | `skip` | [article](../../../doctor/articles/integration/ci-system-connectivity.md) |
| `check.integration.git` | `warn` | `skip` | [article](../../../doctor/articles/integration/git-provider-api.md) |
| `check.integration.ldap` | `warn` | `skip` | [article](../../../doctor/articles/integration/ldap-connectivity.md) |
| `check.integration.oci.capabilities` | `info` | `skip` | [article](../../../doctor/articles/integration/registry-capability-probe.md) |
| `check.integration.oci.credentials` | `fail` | `skip` | [article](../../../doctor/articles/integration/registry-credentials.md) |
| `check.integration.oci.pull` | `fail` | `skip` | [article](../../../doctor/articles/integration/registry-pull-authorization.md) |
| `check.integration.oci.push` | `fail` | `skip` | [article](../../../doctor/articles/integration/registry-push-authorization.md) |
| `check.integration.oci.referrers` | `warn` | `skip` | [article](../../../doctor/articles/integration/registry-referrers-api.md) |
| `check.integration.oci.registry` | `warn` | `skip` | [article](../../../doctor/articles/integration/oci-registry-connectivity.md) |
| `check.integration.oidc` | `warn` | `skip` | [article](../../../doctor/articles/integration/oidc-provider.md) |
| `check.integration.s3.storage` | `warn` | `skip` | [article](../../../doctor/articles/integration/object-storage.md) |
| `check.integration.secrets.manager` | `fail` | `skip` | [article](../../../doctor/articles/integration/secrets-manager-connectivity.md) |
| `check.integration.slack` | `info` | `skip` | [article](../../../doctor/articles/integration/slack-webhook.md) |
| `check.integration.smtp` | `warn` | `skip` | [article](../../../doctor/articles/integration/smtp-connectivity.md) |
| `check.integration.teams` | `info` | `skip` | [article](../../../doctor/articles/integration/teams-webhook.md) |
| `check.integration.webhooks` | `warn` | `skip` | [article](../../../doctor/articles/integration/webhook-health.md) |
## `stellaops.doctor.observability`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.observability.alerting` | `info` | `info` | [article](../../../doctor/articles/observability/observability-alerting.md) |
| `check.observability.healthchecks` | `warn` | `pass` | [article](../../../doctor/articles/observability/observability-healthchecks.md) |
| `check.observability.logging` | `warn` | `warn` | [article](../../../doctor/articles/observability/observability-logging.md) |
| `check.observability.metrics` | `warn` | `info` | [article](../../../doctor/articles/observability/observability-metrics.md) |
| `check.observability.otel` | `warn` | `info` | [article](../../../doctor/articles/observability/observability-otel.md) |
| `check.observability.tracing` | `warn` | `pass` | [article](../../../doctor/articles/observability/observability-tracing.md) |
## `stellaops.doctor.release`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.release.active` | `warn` | `skip` | [article](../../../doctor/articles/release/active.md) |
| `check.release.configuration` | `warn` | `skip` | [article](../../../doctor/articles/release/configuration.md) |
| `check.release.environment.readiness` | `warn` | `skip` | [article](../../../doctor/articles/release/environment-readiness.md) |
| `check.release.promotion.gates` | `warn` | `skip` | [article](../../../doctor/articles/release/promotion-gates.md) |
| `check.release.rollback.readiness` | `warn` | `skip` | [article](../../../doctor/articles/release/rollback-readiness.md) |
| `check.release.schedule` | `info` | `skip` | [article](../../../doctor/articles/release/schedule.md) |
## `stellaops.doctor.scanner`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.scanner.queue` | `warn` | `skip` | [article](../../../doctor/articles/scanner/queue.md) |
| `check.scanner.reachability` | `warn` | `skip` | [article](../../../doctor/articles/scanner/reachability.md) |
| `check.scanner.resources` | `warn` | `skip` | [article](../../../doctor/articles/scanner/resources.md) |
| `check.scanner.sbom` | `warn` | `skip` | [article](../../../doctor/articles/scanner/sbom.md) |
| `check.scanner.slice.cache` | `warn` | `skip` | [article](../../../doctor/articles/scanner/slice-cache.md) |
| `check.scanner.vuln` | `warn` | `skip` | [article](../../../doctor/articles/scanner/vuln.md) |
| `check.scanner.witness.graph` | `warn` | `skip` | [article](../../../doctor/articles/scanner/witness-graph.md) |
## `stellaops.doctor.security`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.security.apikey` | `warn` | `skip` | [article](../../../doctor/articles/security/apikey.md) |
| `check.security.audit.logging` | `warn` | `warn` | [article](../../../doctor/articles/security/audit-logging.md) |
| `check.security.cors` | `warn` | `warn` | [article](../../../doctor/articles/security/cors.md) |
| `check.security.encryption` | `warn` | `skip` | [article](../../../doctor/articles/security/encryption.md) |
| `check.security.evidence.integrity` | `fail` | `skip` | [article](../../../doctor/articles/security/evidence-integrity.md) |
| `check.security.headers` | `warn` | `warn` | [article](../../../doctor/articles/security/headers.md) |
| `check.security.jwt.config` | `fail` | `skip` | [article](../../../doctor/articles/security/jwt-config.md) |
| `check.security.password.policy` | `warn` | `skip` | [article](../../../doctor/articles/security/password-policy.md) |
| `check.security.ratelimit` | `warn` | `info` | [article](../../../doctor/articles/security/ratelimit.md) |
| `check.security.secrets` | `fail` | `fail` | [article](../../../doctor/articles/security/secrets.md) |
| `check.security.tls.certificate` | `fail` | `pass` | [article](../../../doctor/articles/security/tls-certificate.md) |
## `stellaops.doctor.servicegraph`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.servicegraph.backend` | `fail` | `skip` | [article](../../../doctor/articles/servicegraph/servicegraph-backend.md) |
| `check.servicegraph.circuitbreaker` | `warn` | `info` | [article](../../../doctor/articles/servicegraph/servicegraph-circuitbreaker.md) |
| `check.servicegraph.endpoints` | `fail` | `skip` | [article](../../../doctor/articles/servicegraph/servicegraph-endpoints.md) |
| `check.servicegraph.mq` | `warn` | `skip` | [article](../../../doctor/articles/servicegraph/servicegraph-mq.md) |
| `check.servicegraph.timeouts` | `warn` | `pass` | [article](../../../doctor/articles/servicegraph/servicegraph-timeouts.md) |
| `check.servicegraph.valkey` | `warn` | `pass` | [article](../../../doctor/articles/servicegraph/servicegraph-valkey.md) |
## `stellaops.doctor.verification`
| Check ID | Severity | Baseline | Article |
| --- | --- | --- | --- |
| `check.verification.artifact.pull` | `fail` | `skip` | [article](../../../doctor/articles/verification/verification-artifact-pull.md) |
| `check.verification.policy.engine` | `fail` | `skip` | [article](../../../doctor/articles/verification/verification-policy-engine.md) |
| `check.verification.sbom.validation` | `fail` | `skip` | [article](../../../doctor/articles/verification/verification-sbom-validation.md) |
| `check.verification.signature` | `fail` | `skip` | [article](../../../doctor/articles/verification/verification-signature.md) |
| `check.verification.vex.validation` | `fail` | `skip` | [article](../../../doctor/articles/verification/verification-vex-validation.md) |

77
docs/modules/doctor/compose-baseline.md Normal file
View File

@@ -0,0 +1,77 @@
# Doctor Compose Baseline
## Evidence
- Runtime source: local default stack reachable at `http://127.1.0.26/api/v1/doctor`.
- Catalog snapshot: `GET /api/v1/doctor/checks` on 2026-03-31.
- Baseline run: `dr_20260331_195122_99ff09`.
- Duration: `12103ms`.
## Baseline Summary
| Status | Count |
| --- | ---: |
| `pass` | 10 |
| `info` | 7 |
| `warn` | 10 |
| `fail` | 4 |
| `skip` | 70 |
| `total` | 101 |
## Capture Notes
- This baseline was captured from the locally running default compose stack, not from a second fresh stack.
- A parallel `docker compose up` was not used because `devops/compose/docker-compose.stella-ops.yml` hardcodes container names, which would conflict with the already running environment.
- The runtime catalog currently exposes `101` checks across `14` plugins. That supersedes the stale sprint text that still referenced `99` checks across `16` plugins.
## Observed Failures
| Check ID | Diagnosis | Notes |
| --- | --- | --- |
| `check.core.config.required` | Missing 2 required setting(s) | Missing `ConnectionStrings:DefaultConnection` and `Logging:LogLevel:Default` in the captured runtime. |
| `check.docker.daemon` | Cannot connect to Docker daemon: Connection failed | Doctor ran without a reachable Docker daemon socket. |
| `check.docker.socket` | 1 Docker socket issue(s) | `/var/run/docker.sock` was absent in the captured container context. |
| `check.security.secrets` | 2 secrets management issue(s) found | The runtime reported no secrets provider plus a potential plain-text connection string. |
## Observed Warnings
| Check ID | Diagnosis |
| --- | --- |
| `check.attestation.clock.skew` | System clock is off by 5.5 seconds (threshold: 5s) |
| `check.binaryanalysis.buildinfo.cache` | Debian buildinfo services are reachable but cache directory does not exist |
| `check.binaryanalysis.corpus.kpi.baseline` | KPI baseline directory does not exist: `/var/lib/stella/baselines` |
| `check.binaryanalysis.corpus.mirror.freshness` | Corpus mirrors directory does not exist: `/var/lib/stella/mirrors` |
| `check.binaryanalysis.ddeb.enabled` | Ubuntu ddeb repository is not configured but `ddebs.ubuntu.com` is reachable |
| `check.core.env.variables` | No environment configuration variables detected |
| `check.observability.logging` | 1 logging configuration issue(s) |
| `check.security.audit.logging` | 2 audit logging issue(s) |
| `check.security.cors` | 1 CORS configuration issue(s) found |
| `check.security.headers` | 5 security header(s) not configured |
## Observed Informational Results
| Check ID | Diagnosis |
| --- | --- |
| `check.binaryanalysis.debuginfod.available` | `DEBUGINFOD_URLS` not configured but default Fedora debuginfod is reachable |
| `check.binaryanalysis.symbol.recovery.fallback` | Symbol recovery operational with 1/3 sources available |
| `check.observability.alerting` | No alerting destinations configured |
| `check.observability.metrics` | Metrics configuration not found |
| `check.observability.otel` | OpenTelemetry endpoint not configured |
| `check.security.ratelimit` | Rate limiting configuration not found |
| `check.servicegraph.circuitbreaker` | Circuit breakers not configured |
## Healthy Baseline Results
The captured runtime returned `pass` for:
- `check.core.config.loaded`
- `check.core.crypto.available`
- `check.core.env.diskspace`
- `check.core.env.memory`
- `check.core.services.dependencies`
- `check.observability.healthchecks`
- `check.observability.tracing`
- `check.security.tls.certificate`
- `check.servicegraph.timeouts`
- `check.servicegraph.valkey`
## Skipped Checks
- `70` checks were skipped because the captured local stack did not provide the required runtime context, credentials, test artifacts, or dependent services.
- Skips are expected for the database, integration, release, scanner, and verification groups when the default local stack is not fully wired for end-to-end release validation.
## Follow-Up
- Use [the runtime check index](./checks/README.md) to map each runtime check to its article.
- Rebuild and rerun the Doctor services before claiming a fresh-stack zero-false-positive baseline; this document only records the captured live baseline from 2026-03-31.