Mixeway OpenVAS REST API

Informations

Due to problems with using standard TCP Socket which is avaliable after running GVMD process on listening port, we have decided to release REST API for OpenVAS.

This application is using GVM-CLI in order to communicate with unix scocket so it has to be run on the same machine as OpenVAS.

Requirements

1. JAVA 1.8
2. MVN (if installing from sources)
3. OpenVAS installed (https://www.openvas.org/)
4. OpenVAS tools installed (https://github.com/greenbone/gvm-tools)
5. OpenVAS manager (GVMD) process has to be running on unix socket (path to the socket will be needed)
6. PKCS12 file which will contain

Installation

From Sources:

git clone https://github.com/mixeway/mixewayopenvasrestapi
cd mixewayopenvasrestapi
mvn package
# If You want to generate self-signed certificates
# ./setup-certs.sh
# Make sure You know location of trust-store or You have generated one
java -jar target/MixewayOpenVasRestAPI-1.0.0-SNAPSHOT.jar \
    --server.port=8443 \
    --server.ssl.key-store=pki/localhost.p12 \
    --server.ssl.key-store-password=qwerty \
    --server.ssl.trust-store=/etc/pki/localhost.jks \ 
    --server.ssl.trust-store-password=qwerty \
    --openvasmd.socket=/usr/local/var/run/openvasmd.sock \
    --allowed.users=localhost

From Binary:

wget ...
# If You want to generate self-signed certificates download setup scripts or prepare JKS and PKCS12 on YOur own
# Make sure You know location of trust-store or You have generated one
java -jar target/MixewayOpenVasRestAPI-1.0.0-SNAPSHOT.jar \
    --server.port=8443 \
    --server.ssl.key-store=/etc/pki/certificate.p12 \
    --server.ssl.key-store-password=changeit \
    --server.ssl.trust-store=/etc/pki/localhost.jks \ 
    --server.ssl.trust-store-password=changeit \
    --openvasmd.socket=/usr/local/var/run/openvasmd.sock \
    --allowed.users=localhost

Parameters for running:

Parameter	Default Value	Description
server.port	8443	Port REST API will listen on
server.ssl.key-store	pki/certificate.p12	PKCS12 keystore (containing privatekey and certificate) which will be used to encrypt traffic
server.ssl.key-store-password	changeit	password for PKCS12 file
server.ssl.trust-store	/etc/pki/localhost.jks	Java Keystore used to verify if connecting client can be trusted. Mixeway certificate has to be added into this JKS
server.ssl.trust-store-password	changeit	password for JSK file
openvasmd.socket	/usr/local/var/run/openvasmd.sock	path for Unix Socket of OpenVAS Manager (GVMD)
allowed.users	localhost,127.0.0.1	Common Name of TLS Certificate which is allowed to send signed request to REST API (comma separeted if more needed)

Authentication

Mixeway OpenVAS REST API in version 1.0.0 is using only TLS Certificate base authentication. Which means only request signed by trusted TLS Certificate with CN on allow list (allowed.users) can be authenticated.

Mixeway already signs all outgoing requests with its certificate so make sure that Mixeway's certificate is added to trust store and allowed.users is set properly.

Authentication on OpenVAS side is made by username/password generated in OpenVAS (through CLI, gmv-tools or GUI).

For Debugging purposes example command:

curl --insecure --cert cert.crt --key private.key \
     --header "Content-Type: application/json" \
     --request POST \
     --data '{"username":"openvasadmin","password":"changeit"}' \
     "https://127.0.0.1/initialize"

API Methods

Path	HTTP Method	Request Body	Description
/initialize	POST	{ "username":"openvasadmin", "password":"changeit"}	Testing endpoint for verification if everything works properly
/createtarget	POST	{ "user": { "username":"openvasadmin", "password":"changeit" }, "params": { "name":"test_target", "hosts":"127.0.0.0/28" }}	Method which will create targets with name and host values hosts
/createtask	POST	{ "user": { "username":"openvasadmin", "password":"changeit" }, "params": { "config_id":"ffffff-ffff-ffff-ffffffffffff", "target_id":"ffffff-ffff-ffff-ffffffffffff", "name":"task_name", "scanner_id":"ffffff-ffff-ffff-ffffffffffff" }}	Method which will create taks with given configuration, on particular scan and selected target
/starttask	POST	{ "user": { "username":"openvasadmin", "password":"changeit" }, "params": { "task_id":"ffffff-ffff-ffff-ffffffffffff" }}	Starting task by task_id
/checktask	POST	{ "user": { "username":"openvasadmin", "password":"changeit" }, "params": { "task_id":"ffffff-ffff-ffff-ffffffffffff" }}	Checking status of task (Running, completed)
/getreport	POST	{ "user": { "username":"openvasadmin", "password":"changeit" }, "params": { "report_id":"ffffff-ffff-ffff-ffffffffffff" }}	Getting vulnerabilities from OpenVAS by report_id