README
¶
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 rules to write. 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 flags pods deviating from your fleet's actual norm, not from a static checklist. It warns by default and never denies until you have read the warnings and opted into enforcement; the rollout path is warn first, enforce on purpose.
- One unified stream for inbound signal: scan findings, AlertManager, Falco, Trivy CVEs, Kyverno and Gatekeeper PolicyReports.
Consistency is not correctness
The Fleet Score measures one thing: how much your clusters deviate from each other. It is a consistency number, not a correctness number.
That has a specific failure mode, and you should know it before you put the number on a TV. If all fifty of your clusters allow privileged pods, skip resource limits, and run the same end-of-life Kubernetes version, there is no deviation to find. The fleet agrees with itself, so it scores well. A uniformly misconfigured fleet looks the same as a uniformly well-configured one, because the baseline is the fleet, not a standard.
So a Fleet Score of 87 means your clusters mostly agree with each other, and the drivers name the few places they do not. It does not mean they are secure, patched, or compliant with anything. Every score also carries its provenance: how many clusters and scan dimensions produced it, and how many clusters were excluded for insufficient data. A score built from six clusters is a weaker claim than one built from sixty, and the report says which one you are looking at.
Fleetsweeper is therefore not a replacement for policy engines, CIS benchmarks, or vulnerability scanning. Those check clusters against absolute rules, and they are the tools that catch the failure mode above. What they cannot catch is the drift and the one-off snowflake cluster that fleetsweeper exists to find, because nobody wrote a rule for it. Run both: Kyverno or Gatekeeper for the rules you can write down, Fleetsweeper for the anomalies you did not know to write a rule for. The PolicyReport integration feeds their violations into the same finding stream, so the pairing is already wired in.
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 with six days of
scan history renders with a 3D globe, findings, drift, outliers, capacity,
and a guided tour. No kubeconfig required. The demo is real scan data run
through the real engine, so every number on screen is one the engine
computed. Auth is off in the demo, so the scan trigger, acks, and tags all
work. Real data needs --auth-token. The pulsing red dot is the cinematic
part. The outlier detection under it 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 24 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. |
| 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 24 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.
- Distributions. What a strip shows and how the band is drawn.
- 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 |
|---|---|
|
Package client is a Go SDK for the Fleetsweeper HTTP API.
|
Package client is a Go SDK for the Fleetsweeper HTTP API. |
|
internal
|
|
|
admission
Package admission implements the Fleetsweeper ValidatingAdmissionWebhook.
|
Package admission implements the Fleetsweeper ValidatingAdmissionWebhook. |
|
browser
Package browser holds the dashboard's browser smoke test.
|
Package browser holds the dashboard's browser smoke test. |
|
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 export bundles.
|
Package seal provides HMAC-SHA256 sealing for export bundles. |
|
testcerts
Package testcerts generates self-signed X.509 certificates for tests that exercise certificate parsing and expiry logic.
|
Package testcerts generates self-signed X.509 certificates for tests that exercise certificate parsing and expiry logic. |
|
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. |
|
util
Package util holds small helpers shared across packages so a single implementation is imported everywhere rather than duplicated.
|
Package util holds small helpers shared across packages so a single implementation is imported everywhere rather than duplicated. |
|
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. |