Contents
- Step 1 — Installing Dependencies
- Installing Go
- Installing and Running go-cve-dictionary
- Installing and Running goval-dictionary
- Installing and Running gost
- Step 2 — Downloading and Configuring Vuls
- Step 3 — Running a Local Scan
- Step 4 — (Optional) Configuring Multiple Target Machines
- Step 5 — Configuring Periodic Scanning and Reporting to Slack
Step 1 — Installing Dependencies
In this section, you will create a folder to store Vuls data, install the latest version of the Go programming language, and install the other packages required by Vuls and its dependencies.
For this tutorial, you will store all Vuls-related data in the directory. Create it by running the following command: /usr/share/vuls-data
sudo mkdir /usr/share/vuls-data
To make it accessible by kerim, run the following command:
sudo chown -R kerim/usr/share/vuls-data
You have now created the vuls-data folder that will be your workspace. Before continuing with installing the required packages, first update the package manager cache:
sudo apt update
To download and build the dependencies you will need git, gcc, make, sqliteand wget. sqlite is a database system you will use here to store vulnerability information. debian-goodies includes the checkrestart utility, which provides information about which packages can and should be restarted at any given time .debian-goodieswgetsqlitedebian-goodiescheckrestart
You can install them all with a single command:
sudo apt install sqlite git debian-goodies gcc make wget -y
You have now installed the required packages and can continue with installing Go and the related programs that Vuls will use.
Installing Go
Install Go using the snap package manager by running the following command:
sudo snap install go --classic
You use snap to install Go because it installs the latest version of the language, unlike apt, which may install an older version. Working with an older version is not recommended and may prevent you from completing this tutorial.
For Go to work, you need to set a few environment variables: GOPATH and PATH. GOPATHspecifies the working directory for Go. PATH , which contains the directories where programs are placed, must be extended to tell the system where to find Go itself.
These environment variables need to be set every time a user logs in. To automate this, you will create a new executable file named go-env.sh in /etc/profile.d. This causes the directory to be executed every time a user logs in.
Create go-env.sh using your text editor:
sudo nano /etc/profile.d/go-env.sh
Add the following commands to the file: /etc/profile.d/go-env.sh
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin:/snap/bin
The export command sets the given environment variable to the desired value. Here, you use GOPATH and PATH to populate them with the appropriate values.
Save and close the file.
Right now, go-env.sh is not executable. To fix this, mark it as executable by running the following command:
sudo chmod +x /etc/profile.d/go-env.sh
So that you do not have to log in again, you can reload go-env.sh by running the following:
source /etc/profile.d/go-env.sh
The source command reloads the given file into the current shell while preserving its state.
You have now installed the Go language, set up the environment variables, and installed the packages you will need later. Next, you will download and build the Go programs that Vuls requires. These programs are go-cve-dictionary and goval-dictionary, which Vuls uses to query vulnerability databases.
Installing and Running go-cve-dictionary
In this section, you will download and build the Go package go-cve-dictionary that provides access to the National Vulnerability Database . Then you will run it to fetch vulnerability data that Vuls can use. The NVD is the U.S. government's repository of publicly disclosed cybersecurity vulnerabilities, containing vulnerability IDs (CVE — Common Vulnerabilities and Exposures), summaries and impact analyses, and is available in a machine-readable format.
Go stores packages in $GOPATH/src/. You can extend this further by using subdirectories to note the origin. example-user As an example, GitHub packages made by the user go in $GOPATH/src/github.com/example-user.
First, you will install the go-cve-dictionary Go package by cloning it from GitHub and then building it.
Start by creating a directory to store it according to the example path:
mkdir -p $GOPATH/src/github.com/vulsio
Navigate to it by running:
cd $GOPATH/src/github.com/vulsio
Now you will clone go-cve-dictionary from GitHub to your server by running:
git clone https://github.com/vulsio/go-cve-dictionary.git
Then, navigate to the package root:
cd go-cve-dictionary
Finally, build and install it by running the following command:
make install
Note that this command may take some time to complete.
To make it available system-wide, copy it to /usr/local/bin:
sudo cp $GOPATH/bin/go-cve-dictionary /usr/local/bin
go-cve-dictionary requires access to a log output directory; by default /var/log/vuls. Create it by running:
sudo mkdir /var/log/vuls
Right now, the log directory is readable by everyone. Restrict access to the current user with the following command:
sudo chmod 700 /var/log/vuls
Setting the permission flags to 700 restricts access to the owner only.
To make it accessible by kerim or another user, run the following command:
sudo chown -R kerim/var/log/vuls
Next, you will fetch the vulnerability data from the NVD and store it in your Vuls workspace ( ): /usr/share/vuls-data
go-cve-dictionary fetch nvd --dbpath /usr/share/vuls-data/cve.sqlite3
This command will fetch the NVD vulnerability data from 2002 up to the current year and store it in ./usr/share/vuls-data
Note: This command will take a long time to complete and may fail if your server has less than 2 GB of RAM.
In this section, you downloaded and installed go-cve-dictionary and then fetched the NVD data for Vuls to use. Now you will download and install goval-dictionary and fetch the OVAL data for Ubuntu .
Installing and Running goval-dictionary
In this section, you will download and build the Go package goval-dictionary that provides access to the OVAL database for Ubuntu . You will then run it and fetch vulnerability data for Vuls to use. OVAL stands for Open Vulnerability and Assessment Language, an open language used to express checks for determining whether software vulnerabilities exist on a given system.
Navigate to the $GOPATH/src/github.com/vulsio folder:
cd $GOPATH/src/github.com/vulsio
Clone the package from GitHub by running the following command:
git clone https://github.com/vulsio/goval-dictionary.git
Enter the package folder:
cd goval-dictionary
Build and install it with make:
make install
Copy it to /usr/local/bin to make it globally accessible:
sudo cp $GOPATH/bin/goval-dictionary /usr/local/bin
Then, fetch the OVAL data for Ubuntu 22 by running the following command:
sudo goval-dictionary fetch ubuntu --dbpath=/usr/share/vuls-data/oval.sqlite3 22
Here you downloaded and installed goval-dictionary and then fetched the OVAL data for Ubuntu. Next, you will download and install gost and fetch the Debian security tracker data .
Installing and Running gost
In this section, you will download and build a Go package gost that provides access to the Debian security bug tracker . You will then run it and fetch vulnerability data for Vuls to use. The Ubuntu security tracker collects all the information about the vulnerability status of packages distributed with Ubuntu.
You will store this package in the same directory as before. Navigate to it by running the following command:
cd $GOPATH/src/github.com/vulsio
Clone the package from GitHub by running the following:
git clone https://github.com/vulsio/gost.git
When it completes, enter the package folder:
cd gost
Build and install it with make:
make install
Copy it to /usr/local/bin to make it globally accessible:
sudo cp $GOPATH/bin/gost /usr/local/bin
Next, create a log file directory for gost:
sudo mkdir /var/log/gost
Restrict access to the current user with the following command:
sudo chmod 700 /var/log/gost
Setting the permission flags to 700 restricts access to the owner only. To make it accessible by kerim or another user, run the following command:
sudo chown -R kerim/var/log/gost
Then, fetch the Ubuntu security tracker data by running:
gost fetch ubuntu --dbpath=/usr/share/vuls-data/gost.sqlite3
The output may be long. It may not be cleared in the terminal, in which case you can run the clear command.
You have just downloaded and installed gost, and then fetched the data for Debian. In the next step, you will download and install Vuls.
Step 2 — Downloading and Configuring Vuls
With all the dependencies installed, you will now download and build Vuls from its source code. You will also configure it to scan the local machine.
With this command, create a new directory containing the path to the Vuls repository:
mkdir -p $GOPATH/src/github.com/future-architect
Navigate to it:
cd $GOPATH/src/github.com/future-architect
Clone Vuls from GitHub by running the following command:
git clone https://github.com/future-architect/vuls.git
Enter the package folder:
cd vuls
Build and install it in one go by running:
make install
Note that this command may take some time to complete.
Copy it to /usr/local/bin to make it globally accessible:
sudo cp $GOPATH/bin/vuls /usr/local/bin
Now, you will create a configuration file for Vuls. Go back to: /usr/share/vuls-data
cd /usr/share/vuls-data
Vuls reads its configuration from config.toml. Create it using your text editor:
sudo nano config.toml
Enter the following configuration: /usr/share/vuls-data/config.toml
[cveDict]
type = "sqlite3"
SQLite3Path = "/usr/share/vuls-data/cve.sqlite3"
[ovalDict]
type = "sqlite3"
SQLite3Path = "/usr/share/vuls-data/oval.sqlite3"
[gost]
type = "sqlite3"
SQLite3Path = "/usr/share/vuls-data/gost.sqlite3"
[servers]
[servers.localhost]
host = "localhost"
port = "local"
scanMode = [ "fast" ]
#scanMode = ["fast", "fast-root", "deep", "offline"]
The first sections of this configuration ( cveDict, ovalDictand gost) point Vuls to the vulnerability databases you just added. The servers section marks the beginning of the server-related information. Separate sections will group the information about each server. With this configuration, the only server Vuls will scan is the local server: localhost.
Vuls provides four scan modes:
- Fast mode (default) scans without root privileges, has no dependencies, and is very lightweight on the target server.
- Fast root mode scans with root privileges and can detect processes that were upgraded but not yet restarted.
- Deep scan mode is the same as fast root mode but also checks changelogs, which can cause a high load on the target server.
- Offline mode scans the machine without internet access and can be used together with the other modes.
Save and close the file.
To test the validity of the configuration file, run the following command:
vuls configtest
You will get output similar to this:
Output[Jan 5 20:24:29] INFO [localhost] vuls-v0.22.0-build-20230105_201926_554ecc4
[Jan 5 20:24:29] INFO [localhost] Validating config...
[Jan 5 20:24:29] INFO [localhost] Detecting Server/Container OS...
[Jan 5 20:24:29] INFO [localhost] Detecting OS of servers...
[Jan 5 20:24:29] INFO [localhost] (1/1) Detected: localhost: ubuntu 22.10
[Jan 5 20:24:29] INFO [localhost] Detecting OS of containers...
[Jan 5 20:24:29] INFO [localhost] Checking Scan Modes...
[Jan 5 20:24:29] INFO [localhost] Checking dependencies...
[Jan 5 20:24:29] INFO [localhost] Dependencies... Pass
[Jan 5 20:24:29] INFO [localhost] Checking sudo settings...
[Jan 5 20:24:29] INFO [localhost] sudo ... No need
[Jan 5 20:24:29] INFO [localhost] It can be scanned with fast scan mode even if warn or err messages are displayed due to lack of dependent packages or sudo settings in fast-root or deep scan mode
[Jan 5 20:24:29] INFO [localhost] Scannable servers are below...
localhost
You entered the configuration correctly, and Vuls detected that it can scan the local server.
You have installed and configured Vuls to scan the local server. In the next step, you will run a local scan and view the generated report.
Step 3 — Running a Local Scan
In this step, you will run a local scan and then view the generated vulnerability report. So far, you have only configured the local server, which Vuls correctly detected in the last step. If not explicitly specified, the default scan mode is fast.
To run a scan, execute the following command:
vuls scan
The output will be similar to this:
[Jan 5 20:26:14] INFO [localhost] vuls-v0.22.0-build-20230105_201926_554ecc4
[Jan 5 20:26:14] INFO [localhost] Start scanning
[Jan 5 20:26:14] INFO [localhost] config: /usr/share/vuls-data/config.toml
[Jan 5 20:26:14] INFO [localhost] Validating config...
[Jan 5 20:26:14] INFO [localhost] Detecting Server/Container OS...
[Jan 5 20:26:14] INFO [localhost] Detecting OS of servers...
[Jan 5 20:26:14] INFO [localhost] (1/1) Detected: localhost: ubuntu 22.10
[Jan 5 20:26:14] INFO [localhost] Detecting OS of containers...
[Jan 5 20:26:14] INFO [localhost] Checking Scan Modes...
[Jan 5 20:26:14] INFO [localhost] Detecting Platforms...
[Jan 5 20:26:14] INFO [localhost] (1/1) localhost is running on other
[Jan 5 20:26:14] INFO [localhost] Scanning OS pkg in fast mode
[Jan 5 20:26:14] INFO [localhost] Scanning listen port...
[Jan 5 20:26:14] INFO [localhost] Using Port Scanner: Vuls built-in Scanner
Scan Summary
================
localhost ubuntu22.10 695 installed
To view the detail, vuls tui is useful.
To send a report, run vuls report -h.
Vuls logged what it did during the process. To view the report of the vulnerabilities it identified, run:
vuls tui
Vuls divides the report view into four panes:
- Scanned machines, located at the top left, lists the machines Vuls scanned.
- Found vulnerabilities is to the right of the machine list and shows the vulnerabilities found in the installed packages.
- Details takes up the left side of the screen and shows detailed information about the vulnerability retrieved from the databases.
- Affected packages, to the right of the details, shows what the affected package versions are and whether there is a fixed version.

You can move your cursor between each of the panes by pressing ENTER. You can navigate within each pane using the keyboard arrows. When you are done, press CTRL+C to exit.
In this step, you ran a local scan and reviewed the results. In the next (optional) section, you will configure Vuls to scan multiple target machines.
Step 4 — (Optional) Configuring Multiple Target Machines
In this section, you will configure Vuls to scan multiple target machines. This process requires configuring /etc/sudoers on the target machines and configuring Vuls to scan that target.
You can add as many servers as you like, provided you have the IP address of the target server, root access to the target server, and an available account on the target server ( kerim-shark in this tutorial).
To scan in fast mode, you can use just a non-root user account on the target server. To enable scanning in fast root and deep modes, you need to edit the /etc/sudoers file on the target machine(s). The sudoers file controls which users can run which commands and whether you need a password for the specified commands.
Because of the importance of the sudoersfile, it will warn you if you try to exit with an error.
On the target server, log in as root and open sudoers for editing by running visudo:
visudo
Add this line to the end of the file: /etc/sudoers
kerim-shark ALL=(ALL) NOPASSWD: /usr/bin/apt-get update, /usr/bin/stat *, /usr/sbin/checkrestart
This line instructs sudo to allow the user kerim-shark to run apt-get update, checkrestart and stat commands without providing a password.
Save and close the file. If you made a syntax error during the process, visudo will notify you and suggest that you edit again or exit.
Note: By adding the user kerim-shark to sudoers, you allow Vuls to scan using the fast root and deep modes. If you also want to allow these modes for the local machine (localhost), you can edit sudoers on localhost. sudoers
Vuls uses the checkrestart utility to check for packages that were updated but require a restart. To make sure it is on the target server, install it on your secondary server(s) by running the following command:
apt install debian-goodies -y
That is all you need to do on the target server. You can now log out of the target and return to your first server.
To add a new server for scanning, open config.toml and add the following lines under the [servers] marker:/usr/share/vuls-data/config.toml
[servers.target_name]
host = "target_ip"
port = "22"
user = "account_username"
keyPath = "/home/kerim/.ssh/id_rsa"
scanMode = [ "deep" ] # "fast", "fast-root" or "deep"
The lines above are a template for adding new servers. Remember to replace target_namewith the name you want, target_ip with the target server's IP, account_usernamewith the username (this tutorial uses kerim-shark), and to provide the path to your private RSA key for the user kerim. Vuls does not support SSH password authentication, so specifying a keyPath is required.
Save and close the file.
Next, for each target server you added, you will approve the RSA keys on the local machine. To accomplish this, you will log in to the target server from your first server with the appropriate key, for example:
ssh kerim-shark@target_ip -i /home/kerim/.ssh/id_rsa
Remember to enter the path to your private RSA key. When asked whether you want to continue connecting, enter yes and then log out by pressing CTRL + D.
Note: If you get an error that the key file permissions are too open, set the permissions to 600 by running the following command:
chmod 600 account_rsa_key
Setting the permissions to 600 ensures that only the owner can read and write the key file.
To check the validity of the new configuration, run the following command:
vuls configtest
The output will detail everything Vuls checks, such as dependencies, superuser access and operating system versions. If there are any errors, compare config.toml with the configuration provided earlier in this section.
In this step, you added more servers to your Vuls configuration by marking them for scanning. In the next section, you will configure Vuls to scan periodically and send reports to a Slack workspace.
Step 5 — Configuring Periodic Scanning and Reporting to Slack
Now you will configure Vuls to send reports to Slack and set up a cron job to run Vuls scans periodically.
To use the Slack integration, you need to have an incoming webhook in Slack for your workspace . Incoming webhooks allow an app to provide real-time information from other applications. In this case, you will configure Vuls to report to your Slack channel.
If you have not created a webhook, you first need to create an app for your workspace. To do this, first log in to Slack and go to Slack's app creation page . Choose a name you will recognize, select the workspace you want, and press Create App .
You will be redirected to the new app's settings page. In the left navigation bar, select Incoming Webhooks .

Enable webhooks by switching the toggle next to the Activate Incoming Webhooks heading to the On position .

Once enabled, a new section will load on the page. Go to the Add New Webhook to Workspace button and press it . A new page will open asking for access to your workspace. Select the channel you want the reports to be sent to and press Allow .
You will be redirected back to the settings page for webhooks, and a new webhook will now be listed in the table under Webhook URL . Click Copy to copy the URL and make a note of it for later use.
Back in your terminal on the first server, open config.toml for editing:
sudo nano config.toml
Add the following lines: /usr/share/vuls-data/config.toml
[slack]
hookURL = "your_hook_url"
channel = "#your_channel_name"
authUser = "your_username"
#notifyUsers = ["@username"]
Replace your_hook_URL with the webhook URL you noted, your_channel_name with the name of the desired channel, and your_username with the username of the Slack user who created the webhook. Save and close the file.
To test the integration, you can generate a report by running vuls report:
sudo vuls report -to-slack
Vuls will take a few minutes to run and exit. If it returns an error, check what you entered in the previous lines.
Check your Slack app to verify that Vuls successfully sent the report to the specified channel.

Now that you have configured reporting, you can set up scheduled scans. Cron is a time-based job scheduler that comes with every Ubuntu machine. It is configured through the crontab file, which defines in exact syntax when a command should run. To help with editing, you will use the crontab utility, which opens the current file in an editor. crontab
Open the current crontab file by running the following command:
crontab -e
When prompted, choose your preferred text editor from the list.
Add the following line to the end of the file:
0 0 * * * vuls scan -config=/usr/share/vuls-data/config.toml; vuls report -config=/usr/share/vuls-data/config.toml > /dev/null 2>&1
This line tells cron to run vuls scan and vuls report with the specified configuration every day at noon ( represented by 0 0 * * * in the cron syntax).
Save and close the file.
In this step, you connected Vuls to your Slack workspace and configured cron to run a Vuls scan and report to Slack every day at noon.