Doctor plugin checks: implement health check classes and documentation
Implement remediation-aware health checks across all Doctor plugin modules (Agent, Attestor, Auth, BinaryAnalysis, Compliance, Crypto, Environment, EvidenceLocker, Notify, Observability, Operations, Policy, Postgres, Release, Scanner, Storage, Vex) and their backing library counterparts (AI, Attestation, Authority, Core, Cryptography, Database, Docker, Integration, Notify, Observability, Security, ServiceGraph, Sources, Verification). Each check now emits structured remediation metadata (severity, category, runbook links, and fix suggestions) consumed by the Doctor dashboard remediation panel. Also adds: - docs/doctor/articles/ knowledge base for check explanations - Advisory AI search seed and allowlist updates for doctor content - Sprint plan for doctor checks documentation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
@@ -74,7 +74,8 @@ public sealed class PolicyEngineCheck : VerificationCheckBase
|
||||
.Add("BundlePath", bundlePath)
|
||||
.Add("FileExists", "false"))
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Export bundle", "stella verification bundle export --include-policy --output " + bundlePath))
|
||||
.AddShellStep(1, "Export bundle", "stella verification bundle export --include-policy --output " + bundlePath)
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.policy.engine")
|
||||
.Build());
|
||||
}
|
||||
@@ -101,7 +102,8 @@ public sealed class PolicyEngineCheck : VerificationCheckBase
|
||||
"Bundle was exported without policy results",
|
||||
"Policy evaluation not run before export")
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Re-export with policy", "stella verification bundle export --include-policy --output " + bundlePath))
|
||||
.AddShellStep(1, "Re-export with policy", "stella verification bundle export --include-policy --output " + bundlePath)
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.policy.engine")
|
||||
.Build());
|
||||
}
|
||||
@@ -158,7 +160,8 @@ public sealed class PolicyEngineCheck : VerificationCheckBase
|
||||
.WithCauses("Policy engine not configured or disabled")
|
||||
.WithRemediation(r => r
|
||||
.AddManualStep(1, "Enable policy engine", "Set Policy:Engine:Enabled to true")
|
||||
.AddManualStep(2, "Configure default policy", "Set Policy:DefaultPolicyRef to a policy reference"))
|
||||
.AddManualStep(2, "Configure default policy", "Set Policy:DefaultPolicyRef to a policy reference")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.policy.engine")
|
||||
.Build());
|
||||
}
|
||||
@@ -176,7 +179,8 @@ public sealed class PolicyEngineCheck : VerificationCheckBase
|
||||
.WithCauses("No test policy reference configured")
|
||||
.WithRemediation(r => r
|
||||
.AddManualStep(1, "Configure test policy", "Set Doctor:Plugins:Verification:PolicyTest:PolicyRef")
|
||||
.AddManualStep(2, "Or set default", "Set Policy:DefaultPolicyRef for a default policy"))
|
||||
.AddManualStep(2, "Or set default", "Set Policy:DefaultPolicyRef for a default policy")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.policy.engine")
|
||||
.Build());
|
||||
}
|
||||
@@ -198,7 +202,8 @@ public sealed class PolicyEngineCheck : VerificationCheckBase
|
||||
.WithCauses("Policy may not consider VEX statements when evaluating vulnerabilities")
|
||||
.WithRemediation(r => r
|
||||
.AddManualStep(1, "Enable VEX in policy", "Set Policy:VexAware to true")
|
||||
.AddManualStep(2, "Update policy rules", "Ensure policy considers VEX justifications for vulnerabilities"))
|
||||
.AddManualStep(2, "Update policy rules", "Ensure policy considers VEX justifications for vulnerabilities")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.policy.engine")
|
||||
.Build());
|
||||
}
|
||||
|
||||
@@ -76,7 +76,8 @@ public sealed class SbomValidationCheck : VerificationCheckBase
|
||||
.Add("BundlePath", bundlePath)
|
||||
.Add("FileExists", "false"))
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Export bundle", "stella verification bundle export --include-sbom --output " + bundlePath))
|
||||
.AddShellStep(1, "Export bundle", "stella verification bundle export --include-sbom --output " + bundlePath)
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.sbom.validation")
|
||||
.Build());
|
||||
}
|
||||
@@ -101,7 +102,8 @@ public sealed class SbomValidationCheck : VerificationCheckBase
|
||||
"Test artifact has no SBOM attached")
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Re-export with SBOM", "stella verification bundle export --include-sbom --output " + bundlePath)
|
||||
.AddManualStep(2, "Generate SBOM", "Enable SBOM generation in your build pipeline"))
|
||||
.AddManualStep(2, "Generate SBOM", "Enable SBOM generation in your build pipeline")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.sbom.validation")
|
||||
.Build());
|
||||
}
|
||||
@@ -157,7 +159,8 @@ public sealed class SbomValidationCheck : VerificationCheckBase
|
||||
"SBOM attestation not configured")
|
||||
.WithRemediation(r => r
|
||||
.AddManualStep(1, "Enable SBOM generation", "Set Scanner:SbomGeneration:Enabled to true")
|
||||
.AddManualStep(2, "Enable SBOM attestation", "Set Attestor:SbomAttestation:Enabled to true"))
|
||||
.AddManualStep(2, "Enable SBOM attestation", "Set Attestor:SbomAttestation:Enabled to true")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.sbom.validation")
|
||||
.Build());
|
||||
}
|
||||
|
||||
@@ -75,7 +75,8 @@ public sealed class SignatureVerificationCheck : VerificationCheckBase
|
||||
.Add("BundlePath", bundlePath)
|
||||
.Add("FileExists", "false"))
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Export bundle", "stella verification bundle export --output " + bundlePath))
|
||||
.AddShellStep(1, "Export bundle", "stella verification bundle export --output " + bundlePath)
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.signature")
|
||||
.Build());
|
||||
}
|
||||
@@ -102,7 +103,8 @@ public sealed class SignatureVerificationCheck : VerificationCheckBase
|
||||
.Add("SignatureDataFound", "false")
|
||||
.Add("Note", "Bundle should contain DSSE signatures for verification"))
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Re-export with signatures", "stella verification bundle export --include-signatures --output " + bundlePath))
|
||||
.AddShellStep(1, "Re-export with signatures", "stella verification bundle export --include-signatures --output " + bundlePath)
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.signature")
|
||||
.Build());
|
||||
}
|
||||
@@ -154,7 +156,8 @@ public sealed class SignatureVerificationCheck : VerificationCheckBase
|
||||
.Add("Note", "Enable Sigstore to verify artifact signatures"))
|
||||
.WithRemediation(r => r
|
||||
.AddManualStep(1, "Enable Sigstore", "Set Sigstore:Enabled to true")
|
||||
.AddManualStep(2, "Configure signing", "Set up signing keys or keyless mode"))
|
||||
.AddManualStep(2, "Configure signing", "Set up signing keys or keyless mode")
|
||||
.WithRunbookUrl(""))
|
||||
.Build();
|
||||
}
|
||||
|
||||
@@ -180,7 +183,8 @@ public sealed class SignatureVerificationCheck : VerificationCheckBase
|
||||
"Network connectivity issue")
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Test Rekor", $"curl -I {rekorHealthUrl}")
|
||||
.AddManualStep(2, "Or use offline mode", "Configure offline verification bundle"))
|
||||
.AddManualStep(2, "Or use offline mode", "Configure offline verification bundle")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.signature")
|
||||
.Build();
|
||||
}
|
||||
@@ -208,7 +212,8 @@ public sealed class SignatureVerificationCheck : VerificationCheckBase
|
||||
.WithCauses("Network connectivity issue")
|
||||
.WithRemediation(r => r
|
||||
.AddManualStep(1, "Check network", "Verify connectivity to Rekor")
|
||||
.AddManualStep(2, "Use offline mode", "Configure offline verification bundle"))
|
||||
.AddManualStep(2, "Use offline mode", "Configure offline verification bundle")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.signature")
|
||||
.Build();
|
||||
}
|
||||
|
||||
@@ -78,7 +78,8 @@ public sealed class TestArtifactPullCheck : VerificationCheckBase
|
||||
"Path is incorrect")
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Verify file exists", $"ls -la {bundlePath}")
|
||||
.AddShellStep(2, "Export bundle from online system", "stella verification bundle export --output " + bundlePath))
|
||||
.AddShellStep(2, "Export bundle from online system", "stella verification bundle export --output " + bundlePath)
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.artifact.pull")
|
||||
.Build());
|
||||
}
|
||||
@@ -113,7 +114,8 @@ public sealed class TestArtifactPullCheck : VerificationCheckBase
|
||||
.Add("Error", "Could not parse registry and repository"))
|
||||
.WithCauses("Reference format is incorrect")
|
||||
.WithRemediation(r => r
|
||||
.AddManualStep(1, "Fix reference format", "Use format: oci://registry/repository@sha256:digest or registry/repository@sha256:digest"))
|
||||
.AddManualStep(1, "Fix reference format", "Use format: oci://registry/repository@sha256:digest or registry/repository@sha256:digest")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.artifact.pull")
|
||||
.Build();
|
||||
}
|
||||
@@ -151,7 +153,8 @@ public sealed class TestArtifactPullCheck : VerificationCheckBase
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Test with crane", $"crane manifest {reference}")
|
||||
.AddManualStep(2, "Check registry credentials", "Ensure registry credentials are configured")
|
||||
.AddManualStep(3, "Verify artifact exists", "Confirm the test artifact has been pushed to the registry"))
|
||||
.AddManualStep(3, "Verify artifact exists", "Confirm the test artifact has been pushed to the registry")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.artifact.pull")
|
||||
.Build();
|
||||
}
|
||||
@@ -178,7 +181,8 @@ public sealed class TestArtifactPullCheck : VerificationCheckBase
|
||||
"Wrong artifact tag being pulled")
|
||||
.WithRemediation(r => r
|
||||
.AddManualStep(1, "Update expected digest", $"Set Doctor:Plugins:Verification:TestArtifact:ExpectedDigest to {responseDigest}")
|
||||
.AddManualStep(2, "Or use digest in reference", "Use @sha256:... in the reference instead of :tag"))
|
||||
.AddManualStep(2, "Or use digest in reference", "Use @sha256:... in the reference instead of :tag")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.artifact.pull")
|
||||
.Build();
|
||||
}
|
||||
@@ -208,7 +212,8 @@ public sealed class TestArtifactPullCheck : VerificationCheckBase
|
||||
"DNS resolution failure")
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Test registry connectivity", $"curl -I https://{registry}/v2/")
|
||||
.AddManualStep(2, "Check network configuration", "Ensure HTTPS traffic to the registry is allowed"))
|
||||
.AddManualStep(2, "Check network configuration", "Ensure HTTPS traffic to the registry is allowed")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.artifact.pull")
|
||||
.Build();
|
||||
}
|
||||
|
||||
@@ -76,7 +76,8 @@ public sealed class VexValidationCheck : VerificationCheckBase
|
||||
.Add("BundlePath", bundlePath)
|
||||
.Add("FileExists", "false"))
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Export bundle", "stella verification bundle export --include-vex --output " + bundlePath))
|
||||
.AddShellStep(1, "Export bundle", "stella verification bundle export --include-vex --output " + bundlePath)
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.vex.validation")
|
||||
.Build());
|
||||
}
|
||||
@@ -103,7 +104,8 @@ public sealed class VexValidationCheck : VerificationCheckBase
|
||||
"Test artifact has no known vulnerabilities")
|
||||
.WithRemediation(r => r
|
||||
.AddShellStep(1, "Re-export with VEX", "stella verification bundle export --include-vex --output " + bundlePath)
|
||||
.AddManualStep(2, "This may be expected", "VEX documents are only needed when vulnerabilities exist"))
|
||||
.AddManualStep(2, "This may be expected", "VEX documents are only needed when vulnerabilities exist")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.vex.validation")
|
||||
.Build());
|
||||
}
|
||||
@@ -154,7 +156,8 @@ public sealed class VexValidationCheck : VerificationCheckBase
|
||||
.Add("Note", "VEX collection is optional but recommended for vulnerability context"))
|
||||
.WithRemediation(r => r
|
||||
.AddManualStep(1, "Enable VEX collection", "Set VexHub:Collection:Enabled to true")
|
||||
.AddManualStep(2, "Configure VEX feeds", "Add vendor VEX feeds to VexHub:Feeds"))
|
||||
.AddManualStep(2, "Configure VEX feeds", "Add vendor VEX feeds to VexHub:Feeds")
|
||||
.WithRunbookUrl(""))
|
||||
.Build());
|
||||
}
|
||||
|
||||
@@ -170,7 +173,8 @@ public sealed class VexValidationCheck : VerificationCheckBase
|
||||
.Add("Note", "VEX feeds provide vendor vulnerability context"))
|
||||
.WithCauses("No VEX feed URLs configured")
|
||||
.WithRemediation(r => r
|
||||
.AddManualStep(1, "Configure VEX feeds", "Add vendor VEX feeds to VexHub:Feeds array"))
|
||||
.AddManualStep(1, "Configure VEX feeds", "Add vendor VEX feeds to VexHub:Feeds array")
|
||||
.WithRunbookUrl(""))
|
||||
.WithVerification($"stella doctor --check check.verification.vex.validation")
|
||||
.Build());
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user