Setting Up the Agent

August 26, 2024 14:46

The Agent is an image that you install on your own Virtual Machine, therefore it differs from the Virtual Tunnel in that it allows access to patch and maintain the image. A common use case for the Agent is that it can be used at multiple physical locations unlike the Virtual Tunnel . The limitation with the Agent is that it currently only supports Nexpose, newer versions of Nessus (7 & up), and Sonatype. If you use connectors that are not currently supported by the Agent, including ticketing connectors, Cisco recommends using the Virtual Tunnel .
If you have on-premises scanners that are protected by a firewall, you can use the Agent to allow connectivity between Cisco Vulnerability Management and your scanners.

Prerequisites

Cisco recommends that you use a dedicated server or Virtual Machine to run the Agent. Ensure that your firewall rules allow the Agent to communicate with your internal connectors as well as reach out to Cisco Vulnerability Management.

These scanners are currently supported:

Nexpose [only username & password is supported]
Nessus
Sonatype
BlackDuck

Important: The machine must have network access to your scanner and the API.

Recommended specifications

Operating System	RHEL or derivative (RHEL 7+, CentOS 7+, Fedora 28+)
RAM	1-2 GB
Number of CPUs	1-2
Disk Size	20 GB, encrypted

Note: HTTP/S proxying is supported. Refer to the Proxy for Agent section.

Windows server-based installations are not supported at this time. If you are interested, contact Cisco Support.

Important: Open a support ticket to ask that the Agent UI feature flag be turned on. This will enable the checkbox for the Agent to be shown on the connector setup page. In the same ticket, if you are using a proxy or firewall, request a list of URLs that need to be whitelisted.

Download the Agent

To download the Agent, click here.

Install the Agent

Tip: You can execute the commands as Root if you don't want to use sudo.

In the Command Prompt, create a new "kenna.repo" file using

$ sudo yum install kenna-agent-1.2.1798-1.x86.64.rpm

Fedora 28+

$ sudo dnf install kenna-agent-1.2.1798-1.x86.64.rpm

Installation destination folder: /etc/kenna-agent

Connector Setup

You must first select a connector if you have no existing connector before proceeding with the connector setup.
1. Log in to the UI, and click Connectors.

2. Click Add Connector.
3. Select a connector. The connector-specific setup page opens.

4. Click the Use Agent checkbox. If there is no checkbox visible, open a ticket with Cisco Support and request that the feature flag for the UI be enabled.
5 . Fill in the Username, Password, and Host information, and select a Schedule.
Note: You can make changes to your cron as required. Changes to the Schedule change the config snippet.
Important: The connector ID is blank initially and only populates after the connector is saved.

Note: All times are in UTC.

6. Click Save.

Important: By clicking Save, the Run and Upload & Run buttons are clickable but their functionality will be disabled.

Any previously set schedule will not work and all new connector runs will be completed using the Agent.

Configure the Agent

Note: A connector must be added, as shown in the previous section, before you configure the Agent.

Important: You require your API token to configure and use the Agent.

1. Select the Settings () icon and click API keys.

2. Locate your API key and click the Copy button to copy the API token.

3. Edit the "/etc/kenna-agent/kenna-agent.toml" file.

Item	What to Enter
token	Paste in the API token.
id	Enter the connector ID. Tip: To locate your connector ID, select the connector in the Connectors tab. In the Details page that displays, highlight and copy the Connector ID.
type	Enter the connector type such as “nexpose”, “nessus”.
url	Enter the scanner URL (protocol + host + port).
username	Enter the scanner credentials.
password	Enter the scanner credentials.
schedule	Enter a cron job schedule using the “min hr dom mon dow” format. Important: Time is interpreted in UTC.
scan_list	Contains scan IDs for the Nessus connector. For a single list, enter scan_list = [#]. For example, scan_list = [5]. For multiple lists, enter numbers separated by commas. For example, scan_list = [5, 246, 248].

To manually start the connector outside of the scheduled window, you must log into the Agent console and run the following command:

kenna-agent oneshot

Multiple Connectors Setup

The Agent allows for multiple connectors to be set up simultaneously by simply editing the kenna-agent.toml file as shown here:


url = "https://api.kennasecurity.com"
token = "your token"

[connector.nexpose]
id = 12345
type = "nexpose"
url = "https://nexpose.example.com"
username = "user"
password = "pass"
schedule = "*45 23 * * *"

[connector.blackduck]
id = 12346
type = "blackduck"
url = "https://blackduck.example.com"
username = "user"
password = "pass"
schedule = "55 23 * * *"

The Agent runs each connector when the schedule is set.
Important: Ensure that schedules are spread out to avoid encountering memory errors.

Directory Connector

A directory connector gathers all files inside a specified directory, uploads them to conduit, and starts a connector run. To set up a directory connector, you need to create a connector to which you upload files.
Important: The Agent will pick up all files in the given directory for each run.

url = "https://api.kennasecurity.com"
token = "your token"

[connector.directory_nexpose]
id = 
type = "directory"
url = "file:/home/kenna/Downloads/nexpose"
username = ""
password = ""
schedule = "*45 23 * * *"

Item	What to Enter
token	Paste in the API token.
id	Enter the connector ID. The connector should be a supported XML connector only.
type	Enter the connector type as “directory”.
url	Enter the path where the directory is located. For example, if the directory is in home/[User]/Downloads/nexpose, then the url would be as follows: “file:/home/kenna/Downloads/nexpose” Important: Ensure the specified directory has read permissions.
username	Leave blank.
password	Leave blank.
schedule	Enter a cron job schedule using the “min hr dom mon dow” format. Important: Time is interpreted in UTC.

Start and Enable the Agent

Once installation is complete, you are ready to run the Agent.

$ sudo systemctl enable kenna-agent

In the Command Prompt, enter "kenna-agent check" to check the configuration details of the Agent. Use this command to troubleshoot issues by reviewing the Check Summary.

Run Agent Check from the terminal

In the Command Prompt, enter "kenna-agent check" to check the configuration details of the Agent. Use this command to troubleshoot issues by reviewing the Check Summary.

$ kenna-agent check

Run the connector from the terminal

To manually start the connector outside of the scheduled window, you must log into the Agent console and run the following command:

$ kenna-agent oneshot

Proxy for Agent

When a proxy is used, the Agent is capable of working with HTTP and HTTPS settings.
In the command prompt, enter the following command:

sudo systemctl edit kenna-agent.service

In the editor, create/add an environment variable override.
Note: For different proxy settings, multiple environment variables can be added.

[Service]
Environment=HTTPS_PROXY=https://myproxy:4566(replace the URL with your proxy)
Environment=HTTP_PROXY=https://myproxy:4566

Enter the following command to restart the Agent. After adding or creating the variables, save the changes and exit the editor.

sudo systemctl restart kenna-agent.service

Helpful commands

Start agent:

$ sudo systemctl start kenna-agent

Enable agent:

$ sudo systemctl enable kenna-agent

Stop agent:

$ sudo systemctl stop kenna-agent

Agent process status:

$ sudo systemctl status kenna-agent

Check config details:

$ kenna-agent check

Run connector from the terminal:

To manually kick-off the connector outside of the scheduled window, you must log into the agent console and run the following command:

$ kenna-agent oneshot