Scanning

Hawkra supports multiple scanning methods to discover assets and vulnerabilities across your networks. Scanners are configured in the Admin Dashboard under the Scanning section.

WingSpan Agent

WingSpan is Hawkra's deployable scanning agent. It can be installed on remote endpoints to scan networks from different vantage points, with results automatically fed back into Hawkra. WingSpan agents are managed from the Scans tab within each workspace. See the WingSpan documentation for deployment and usage details.

Nmap

Nmap is a network port scanner and service detection tool. Due to the Nmap Public Source License (NPSL), Nmap must be explicitly opted into by an administrator via the Scanning section on the Admin Dashboard.

Click Install Nmap and accept the license agreement to enable it. Nmap is installed at the container level and must be re-installed after each container restart.

Once enabled, users can run Nmap scans from the Scans > Third Party Scanners tab in any workspace.

OpenVAS

OpenVAS (Open Vulnerability Assessment Scanner) is a full-featured vulnerability scanner. Hawkra can connect to one or more remote OpenVAS servers over SSH to run scans and automatically import results. You can configure up to 10 OpenVAS servers and choose which one to use for each scan.

Prerequisites

The OpenVAS server must have gvm-tools installed. This is the command-line interface Hawkra uses to communicate with the GVM daemon over SSH.

Install gvm-tools on the OpenVAS server:

apt-get install python3-pip
pip3 install --user gvm-tools

Or alternatively:

python3 -m pip install gvm-tools

Verify the installation:

gvm-cli --version

The SSH user that Hawkra connects with must be a member of the gvm group, otherwise it will not have permission to communicate with the GVM daemon socket:

sudo usermod -aG gvm $USER

Log out and back in (or restart the SSH session) for the group change to take effect.

Configuration

OpenVAS servers are managed in the Admin Dashboard under Scanning → OpenVAS Servers. You can configure up to 10 servers, each identified by a unique name.

Click Add Additional OpenVAS Server and fill in:

Field	Encrypted	Description
Name	No	A label used to identify this server (must be unique).
Server IP	No	IP address or hostname of the OpenVAS server.
SSH Username	No	SSH username for connecting to the OpenVAS server.
SSH Password	Yes	SSH password for connecting to the OpenVAS server.
GVM/Web Username	No	GVM/gvm-cli username for authenticating with the OpenVAS daemon.
GVM/Web Password	Yes	GVM/gvm-cli password for authenticating with the OpenVAS daemon.

Each server has its own Test Connection button to verify that Hawkra can reach it and authenticate over SSH + GMP. Use Edit to change a server's details (leave the password fields blank to keep the existing passwords) and Remove to delete one. A server cannot be removed while it has a scan in progress.

Passwords are encrypted at rest.

tip

The SSH user must be a member of the gvm group and able to run gvm-cli on the OpenVAS server. The GVM user/password is the credential used to authenticate with the GVM daemon itself (the same credentials you would use in the Greenbone web interface).

Running a Scan

From the Scans → Third Party Scanners tab in a workspace, select OpenVAS as the scanner type, then configure:

• Scanner — the configured OpenVAS server to use, selected by name. If only one server is configured it is selected automatically. A server already running a scan is shown as "(scan in progress)" and cannot be selected until it finishes.
• Network — the workspace network to import results into.
• Port List, Scan Configuration, Scanner Config — synced from the selected server.
• Target — a single IP address or a CIDR range to scan.
• Excluded Targets (optional) — a comma-separated list of IP addresses to exclude from the scan. These are passed to OpenVAS as excluded hosts on the scan target.
• Alive Test (experimental — see note) — controls how OpenVAS decides whether a host is alive before scanning.

Multiple OpenVAS scans can run at the same time on different servers, but Hawkra blocks starting a second scan on a server that is already scanning. This block is global — it applies across all workspaces, because the server is a shared resource. Each scan imports into the network chosen for it.

Alive Test is experimental

The Alive Test option is still being stabilized and may not behave correctly in all cases. Unless you are specifically testing it, leave it set to Scan Config Default.

How It Works

Once a server is configured, Hawkra syncs its available scan configurations, scanners, and port lists. When a scan is started, Hawkra connects over SSH using that server's credentials and:

1. Creates a target (including any excluded hosts) and a task on the OpenVAS server.
2. Starts the scan and polls progress every 3 minutes.
3. When the scan completes, retrieves the report and imports the results (assets, ports, vulnerabilities) into the selected network.

Scan progress and results are visible in real time from the Third Party Scanners tab.

Connection loss and recovery

The scan itself runs on the OpenVAS server, so a temporary loss of connectivity between Hawkra and the server does not stop it. If a progress poll fails, Hawkra:

• Keeps retrying (at a faster cadence) for up to 1 hour, showing a "Connection lost — retrying" indicator on the scan. If connectivity returns within that window, monitoring resumes and the results import normally.
• After 1 hour of continuous failure, marks the scan failed with a message that the instance was unreachable and the results must be imported manually. The scan may still complete on the OpenVAS server.

A failed OpenVAS scan that had already started on the server offers two actions in the scan list:

• Attempt to Reconnect — Hawkra tries once to re-attach to the running task. On success the scan resumes and imports when it finishes; on failure the scan stays stopped so you can try again or discard it.
• Discard Scan Task — marks the scan discarded in Hawkra. Because the connection was lost, this does not stop the scan on the OpenVAS server; stop it from the OpenVAS web interface if needed.

If the Hawkra backend restarts while OpenVAS scans are running, it automatically resumes monitoring them on startup.