Vuls: an agent-less vulnerability scanner for Linux, FreeBSD and containers

The manual patching problem Vuls was written for

The README opens with a scenario that most system administrators recognise. Automatic updates are turned off in production to avoid downtime, so patching happens by hand. That creates three recurring costs: someone has to watch NVD and similar databases for new entries, someone has to know every package installed across every server, and someone has to work out which machines a new CVE actually affects. The README names the risk of overlooking a server or two during that analysis.

Vuls is aimed at that workflow. It is not a network vulnerability scanner in the sense of probing open ports and services; it collects the software inventory from a host and matches it against vulnerability data. The README describes the output in plain terms: which vulnerabilities relate to the system, and which servers are affected. The intended usage pattern is a report generated on a schedule with CRON or a similar mechanism, so the inventory is refreshed rather than assembled on demand.

The audience is therefore narrow and specific: people who own the hosts, can log into them, and want a machine-readable list of affected packages. If you need to scan hosts you do not administer, or you want a service that maps findings to business assets, Vuls is the wrong layer.

How the scan actually works: collection, matching, reporting

The repository layout shows the split clearly. There are scanner/, detector/, models/, reporter/, cache/, server/ and tui/ directories at the top level, plus subcmds/ for the CLI verbs. That maps onto the pipeline the documentation describes: a scanner collects software state from a target, the detector matches it against vulnerability sources, results are stored in a cache, and a reporter renders them.

Collection happens in one of three ways. In remote scan mode you set up one machine that reaches the targets over SSH. In local scan mode the binary runs on the host itself, so the central server never connects outward. In server mode Vuls listens as an HTTP server, and the target host runs commands to collect software information and posts the result back as JSON. The README states that server mode needs no SSH and no scanner on the target, only issued Linux commands.

There are two privilege levels. Fast Scan runs without root and, per the documentation, with almost no load on the target. Fast Root Scan runs with root and adds process-level checks: yum-ps on Amazon Linux, CentOS, AlmaLinux, Rocky Linux, Oracle Linux, Fedora and RHEL to find processes affected by an update, and checkrestart from debian-goodies on Debian and Ubuntu to find processes that were updated but not restarted. Both modes support offline scanning on the listed distributions.

The matching side is where most of the configuration weight sits. Vuls draws on NVD and JVN, vendor OVAL feeds from Red Hat, Debian, Ubuntu, SUSE and Oracle Linux, security advisories including Alpine-secdb, the Debian Security Bug Tracker and the Ubuntu CVE Tracker, and command output such as yum, zypper and pkg-audit for RHSA, ALAS, ELSA and FreeBSD-SA identifiers. It also pulls exploit and PoC signals from Exploit Database, Metasploit modules, several GitHub PoC collections, inthewilddb and Nuclei templates, KEV data from CISA and VulnCheck, MITRE ATT&CK and CAPEC, and the aquasecurity/vuln-list. That is a lot of upstream sources, and each one is a moving dependency.

Installing Vuls and running a first scan

The repository ships a Dockerfile that builds the binary in a golang:alpine builder stage with make install, then copies /go/bin/vuls into an alpine:3.24 runtime image. The runtime installs openssh-client, ca-certificates, git and nmap, and declares two volumes: /vuls for the working directory and /var/log/vuls for logs. The entrypoint is vuls and the default command is --help.

If you build from source instead, the module path is github.com/future-architect/vuls and go.mod declares go 1.26.3, so the toolchain version matters before you start.

git clone https://github.com/future-architect/vuls.git
cd vuls
make install
vuls --help

Running vuls --help after make install prints the available subcommands, which is the quickest way to confirm the binary built and to see the verbs available in your version. The README points to vuls.io for the detailed setup pages, including the architecture pages for fast scan, fast root scan, remote, local and server modes.

The configuration file is TOML; go.mod lists github.com/BurntSushi/toml as a dependency, and the config/ directory holds the schema. The README does not reproduce a full config example inline, so treat the vuls.io usage pages as the source of truth for keys rather than guessing at them. The repository does not show a minimal config snippet in the files available here.

In server mode, the flow is reversed. You start Vuls as an HTTP listener on the central machine, then run the discovery commands on the target and post the JSON result back. The README describes the result as JSON. That mode is the one to reach for when a policy forbids inbound SSH to production hosts.

Where Vuls stops being the right tool

The biggest constraint is data freshness. Vuls does not compute vulnerabilities itself; it compares your inventory against upstream feeds. If the NVD, OVAL or advisory data in your local cache is stale, the report is stale, and nothing in the scan will tell you that a patch shipped last week is missing from the feed. The cache/ directory exists precisely because the data is fetched and stored locally, which means someone has to own the update step.

Offline scanning is advertised, but the README scopes it. Offline mode is listed for CentOS, AlmaLinux, Rocky Linux, Debian, Oracle Linux, Red Hat, Fedora and Ubuntu. If your estate is mostly Alpine, FreeBSD or SUSE, check the supported OS page before assuming the same workflow applies.

Server mode removes the SSH requirement but introduces an HTTP listener on the central machine and a collection step you must run on each target. That is a different operational surface from a pull-based scan, and it is not a drop-in substitute for remote mode.

Finally, Vuls is not a runtime or network scanner. It reads package state. A service that is vulnerable because of its configuration, a web application flaw, or an exposed port will not appear because no package changed. The README's own framing is package and library versions, which is a deliberate boundary, not a gap the project is trying to close.

How Vuls compares with Trivy

The dependency list in go.mod includes github.com/aquasecurity/trivy and trivy-db, and the README lists aquasecurity/vuln-list as a library data source. So the two projects are not strangers; Vuls consumes Trivy-adjacent data rather than ignoring it.

The difference is the unit of analysis. Trivy is commonly pointed at a container image, a filesystem or a repository and returns findings for that artifact. Vuls is pointed at a fleet of running hosts and answers a fleet question: which servers are affected by this vulnerability. That is why Vuls has SSH collection modes, a persistent cache, a server mode with an HTTP listener, and reporters that produce scheduled reports. Those pieces exist to answer "which hosts" rather than "what is in this image".

If your problem is scanning images in a CI pipeline before deployment, Trivy is the more direct fit. If your problem is a set of long-lived servers that are patched manually and you need a recurring host-level report, Vuls is built around that shape. Choosing Vuls for image scanning means carrying its host-collection machinery for no benefit; choosing Trivy for fleet-wide host reporting means building the inventory and scheduling layers yourself.

Maintenance, release cadence and the GPL-3.0 licence

The repository is not archived, and the last push was on 2026-07-30, the same day as the v0.40.1 release. Recent tags include v0.40.1, v0.40.1-rc.1 and v0.40.0-rc.1, all dated 2026-07-29 or 2026-07-30. The project tags release candidates before final releases, so upgrades can be staged against an rc first.

Upgrade cost is dominated by the data sources, not the binary. Every feed in the README (NVD, JVN, five OVAL vendors, multiple advisory trackers, KEV lists, PoC collections) is an external dependency that can change format or availability. The go.mod file also pins a long list of modules, including vuls2 and vuls-data-update, so a rebuild after a Go toolchain bump is not a trivial operation. Budget for periodic rebuilds rather than a one-time install.

The licence is GPL-3.0, listed in the repository as LICENSE. That matters if you intend to redistribute a modified binary or link the code into a product. GPL-3.0 carries obligations around source distribution that permissive licences do not. This is not legal advice; if you plan to ship Vuls inside a commercial offering, have someone qualified read the licence against your distribution model. Running it internally as a tool is a different question from redistributing it.

Editorial conclusion

Vuls fits administrators who already run SSH access to a fleet of Linux or FreeBSD hosts and want a scheduled, scriptable report of which packages are affected by known vulnerabilities. It does not fit teams that want a hosted dashboard with no local database maintenance, or environments where outbound access to NVD, OVAL and vendor feeds is blocked. Before adopting it, verify that the supported OS list covers your distributions, confirm the go.mod toolchain requirement (go 1.26.3) against your build environment, and check whether the GPL-3.0 licence is compatible with how you intend to distribute anything built from the source tree.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes