README
¶
Fleetsweeper
The cluster that drifted is the one that pages you at 3am.
Fleetsweeper finds it before it does.
You run twelve clusters. Or fifty. Or two hundred. They started identical and they did not stay that way. Versions skew. Admission policies drift. Service accounts get patched at 3am and nobody writes it down. Every cluster is "healthy" on its own, so every tool you already own stays quiet. Fleetsweeper finds the one cluster that wandered off the herd.
The fleet itself is the baseline. No rulebook. No thresholds to tune. The modified z-score across your own clusters does the work.
What you walk away with after one scan
- A Fleet Score from 0 to 100 with a one-line headline you can put on a status TV.
- The cluster that is most unlike the rest, plus the exact fields that flagged it.
- Ranked, leverage-weighted recommendations. The fix that takes ten clusters from drifted to clean ranks ahead of the same fix on one.
- An optional admission webhook that denies pods deviating from your fleet's actual norm, not from a static checklist.
- One unified stream for inbound signal: scan findings, AlertManager, Falco, Trivy CVEs, Kyverno and Gatekeeper PolicyReports.
See it in 30 seconds
go install github.com/dcadolph/fleetsweeper@latest
fleetsweeper serve --demo --addr :8080
Open http://localhost:8080. A synthetic 26-cluster fleet renders across
four continents with a 3D globe, findings, trends, outliers, capacity, and
a guided tour. No kubeconfig required. The pulsing red dots are the
cinematic part. The outlier detection under them is the real part.
Install for real
helm install fleetsweeper deploy/helm/fleetsweeper \
--set auth.token=$(openssl rand -hex 32) \
--set controller.enabled=true
kubectl apply -f deploy/examples/clusterscan-prod.yaml
The controller reconciles ClusterScan resources and writes outcomes back
to .status. Full installation paths in
docs/operator/helm.md. Scoped API keys for
pipelines in docs/operator/rbac.md.
Why this and not what you already have
| You already use | What it tells you | What Fleetsweeper adds |
|---|---|---|
kubectl, k9s |
The state of one cluster, right now. | A fleet-wide comparison across 16 dimensions. Names the outlier. |
| Argo CD, Flux | Whether each cluster matches its manifest. | Drift across clusters even when every cluster matches its own source of truth. |
| Prometheus, Grafana | Time series for what you remembered to instrument. | Statistical baselines derived from the fleet, with no rules to write. |
| Datadog Cluster Insights | Per-cluster alerts scored by a vendor rulebook. | The norm is your own fleet, not a vendor checklist. |
| OPA, Kyverno | Violations against rules you authored. | Detects drift you forgot to write a rule for. Complements, does not replace. |
Production-ready out of the box
HA backends, leader election, scoped RBAC, audit log, declarative CRDs,
Prometheus and OpenTelemetry, signed reports, backups, GitOps integrations,
admission webhook, and supply-chain signed images. Full checklist:
docs/production-readiness.md.
Where to go next
Start here
- Getting started. First scan, persistence, history, groups.
- Architecture. How the pipeline fits together.
- Scanners. The 16 dimensions Fleetsweeper checks.
Concepts
- The fleet is the policy. Why norm-based detection scales.
- Fleet Score. What the number means.
- Outliers. MAD-based statistical detection.
- Findings and remediation. Severity calibration and
kubectloutputs. - Globe view. Geolocation sources and overrides.
Operator
- Overview, Helm, Server mode
- ClusterScan CRD, Leader election, Backends
- RBAC and API keys, Audit log, OIDC
- Admission webhook, Recommend, What changed
Integrations
- Prometheus, Slack, Webhooks
- PolicyReport, FleetDriftReport
- AlertManager, Falco, Trivy
- Registry probing
Reference
Contributing
Issues and PRs welcome. Start with CONTRIBUTING.md and
the code of conduct. Security disclosures go through
SECURITY.md.
License
MIT. See LICENSE.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
admission
Package admission implements the Fleetsweeper ValidatingAdmissionWebhook.
|
Package admission implements the Fleetsweeper ValidatingAdmissionWebhook. |
|
cohort
Package cohort partitions a fleet into groups of clusters that look like each other.
|
Package cohort partitions a fleet into groups of clusters that look like each other. |
|
compare
Package compare produces a structured diff between two Fleetsweeper reports: what changed in the Fleet Score, which findings are new, which resolved, which persisted, and how cluster statuses moved.
|
Package compare produces a structured diff between two Fleetsweeper reports: what changed in the Fleet Score, which findings are new, which resolved, which persisted, and how cluster statuses moved. |
|
controller
Package controller reconciles ClusterScan custom resources by triggering scans on the configured cadence and writing the outcome back to the resource status.
|
Package controller reconciles ClusterScan custom resources by triggering scans on the configured cadence and writing the outcome back to the resource status. |
|
cost
Package cost correlates Fleetsweeper findings and per-cluster scores with a user-provided cost CSV.
|
Package cost correlates Fleetsweeper findings and per-cluster scores with a user-provided cost CSV. |
|
diagnose
Package diagnose runs an end-to-end sanity check across every Fleetsweeper integration.
|
Package diagnose runs an end-to-end sanity check across every Fleetsweeper integration. |
|
explain
Package explain provides operator-facing explanations for Fleetsweeper findings and scanners.
|
Package explain provides operator-facing explanations for Fleetsweeper findings and scanners. |
|
fleetdrift
Package fleetdrift converts Fleetsweeper reports into FleetDriftReport Kubernetes custom resources, one per scanned cluster, and writes them to a local directory as YAML files.
|
Package fleetdrift converts Fleetsweeper reports into FleetDriftReport Kubernetes custom resources, one per scanned cluster, and writes them to a local directory as YAML files. |
|
integration
Package integration contains integration tests that create real Kubernetes clusters using kind.
|
Package integration contains integration tests that create real Kubernetes clusters using kind. |
|
kube
Package kube wraps client-go and provides Fleetsweeper's connection helpers for multi-cluster scans, including QPS/burst tuning, a user agent for apiserver audit trails, and concurrent ConnectAll fan-out.
|
Package kube wraps client-go and provides Fleetsweeper's connection helpers for multi-cluster scans, including QPS/burst tuning, a user agent for apiserver audit trails, and concurrent ConnectAll fan-out. |
|
leader
Package leader provides a thin Kubernetes Lease-based leader election wrapper.
|
Package leader provides a thin Kubernetes Lease-based leader election wrapper. |
|
logutil
Package logutil ties a structured zap logger to a context.Context so handlers thread the same logger without explicit arguments.
|
Package logutil ties a structured zap logger to a context.Context so handlers thread the same logger without explicit arguments. |
|
policyreport
Package policyreport converts Fleetsweeper findings into PolicyReport CRs using the wgpolicyk8s.io/v1alpha2 schema, the CNCF-standard format consumed by Kyverno, Trivy Operator, Falco Sidekick, and the Policy Reporter UI.
|
Package policyreport converts Fleetsweeper findings into PolicyReport CRs using the wgpolicyk8s.io/v1alpha2 schema, the CNCF-standard format consumed by Kyverno, Trivy Operator, Falco Sidekick, and the Policy Reporter UI. |
|
remediate
Package remediate turns a Fleetsweeper finding with an inline YAML remediation into a pull request against a GitOps repository.
|
Package remediate turns a Fleetsweeper finding with an inline YAML remediation into a pull request against a GitOps repository. |
|
scanner/admission
Package admission audits MutatingWebhookConfigurations and ValidatingWebhookConfigurations for two failure modes that silently break clusters: webhooks whose backing service has zero healthy endpoints, and webhooks whose caBundle is expiring soon.
|
Package admission audits MutatingWebhookConfigurations and ValidatingWebhookConfigurations for two failure modes that silently break clusters: webhooks whose backing service has zero healthy endpoints, and webhooks whose caBundle is expiring soon. |
|
scanner/certs
Package certs scans TLS Secrets, Ingress TLS references, and admission webhook caBundles for upcoming expiry.
|
Package certs scans TLS Secrets, Ingress TLS references, and admission webhook caBundles for upcoming expiry. |
|
scanner/clusterinfo
Package clusterinfo collects node OS, kernel, container runtime, kubelet and kube-proxy versions and reports drift within a single cluster.
|
Package clusterinfo collects node OS, kernel, container runtime, kubelet and kube-proxy versions and reports drift within a single cluster. |
|
scanner/crd
Package crd enumerates the CustomResourceDefinitions installed on a cluster and surfaces per-cluster CRD divergence as a scanner result.
|
Package crd enumerates the CustomResourceDefinitions installed on a cluster and surfaces per-cluster CRD divergence as a scanner result. |
|
scanner/deprecatedapis
Package deprecatedapis identifies in-use API versions that Kubernetes has deprecated or removed.
|
Package deprecatedapis identifies in-use API versions that Kubernetes has deprecated or removed. |
|
scanner/events
Package events scans the apiserver's recent Event stream and aggregates per-namespace warning counts, surfacing clusters whose signal-to-noise has degraded.
|
Package events scans the apiserver's recent Event stream and aggregates per-namespace warning counts, surfacing clusters whose signal-to-noise has degraded. |
|
scanner/geo
Package geo locates clusters on Earth from node region/zone labels.
|
Package geo locates clusters on Earth from node region/zone labels. |
|
scanner/imageaudit
Package imageaudit reports image hygiene across the fleet: digest pinning, latest-tag usage, distinct image counts, and optional registry probes for age and signature checks.
|
Package imageaudit reports image hygiene across the fleet: digest pinning, latest-tag usage, distinct image counts, and optional registry probes for age and signature checks. |
|
scanner/policyreportingest
Package policyreportingest reads wgpolicyk8s.io PolicyReport and ClusterPolicyReport custom resources written by other tools (Kyverno, Gatekeeper, Trivy, kube-bench) and aggregates their fail/warn results per cluster.
|
Package policyreportingest reads wgpolicyk8s.io PolicyReport and ClusterPolicyReport custom resources written by other tools (Kyverno, Gatekeeper, Trivy, kube-bench) and aggregates their fail/warn results per cluster. |
|
scanner/quota
Package quota inspects ResourceQuota and LimitRange coverage across namespaces.
|
Package quota inspects ResourceQuota and LimitRange coverage across namespaces. |
|
scanner/rbac
Package rbac scans the cluster's RBAC graph (ClusterRoles, RoleBindings, ServiceAccounts) and flags wildcard permissions and over-broad bindings.
|
Package rbac scans the cluster's RBAC graph (ClusterRoles, RoleBindings, ServiceAccounts) and flags wildcard permissions and over-broad bindings. |
|
scanner/security
Package security audits security-affecting workload configuration: PodSecurityStandards labels, default-deny NetworkPolicy presence, and similar fleet-wide hardening signals.
|
Package security audits security-affecting workload configuration: PodSecurityStandards labels, default-deny NetworkPolicy presence, and similar fleet-wide hardening signals. |
|
scanner/version
Package version reports the Kubernetes server version from each cluster and detects fleet-wide skew.
|
Package version reports the Kubernetes server version from each cluster and detects fleet-wide skew. |
|
scanner/vulnerabilities
Package vulnerabilities reads aquasecurity.github.io/v1alpha1 VulnerabilityReport custom resources produced by the Trivy Operator and aggregates their severity counts into a per-cluster baseline.
|
Package vulnerabilities reads aquasecurity.github.io/v1alpha1 VulnerabilityReport custom resources produced by the Trivy Operator and aggregates their severity counts into a per-cluster baseline. |
|
scanner/workloadcoverage
Package workloadcoverage reports on PDB and HPA coverage of replicated workloads.
|
Package workloadcoverage reports on PDB and HPA coverage of replicated workloads. |
|
seal
Package seal provides HMAC-SHA256 sealing for scan reports.
|
Package seal provides HMAC-SHA256 sealing for scan reports. |
|
tracing
Package tracing wires up an OpenTelemetry tracer provider configured by the standard OTEL_EXPORTER_OTLP_ENDPOINT environment variable.
|
Package tracing wires up an OpenTelemetry tracer provider configured by the standard OTEL_EXPORTER_OTLP_ENDPOINT environment variable. |
|
webhooks
Package webhooks loads a YAML config of outbound HTTP subscribers and dispatches matching findings to each one after every scan.
|
Package webhooks loads a YAML config of outbound HTTP subscribers and dispatches matching findings to each one after every scan. |
Click to show internal directories.
Click to hide internal directories.