doctor: complete runtime check documentation sprint
Signed-off-by: master <>
This commit is contained in:
master
@@ -0,0 +1,56 @@
|
||||
---
|
||||
checkId: check.verification.artifact.pull
|
||||
plugin: stellaops.doctor.verification
|
||||
severity: fail
|
||||
tags: [verification, artifact, registry, supply-chain]
|
||||
---
|
||||
# Test Artifact Pull
|
||||
|
||||
## What It Checks
|
||||
Requires the verification plugin to be enabled and a test artifact to be configured with either `Doctor:Plugins:Verification:TestArtifact:Reference` or `Doctor:Plugins:Verification:TestArtifact:OfflineBundlePath`.
|
||||
|
||||
For offline mode it checks the bundle file exists. For online mode it performs a registry `HEAD` request against the OCI manifest and optionally compares the returned digest to the expected digest.
|
||||
|
||||
## Why It Matters
|
||||
The rest of the verification pipeline is meaningless if Doctor cannot retrieve the artifact it is supposed to validate.
|
||||
|
||||
## Common Causes
|
||||
- No test artifact reference or offline bundle path is configured
|
||||
- Registry credentials are missing or do not allow manifest access
|
||||
- The artifact digest or tag points to content that no longer exists
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```yaml
|
||||
services:
|
||||
doctor-web:
|
||||
environment:
|
||||
Doctor__Plugins__Verification__Enabled: "true"
|
||||
Doctor__Plugins__Verification__TestArtifact__Reference: ghcr.io/example/app@sha256:<digest>
|
||||
```
|
||||
|
||||
For air-gapped mode:
|
||||
|
||||
```yaml
|
||||
Doctor__Plugins__Verification__TestArtifact__OfflineBundlePath: /var/lib/stella/verification/offline-bundle.json
|
||||
```
|
||||
|
||||
```bash
|
||||
docker compose -f devops/compose/docker-compose.stella-ops.yml exec doctor-web crane manifest ghcr.io/example/app@sha256:<digest>
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
Use an immutable digest reference instead of a mutable tag whenever possible.
|
||||
|
||||
### Kubernetes / Helm
|
||||
Mount registry credentials and the offline bundle path into the Doctor workload if the cluster is disconnected.
|
||||
|
||||
## Verification
|
||||
```bash
|
||||
stella doctor --check check.verification.artifact.pull
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.verification.signature` - signature validation depends on the same artifact input
|
||||
- `check.integration.oci.pull` - registry authorization issues often show up there too
|
||||
@@ -0,0 +1,50 @@
|
||||
---
|
||||
checkId: check.verification.policy.engine
|
||||
plugin: stellaops.doctor.verification
|
||||
severity: fail
|
||||
tags: [verification, policy, vex, compliance]
|
||||
---
|
||||
# Policy Engine Evaluation
|
||||
|
||||
## What It Checks
|
||||
Requires the verification plugin plus a configured test artifact. In offline mode it looks for policy results inside the exported bundle. In online mode it validates `Policy:Engine:Enabled`, a policy reference, and `Policy:VexAware`.
|
||||
|
||||
The check fails when the policy engine is disabled, warns when no policy reference is configured or when VEX-aware evaluation is off, and passes when the prerequisites are present.
|
||||
|
||||
## Why It Matters
|
||||
Release verification is only trustworthy if the same policy engine and VEX rules used in production can be exercised by Doctor.
|
||||
|
||||
## Common Causes
|
||||
- `Policy__Engine__Enabled` is false
|
||||
- No default or test policy reference is configured
|
||||
- Policy rules were not updated to account for VEX justifications
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```yaml
|
||||
services:
|
||||
doctor-web:
|
||||
environment:
|
||||
Policy__Engine__Enabled: "true"
|
||||
Policy__DefaultPolicyRef: policy://default/release-gate
|
||||
Policy__VexAware: "true"
|
||||
Doctor__Plugins__Verification__PolicyTest__PolicyRef: policy://default/release-gate
|
||||
```
|
||||
|
||||
If you use offline verification, export the bundle with policy data included before copying it into the air-gapped environment.
|
||||
|
||||
### Bare Metal / systemd
|
||||
Keep the Doctor policy reference aligned with the policy engine configuration used by release orchestration.
|
||||
|
||||
### Kubernetes / Helm
|
||||
Store the policy ref in ConfigMaps and enforce the same value across the policy engine and Doctor service.
|
||||
|
||||
## Verification
|
||||
```bash
|
||||
stella doctor --check check.verification.policy.engine
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.verification.vex.validation` - VEX-aware policy only helps if VEX collection works
|
||||
- `check.verification.sbom.validation` - policy evaluation usually consumes SBOM and vulnerability evidence
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
checkId: check.verification.sbom.validation
|
||||
plugin: stellaops.doctor.verification
|
||||
severity: fail
|
||||
tags: [verification, sbom, cyclonedx, spdx]
|
||||
---
|
||||
# SBOM Validation
|
||||
|
||||
## What It Checks
|
||||
Requires the verification plugin plus a test artifact. In offline mode it looks for CycloneDX or SPDX JSON inside the bundle. In online mode it checks whether `Scanner:SbomGeneration:Enabled` or `Attestor:SbomAttestation:Enabled` is turned on.
|
||||
|
||||
The check warns when SBOM generation and attestation are both disabled, and fails when the offline bundle is missing or contains no recognizable SBOM.
|
||||
|
||||
## Why It Matters
|
||||
SBOMs are the input for downstream vulnerability analysis, policy decisions, and customer evidence exports. If SBOM generation is off, release evidence is incomplete.
|
||||
|
||||
## Common Causes
|
||||
- The build pipeline is not producing SBOMs
|
||||
- SBOM attestation is disabled even though verification expects it
|
||||
- Offline bundles were exported without `--include-sbom`
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```yaml
|
||||
services:
|
||||
doctor-web:
|
||||
environment:
|
||||
Scanner__SbomGeneration__Enabled: "true"
|
||||
Attestor__SbomAttestation__Enabled: "true"
|
||||
```
|
||||
|
||||
For offline mode:
|
||||
|
||||
```bash
|
||||
stella verification bundle export --include-sbom --output /var/lib/stella/verification/offline-bundle.json
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
Enable SBOM generation in the scanner and keep artifact attachments immutable once published.
|
||||
|
||||
### Kubernetes / Helm
|
||||
Mount the same scanner and attestor config into Doctor that the production verification pipeline uses.
|
||||
|
||||
## Verification
|
||||
```bash
|
||||
stella doctor --check check.verification.sbom.validation
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.verification.artifact.pull` - the artifact must be reachable before attached SBOMs can be validated
|
||||
- `check.verification.policy.engine` - policy rules commonly consume SBOM-derived vulnerability data
|
||||
56
docs/doctor/articles/verification/verification-signature.md
Normal file
56
docs/doctor/articles/verification/verification-signature.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
checkId: check.verification.signature
|
||||
plugin: stellaops.doctor.verification
|
||||
severity: fail
|
||||
tags: [verification, signatures, dsse, rekor]
|
||||
---
|
||||
# Signature Verification
|
||||
|
||||
## What It Checks
|
||||
Requires the verification plugin plus a test artifact. In offline mode it looks for DSSE-style signature material in the bundle. In online mode it checks `Sigstore:Enabled` and verifies the Rekor log endpoint is reachable.
|
||||
|
||||
The check reports info when Sigstore is disabled, and fails when the offline bundle is missing or Rekor cannot be reached.
|
||||
|
||||
## Why It Matters
|
||||
Signature verification is the minimum control that proves the artifact under review was signed by the expected supply-chain path.
|
||||
|
||||
## Common Causes
|
||||
- `Sigstore__Enabled` is false
|
||||
- Rekor URL is unreachable from the Doctor workload
|
||||
- Offline bundles were exported without signatures
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```yaml
|
||||
services:
|
||||
doctor-web:
|
||||
environment:
|
||||
Sigstore__Enabled: "true"
|
||||
Sigstore__RekorUrl: https://rekor.sigstore.dev
|
||||
```
|
||||
|
||||
```bash
|
||||
docker compose -f devops/compose/docker-compose.stella-ops.yml exec doctor-web curl -fsS https://rekor.sigstore.dev/api/v1/log
|
||||
```
|
||||
|
||||
For offline verification:
|
||||
|
||||
```bash
|
||||
stella verification bundle export --include-signatures --output /var/lib/stella/verification/offline-bundle.json
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
Ensure the Doctor host trusts the CA chain used by the Rekor endpoint or use the approved internal Rekor deployment.
|
||||
|
||||
### Kubernetes / Helm
|
||||
Prefer an internal Rekor service URL in disconnected or regulated clusters.
|
||||
|
||||
## Verification
|
||||
```bash
|
||||
stella doctor --check check.verification.signature
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.attestation.rekor.connectivity` - validates the transparency log path more directly
|
||||
- `check.verification.artifact.pull` - signature checks need a reachable artifact reference
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
checkId: check.verification.vex.validation
|
||||
plugin: stellaops.doctor.verification
|
||||
severity: fail
|
||||
tags: [verification, vex, csaf, openvex]
|
||||
---
|
||||
# VEX Validation
|
||||
|
||||
## What It Checks
|
||||
Requires the verification plugin plus a test artifact. In offline mode it looks for OpenVEX, CSAF VEX, or CycloneDX VEX content inside the bundle. In online mode it validates `VexHub:Collection:Enabled` and at least one configured VEX feed URL.
|
||||
|
||||
The check reports info when VEX collection is disabled, warns when feeds are missing, and fails only for unusable offline bundle inputs.
|
||||
|
||||
## Why It Matters
|
||||
VEX data is what allows policy to distinguish exploitable findings from known-not-affected cases. Without it, release gates become overly noisy or overly permissive.
|
||||
|
||||
## Common Causes
|
||||
- `VexHub__Collection__Enabled` is false
|
||||
- Vendor or internal VEX feeds were never configured
|
||||
- Offline bundles were exported without `--include-vex`
|
||||
|
||||
## How to Fix
|
||||
|
||||
### Docker Compose
|
||||
```yaml
|
||||
services:
|
||||
doctor-web:
|
||||
environment:
|
||||
VexHub__Collection__Enabled: "true"
|
||||
VexHub__Feeds__0__Url: https://vendor.example/vex.json
|
||||
```
|
||||
|
||||
For offline mode:
|
||||
|
||||
```bash
|
||||
stella verification bundle export --include-vex --output /var/lib/stella/verification/offline-bundle.json
|
||||
```
|
||||
|
||||
### Bare Metal / systemd
|
||||
Keep VEX feeds in a controlled mirror if the environment cannot reach upstream vendors directly.
|
||||
|
||||
### Kubernetes / Helm
|
||||
Mount VEX feed configuration from the same source used by the running VexHub deployment.
|
||||
|
||||
## Verification
|
||||
```bash
|
||||
stella doctor --check check.verification.vex.validation
|
||||
```
|
||||
|
||||
## Related Checks
|
||||
- `check.verification.policy.engine` - VEX-aware policy is only as good as the VEX data it receives
|
||||
- `check.verification.sbom.validation` - VEX statements refer to components identified in the SBOM
|
||||
Reference in New Issue
Block a user