- Go 69%
- TypeScript 25.1%
- CSS 2.2%
- JavaScript 1.8%
- Go Template 1.2%
- Other 0.7%
|
Some checks failed
ci / publish-release-manifest (push) Blocked by required conditions
ci / sbom (push) Blocked by required conditions
ci / upload-agent-releases (push) Blocked by required conditions
ci / upload-sboms (push) Blocked by required conditions
ci / chart-k8s-agent (push) Blocked by required conditions
ci / chart (push) Blocked by required conditions
ci / docs (push) Blocked by required conditions
ci / go-checks (push) Has started running
ci / agent-binaries (push) Has started running
ci / web-checks (push) Successful in 53s
ci / web-build (push) Successful in 58s
ci / server-binary (push) Waiting to run
ci / build (push) Failing after 1m23s
ci / backend-docker (push) Failing after 0s
ci / build-2 (push) Failing after 59s
ci / build-3 (push) Failing after 45s
ci / k8s-agent-docker (push) Failing after 0s
ci / host-agent-docker (push) Failing after 0s
ci / build-4 (push) Waiting to run
ci / build-1 (push) Successful in 4m25s
ci / frontend-docker (push) Successful in 0s
ci / build-5 (push) Waiting to run
|
||
|---|---|---|
| .claude | ||
| .forgejo/workflows | ||
| cmd | ||
| deploy/helm | ||
| docs | ||
| graphify-out | ||
| internal | ||
| scripts | ||
| site | ||
| web | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| .golangci.yml | ||
| CLAUDE.md | ||
| docker-compose.yml | ||
| Dockerfile | ||
| Dockerfile.agent | ||
| Dockerfile.k8s-agent | ||
| go.mod | ||
| go.sum | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| renovate.json | ||
| server.log | ||
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-agentfor 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-agentruns 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
fimPathsare 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.enabledneeds 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
-
In the UI open Agents, register an agent of type
linux,windowsormacos, and copy its key. It is shown only once. -
Create a config file (
vop-agent.json):{ "serverUrl": "https://vulnerability-operator.example.internal", "agentKey": "vopa_…", "heartbeatInterval": "60s", "inventoryInterval": "6h", "insecureSkipVerify": false }Without
scanPathsthe 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 noscanPaths; setscanPaths: ["C:\\"]only to catalog files. macOS catalogs the application bundles in/Applicationsand the Homebrew formulas under/opt/homebrewor/usr/local, and needs noscanPaths. -
Run it:
vop-agent -config /etc/vop/vop-agent.json. Add-versionto 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, aDPkg::Post-Invokeafter each dpkg call. - pacman:
/etc/pacman.d/hooks/vop-inventory.hook, aPostTransactionhook for installs, upgrades and removals. - dnf 4:
/etc/dnf/plugins/post-transaction-actions.d/vop-inventory.action. It needs thepost-transaction-actionsplugin 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/binand/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 theirvopa_…key. - MCP endpoint:
POST /mcp(streamable HTTP, stateless) with a personal token asAuthorization: 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.