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

Doctor plugin checks: implement health check classes and documentation

Browse Source 
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
2026-03-27 12:28:00 +02:00
parent fbd24e71de
commit c58a236d70
326 changed files with 18500 additions and 463 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
src/__Libraries/StellaOps.Doctor.Plugins.Attestation/Checks/ClockSkewCheck.cs
View File

@@ -96,7 +96,8 @@ public sealed class ClockSkewCheck : AttestationCheckBase
.Add("Note", "Clock skew verification skipped - no network reference available"))
.WithRemediation(r => r
.AddShellStep(1, "Check system time", GetTimeCheckCommand())
.AddManualStep(2, "Configure NTP", "Ensure NTP is configured for time synchronization"))
.AddManualStep(2, "Configure NTP", "Ensure NTP is configured for time synchronization")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-clock-skew.md"))
.Build();
}
@@ -122,7 +123,8 @@ public sealed class ClockSkewCheck : AttestationCheckBase
.WithRemediation(r => r
.AddShellStep(1, "Check current time", GetTimeCheckCommand())
.AddShellStep(2, "Force NTP sync", GetNtpSyncCommand())
.AddManualStep(3, "Configure NTP", "Ensure NTP is properly configured and the NTP service is running"))
.AddManualStep(3, "Configure NTP", "Ensure NTP is properly configured and the NTP service is running")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-clock-skew.md"))
.WithVerification($"stella doctor --check {CheckId}")
.Build();
}
@@ -143,7 +145,8 @@ public sealed class ClockSkewCheck : AttestationCheckBase
"Infrequent NTP sync interval")
.WithRemediation(r => r
.AddShellStep(1, "Check NTP status", GetNtpStatusCommand())
.AddShellStep(2, "Force NTP sync", GetNtpSyncCommand()))
.AddShellStep(2, "Force NTP sync", GetNtpSyncCommand())
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-clock-skew.md"))
.WithVerification($"stella doctor --check {CheckId}")
.Build();
}

18
src/__Libraries/StellaOps.Doctor.Plugins.Attestation/Checks/CosignKeyMaterialCheck.cs
View File

@@ -93,7 +93,8 @@ public sealed class CosignKeyMaterialCheck : AttestationCheckBase
.Add("Note", "Enable Sigstore to use attestation signing"))
.WithRemediation(r => r
.AddManualStep(1, "Enable Sigstore", "Set Sigstore:Enabled to true in configuration")
.AddManualStep(2, "Configure signing mode", "Set either Sigstore:KeyPath, Sigstore:Keyless:Enabled, or Sigstore:KMS:KeyRef"))
.AddManualStep(2, "Configure signing mode", "Set either Sigstore:KeyPath, Sigstore:Keyless:Enabled, or Sigstore:KMS:KeyRef")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-cosign-keymaterial.md"))
.Build());
}
@@ -112,7 +113,8 @@ public sealed class CosignKeyMaterialCheck : AttestationCheckBase
.AddShellStep(1, "Generate a signing key pair", "cosign generate-key-pair")
.AddManualStep(2, "Configure key path", "Set Sigstore:KeyPath to the path of the private key")
.AddManualStep(3, "Or enable keyless", "Set Sigstore:Keyless:Enabled to true for OIDC-based signing")
.AddManualStep(4, "Or use KMS", "Set Sigstore:KMS:KeyRef to your KMS key reference"))
.AddManualStep(4, "Or use KMS", "Set Sigstore:KMS:KeyRef to your KMS key reference")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-cosign-keymaterial.md"))
.WithVerification($"stella doctor --check check.attestation.cosign.keymaterial")
.Build());
}
@@ -135,7 +137,8 @@ public sealed class CosignKeyMaterialCheck : AttestationCheckBase
.WithRemediation(r => r
.AddShellStep(1, "Verify file exists", $"ls -la {keyPath}")
.AddShellStep(2, "Generate new key pair if needed", "cosign generate-key-pair")
.AddManualStep(3, "Update configuration", "Ensure Sigstore:KeyPath points to the correct file"))
.AddManualStep(3, "Update configuration", "Ensure Sigstore:KeyPath points to the correct file")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-cosign-keymaterial.md"))
.WithVerification($"stella doctor --check check.attestation.cosign.keymaterial")
.Build());
}
@@ -172,7 +175,8 @@ public sealed class CosignKeyMaterialCheck : AttestationCheckBase
.WithCauses("File permissions prevent reading the key file")
.WithRemediation(r => r
.AddShellStep(1, "Check file permissions", $"ls -la {keyPath}")
.AddShellStep(2, "Fix permissions if needed", $"chmod 600 {keyPath}"))
.AddShellStep(2, "Fix permissions if needed", $"chmod 600 {keyPath}")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-cosign-keymaterial.md"))
.WithVerification($"stella doctor --check check.attestation.cosign.keymaterial")
.Build());
}
@@ -213,7 +217,8 @@ public sealed class CosignKeyMaterialCheck : AttestationCheckBase
"Fulcio URL is incorrect")
.WithRemediation(r => r
.AddShellStep(1, "Test Fulcio endpoint", $"curl -I {fulcioApiUrl}")
.AddManualStep(2, "Check service status", "Visit https://status.sigstore.dev"))
.AddManualStep(2, "Check service status", "Visit https://status.sigstore.dev")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-cosign-keymaterial.md"))
.WithVerification($"stella doctor --check check.attestation.cosign.keymaterial")
.Build();
}
@@ -242,7 +247,8 @@ public sealed class CosignKeyMaterialCheck : AttestationCheckBase
"Firewall blocking HTTPS traffic")
.WithRemediation(r => r
.AddShellStep(1, "Test connectivity", $"curl -I {fulcioUrl}")
.AddManualStep(2, "Check network configuration", "Ensure HTTPS traffic to Fulcio is allowed"))
.AddManualStep(2, "Check network configuration", "Ensure HTTPS traffic to Fulcio is allowed")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-cosign-keymaterial.md"))
.WithVerification($"stella doctor --check check.attestation.cosign.keymaterial")
.Build();
}

15
src/__Libraries/StellaOps.Doctor.Plugins.Attestation/Checks/OfflineBundleCheck.cs
View File

@@ -69,7 +69,8 @@ public sealed class OfflineBundleCheck : AttestationCheckBase
.WithRemediation(r => r
.AddShellStep(1, "Export bundle from online system", "stella attestation bundle export --output /path/to/bundle.json")
.AddManualStep(2, "Configure bundle path", "Set Doctor:Plugins:Attestation:OfflineBundlePath to the bundle location")
.AddManualStep(3, "Transfer bundle", "Copy the bundle to the target system"))
.AddManualStep(3, "Transfer bundle", "Copy the bundle to the target system")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-offline-bundle.md"))
.WithVerification($"stella doctor --check {CheckId}")
.Build());
}
@@ -89,7 +90,8 @@ public sealed class OfflineBundleCheck : AttestationCheckBase
.WithRemediation(r => r
.AddShellStep(1, "Check file existence", $"ls -la {options.OfflineBundlePath}")
.AddShellStep(2, "Export new bundle", "stella attestation bundle export --output " + options.OfflineBundlePath)
.AddManualStep(3, "Verify path", "Ensure the configured path is correct"))
.AddManualStep(3, "Verify path", "Ensure the configured path is correct")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-offline-bundle.md"))
.WithVerification($"stella doctor --check {CheckId}")
.Build());
}
@@ -134,7 +136,8 @@ public sealed class OfflineBundleCheck : AttestationCheckBase
.Add("ParseError", parseError))
.WithRemediation(r => r
.AddShellStep(1, "Validate bundle", "stella attestation bundle validate " + options.OfflineBundlePath)
.AddShellStep(2, "Export fresh bundle", "stella attestation bundle export --output " + options.OfflineBundlePath))
.AddShellStep(2, "Export fresh bundle", "stella attestation bundle export --output " + options.OfflineBundlePath)
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-offline-bundle.md"))
.WithVerification($"stella doctor --check {CheckId}")
.Build());
}
@@ -167,7 +170,8 @@ public sealed class OfflineBundleCheck : AttestationCheckBase
.WithRemediation(r => r
.AddShellStep(1, "Export fresh bundle from online system", "stella attestation bundle export --output /path/to/new-bundle.json")
.AddManualStep(2, "Transfer to air-gap environment", "Copy the new bundle to the target system")
.AddManualStep(3, "Update bundle path if needed", "Point configuration to the new bundle file"))
.AddManualStep(3, "Update bundle path if needed", "Point configuration to the new bundle file")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-offline-bundle.md"))
.WithVerification($"stella doctor --check {CheckId}")
.Build());
}
@@ -191,7 +195,8 @@ public sealed class OfflineBundleCheck : AttestationCheckBase
})
.WithRemediation(r => r
.AddShellStep(1, "Export fresh bundle", "stella attestation bundle export --output /path/to/new-bundle.json")
.AddManualStep(2, "Schedule regular updates", "Consider automating bundle refresh"))
.AddManualStep(2, "Schedule regular updates", "Consider automating bundle refresh")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-offline-bundle.md"))
.WithVerification($"stella doctor --check {CheckId}")
.Build());
}

6
src/__Libraries/StellaOps.Doctor.Plugins.Attestation/Checks/RekorConnectivityCheck.cs
View File

@@ -60,7 +60,8 @@ public sealed class RekorConnectivityCheck : AttestationCheckBase
.Add("ConfigKey", "Doctor:Plugins:Attestation:RekorUrl or Sigstore:RekorUrl"))
.WithRemediation(r => r
.AddManualStep(1, "Configure Rekor URL", "Set the Rekor URL in configuration: STELLA_REKOR_URL=https://rekor.sigstore.dev")
.AddManualStep(2, "Or use offline mode", "Set Doctor:Plugins:Attestation:Mode to 'offline' and configure OfflineBundlePath"))
.AddManualStep(2, "Or use offline mode", "Set Doctor:Plugins:Attestation:Mode to 'offline' and configure OfflineBundlePath")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-rekor-connectivity.md"))
.Build();
}
@@ -86,7 +87,8 @@ public sealed class RekorConnectivityCheck : AttestationCheckBase
.WithRemediation(r => r
.AddShellStep(1, "Test endpoint manually", $"curl -I {logInfoUrl}")
.AddManualStep(2, "Verify Rekor URL", "Ensure the URL is correct (default: https://rekor.sigstore.dev)")
.AddManualStep(3, "Check service status", "Visit https://status.sigstore.dev for public Rekor status"))
.AddManualStep(3, "Check service status", "Visit https://status.sigstore.dev for public Rekor status")
.WithRunbookUrl("docs/doctor/articles/attestor/attestation-rekor-connectivity.md"))
.WithVerification($"stella doctor --check {CheckId}")
.Build();
}