Introduction

Use this article to set up the Nucleus agent on a local, internal machine that can talk to all the internal tools in use in your organization without externally exposing them to your firewall.  We recommend installing the Nucleus agent on a machine that can talk to all of your scanning consoles to make life easier and to manage fewer instances as you add more tools. The following image illustrates the high level architecture of the Nucleus agent.

If you have questions about the process, please contact Nucleus support and we will be happy to help you out.

System requirements

Centos7 or RHEL7 is the officially supported OSes. We have some deviations for Debian/Ubuntu shown below, but they may not be comprehensive.

Operating System	RedHat/Centos 7+ (officially supported) Debian, Ubuntu (experimental)
CPU	1 Core
Memory	4 GB
Storage	12 GB (minimal install)
Firewall	Open port 2222 outbound from the server you are installing the Nucleus agent on to the Nucleus Manager FQDN that will be provided by the Nucleus support team.
Misc	root access (or full sudo privileges) on the machine you are installing the Nucleus agent on.  This procedure assumes you are logged in as the root user.

 

Before Proceeding

Please submit a support request with the subject "Nucleus Agent Setup" here: https://support.nucleussec.com/hc/en-us/requests/new

You will be provided with the following information with 24 hours:

1. The FQDN of the Nucleus Manager for your instance (referred to as <nucleus manager fqdn> in this procedure)
   • Note: Your firewall must be configured to allow outbound access from the server you are installing the Nucleus agent on to this FQDN. 
2. A username (referred to as <username> in this procedure)
   • Note: The Nucleus agent uses key based authentication.  We will never ask for an account password or the private key.
3. A list of 5 ports assigned to your organization.   Each internal tool that Nucleus will be connecting to will use one of these assigned ports. (referred to as <assigned port> in this procedure)
   • Note:   If you are connecting to more than 5 internal tools, contact Nucleus support for additional ports.

Once you have the above information, proceed to the next section. 

  

Install Dependencies

# For CentOS/RHEL 7+
yum install -y epel-release
yum install -y supervisor autossh
systemctl enable supervisord
systemctl start supervisord

# For Debian/Ubuntu
apt-get install supervisor autossh
systemctl enable supervisor
systemctl start supervisor
 

 

Create service account 

# Create service account, replacing <username> with the username provided to you by Nucleus support
Note: Use a strong password. We will never ask you for this password
sudo adduser <username>
sudo passwd <username>

# Setup SSH keys for authentication
mkdir /home/<username>/.ssh
ssh-keygen -t rsa -b 4096 -C "<username>"
   Enter the file in which to save the key: /home/<username>/.ssh/id_rsa 
   Enter the passphrase: <Leave Blank>
   Enter the same passphrase again: <Leave Blank>

 

Set up permissions

# Set permissions, replacing <username> with the username provided to you by Nucleus support
chmod 700 /home/<username>/.ssh
chown -R <username>:<username> /home/<username>/.ssh
cat /home/<username>/.ssh/id_rsa.pub
   Note: Copy this output and send to your Nucleus support rep or to [email protected]

 

STOP HERE: Send your public key file to your Nucleus support representative before continuing 

 

 

Install & Configure the Nucleus Agent

  1. Create Supervisord File 

You will need to complete this step to create a supervisord configuration file for each internal tool you wish to make accessible to Nucleus.   Replace <internal tool name> with the name of the internal tool you are connecting to (e.g. Nessus, Jira, etc.).

• For RHEL/CentOS systems, create a new file /etc/supervisord.d/<internal tool name>.ini
• For Debian/Ubuntu systems, create a new file /etc/supervisor/conf.d/<internal tool name>.conf

Note: The new file should contain the following contents, with all fields inside of "< >" being replaced with custom values for your configuration.

[program:<internal tool name>]
command=/usr/bin/autossh -M 0 -N -R *:<assigned port>:<IP of internal tool>:<port of internal tool> <username>@<nucleus manager fqdn> -p 2222 -i /home/<username>/.ssh/id_rsa -o "ServerAliveInterval 30" -o "ServerAliveCountMax 3" -o "StrictHostKeyChecking=no"
user=<username>

Description of fields

• <internal tool name>:  The name of the internal tool you are connecting to (e.g. Nessus, Jira, etc.)
• <assigned port>:  One unused port from the range of ports that Nucleus assigned to your organization.  If you need more ports, reach out to your Nucleus support representative.
• <IP of internal tool>: The internal IP of the internal tool/application that you would like to expose to Nucleus.  If you are installing the Nucleus agent on the server that runs the internal tool, use 127.0.0.1
• <port of internal tool>: This is the port that the internal tool/application listens on. For example, Nessus Professional listens on port 8834 by default.
• <nucleus manager fqdn> - this is the FQDN of the Nucleus Manager given to you by Nucleus support.

Example file

We are connecting an internal Rapid7 InsightVM console

• The name of the internal tool we are connecting to is: insightvm
• The assigned Nucleus port is: 2000
• The internal IP of the Rapid7 InsightVM console is: 192.168.1.140
• The InsightVM console is listening on port: 3780
• The username provided by support was acme-nucleusagent
• The Nucleus Manager FQDN provided by support was: nucleus-manager.nucleussec.com
• The example file would be as listed

[program:insightvm]
command=/usr/bin/autossh -M 0 -N -R *:2000:192.168.1.140:3780 [email protected] -p 2222 -i /home/acme-nucleusagent/.ssh/id_rsa -o "ServerAliveInterval 30" -o "ServerAliveCountMax 3" -o "StrictHostKeyChecking=no"
user=acme-nucleusagent

 

  2. Start the service

# For CentOS/RHEL 7+
systemctl stop supervisord
systemctl start supervisord

# For Debian/Ubuntu
systemctl stop supervisor
systemctl start supervisor

If you get errors during this part, please check your config file against the config file above: Example File and refer to the troubleshooting steps at the bottom of this article: Troubleshooting Checklist

 

3. Verify that the agent is running successfully

# supervisorctl status <internal tool name>
<internal tool name> RUNNING pid 23198, uptime 0:12:48

If the service is not starting correctly, please refer to the Troubleshooting Checklist below or contact Nucleus support.  If you need any assistance, we're always close at [email protected]

 

Next Steps

Now that you've set up Nucleus Agent, it's time to set up a Connector through the agent. Here's how.

 

Troubleshooting Checklist

If you are having issues with the connection, here's a checklist to attempt:

Check	Result	Solution
From the machine where you installed the Nucleus agent, ensure you can reach the destination: Use something like curl, telnet or wget to ensure you can reach the destination server on that port	You should see something back from the web server	If there is connection denied or any other message that is not a web response, check your internal firewall and routing to open the connection
From the machine where you installed the Nucleus agent, ensure you can reach the Nucleus manager in your region: Use "ssh -v <username>@<nucleus manager fqdn> -p 2222"	The connection should show an SSH error like "permission denied (publickey)"	If you are not getting an SSH error, there is most likely something blocking your outbound connections to the Nucleus manager. Please open the OUTGOING port 2222 from the machine where the Nucleus agent is installed to the Nucleus manager.
From the machine where you installed the Nucleus agent, ensure you can log in to the Nucleus manager in your region: Use "ssh <username>@<nucleus manager fqdn> -p 2222 -i <path to identify file>"	You should get an error like: "PTY allocation request failed on channel 0 This account can only be used for tunnels" That is correct, that means you can log in	If you are unable to login, please verify the firewall settings in the previous step, then contact support for verification of your credentials
If the above steps pass, check your connection from Nucleus to the Nucleus manager: From within Nucleus set up a connector using the Nucleus manager's URL as the URL with the port you have mapped. E.g. within Nucleus you would use: "https://nucleus-manager.nucleussec.com:1995" if the port assigned to you is 1995.	Verify connection should not time out	If you are getting a credential error: the tunnel is set up and credential verification is required. If the connection is timing out, please check the above steps then contact support for assistance.