Install the agent on Linux
The agent is designed to run on Linux systems, both x64 and ARM processors builds are available.
This secure solution does not require any open ports, tunnels, or other access to your network.
Internal scanning requires a Premium or MSP account. If you have a Premium or MSP account, please contact us to enable internal scanning for your account.
Scanning Server
To run vulnerability scans on an internal network, you will install trusted scanners that are widely used across the industry by millions of cybersecurity professionals along with a lightweight agent application.
The agent is installed on a scanning server alongside the vulnerability scanners. The agent interfaces with the vulnerability scanners to coordinate the running of scans and the collection of the results, along with connecting to HostedScan to enable full command and control from your HostedScan dashboard.
System requirements
Recommended resources
To run scans effectively, we recommend that the scanning machine scales based on the number of active IPs scanned:
| Active IPs | CPU | RAM | Disk Space |
|---|---|---|---|
| ~ 512 | 4 cores | 8 GB | 60 GB |
| ~ 2,500 | 6 cores | 12 GB | 80 GB |
| ~ 10,000 | 8 cores | 16 GB | 100 GB |
Additional resources may improve scan performance.
Operating System
The HostedScan agent runs on most common Linux distributions. Officially tested and supported on:
| OS | Version |
|---|---|
| Debian | 12+ |
| Ubuntu | 24.10+ |
| RHEL/CentOS | 9+ |
Docker
The recommended setup uses Docker Compose with Greenbone Community Edition containers. This requires Docker and Docker Compose to be installed on the scanning server - https://docs.docker.com/compose/install/.
Alternatively, you can run your own OpenVAS/GVM installation and interface the agent with it.
Network
The HostedScan agent and OpenVAS access these domains:
| Domain | Port | Protocol | Reason | Required |
|---|---|---|---|---|
| api.hostedscan.com | 443 | HTTPS | Allows agent to receive commands and send scan results | yes |
| api.hostedscan.com | 443 | WSS | Real-time communication with agent via websockets | no |
| registry.community.greenbone.net | 443 | HTTPS | Install OpenVAS/GVM Scanner and update vulnerability feeds | yes |
Install the agent
Commands are shown for root users. Use sudo if running as a less privileged user.
These steps are expected to be run on the scanning server.
-
Setup an agent source on hostedscan.com. See the Setup and Run the HostedScan agent guide for getting started.
-
Create a user for running the hostedscan-agent:
useradd --system --home-dir /opt/hostedscan --create-home --shell /usr/sbin/nologin hostedscan
This creates the hostedscan user with a home directory at the install location.
- Copy the agent to the scanning server. For example, from your local machine:
scp hostedscan-agent user@your-server-ip:~/
- On the scanning server, place the agent in
/opt/hostedscan/and make it executable:
cp hostedscan-agent /opt/hostedscan/
cd /opt/hostedscan/
chmod +x /opt/hostedscan/hostedscan-agent
- Run the agent with the
--generateflag to generate the necessary files for installation.
./hostedscan-agent --generate
You will be prompted to enter both your HostedScan Agent key, and a password for your OpenVAS install. The OpenVAS password is something you choose, and sets the credentials for interacting with the OpenVAS scanner.
This generates:
/opt/hostedscan/compose.yml # Docker compose file for OpenVAS
/opt/hostedscan/hostedscan-agent.service # Systemd configuration for the agent
Both the HostedScan Agent key and OpenVAS password are stored in the .hostedscan directory.
- Move the systemd file to the proper location:
mv hostedscan-agent.service /etc/systemd/system/
- Ensure the correct permissions on the agent installation and the associated files:
chown -R hostedscan:hostedscan /opt/hostedscan/
- Enable and start the agent:
systemctl daemon-reload
systemctl enable hostedscan-agent.service
systemctl start hostedscan-agent.service
- Check the agent logs to ensure the agent has started:
journalctl -u hostedscan-agent.service -f
If no logs appear, restart journald:
systemctl restart systemd-journald
You can also find the logs in the file /var/log/syslog
The agent will now attempt to connect to OpenVAS. Proceed to setup the OpenVAS scanner.
Setup the OpenVAS scanner
OpenVAS runs as a collection of docker containers. Ensure the docker engine is installed before continuing.
- From
/opt/hostedscan/run:
docker compose up -d
This uses the compose.yaml file to pull images and start containers.
- Enable Docker on startup:
systemctl enable docker
The first launch of OpenVAS may take an hour or longer before it is ready. Subsequent restarts are faster but may still take a few minutes.
The HostedScan agent monitors OpenVAS and will start scans when OpenVAS is ready.
Helpful Commands
Check agent status:
systemctl status hostedscan-agent.service
Restart the agent:
systemctl restart hostedscan-agent.service
Stop the agent:
systemctl stop hostedscan-agent.service
View the agent logs:
journalctl -u hostedscan-agent.service -f
To view the OpenVAS container logs, from /opt/hostedscan run:
docker compose logs -f