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.
Our Free and Basic plans allow setting up and running the internal network scanner to do a Host Discovery scan. This will not impact your plan usage. To perform a full vulnerability scan, a Premium or MSP plan is required.
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 | 16 GB | 80 GB |
| ~ 2,500 | 6 cores | 20 GB | 100 GB |
| ~ 10,000 | 8 cores | 24 GB | 120 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 or later LTS |
| Ubuntu | 24.04 or later LTS |
| RHEL/CentOS | 9 or later LTS |
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 (automatic)
The easiest way to get started is to run our single install script. This will perform all the manual steps detailed in the section below, along with installing docker, and performing any cleanup (in the event of upgrading).
To do so, follow these quick setup steps.
Install the agent (manual)
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:
compose.yml # docker compose for OpenVAS
hostedscan-agent.service # systemd configuration for the agent
hostedscan-update-feed.service # systemd service for OpenVAS feed updates
hostedscan-update-feed.timer # systemd timer for scheduling feed updates at 2:00 AM
hostedscan.rotate # logrotate for OpenVAS, and other logs
update_feed.sh # script to update OpenVAS feeds
Both the HostedScan Agent key and OpenVAS password are stored in the .hostedscan directory.
- Move the systemd file to the proper location, and ensure they have correct permissions:
mv hostedscan-agent.service /etc/systemd/system/
mv hostedscan-update-feed.service /etc/systemd/system/
mv hostedscan-update-feed.timer /etc/systemd/system/
mv /opt/hostedscan/hostedscan.rotate /etc/logrotate.d/hostedscan
chmod 644 /etc/systemd/system/hostedscan-agent.service
chmod 644 /etc/systemd/system/hostedscan-update-feed.service
chmod 644 /etc/systemd/system/hostedscan-update-feed.timer
chmod 644 /etc/logrotate.d/hostedscan
- 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.
Feed Updates
It is important to update OpenVAS feeds regularly to ensure you have the latest vulnerability tests and security data. The agent generates an update_feed.sh script that downloads and updates the Greenbone Community Edition feed data containers.
Manual Feed Update
To manually update the feeds, run:
cd /opt/hostedscan
./update_feed.sh
Automated Feed Updates
When you copied the hostedscan-update-feed.service and hostedscan-update-feed.timer, you setup automatic feed updates for OpenVAS.
The feed updates are set to occur at 2 AM by default. You can adjust this time by modifying hostedscan-update-feed.timer.
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 -n 1000
Check the automatic feed update logs:
journalctl -u hostedscan-update-feed.service -n 1000
To view the OpenVAS container logs, from /opt/hostedscan run:
docker compose logs -f