xeol-operator
Is end-of-life software still running in your cluster? Python 3.8, Node 16 and Alpine 3.18 are past end of life (EOL), but are any of your images still built on them?
xeol-operator scans every image running in your Kubernetes cluster, finds runtimes, databases, frameworks and distros that are past end of life or close to it, and shows you which workloads to fix first. Turn on trivy and the same scan also lists known vulnerabilities (CVEs). Results go to Grafana, Prometheus alerts, or a built-in web page.
Why use it
- Covers every running workload. It reads what Pods actually run (by image digest), not what a manifest claims. Private registries work with the Pods' own pull secrets.
- Gives dates, not just labels. Every finding has its EOL date and days left, so "due within 90 days" is just a query.
- Fits the tools you already have. It ships Prometheus metrics, ready-made alert rules and a Grafana dashboard with the Helm chart. Without Grafana, turn on the built-in web page or MCP tools for AI assistants.
- Uses EOL data that's kept up to date. It builds its database daily from endoflife.date, covering language runtimes, databases, frameworks and distros (Debian, Alpine, Ubuntu, ...).
- Finds CVEs too, at little extra cost. With
trivy.enabled, trivy matches the SBOM already built for the EOL scan, so images aren't pulled twice. It adds about 0.2 s and 150 MB per image. CVEs you've accepted can be hidden by ID or package, like accepted EOL products.
- Is light to run. It's one read-only pod with no database or extra services, and it works in air-gapped clusters too.
Quick start
helm repo add xeol-operator https://rishang.github.io/xeol-operator
helm repo update
# With kube-prometheus-stack and Grafana (Infinity plugin):
helm install xeol-operator xeol-operator/xeol-operator -n xeol-system --create-namespace \
--set serviceMonitor.enabled=true \
--set prometheusRule.enabled=true \
--set grafanaDatasource.enabled=true
kubectl -n xeol-system port-forward svc/xeol-operator-metrics 8080 &
curl -s localhost:8080/api/v1/status # images_scanned, workloads_eol, last_sweep, ...
No Grafana? Use the built-in page instead:
helm install xeol-operator xeol-operator/xeol-operator -n xeol-system --create-namespace \
--set ui.enabled=true --set mcp.enabled=true
kubectl -n xeol-system port-forward deploy/xeol-operator 8080
# open http://localhost:8080/
Ask an AI assistant over MCP:
claude mcp add --transport http xeol http://localhost:8080/mcp
# "Which workloads in prod run software that is already end of life?"
Vulnerability scanning (optional)
Add trivy to the same scan:
helm upgrade xeol-operator xeol-operator/xeol-operator -n xeol-system --reuse-values --set trivy.enabled=true
- syft builds each image's SBOM once; xeol reads it for EOL software and
trivy sbom reads it for known vulnerabilities. The image isn't pulled again.
- The pod downloads trivy's database (~1.6 GB) at start and daily, and turns Ready once it has it. Scans never call out. Air-gapped clusters mount it instead (air-gapped installation).
- You get a second Grafana dashboard (
xeol: vulnerabilities (trivy)), a Trivy tab on the web page, /api/v1/vulnerabilities, per-image counts in Prometheus and a stale-database alert.
- Only want vulnerabilities? Add
--set eol.enabled=false. At least one scan type stays on.
The web page, MCP tools and JSON API are read-only and have no login: reach them with port-forward, and don't expose them through a public Ingress.
How it works
Each image is scanned once, no matter how many Pods run it, and rescanned every interval (default 24h). The numbered steps are explained in Architecture.
Alerts
With prometheusRule.enabled:
| Alert | Fires when |
|---|
XeolEOLSoftwareRunning | A running image contains software past EOL |
XeolEOLSoftwareSoon | Software reaches EOL within 90 days (prometheusRule.eolSoonDays) |
XeolDatabaseStale | The EOL database is older than 30 days |
XeolDatabaseMissing | There is no EOL database, so nothing is scanned |
XeolScanErrors | Images keep failing to scan |
XeolVulnDatabaseStale | The trivy database is older than 7 days (trivy.enabled) |
Add scanner.workloadLabels: [team] to label metrics with each workload's team and route every team its own alerts.
Configure
Scan scope lives in Helm values under scanner.*. The chart renders them into a config file (the ConfigMap xeol-operator-config, mounted into the pod), which the operator reloads when it changes:
scanner:
namespaceSelector: {} # empty = all namespaces
excludeNamespaces: ["kube-*"] # globs
excludeImages: [] # globs on the image reference
interval: 24h # rescan each image this often
workloadLabels: [team] # copied onto metrics as k8s_label_team
ignoreProducts: # accepted findings, hidden everywhere
- products: [perl] # endoflife.date name
namespaces: [test] # optional; also cycles, selector
ignoreVulnerabilities: # accepted vulnerabilities (trivy), same scoping
- ids: [CVE-2024-1234] # and/or packages: [libcrypto3]
Changes apply without a restart, from helm upgrade or kubectl edit configmap xeol-operator-config; a bad edit is rejected and the previous config stays (Configuration). Memory, timeouts, workers and the air-gapped DB are covered in Helm setup.
To rescan now instead of waiting for interval: kubectl -n xeol-system exec deploy/xeol-operator -- /manager rescan ['python:3.8*' ...] (every running image without globs). An AI assistant can do the same through MCP with mcp.allowRescan=true (Rescan now).
Metrics
| Metric | Value | Labels |
|---|
xeol_eol_date_seconds | EOL date (Unix seconds) | image, digest, product, cycle, package, version, url |
xeol_image_workload | 1 | digest, namespace, kind, name, k8s_label_* |
xeol_db_built_timestamp_seconds | DB build time | |
xeol_scan_duration_seconds | histogram | |
xeol_vulnerabilities | count (trivy.enabled) | digest, severity, fixable |
xeol_vuln_db_updated_timestamp_seconds | trivy DB publish time (trivy.enabled) | |
xeol_scan_errors_total | counter | reason (auth, not_found, timeout, oom, other, trivy) |
The EOL date is the metric value, so how close counts is up to your query:
xeol_eol_date_seconds < time() # already EOL
(xeol_eol_date_seconds - time()) / 86400 < 90 # EOL within 90 days
Join xeol_image_workload on digest to get workloads (the dashboard's main table does this). Vulnerabilities are counts per image, never one series per CVE; the CVE list is at /api/v1/vulnerabilities:
sum by (namespace, name) (xeol_image_workload * on(digest) group_left sum by (digest) (xeol_vulnerabilities{severity="CRITICAL"}))
Good to know
- Only products tracked by endoflife.date are reported, so "no findings" doesn't prove nothing is EOL.
- trivy only sees packages syft records (OS and language packages). Software copied into an image outside a package manager, such as a Python built from source, gets no vulnerability rows, though the EOL scan still reports its version.
- Images loaded straight onto nodes, with no registry digest, are skipped.
- Results are saved to a small SQLite file on the pod's volume. A container restart (e.g. after an out-of-memory kill) picks up where it left off; a new pod starts fresh.
Docs
Full documentation: https://rishang.github.io/xeol-operator/
| |
|---|
| Quick start | Install from the Helm repository, first results |
| Usage | Install, read results, tune, troubleshoot |
| Helm | Every chart value, upgrade, uninstall |
| Configuration | Config file fields, globs, ignore rules, live reload, errors |
| Air-gapped | Clusters without internet access |
| Architecture | Components, scan flow, where data is stored, failure handling |
For AI tools, the site also serves llms.txt, llms-small.txt and llms-full.txt.
The chart is also listed on Artifact Hub; its source is in helm/xeol-operator.
Development
task --list # all tasks
task test # unit + envtest
task test-e2e # Helm smoke test in a throwaway k3d cluster
task cluster-up # local k3d cluster: kube-prometheus-stack, EOL test apps, operator
task deploy-dev # rebuild and redeploy the operator to k3d
task docs-dev # docs site (ui/, Astro Starlight) at http://localhost:4321/xeol-operator/
The docs live in ui/src/content/docs/*.mdx; to install from a clone instead of the Helm repository, use helm install xeol-operator ./helm/xeol-operator.
Design and conventions: AGENTS.md. Specs: openspec/specs/.
License
Apache 2.0.
