WingSpan Agent Scanner
Requires Premium (or Self-Hosted).
WingSpan is Hawkra's agent-based network scanner. It discovers live hosts, open ports, running services and operating systems, and can optionally check for common vulnerabilities such as anonymous access, default credentials and misconfigurations. Scan results automatically create and update assets and ports in your workspace, keeping your inventory current without manual data entry.
How It Works
WingSpan scans are run by an agent: a small program that runs on a machine with network access to the systems you want to scan. You give the agent a scan task in Hawkra, the agent runs it, and it streams progress back while the scan runs. When the scan finishes, the results are imported into your workspace.
There are two kinds of agent:
- Deployed agents run on a machine you choose, such as a laptop on a client network or a server in a DMZ. Use these to scan networks the Hawkra server cannot reach.
- Hawkra Host is a built-in agent that runs on the Hawkra server itself. It is available on self-hosted installs and needs no download or setup.
Both appear in the Active Agents table on the WingSpan Scanner tab of a workspace's Scans tab, and both use the same scan form, task list and progress display.
Deploying an Agent
- Open the workspace's Scans tab and select WingSpan Scanner.
- Click Deploy New Agent and enter a name that identifies the agent, such as
Office ScannerorDMZ Agent. - Choose the platform of the machine that will run it and download the agent binary. The binary already contains everything it needs to connect to Hawkra; there is no token to copy.
- Copy the binary to the target machine and run it.
- When the agent connects, it appears in the Active Agents table as Pending Approval. Click Approve to let it receive scans, or Deny to remove it.
An agent that is still pending (never connected, or connected but not approved) after an hour is removed automatically. You can run several agents in a workspace, for example one per network segment.
Hawkra Host
On self-hosted installs, every workspace has a built-in agent called Hawkra Host. It is listed first in the Active Agents table with a Built-in tag.
- It needs no download and no approval. New Scan is always available to anyone who can edit the workspace.
- Its badge reads Ready when idle and Running while a scan is in progress.
- It cannot be approved, revoked or deleted. To turn it off for everyone, use the admin switch described below.
Hawkra Host starts a short-lived scanner container on the Hawkra server when a scan is waiting, and stops it about a minute after the last scan finishes. Each workspace gets its own scanner, so scans in different workspaces can run at the same time (up to three at once across the server; other workspaces wait as Pending until a slot frees up).
Requirements
- A Linux Docker host. The scanner uses host networking to reach your LAN, which Docker Desktop for Mac and Windows does not provide.
- The Docker socket mounted into the Hawkra backend. This is already the case in the standard self-hosted and air-gapped Docker Compose files.
- An x86_64 or arm64 server.
If Hawkra is not running from its Docker image (for example, a native development install), set the HOST_AGENT_IMAGE environment variable to the image the scanner container should use. Without either, scans fail with Hawkra Host scanning requires Hawkra to run from its Docker image, or HOST_AGENT_IMAGE to be set.
One Scan at a Time per Workspace
Hawkra Host runs one scan at a time in each workspace. If you start another scan while one is running, it waits as Pending and starts automatically when the first one finishes. You can cancel a pending scan at any time.
The Admin Switch
Administrators can turn Hawkra Host on or off under Admin > Settings > Scanning > Enable Hawkra Host Scanning. It is on by default.
When the switch is off:
- The Hawkra Host row is hidden in every workspace.
- New Hawkra Host scans are refused with
Host scanning is disabled by an administrator. - Scans already running finish normally.
- Scans that were already queued stay queued and start when the switch is turned back on. While the row is hidden, the history for those scans shows the agent as Unknown.
What the Switch Grants
Hawkra Host has no restrictions on its targets. Any workspace editor can point it at anything the Hawkra server can reach: the server itself (loopback), the Docker networks Hawkra runs on, and your LAN. This is the same freedom a deployed agent has on the machine it runs on, but here the machine is your Hawkra server.
Leave the switch on only if you trust everyone who has edit access to your workspaces. Turn it off if you do not.
The scanner container itself is limited: 1 CPU, 1 GiB of memory and at most 256 processes, only the raw-socket capability WingSpan needs (everything else is dropped and it cannot gain privileges), no access to the Docker socket, and no files from the host mounted into it.
Running a Scan
- In the Active Agents table, click New Scan on the agent you want to use. Deployed agents must be online and approved; Hawkra Host is always available.
- Fill in the New Scan Task form:
| Field | Description |
|---|---|
| Network | The network in your workspace the results belong to. Required. Selecting a network fills in its CIDR range as the target. |
| Target | The address range or host to scan, such as 192.168.1.0/24 or 10.0.0.1. |
| Ports | Optional. A list or range such as 22,80,443 or 1-1000. Leave blank to scan the top 100 ports. |
| Scan Speed | A preset from Very Slow to Very Fast. Defaults to Medium. Slower presets send fewer probes at a time and wait longer for replies, which is gentler on fragile networks. Faster presets finish sooner but are noisier and may miss results on slow networks. |
| Bruteforce Unknown Services | Try many protocols against open ports whose service could not be identified. |
| Skip Host Discovery | Treat every address in the target as online and go straight to port scanning. Use this when hosts block discovery probes. |
| Vulnerability Scanning (Beta) | Check discovered services for anonymous access, default credentials and misconfigurations. |
| Exclusions | Addresses or CIDR ranges to skip, one per line. Use this to protect devices that must not be scanned. |
- Optionally open Advanced Configuration to override the values set by the speed preset: Max Hosts, Concurrency, Rate Limit (pps), Connect Timeout (ms), Retries, Discovery Timeout (s) and Host Timeout (ms). Choosing a speed preset resets these to that preset's values.
- Click Start Scan.
Only scan networks and systems you own or have written permission to test.
Task States and Progress
Every scan is a task in the task list, which shows the date, target, agent, status, results and duration. A task moves through these states:
Pending --> Running --> Completed
\--> Failed
\--> Cancelled
| State | Meaning |
|---|---|
| Pending | The task is queued. It starts when the agent picks it up, or, for Hawkra Host, when a scanner container is available. |
| Running | The agent is scanning. The status shows a progress percentage, and the results column shows what the scan is doing now. |
| Completed | The scan finished and its results have been imported. |
| Failed | The scan could not finish. The results column shows the reason; hover it to read the whole message. |
| Cancelled | A user cancelled the scan before it finished. |
Progress is pushed to the browser in real time, so you do not need to refresh the page.
Failures You May See with Hawkra Host
| Message | Meaning |
|---|---|
Hawkra Host scanner exited unexpectedly | The scanner container stopped while it still had work. The running scan fails, and so do any scans queued behind it. (The 6-hour limit below fails only the running scan.) |
Hawkra Host scanner could not reach the Hawkra server at <url> | The built-in agent could not connect to the server address taken from the backend URL (the one Deploy New Agent uses). Check that the domain resolves and routes on the Hawkra server itself. |
Hawkra Host scan exceeded the maximum scan time (6 hours) | A single scanner container is stopped after six hours. Split very large targets into smaller scans. Queued scans are not affected: only the scan that was running fails, and the queued ones start in a fresh container. |
Hawkra Host scanning is only available on x86_64 and arm64 Linux servers | The server's CPU architecture is not supported. |
server_restart | The Hawkra server restarted while the scan was running. Start the scan again. |
If Hawkra cannot reach Docker, the waiting scans fail with the reason Docker reported.
Cancelling a Scan
Click Cancel on a task that is Pending or Running. For a Hawkra Host scan, cancelling stops its scanner immediately. Cancelling does not import partial results.
A finished task (Completed, Failed or Cancelled) can be removed from the list with the delete button. Pending and running tasks cannot be deleted; cancel them first.
What Gets Imported
When a scan completes, Hawkra imports the results into the network you selected:
- New assets are created for hosts that do not already exist.
- Existing assets are updated with new information, such as operating system and MAC address.
- Ports are created for each open port found, with the protocol, service name and version where it could be identified.
- Vulnerabilities found by a vulnerability scan are created and linked to the affected assets, with the evidence captured as proof.
The Results column of a completed task summarizes how many assets and ports were created or updated.