Skip to content

Vulners proxy

Having several Vulners agents running on similar hosts may result in many identical requests being sent to Vulners. This also applies to the use of API when controlling similar machines. To avoid the unnecessary waste of credits and add another layer of security to your infrastructure, we are happy to introduce to you our very own Vulners proxy.

Vulners proxy is a caching proxy that allows you to optimize the number of API requests sent by your infrastructure to the Vulners database. All you need is to set up Vulners proxy and redirect all your agents and API requests to it, where they will be processed and the results cached, thereby eliminating unnecessary requests to the Vulners database. In addition, this feature provides data obfuscation where all real IP addresses from similar hosts undergo encryption.

Installation

Debian-based OS

First, add vulners.com pubkey: 

wget -O- https://repo.vulners.com/pubkey.txt | apt-key add -

Then, create file /etc/apt/sources.list.d/vulners.list

deb http://repo.vulners.com/debian focal main

Finally, install package:

apt-get update && apt-get install vulners-proxy

Source code

You can clone the source code and run the server using Python.

  • Install python3 and python3-pip
  • Clone source code from repository git clone https://github.com/vulnersCom/vulners-proxy.git
  • Install requirements.txt with pip install -U -r requirements.txt
  • You can run the server manually using the command uvicorn main:app --host 0.0.0.0 --port 8000
  • Or you could configure systemd to run the server as a service. See example below:
$ cat /etc/systemd/system/vulners-proxy.service
[Unit]
Description=Vulners proxy
After=network.target

[Service]
WorkingDirectory=/var/lib/vulners-proxy
User=nobody
PermissionsStartOnly=true
ExecStart=/usr/local/bin/uvicorn main:app --host 0.0.0.0 --port 8000

[Install]
WantedBy=multi-user.target

Proxy configuration

Proxy configuration is located in file /etc/vulners_proxy/vulners_proxy.conf. See example below: 

[logging]
LogFile = /var/log/vulners_proxy/vulners_proxy.log
LogLevel = ERROR

[app]
Workers = 1
Port = 8000
Host = 0.0.0.0
Reload = False
ApiCacheTimeout = 3600                  # seconds
CacheTimeout = 10800                    # seconds
CacheDir = /tmp/vulners-proxy.cache/
StatisticCacheDir = /tmp/vulners-proxy.statistic.cache/
Secret = secret_for_encrypt_ip_fqdn     # 32 symbols required length
EnableEncryption = 0                    # 0 - disabled, 1 - enabled
ApiRequestTimeout = 120

[vulners]
ApiKey = YOUR_SECRET

You can adjust logging settings, the proxy server host and port, cache directory, and timeout.

Also, the proxy can encrypt the IPs and FQDN of your agents before forwarding them to Vulners. To enable this feature, set a secret key and change the EnableEnclyption flag to 1.

NB. While the encryption is enabled, you will not be able to see readable agent identificators in Linux scanner dashboard, only hashes. If you would like to get nice reports, you should configure a custom dashboard on your side of the proxy. For example, you can use Defect Dojo with Vulners plugin.

Proxy start

Run service 

systemctl daemon-reload; systemctl enable vulners-proxy; systemctl start vulners-proxy

Agent configuration

Now, configure you Vulners agents and redirect traffic to proxy. Agent configuration is located in file /etc/vulners/vulners_agent.conf.

Add the proxy host address at the end.

[DEFAULT]
api_key = YOUR_SECRET
vulners_host = http://<proxy_vm_ip_address_or_fqdn>:8000

API configuration

If you want to redirect your API requests to proxy, use a constructor with a server_url parameter, see below: 

import vulners

vulners_api = vulners.VulnersApi(api_key="YOUR_SECRET", server_url="http://<proxy_vm_ip_address_or_fqdn>:8000")

# Plain text software + version example for Ngnix 1.4
sw_results = vulners_api.get_software_vulnerabilities("nginx", "1.4")
sw_exploit_list = sw_results["exploit"]

Proxy UI

Vulners proxy has a simple web GUI. With it, you can monitor the proxy status, credits consumption, and some statistics. To log in to the GUI, set your API key in the proxy configuration. To generate an API key, log in to Vulners, go to the userinfo space and click on the API KEYS tab. In the "Scope" field, select "scan", and click SAVE. The result should look something like this:

RGB9YPJG7CFAXP35PMDVYFFJPGZ9ZIRO1VGO9K9269B0K86K6XQQQR32O6007NUK

To see GUI, open proxy host in browser:

Proxy GUI

Docker

Finally, you can simply run the Docker image: 

docker run vulners/proxy

Or you can forward the default port and set the API key, so you could use the UI:

docker run -p 80:8000 -e apiKey=YOUR_SECRET vulners/proxy

To set the configuration, mount the config file to your container:

docker run --rm -p 8000:8000 -v /path/to/local/config.conf:/etc/vulners_proxy/vulners_proxy.conf vulners/proxy:latest
Back to top