Install the Internal Scanner on Linux

The HostedScan Internal Scanner is designed to run on Linux systems; both x64 and ARM processor builds are available.

tip

This secure solution does not require any open ports, tunnels, or other access to your network.

Scanning Server

To run vulnerability scans on an internal network, you will install trusted vulnerability scanners that are widely used across the industry by millions of cybersecurity professionals, alongside the lightweight HostedScan Internal Scanner application.

The internal scanner is installed on a scanning server alongside the underlying vulnerability scanners. It coordinates the running of scans and the collection of results, and connects 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 Internal Scanner 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 internal scanner with it.

Network

The HostedScan Internal Scanner and OpenVAS access these domains:

Domain	Port	Protocol	Reason	Required
api.hostedscan.com	443	HTTPS	Allows the internal scanner to receive commands and send scan results	yes
api.hostedscan.com	443	WSS	Real-time communication with the internal scanner via websockets	no
registry.community.greenbone.net	443	HTTPS	Install OpenVAS/GVM Scanner and update vulnerability feeds	yes

Install the internal scanner (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 internal scanner (manual)

tip

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.

Set up an internal scanner source on hostedscan.com. See the Set Up and Run the HostedScan Internal Scanner 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 internal scanner binary to the scanning server. For example, from your local machine:

scp hostedscan-agent user@your-server-ip:~/

On the scanning server, place the binary in /opt/hostedscan/ and make it executable:

cp hostedscan-agent /opt/hostedscan/
cd /opt/hostedscan/
chmod +x /opt/hostedscan/hostedscan-agent

Run the internal scanner with the --generate flag 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 internal scanner
  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 internal scanner installation and the associated files:

chown -R hostedscan:hostedscan /opt/hostedscan/

Enable and start the internal scanner:

systemctl daemon-reload
systemctl enable hostedscan-agent.service
systemctl start hostedscan-agent.service

Check the internal scanner logs to ensure it has started:

journalctl -u hostedscan-agent.service -f

tip

If no logs appear, restart journald:

systemctl restart systemd-journald

You can also find the logs in the file /var/log/syslog

The internal scanner will now attempt to connect to OpenVAS. Proceed to set up 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

tip

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 Internal Scanner 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 internal scanner 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 internal scanner status:

systemctl status hostedscan-agent.service

Restart the internal scanner:

systemctl restart hostedscan-agent.service

Stop the internal scanner:

systemctl stop hostedscan-agent.service

View the internal scanner 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

Scanning Server​

System requirements​

Recommended resources​

Operating System​

Docker​

Network​

Install the internal scanner (automatic)​

Install the internal scanner (manual)​

Setup the OpenVAS scanner​

Feed Updates​

Manual Feed Update​

Automated Feed Updates​

Helpful Commands​