No description
  • Go 69%
  • TypeScript 25.1%
  • CSS 2.2%
  • JavaScript 1.8%
  • Go Template 1.2%
  • Other 0.7%
Find a file
Jonas Leder 1b084d3d67
Some checks failed
ci / backend-docker (push) Successful in 0s
ci / build-5 (push) Successful in 49s
ci / web-checks (push) Successful in 38s
ci / upload-agent-releases (push) Successful in 38s
ci / web-build (push) Successful in 45s
ci / go-checks (push) Successful in 16m58s
ci / publish-release-manifest (push) Successful in 39s
ci / build-1 (push) Successful in 2m7s
ci / frontend-docker (push) Successful in 0s
ci / upload-sboms (push) Successful in 30s
ci / docs (push) Has been cancelled
ci / build-3 (push) Successful in 7m30s
ci / host-agent-docker (push) Successful in 0s
ci / build-4 (push) Successful in 42s
ci / build-2 (push) Successful in 8m2s
ci / chart-k8s-agent (push) Successful in 0s
ci / build (push) Successful in 10m13s
ci / agent-binaries (push) Successful in 19m0s
ci / sbom (push) Successful in 2m19s
ci / k8s-agent-docker (push) Successful in 0s
ci / server-binary (push) Successful in 11m51s
ci / chart (push) Successful in 0s
Publish the manual to git-pages from Forgejo Actions
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-18 15:26:05 +01:00
.claude add graphify instructions 2026-10-30 22:07:39 +01:00
.forgejo/workflows Publish the manual to git-pages from Forgejo Actions 2026-11-18 15:26:05 +01:00
cmd register hook in package manager for live updates 2026-10-30 09:54:17 +01:00
deploy/helm agents: let the node agent skip the pods of excluded namespaces 2026-11-01 19:52:18 +01:00
docs web: add a dashboard chart of new findings per day 2026-11-12 13:23:37 +01:00
graphify-out reports: document grouping a vulnerability report by software 2026-11-12 14:17:53 +01:00
internal bundle notifications 2026-11-15 01:42:18 +01:00
scripts agent: add a macOS agent 2026-10-30 20:13:24 +01:00
site Publish the manual to git-pages from Forgejo Actions 2026-11-18 15:26:05 +01:00
web Merge pull request 'chore(deps): update dependency typescript to v7' (#23) from renovate/typescript-7.x into master 2026-11-18 13:16:55 +00:00
.dockerignore build: container images on the scratch-rootless base and a separate frontend 2026-10-29 16:52:09 +01:00
.env.example storage: add local directory backend next to s3 2026-10-31 11:10:28 +01:00
.gitignore explude some more files 2026-10-31 12:01:01 +01:00
.golangci.yml ci: run golangci-lint as a static analysis job 2026-10-30 22:17:22 +01:00
CLAUDE.md ci: run the same checks as make check in CI and document it in CLAUDE.md 2026-11-01 13:52:55 +01:00
docker-compose.yml chore(deps): update redis docker tag to v8 2026-10-30 09:38:28 +00:00
Dockerfile rearange order to reduce updated layer 2026-10-31 12:35:10 +01:00
Dockerfile.agent rearange order to reduce updated layer 2026-10-31 12:35:10 +01:00
Dockerfile.k8s-agent rearange order to reduce updated layer 2026-10-31 12:35:10 +01:00
go.mod fix(deps): update module github.com/anchore/grype to v0.121.1 2026-11-17 07:20:50 +00:00
go.sum fix(deps): update module github.com/anchore/grype to v0.121.1 2026-11-17 07:20:50 +00:00
LICENSE license: switch to GPL-3.0-or-later 2026-10-31 12:32:56 +01:00
Makefile ci: run the same checks as make check in CI and document it in CLAUDE.md 2026-11-01 13:52:55 +01:00
README.md Publish the manual to git-pages from Forgejo Actions 2026-11-18 15:26:05 +01:00
renovate.json renovate: wait 14 days after a release before proposing it 2026-10-30 20:36:36 +01:00
server.log switch s3 server 2026-10-31 00:35:07 +01:00

vulnerability-operator

Collects software inventories (SBOMs) from Linux, Windows, macOS and Kubernetes agents, scans every dependency with Grype on the server, and shows where each CVE lives: host, cluster, namespace, pod and container.

Features

  • Agents
    • vop-agent for Linux, Windows and macOS collects an SBOM with the syft library. On Windows it also reads the installed programs from the registry and from winget, and runs as a service.
    • vop-k8s-agent runs on every node. It scans the images of the pods on its node with syft, read from the containerd content store, and reports the containers. It needs no other scanner.
    • File integrity monitoring on host agents: the paths in fimPaths are hashed on a schedule, and added, changed or deleted files are recorded.
    • Agents heartbeat, show online or offline status, and update themselves when an administrator requests it in the UI.
    • Software inventory: packages installed, updated or removed between two scans of a host, with an allowed list. Installs outside the list raise an alert.
    • Windows update status like WSUS: each Windows host lists the cumulative updates it is missing, security, optional preview and out-of-band alike, and each update shows how many hosts need it.
  • Server
    • Grype vulnerability database, downloaded and refreshed by a scheduled task.
    • Scheduled tasks with configurable cron schedules: database update, scans, agent-offline checks, retention cleanup.
    • Dashboard with filters on severity, cluster, namespace, pod, agent, package and CVE, plus free text and the fixable flag.
    • Exports of findings as CSV, JSON, SARIF (for CI security tabs) and PDF, and of the triage decisions as OpenVEX. Dependencies export as CSV, JSON and PDF.
    • Known exploited (CISA KEV) and EPSS data on each finding, refreshed daily.
    • Triage decisions per finding: not affected, affected, fixed or under investigation, with an owner and a ticket link. Not-affected findings are hidden from the lists, exports and alerts.
    • PDF reports, optionally with an executive summary from an OpenAI-compatible AI backend (only aggregated statistics are sent).
    • Alert rules for new findings, offline agents and software outside the allowed list, delivered to ntfy, gotify, SMTP mail, Slack, Microsoft Teams or Discord.
    • REST API documented with Swagger, and an MCP endpoint for AI assistants.
  • Storage: gorm with SQLite by default (MySQL, PostgreSQL and MSSQL are supported). Redis holds locks, cached dashboard data, login throttling and the matches of each package per vulnerability database build (three days, see internal/scanner/match_cache.go). The vulnerability database stays on the workers. S3 holds SBOM documents, generated reports and agent binaries.
  • No cgo: all binaries are built with CGO_ENABLED=0.

Architecture

 linux / windows agents ──┐                 ┌── Grype DB (download)
   (syft, registry)       │  HTTPS, key     │
                          ├──► REST API ◄───┤        ┌── Redis (locks, cache)
 k8s agent ───────────────┘   /api/v1       │        │
   (node agent: syft over containerd, or registries)       ├── scanner ── gorm DB (SQLite/…)
                                            │
 browser / MCP client ──► UI + /mcp ────────┴── S3 (SBOMs, reports, releases)

One binary (vop-server) runs in one of three roles, chosen with VOP_ROLE. all (the default) serves the API and runs the workers in the same process, which is what a single container needs. api serves HTTP and queues the background work. worker runs the queued work and the scheduler without HTTP. The queue is a Redis stream, so any number of workers share it. A running job is renewed every 10 seconds, and a job whose worker stopped is taken over by another one within a minute.

Packages live under internal/: api (HTTP handlers), jobs (the Redis queue), reports (PDF rendering), scanner (Grype), inventory (SBOM ingest), scheduler, alerting, ai, report, mcpserver, store and query (shared read queries), agent, collector and k8sagent (agent side). web/ is the React UI. make build embeds it into the server binary; the Docker images ship it as a separate nginx container.

Quick start

docker compose up --build

Open http://localhost:8080 and log in as admin@localhost. The nginx frontend forwards /api, /swagger and /mcp to the backend. If you did not set INITIAL_ADMIN_PASSWORD, the generated password is in the server log. MinIO's console is on http://localhost:9001.

Documentation

The docs are published at https://jonasled.jonasled.dev/vulnerability-operator/ (git-pages), built by the docs job.

The user guide, the administrator guide and the reference are in site/, built with Docusaurus. The screenshots in them are not kept in the repository: each run of the docs job captures them again from a server that holds demo data and publishes the result to git-pages (default branch only). See site/README.md.

make docs              # build the site into site/build
make docs-start        # live preview at http://localhost:3000
make docs-screenshots  # capture the screenshots from a fresh server

Docker images

Three images, all on the same pattern as the other projects: cross compiled with xx on golang:1.27.3-alpine (or node for the frontend) and copied onto a minimal base. The backend and the kubernetes agent run on jonasled.dev/infra/images/scratch-rootless as UID 1000 with no shell. The frontend is served by cgr.dev/chainguard/nginx.

Image Dockerfile Contents
backend Dockerfile vop-server and the writable /data directory (SQLite, Grype database, temporary uploads)
frontend web/Dockerfile the built UI and web/nginx.conf
kubernetes agent Dockerfile.k8s-agent vop-k8s-agent only
make docker                      # all three, tagged with VERSION (git describe)
make docker-backend GOPROXY=...  # optional module proxy for the backend build

Mount a volume at /data for the backend, so the database and the Grype database survive restarts. nginx resolves the backend host (server) when it starts, so the backend must be reachable then. In Kubernetes, rename the host in web/nginx.conf to the backend Service.

Development

Schema changes are migrations in internal/database/migrations.go, run by gormigrate and recorded in the migrations table. Append a new one with a new ID; never rename or reorder the existing ones. Each migration must be safe on a database that already has its effect, because a database from an earlier release runs them all once. The permissions of the built-in roles are synced on every start and do not need a migration.

Requirements: Go 1.27, pnpm, Docker (optional).

make web        # install and build the UI into web/dist
make swagger    # regenerate docs/ after changing handler annotations
make build      # bin/vop-server, bin/vop-agent, bin/vop-k8s-agent
make test
make dist       # cross compiled agents and server for Linux, Windows and macOS

For local runs, copy .env.example to .env. The server and all agents read .env from their working directory at startup. Variables already set in the real environment (containers, systemd, Windows services, Kubernetes) take precedence over the file.

Redis must be reachable for the server to start, and S3 too unless STORAGE_BACKEND=local. For local runs, docker compose up redis minio is enough.

Server configuration

Every variable can be set in the environment or in a .env file.

Variable Default Description
HTTP_ADDR :8080 Listen address
TLS_CERT_FILE, TLS_KEY_FILE Serve HTTPS when both are set
REDIS_ADDR, REDIS_PASSWORD, REDIS_DB localhost:6379, ``, 0 Redis connection
STORAGE_BACKEND s3 s3 or local (files in STORAGE_DIR)
STORAGE_DIR ./data/storage Directory for the local backend
S3_ENDPOINT localhost:9000 S3 endpoint without scheme
S3_ACCESS_KEY, S3_SECRET_KEY Required with the s3 backend
S3_BUCKET vulnerability-operator Created on startup when missing
S3_REGION, S3_USE_SSL, S3_PATH_STYLE us-east-1, false, true S3 options
DB_DRIVER sqlite sqlite, mysql, postgres or mssql
DB_NAME, DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_SSLMODE, DB_TIMEZONE DB_TIMEZONE=UTC Database connection
DB_MAX_OPEN_CONNS, DB_MAX_IDLE_CONNS, DB_CONN_MAX_LIFETIME_MINUTES 50, 10, 5 Connection pool
EXECUTE_MIGRATIONS true Run AutoMigrate on startup
INITIAL_ADMIN_EMAIL, INITIAL_ADMIN_PASSWORD admin@localhost, generated First admin account
GRYPE_DB_DIR ./data/grype Local Grype database
SCAN_WORKERS 4 Assets matched in parallel. Saving the results stays one at a time
VOP_ROLE all all: API and workers in one process. api: HTTP only, queues the work. worker: jobs and scheduler only, no HTTP
WORKER_CONCURRENCY 2 Jobs a process runs at once
GRYPE_DB_UPDATE true false only reads the local Grype database, for air-gapped installs
PUBLIC_URL Address of the UI, for example https://vop.example.com. Required with OIDC or SAML
AUTH_PASSWORD_LOGIN true false: sign-in only through a provider. Needs OIDC or SAML configured
OIDC_ISSUER_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET OpenID Connect provider. Enabled by the issuer
OIDC_NAME, OIDC_SCOPES, OIDC_GROUPS_CLAIM SSO, openid,email,profile, groups Button label, requested scopes, claim with the group list
OIDC_ADMIN_GROUPS Comma separated groups whose members become administrators for every cluster and node. Kept for compatibility, see OIDC_GROUP_MAPPINGS
OIDC_GROUP_MAPPINGS JSON list that maps provider groups to roles and to the clusters and nodes a user sees, see Users, roles and scopes
OIDC_ALLOW_UNVERIFIED_EMAIL false Accept sign-ins whose email the provider reports as unverified. Only turn on when the provider cannot verify emails
SAML_METADATA_URL or SAML_METADATA_FILE SAML identity provider metadata. Enabled by either
SAML_NAME, SAML_ENTITY_ID SAML, <PUBLIC_URL>/api/v1/auth/saml/metadata Button label and service provider entity ID
SAML_EMAIL_ATTRIBUTE, SAML_NAME_ATTRIBUTE, SAML_GROUPS_ATTRIBUTE email, displayName, groups Attribute names in the assertion
SAML_ADMIN_GROUPS Comma separated groups whose members become administrators for every cluster and node. Kept for compatibility, see SAML_GROUP_MAPPINGS
SAML_GROUP_MAPPINGS The same mapping as OIDC_GROUP_MAPPINGS, for the groups attribute of the assertion
SAML_SP_CERT_FILE, SAML_SP_KEY_FILE Optional PEM certificate and key that sign the sign-in requests

Sign-in with a provider matches users by email and creates them on first use. Roles and scope come from the groups of the user at every sign-in, see Users, roles and scopes. A provider sign-in needs a verified email: an OIDC token that says email_verified: false is refused. Register these addresses at the provider:

  • OpenID Connect redirect URI: <PUBLIC_URL>/api/v1/auth/oidc/callback
  • SAML assertion consumer service (HTTP-POST): <PUBLIC_URL>/api/v1/auth/saml/acs
  • SAML service provider metadata: <PUBLIC_URL>/api/v1/auth/saml/metadata

The sign-in state lives in Redis for ten minutes, so any replica can finish a sign-in that another one started. | AGENT_OFFLINE_AFTER | 5m | Silence after which an agent is offline | | ALERT_DIGEST_INTERVAL | 0 | Bundle finding and software alerts into one message per channel per interval, for example 4h. 0 sends each alert at once | | SESSION_TTL | 12h | Web session lifetime | | MAX_SBOM_MB | 128 | Largest accepted SBOM upload | | REPORT_MAX_ROWS | 10000 | Row limit of PDF reports and exports | | RETENTION_DAYS | 90 | Age after which scan history and alert logs are deleted | | LOG_LEVEL | INFO | ERROR, WARN, INFO or DEBUG |

The JWT signing secret is generated on first start and stored in the database. AI backend and alert channel settings are managed in the UI and stored in the database.

Built-in scheduled tasks

Task Default schedule Purpose
grype-db-update 0 */6 * * * Download the newest Grype database
vulnerability-scan 0 */2 * * * Scan pending assets and rescan after database updates
agent-offline-check */5 * * * * Send offline alerts
alert-digest */5 * * * * Send queued alerts as one message when ALERT_DIGEST_INTERVAL is set
retention-cleanup 30 3 * * * Delete old scan runs and alert logs
unused-package-cleanup 45 3 * * * Delete packages no asset has installed, with their findings
exploit-intel-update 30 4 * * * Download the CISA KEV catalog and EPSS scores
windows-update-catalog 15 4 * * * Read the Windows cumulative updates and builds that Microsoft published

Schedules can be changed and tasks run on demand in the UI. A scan also starts shortly after an SBOM is uploaded.

Kubernetes with Helm

The chart in deploy/helm/vulnerability-operator installs the backend and the frontend. Redis, S3 and the database are external services; the chart does not bundle them. The kubernetes agent is installed separately (see below).

helm install vop oci://jonasled.dev/jonasled/vulnerability-operator/charts/vulnerability-operator \
  --version 0.1.7 \
  --set secrets.inline.s3AccessKey=... --set secrets.inline.s3SecretKey=... \
  --set config.s3.endpoint=s3.example.internal:9000 \
  --set config.redis.addr=redis.example.internal:6379 \
  --set ingress.enabled=true --set 'ingress.hosts={vop.example.com}'

With the ingress enabled, /api, /swagger and /mcp go straight to the backend Service, and only the web UI's files come from the frontend pod. The ingress annotations in values.yaml are set for ingress-nginx.

Use secrets.existingSecret instead of the inline secrets in production. The secret needs the keys s3AccessKey, s3SecretKey, dbPassword, redisPassword and adminPassword. The chart values are documented in values.yaml.

The optional worker deployment runs the scans, the scheduled tasks and the report renders, so the backend only serves the API and can be scaled freely:

helm install vop ... --set worker.enabled=true --set config.database.driver=postgres \
  --set config.database.host=postgres.example.internal --set secrets.inline.dbPassword=...

With worker.enabled the backend runs with VOP_ROLE=api and needs no volume; the worker holds the Grype database in its own worker.persistence volume. The worker has no HTTP port and no probes, so a stuck worker is noticed through the Running now panel and the job logs, not a restart. Without worker.enabled the backend runs everything itself, as before.

Two rules are enforced when the chart is rendered:

  • The sqlite driver supports one backend replica. For more replicas use postgres, mysql or mssql, and a ReadWriteMany storage class, because every replica mounts /data (the Grype database).
  • postgres, mysql and mssql need a host and a database password.

Migrations: with postgres, mysql or mssql a job runs vop-server migrate before the server pods start, and the pods do not migrate. The job is a pre-install and pre-upgrade hook, so it works with helm install --wait. Set migrations.hook=post to run it after the install instead, which needs no --wait. sqlite migrates on start, since its file cannot be shared with a job before the first install. config.migrateOnStart=true makes the pods migrate with the other drivers too.

  • worker.enabled needs a shared database, so it does not work with sqlite.

The backend runs on the same scratch image as in Docker, with a read-only root filesystem. Everything it writes goes to the /data volume.

Continuous integration

.forgejo/workflows/ci.yml runs these jobs:

Job What it does
go-checks make check-go: gofmt, go vet and golangci-lint on Linux, Windows and macOS, go test ./..., and the swagger docs in sync
web-checks make check-web: the TypeScript check of the web interface
web-build, server-binary build the web interface and vop-server with it embedded (for the SBOM)
agent-binaries cross-compiles the agent for Linux, Windows and macOS
backend-docker, frontend-docker, k8s-agent-docker, host-agent-docker build and scan the images, tag them with the commit SHA
upload-agent-releases, publish-release-manifest publish the agent binaries (default branch only)
sbom, upload-sboms make CycloneDX SBOMs of the binaries and images, and upload them to sboms/<version>/ in the bucket (default branch only)
chart, chart-k8s-agent render the charts, package them and push them to the project's OCI registry
docs capture the screenshots, build the Docusaurus manual and publish it to git-pages (default branch only)

No job deploys the backend chart: Flux pulls it from the registry.

The SBOM files are named after their artifact: vop-agent-linux-amd64.cdx.json for a binary, image-backend.cdx.json for an image. The Helm charts have no SBOM.

The HelmChart job runs only after both image builds succeed. It replaces the __GIT_COMMIT_SHA__ and __CI_REGISTRY_IMAGE__ placeholders in values.yaml in the CI workspace, so the chart points at the images it was built with. The chart version is <major.minor from Chart.yaml>.<pipeline IID>, so Flux always sees a higher version.

Adding a Linux, Windows or macOS host

On the Agents page, Add host creates a one-time enrollment token and the command that installs the agent with it:

  • Linux: curl -fsSL '<url>' | sudo bash
  • Windows, in an administrator PowerShell: irm '<url>' | iex
  • macOS, in Terminal: curl -fsSL '<url>' | sudo bash

The link works once and expires after one or 24 hours. The installer detects systemd or OpenRC, downloads the agent of the latest release and checks its sha256, registers the host, writes /etc/vop/vop-agent.json (Linux) or C:\vop\vop-agent.json (Windows) or /etc/vop/vop-agent.json (macOS), and starts the agent as a service that starts at boot. On macOS the service is a launchd daemon, dev.vop.agent, and its log is /var/log/vop-agent.log. The registered key is written by the installer and is not shown to anyone. The agent binary is public; the token is what makes the registration work, once.

Linux and Windows agents

  1. In the UI open Agents, register an agent of type linux, windows or macos, and copy its key. It is shown only once.

  2. Create a config file (vop-agent.json):

    {
      "serverUrl": "https://vulnerability-operator.example.internal",
      "agentKey": "vopa_…",
      "heartbeatInterval": "60s",
      "inventoryInterval": "6h",
      "insecureSkipVerify": false
    }
    

    Without scanPaths the agent reads the package manager databases on the host (/var/lib/dpkg, /var/lib/rpm, /var/lib/pacman, /lib/apk/db), like the Wazuh syscollector does. It does not walk the disk. To also catalog application directories, such as language dependencies, add them explicitly: "scanPaths": ["/opt/app"]. Scanning / is slow and uses a lot of memory. Windows reads the installed programs from the registry and from winget, and needs no scanPaths; set scanPaths: ["C:\\"] only to catalog files. macOS catalogs the application bundles in /Applications and the Homebrew formulas under /opt/homebrew or /usr/local, and needs no scanPaths.

  3. Run it: vop-agent -config /etc/vop/vop-agent.json. Add -version to print the build version.

Windows service

sc create vop-agent binPath= "C:\vop\vop-agent.exe -config C:\vop\vop-agent.json" start= auto
sc failure vop-agent reset= 0 actions= restart/5000
sc start vop-agent

The restart action is needed for self-updates: after a successful update the agent exits and the service manager starts the new binary.

Linux service

Run it under systemd with Restart=always. A self-update re-executes the new binary in place, so the PID is kept.

Package hooks

On Linux the agent hooks into the package managers of the host, so the inventory follows a change within seconds instead of at the next inventory interval. The hooks are written when the agent starts, and again on every start, so an updated agent refreshes them:

  • apt: /etc/apt/apt.conf.d/99vop-inventory, a DPkg::Post-Invoke after each dpkg call.
  • pacman: /etc/pacman.d/hooks/vop-inventory.hook, a PostTransaction hook for installs, upgrades and removals.
  • dnf 4: /etc/dnf/plugins/post-transaction-actions.d/vop-inventory.action. It needs the post-transaction-actions plugin of dnf-plugins-core.

After a transaction the hook runs vop-agent -request-scan. That only touches /var/lib/vop/inventory.trigger, so the package manager never waits for a scan. The agent checks the file every 5 seconds and collects the SBOM once the file has been quiet for 5 seconds. A transaction that touches it several times yields one inventory.

Turn the hooks off with "packageHooks": false in the configuration file, or VOP_PACKAGE_HOOKS=false. vop-agent -remove-hooks deletes them. Set the switch to off first, or the next start writes them again.

Not covered: dnf 5, which has a different hook format, zypper, yum 3 (RHEL 7), apk, and Windows. A container gets no hooks, including the host agent of the Kubernetes chart: a container cannot reach the package managers of its node.

Kubernetes agent

The chart in deploy/helm/vop-k8s-agent installs the agents of a cluster in one release:

  • A DaemonSet of the node agent, one per node. It watches the pods on its node. When a pod starts, it scans the images of the pod's containers with syft and reports them as containers of the cluster. It reads the images from the containerd content store on the node, read-only. A node without that store, such as a Docker or CRI-O node, pulls its images from their registries. Each image is scanned once per digest. Containers of pods that are gone, and containers that have stopped, are removed.
  • A DaemonSet of the linux agent, one per node. It reports the packages of the node, read from its package databases, read-only.

The cluster name is set when the registration token is created. It can be changed later in the UI: the containers and their keys follow the new name. A cluster name that the agent reports is ignored. After a rename, a node that starts again is refused by the old token, so create a new one. A linux agent without a cluster can be given one in the same way, on the Agents page.

Create one registration token per cluster as an administrator, on the Agents page with Add cluster, or with POST /api/v1/cluster-tokens and {"clusterName": "<name>"}. The token is shown once. The Agents page lists the tokens and revokes them. The node agent and the host agent of every node register with it at start. The node agent is named after its node, and the host agent after its node with a -host suffix, since agent names are unique. The server creates the agents on first use. Each start gets a new key for the agent, and the key stays in memory. The token works until it is deleted with DELETE /api/v1/cluster-tokens/<id>: the agents that run keep their keys, and an agent that starts again can no longer register.

Install with --set server.url=... --set cluster.name=... --set cluster.registrationToken=.... No key is set per node.

The node agent works with containerd, and with Docker and CRI-O nodes by pulling their images. It does not need trivy-operator.

Talos Linux works too. Talos has no shell and no package manager, so no host agent can read its packages. The node agent reports the node itself, as a host named after the node, in the cluster of the agent. It recognises Talos by the OS image in the node object (Talos (v1.11.0)) and collects what the node has:

  • Talos, the Linux kernel and the kubelet, from the node object. The kernel is in no file of the root filesystem, and the kubelet runs from an image of its own.
  • The rest of the operating system (runc, containerd, musl, openssl, udev, util-linux, iptables and the Go modules of Talos) from the SBOM that Talos ships in /usr/share/spdx. A release without one is read from the Go modules of the binaries in /usr/bin and /opt, which cannot name runc's version.

Install with -f deploy/helm/vop-k8s-agent/values-talos.yaml. It mounts /usr and /opt of the node read-only for the node agent, and turns the host agent off, which would only add an empty second host. Without those mounts a Talos node is reported from the node object alone. The agent needs the right to get its node, which the chart grants. System extensions are not read. Talos enforces the baseline pod security level, which forbids hostPath volumes, so label the namespace pod-security.kubernetes.io/enforce=privileged first. Check the containerd root of your Talos release against nodeAgent.containerdRoot. Images of pods are found through the pod status, so an image that is not used by a pod is not reported. The DaemonSets create the paths they mount when a node lacks them, as empty directories. Node agents are not updated in place: roll out a new chart or image instead.

Managed updates

CI publishes every linux, windows and macOS agent build to the release bucket and writes releases.json next to them: the versions, with the URL, sha256 and size of each binary. RELEASE_MANIFEST_URL defaults to https://s3.jonasled.de/vulnerability-operator-release/releases.json; set it to an empty value to turn managed updates off. The Agents page then lists the published versions, and an admin can update an agent to any of them. The server fetches a version it does not hold yet, checks its sha256, and stores it. The agent picks the update up on its next heartbeat and replaces its own binary.

Container agents do not update themselves: a changed file in an image is lost on the next start. The agent detects a container and ignores updates, and the server refuses to offer one. Roll out a new image for them instead. Set VOP_MANAGED_UPDATES=false to turn off self-updates on a host, too.

The bucket must allow public reads of releases.json and the binaries. Only the CI credentials should be able to write.

API, UI and MCP

  • REST API: /api/v1. Interactive Swagger UI: /swagger/index.html.
  • Authentication: a session token from POST /api/v1/auth/login, or a personal token (vopt_…) created on the Account page. Agents use their vopa_… key.
  • MCP endpoint: POST /mcp (streamable HTTP, stateless) with a personal token as Authorization: Bearer. Read-only tools: search_findings, vulnerability_summary, list_packages, list_assets, list_agents.

Exports keep the filters of the dashboard, for example /api/v1/export/findings?format=pdf&severity=critical,high&cluster=prod. CSV and JSON download at once. A PDF is a report: a worker renders it, and the request answers with the report (202) to download from /api/v1/reports/{id}/download once it is ready.

Users, roles and scopes

A user holds one or more roles. A role is a set of permissions, and the user has the union of them. Every API route and every page of the UI asks for one permission, and the server checks it on each request.

The built-in roles are admin (every permission, every cluster and node) and viewer (read the inventory, agents, scans, reports, alerts and CPE mappings). Recording a triage decision needs findings.triage, which only admin holds by default. Admins create more roles on the Settings page, with a checklist of the permissions in internal/rbac. A user with users.manage or roles.manage can only grant what they hold themselves, and cannot widen a scope beyond their own: nobody can make an admin of themselves.

A scope limits what a user sees. It is either every cluster and node, or a list of clusters and a list of nodes. A row is visible when its cluster is listed, or its node is listed. A node is the host name of the agent that reported the row, so the node agent and the host agent of a Kubernetes node are one node. Hosts without a cluster are reached through their node only. The scope applies to findings, dependencies, assets, agents, the dashboard, exports, reports and the MCP tools. Alert rules and channels, scan runs and settings are not scoped: they follow the permissions only.

Local users get their roles and scope from the Users page. Accounts of an identity provider get them from OIDC_GROUP_MAPPINGS (or SAML_GROUP_MAPPINGS), a JSON list. A user in several groups gets the union of their roles and scopes:

[
  {"group": "vop-admins", "roles": ["admin"], "all": true},
  {"group": "vop-prod-viewers", "roles": ["viewer"], "clusters": ["prod"]},
  {"group": "vop-node-watch", "roles": ["viewer"], "nodes": ["talos-worker-3"]}
]

When mappings are configured, a user in no mapped group cannot sign in and loses the roles it had. Without mappings, a new provider user gets the viewer role for every cluster and node, and existing users keep what they have. Registering an agent needs the scope to be unrestricted: a scoped user cannot add hosts or clusters, since the scope cannot be checked before the agent reports.

Alerts and AI

  • Channels: ntfy (server, topic, optional token), gotify (URL and app token), SMTP mail (host, port, credentials, STARTTLS or TLS), Slack and Microsoft Teams and Discord (webhook URL). Secrets are masked in the UI.
  • Rules: finding rules match minimum severity, CVE and package regexes, cluster and namespace globs, agent type and the fixable flag. A rule fires once per newly seen finding; many matches are summarised in one message. Agent-offline rules fire once per offline episode.
  • AI summaries: any OpenAI-compatible chat completions server, for example OpenAI, Ollama or vLLM. Set the API root (containing /chat/completions), a model and an optional key. Only counts and the top items are sent.

Status

Verified by running the server against Redis, an S3 endpoint and the real Grype database:

  • Agent registration, heartbeat, SBOM upload and deduplication.
  • Linux agent collecting a real npm lockfile, then findings with fix versions.
  • trivy CycloneDX SBOM ingestion and scanning.
  • Exports (CSV, PDF), filters, facets and the dashboard summary.
  • Alert delivery to an ntfy endpoint, including a new critical finding.
  • PDF report with an AI summary against an OpenAI-compatible endpoint.
  • Agent self-update: release upload, SHA-256 check, re-exec, version report.
  • Scheduled task updates, MCP initialize and tool calls.

Not verified in this environment:

  • The Windows agent on a Windows host, and the Windows service behaviour.
  • The macOS agent on a Mac: the launchd installer, the inventory of the application bundles and Homebrew formulas, and the vulnerability matches for them. Neither the binary nor the installer has run on macOS yet.
  • The node agent against a live cluster with containerd.
  • Delivery to gotify and SMTP servers. The code paths compile and validate their settings, but no real server was used.
  • Slack, Microsoft Teams and Discord webhooks, the KEV and EPSS downloads, the SARIF and OpenVEX exports, and the Docker and CRI-O image pulls. Their code has unit tests, but none was run against a live webhook, feed, registry or node.
  • MySQL and MSSQL. Their drivers are compiled in, but they were not run.

PostgreSQL 16 was run for migrations, ingest, scans, filters, dashboard aggregates, package lists, facets and PDF export.

License

Vulnerability Operator is licensed under the GNU General Public License, version 3 or any later version. See LICENSE. The Settings page lists every dependency with its license.