Private Scan Hub Setup Guide

This guide explains how to deploy a private (internal) AppCheck scan hub. AppCheck provides private scan hubs to allow clients to scan target infrastructure and applications from inside their organisation’s perimeter firewall boundary (while AppCheck’s public scan hubs allow scanning from outside, over the public internet).

Note: The scan hub software is designed to be installed on servers and to be always online.  Installing hubs on personal computers and switching hubs off or disconnecting them from the internet for significant periods of time is not recommended and can result in the hub failing to update.

If you encounter any issues with hub deployment or configuration, please refer to Troubleshooting Problems Setting Up an AppCheck Scan Hub; if this does not resolve your issue you can contact our technical support team via https://appcheck-ng.com/get-help/.

Contents

1. Requirements
2. Download Image
3. Deploy Hub
4. Start Hub
5. Configure Network Access
6. Open Outbound Firewall Access
7. Limit Inbound Firewall Access
8. Complete Setup Wizard in Web Browser
9. Wait for the Hub to Provision
10. Inform AppCheck Support
11. Configure FQDN Resolution
12. Perform a Test Scan

Requirements

• Access to your organization's VM hosting platform.
• Capacity for a VM with:
  • 16GB RAM
  • 4 CPU cores
  • 60GB storage.
• Access to your organization's network admin interface to assign the scan hub the appropriate IP address with access to the scan targets.
• Access to your organization's firewall and IPS/WAF settings to enable the necessary access for the scan hub.
• Access to the scan hub's internal IP address on port 8080 so you can access it's local web GUI.

Download Image

To get started download the latest version of the bootstrap image from https://appcheck-ng.com/get-help/downloads/

The image is provides in the Open Virtual Appliance (OVA) file format which is supported by most common platforms, and as a VHD file for platforms which require that, such as HyperV and Azure.

Deploy Hub

The exact mechanism to deploy your hub will depend on your hypervisor/platform, but typically you will need to "import" the OVA image as an "appliance".

Your platform should detect the correct settings and resource allocation automatically, as is specified within the OVA file, but if you need to set them manually for any reason (such as when using the VHD instead of the OVA) you should use the requirements listed below.

OS Type

The image is based on Ubuntu Linux. Where your platform requires you to specify the OS, please select the “General Linux”, “Ubuntu (64-bit)”, “Ubuntu 18.04 (Linux) OS” or similar (the exact options will vary based on your platform).

Memory

The standard amount is 16GB. You may need to increase this in future depending on the number and size of scans you run, but this is difficult to estimate ahead of time.  A hub can operate on 8GB but would be limited in the number of concurrent scans it could run, and may not be able to install updates while scanning.

CPU

The number of assigned cores should match the maximum number of concurrent scans that you want to run, plus one core for other OS function, with a minimum requirement of 4 cores recommended.

For example, to support 4 concurrent scans, please assign 5 CPU cores.

Disk Capacity

60GB.

The VM should be configured to use dynamically allocated virtual disk/image sizing. If only static disk size allocation is supported by your platform, then the image should be statically sized to 60GB.

Cloud Deployment

Our developers have provided a guide to deploying a hub in Azure.  However, we do not maintain an Azure environment or regularly test against one. As such, though these instructions work at time of writing, changes in Azure may mean the process needs to be adjusted.

At time of writing Amazon offer a guide to converting a virtual machine into an image suitable for import to AWS EC2 at https://aws.amazon.com/ec2/vm-import/.  AppCheck does not offer an AMI image or specific guidance for deploying to other cloud platforms at this time.  

Other cloud providers may provide their own tools and documentation to aid the process of deploying an appliance to their platform.

Start Hub

Ensure that the hub has network provision and then power on the virtual machine in your hypervisor.  After a short boot process, you should be presented with a console screen like this one:

The first line includes a URL, in the above example https://192.168.0.8:8080/. If the IP address portion of this URL is the desired IP address for the hub then you can skip the next step, Assign an IP Address, though you may still wish to change the default credentials as described in that step.

Note: it is possible for this screen to load before the VM has finished establishing its network connection, in which case the IP address will be incorrect (it will use one of the hub’s internal containers’ addresses). To ensure you’re seeing the actual address you can press enter (without typing anything in the login prompt) a few times to reload the screen. If it still does not show the desired IP address then move on to Configure Hub’s Network Access.

Configure Network Access

Once the hub is deployed, access should be possible via the virtual console on your hypervisor platform. See your hypervisor (eg VMWare) documentation for further detail.

This is the only stage where you will need to interact with the Linux Command Line Interface (CLI). If somebody in your organisation is familiar with the Linux CLI it is recommended to have them assist with this step.

Required Information

Assigning an IP address can be done automatically using DHCP or statically. If you wish to assign it statically you will need to know the following:

• The desired IP address
• The gateway address
• The DNS server addresses

Logging in to the Command Line Interface

Log in to the hub's CLI with the following username:

appcheck

Contact AppCheck Support if you have not been provided with the password.

Note that both the username and password are case sensitive.

To log in type the username at the login prompt, press enter, then type the password and press enter.  The password is not shown as you type it, not even in the forms of *s.  You will need to be careful to type it correctly.  It is not unusual to take several attempts to get this right.

You should now see a command prompt, which ends with :~$ and a blinking _. This is where you will type commands, then press enter to run them.

Change Default Credentials

The credentials listed above are common to all hubs downloaded. From a security point of view is is therefore highly recommended to change these default credentials to a unique set.

To change the credentials run the following command when logged in as the appcheck user:

passwd

This will prompt you to enter the current password, then press enter, then enter a new password and press enter, then enter the new password again, and press enter.

Ascertain the VM’s network adapter name

Note: This is an information gathering step - we are not yet editing anything.

The host OS uses netplan for its network configuration. You will need to edit the file /etc/netplan/01-netcfg.yaml to add/edit an entry that defines the configuration for your network adapter. To do this you will need to know the name of the network adapter, which varies based on your hypervisor/platform. You can see a list of network adapters on the platform by running the following command:

ls /sys/class/net/

Ignore the entries beginning with “br-”, “docker”, “lo” and “veth”. You can see in this example that leaves us with “enp0s17”:

Therefore in this example “enp0s17” is the adapter name we will use.

Determine the Desired Netplan Configuration

Note: This is a planning step - we are not yet editing anything.

An example netplan configuration file might look like this:

# This file describes the network interfaces available on your system
# For more information, see netplan(5).
network:
  version: 2
  renderer: networkd
  ethernets:
    adapter_name_1:
      dhcp4: yes
    adapter_name_2:
      dhcp4: yes
    adapter_name_3:
      dhcp4: yes

Note: White-space indentation is used for denoting structure in the netplan configuration file – you must maintain the indentation of two space characters at each “level” as shown in the examples.

The file may contain multiple adapter names within the “ethernets” section, along with the default configurations for them, but only one will be relevant for your environment. The rest can be ignored (they are there simply for convenience, by providing defaults for common adapter names). If there is a section using your adapter name edit it, if not add one.

Using DHCP

Note: This is a planning step - we are not yet editing anything.

If you wish to use DHCP then there will only be one line in the settings for your adapter, as shown in this example. No entry existed for enp0s17 so a new section has been added:

# This file describes the network interfaces available on your system
# For more information, see netplan(5).
network:
  version: 2
  renderer: networkd
  ethernets:
    adapter_name_1:
      dhcp4: yes
    adapter_name_2:
      dhcp4: yes
    adapter_name_3:
      dhcp4: yes
    enp0s17:
      dhcp4: yes

Assigning a Static IP Address

Note: This is a planning step - we are not yet editing anything.

To assign a static IP address you must specify the desired address, the gateway address and the DNS server addresses (these do not need to be internal – in the example below we use Google’s public DNS servers).

For example, to set our interface (“enp0s17”) to use IP address 192.168.1.222 with gateway 192.168.1.1 and DNS servers 8.8.8.8 and 8.8.4.4, the configuration would be:

# This file describes the network interfaces available on your system
# For more information, see netplan(5).
network:
  version: 2
  renderer: networkd
  ethernets:
    adapter_name_1:
      dhcp4: yes
    adapter_name_2:
      dhcp4: yes
    adapter_name_3:
      dhcp4: yes
    enp0s17:
      dhcp4: no
      addresses: [192.168.1.222/24]
      gateway4: 192.168.1.1
      nameservers:
        addresses: [8.8.8.8, 8.8.4.4]

Editing the Netplan Configuration File

Once you have confirmed what the contents should be you can edit the netplan configuration file using the CLI program “nano” (the CLI program “vim” is also available if you prefer to use that, but that is more complex and not covered in this guide).

The name of the netplan configuration file can vary depending on the version of the image you downloaded.  It will always reside in "/etc/netplan/" and end in ".yaml".  In the example below it is "/etc/netplan/01-netcfg.yaml".

To open the file in “nano” run the following command at the command prompt (type the command exactly as shown and press enter):

sudo nano /etc/netplan/01-netcfg.yaml

You will be asked to enter the password again, do so then press enter and you will see the contents of the file.

To edit the file within nano use the arrow keys to move the cursor (the blinking _ in the text, not your mouse cursor), type text as normal (you can also use delete and backspace as normal). Do not attempt common Windows shortcuts such as ctrl+u or ctrl+p.

To save your changes press ctrl+o (the control key and the o key together). You will be asked to confirm the filename (the prompt is three lines from the bottom of the screen, just above the control hints):

Press enter to keep the existing filename, it will confirm it has written a number of lines:

Then press ctrl+x (the control key and the x key together) to close nano.

Now that the netplan configuration file has been changed run the following command to make the new configuration take effect:

sudo netplan apply

You may or may not be asked to enter the password again when running this command depending how much time has elapsed since last entered it.

To confirm your host now has the correct IP address run the following command:

ip a | grep -A2 '^2:'

The last line of the output should include your IP address, for example:

Now press ctrl+d to log out of the CLI and you will see the login screen again. The URL shown should now include the correct IP address:

In this example the hub’s IP address is 192.168.1.151 and the URL of its local web GUI is https://192.168.1.151:8080.

Open Outbound Firewall Access

You must ensure that your hub has outbound access the necessary destinations, which are mostly AppCheck servers but also include Ubuntu for some asset retrieval and Google’s DNS which is uses to confirm internet connectivity even if you are using alternative DNS servers.

All access granted is outbound from your network to AppCheck, and it is not necessary to open up any inbound connectivity from the public internet.

Required Access

Source	Destination Host	Destination (IP)	Port(s)	Protocol
Purpose:Hub system and OS updates and provisioning
(internal hub)	assets.appcheck-ng.com	167.99.85.223	80 443	TCP
(internal hub)	*.archive.ubuntu.com	-	80 443	TCP
(internal hub)	docker.appcheck-ng.com	68.183.33.54	80 443	TCP
Purpose: Hub command & control communication with AppCheck cloud platform
(internal hub)	wire1.appcheck-ng.com wire2.appcheck-ng.com	178.128.173.89	80 443 5671	TCP
(internal hub)	wire3.appcheck-ng.com	178.128.163.167	80 443 5671	TCP
(internal hub)	lograbbit.appcheck-ng.com	178.62.17.110	80 443	TCP
Purpose: DNS / hostname resolution
(internal hub)	dns.google	8.8.8.8 8.8.4.4	53	TCP, UDP
Purpose: Scan hub software licence activation and renewal
(internal hub)	licensing.appcheck-ng.com	104.248.173.23	80 443	TCP
(internal hub)	licensing-master.appcheck-ng.com	142.93.43.105	80 443 4505 4506	TCP

Bypass HTTP Proxy If Present

The deployed internal hub will, during normal operation, call out to the AppCheck cloud platform on ports 80 and 443 in order to retrieve Command & Control (C&C) tasking, and to report back results. These connections are initiated outbound from your network to the AppCheck cloud.

Because of the use of ports 80 and 443, some customers may find that the traffic is intercepted by operated HTTP proxies. Despite using port 80 and 443 (among others), the traffic is not HTTP traffic (it uses a custom protocol), so it is necessary to bypass the HTTP proxy (if you use one) or add an exception for each of the below endpoints:

Source	Destination Host	Destination (IP)	Protocol
(internal hub)	wire1.appcheck-ng.com wire2.appcheck-ng.com	178.128.173.89	TCP
(internal hub)	wire3.appcheck-ng.com	178.128.163.167	TCP
(internal hub)	licensing.appcheck-ng.com	104.248.173.23	TCP
(internal hub)	licensing-master.appcheck-ng.com	142.93.43.105	TCP
(internal hub)	docker.appcheck-ng.com	68.183.33.54	TCP
(internal hub)	lograbbit.appcheck-ng.com	178.62.17.110	TCP
(internal hub)	assets.appcheck-ng.com	167.99.85.223	TCP

Note that even if your proxy allows the traffic through it mat interfere with it in a manner that would be harmless for HTTP traffic but interferes with AppCheck’s custom protocol, so bypassing the proxies entirely is recommended.

Limit Inbound Firewall Access

For maximum security given the scan hub's likely privileged location on your network we recommend restricting access to the hub in your firewall so non-essential access is blocked.

The vast majority of connections will be established outbound from the hub, so very little inbound access is required.

Required Access

Source	Destination (IP)	Port(s)	Protocol	Purpose
Administrators such as the user setting up the hub and users performing future maintenance	The scan hub's internal IP address	8080	HTTPS	Access to the hub's local web GUI

Complete Setup Wizard in Web Browser

Access the Hub Setup GUI

With the IP address correctly assigned you should now be able to access the hub’s Graphical User Interface (GUI) in your web browser, using the URL listed on the CLI login screen as detailed previously in the guide. For example, when the hub’s IP address is 192.168.1.151 the URL for the GUI is https://192.168.1.151:8080. You will need to enter the URL exactly, including the scheme (HTTPS) and the port number (8080).

If everything is working as expected you should see a login screen as below:

Log in with the following username:

[e-mail]

Contact AppCheck Support if you have not been provided with the password.  Note that both the username and password are case sensitive.

Confirm Outbound Connectivity

The setup wizard will confirm the required outbound connectivity is in place. If the required access is not in place you will need to go back to the step Open Outbound Firewall Access.

Insert License Key

Once connectivity is confirmed, click Next and you will be asked to enter a license key. Contact your account manager if you do not have a license.

Enter your license key and click Next. Note that each license key can only be used once - if you need to rebuild your hub for any reason just contact Technical Support and a replacement key will be created.

Finish Wizard

Click “Finish” on the next screen to complete the registration process.

Wait for the Hub to Provision

Note: Do not restart or power off the hub during this provisioning process.  Doing so could corrupt the hub and necessitate deleting the VM and starting again.

The hub will now perform a full package update and start up various local services.  You will first be presented with the text "Your license has been accepted and your hub is being set up. A list of expected services will appear here when provisioning starts", which after some time (see note below) will be replaced with a list of running services as shown below:

You can refresh the web interface to monitor the progress of provisioning.

Provisioning will be complete once all services* are shown in green and with a status indicating they are "Up", such as “Up 3 hours (healthy)”

* the exception to this is "scanhub_plugins_builder", which will display "Starting up" when operating.

Note: This process typically takes between 1 and 24 hours.  The time can vary significantly depending upon a number of factors (such as the bandwidth available at the client side, the resources assigned to the VM, and the current load on AppCheck's provisioning servers). If the configuration has not finished within 24 hours, please contact the AppCheck Technical Support (if you already have a support ticket open regarding the setup of your internal hub then you should update this ticket. If you do not, you can open a new ticket at https://appcheck-ng.com/get-help/).

Inform AppCheck Support

Once the hub has completed provisioning you will need to inform AppCheck Technical Support so that they can grant your account access to run scans from the new hub. Note that AppCheck will not be able to do this (and will have no visibility of the provisioning hub) until it has completed provisioning, so you must wait until the previous step is complete before informing them.

If you already have a support ticket open regarding the setup of your internal hub then you should update this ticket. If you do not, you can open a new ticket at https://appcheck-ng.com/get-help/.

Support will inform you once they have completed the necessary steps on their side. Once this is done the hub will be selectable when configuring scans, and will be listed at https://scanner.appcheck-ng.com/scan_hubs.

Configure FQDN Resolution

If you wish to specify scan targets by hostname (as opposed to by IP address) and those hostnames are not resolvable via public DNS, then you will need to add hosts-file-style entries at https://scanner.appcheck-ng.com/scan_hubs as shown in the below example. You will only be able to edit this once AppCheck Technical Support have linked to hub to your account (see previous step).

Note: the scanning engine will not make use of your internal DNS server to resolve targets even if you have configured one in the netplan configuration file. Internal DNS servers are only refereed to after scans have completed in order to display host names alongside scanned IP addresses (using reverse lookups).

Perform a Test Scan

Once the above steps have been completed as required, it is a good idea to perform a test scan using your new hub, ideally scanning a single or small number of targets, which you know to be online and responsive.

Internal scans are configured the same way as external ones, through the same user interface at https://scanner.appcheck-ng.com/. You will need to assign your new scan hub to any scans that you wish it perform by setting the scan hub in the “Advanced Config Settings” options at the foot of your scan configuration page:

Note that if you select the hub by name and in future you need to redeploy it for any reason then the hub’s name will change, and you would need to update all your affected scans to select the new name. Therefore it is usually better to select “Any Private Hub”.

For scans that you wish to have run always from public hubs, never from your private hub, select “Any Public Hub” (the default “Auto Select” option could result in the same scan running from public hubs some times and your private hub other times).

Further Help

If you run into any problems or need any further help visit the rest of AppCheck’s support pages at https://appcheck-ng.com/get-help/. There are a number of other in-depth guides like this one, as well as many useful FAQs on both simple and complex questions.

You can also contact AppCheck’s Technical Support team if you need any further assistance.