Category: Tenable.io

Tenable.io API

Authorizing You App to Use the Tenable.io API

Requests that require authentication need an API key to be sent with their headers.

API Keys

These keys are generated per account through session:keys or users:keys and can be used to authenticate without creating a session.

Add them to your request using the following HTTP header:

X-ApiKeys: accessKey={accessKey}; secretKey={secretKey};

Example:

curl -H "X-ApiKeys: accessKey={accessKey}; secretKey={secretKey}" https://cloud.tenable.com/scans

In addition, it is possible to perform actions as if authenticated as a different user by adding an additional HTTP header.

X-Impersonate: username={username}

Example:

curl -H "X-Impersonate: username={username}" -H "X-ApiKeys: accessKey={accessKey}; secretKey={secretKey}" https://cloud.tenable.com/scans

Generating API Keys

NOTICE: API Keys are only presented upon initial generation. Please store them in a safe location as they can not be retrieved later and will need to be regenerated if lost.

The Tenable.io API UI can help you build a sufficient foundation so that you can then perform more complex requests via other API utilities such as cURL or Postman. As usual, authentication is necessary with these utilities before the requests for data will work. A POST to <https://cloud.tenable.com/session> with your credentials in the body will give you the session token you need to perform data queries. The cURL request for getting your authenticated session token would look similar to this, but with your own credentials (note that because this is a POST request to an https URL, your credentials are not being transmitted in the clear!):

curl -X POST -H "Content-Type: application/json" -H "Cache-Control: no-cache" -d '{"username":"sample@tenableio.user", "password":"YourPasswordHere"}' "https://cloud.tenable.com/session"

Once you have the session token, you can perform queries to accomplish any of the tasks available via the API UI. In the API UI, look at the HTTP Request information to get the proper method and URL syntax to run a query. For example, this query would provide you with your list of scans and details about them:

curl -X GET -H "X-Cookie: token=YourSessionTokenHere" -H "Cache-Control: no-cache" "https://cloud.tenable.com/scans"

A request like this one would return your list of target groups:

curl -X GET -H "X-Cookie: token=YourSessionTokenHere" -H "Cache-Control: no-cache" "https://cloud.tenable.com/target-groups"

And this request closes down your session:

curl -X DELETE -H "X-Cookie: token=YourSessionTokenHere" -H "Cache-Control: no-cache" "https://cloud.tenable.com/session"

Any of these cURL requests can be easily modified for use in Postman or scripting in various languages.

Tenable

Tenable.io enables you to analyze data from multiple sensors — Nessus scanners and agents, as well as passive listening.

With a “software as a service” approach, Tenable handles the administration of the Tenable.io platform, so your focus remains on reducing risk in your organization. Your security and audit teams can share sensors within Tenable.io. You can also share scan schedule, scan policies and scan results among an unlimited set of users or groups.

You will no longer have to relay purely on IP addresses that don’t accurately reflect dynamic assets like virtual machines, cloud instances, and multi-homed hosts.

The combination of asset and vulnerability tracking in Tenable.io means that vulnerabilities can be tracked from the time they are recognized through remediation.

A successful vulnerability management program accomplishes four goals: discovery, assessment, remediation, and validation. Gathering timely and accurate data is essential. You accomplish this through regularly scheduled credentialed scans, agent scans, and network traffic analysis.

Scanners and agents collect data to be reported by Tenable.io.

Scanners

By default, Tenable.io is configured with a regional, specific cloud scanner. In addition to using the default cloud scanner, users can also link Nessus scanners, NNM scanners, and Nessus Agents to Tenable.io.

Once linked to Tenable.io, use the Tenable.io key to add remote scanners to Scanner Groups. You can also manage and select remote scanners when configuring scans.

You must install a Nessus scanner or NNM instance on a host before you can link the scanner to Tenable.io.

The Linked Scanners page displays scanner names, types, and permissions.

Agents

Agents increase scan flexibility by making it easy to scan assets without needing ongoing host credentials or assets that are offline. Additionally, agents enable large-scale concurrent scanning with little network impact.

You must install a Nessus Agent on a host before you can link the agent to Tenable.io.

Deploy and Link Nessus Scanners

  • Log in as an administrator and navigate to the “Scanners” Page by clicking on “Scans” and then “Scanners”.
  • To define permissions for Tenable.io, first choose a scanner. Then, click on “Permissions”.
    • If the default permissions are set to “No access”, no users can launch scans using this scanner.
    • If set to “Can use”, every user with scanning permissions can launch scans with this scanner.
    • If set to “Can manage”, standard users and administrators can also share the scanner.
    • You may define permissions for specific users or groups by adding them manually, which is helpful if you need to restrict local scanner access to certain users only.
    • It is common to user manually defined permissions in conjunction with the default permission “No access”.
  • To begin adding scanners, navigate to the “Scanners” section. Here, you see a key that you can use to link additional Nessus scanners and Passive Vulnerability Scanners, plus an option to regenerate the key. Copy this key. You will need it during registration. Now, let’s configure an additional Nessus scanner.
    • Once you have downloaded and installed Nessus, load the initial configuration page in a web browser. To access the configuration page, please visit: https://<hostname > : 8834
    • Create an administrative username and password.
    • Choose the registration option “link to Tenable.io” and paste in the key you obtained earlier.
    • If a proxy is required, check “User Proxy” and enter the settings. When finished, click “Continue”.
    • The scanner initializes and begins downloading plugins and any required software updates from Tenable.io. Once this is complete, you may log in with the username and password you created. You may manage user accounts, configure a proxy server, and access advanced settings.
  • To begin using the new scanner, log into the Tenable.io interface. Go to the “Scanners” page. Here, you see the new scanner’s operational status and current scan count, along with options to disable or delete the scanner entirely.
    • You cannot choose a disabled scanner when creating an launching a new scan. Disabling is useful during scanner system maintenance, as you do not need to reconfigure the scanner.
    • Deleting the scanner removes it completely. You must reconfigure the scanner to reconnect it to Tenable.io.
    • Click on the scanner to reveal details and information about the scanner.
  • To update the scanner’s plugins, click the “Update Plugins” icon.
    • When the scanner is actively scanning, this page also shows the currently running scan, when it last updated, the scan owner, and status. You can also pause or stop the scan.
    • You can define permission for the scanner as you did for the built-in Tenable.io scanners, using the options “no access”, “can use”, and “can manage”.
  • To configure scanner groups, navigate to the “Scanner Groups” section.
    • Click the “New Group” button.
    • Provide a descriptive name.
    • After creating the group, add your desired scanners.
    • In the “Manage Scans” section, you can see currently running scans and their owners, and pause or stop the scans.
    • The “Settings” page is where you can rename the scanner group.
    • In the “Permissions” section, you can define access to the scanner group, like for other Tenable.io components.

Deploy and Link Nessus Agents

Setting up Nessus Agents is a two-part process. You must first define the agent groups and permission in Tenable.io, and then configure the remote agents to connect to Tenable.io.

  • To start configuring Nessus Agent integration
    • log into Tenable.io as an administrative user.
    • Navigate to your agents (Scans -> Agents)
    • Make note of the key, as you will need it later when configuring the installed agents.
    • To view instructions for configuring installed agents, click the link in the description.
    • Next, create an agent group. Creating groups can help you organize agents for scanning purposes. Navigate to the “Agent Groups” section.
    • Create a New Group. Provide a descriptive name that will be useful when creating scans.
    • Next, define the permissions for the group.
      • If default permissions are set to “No access”, no users will be allowed to launch agent-based scans against systems in this group.
      • If set to “Can use”, users will be allowed to launch agent-based scans against this group, but will not be allowed to edit the group or any of its agents.
      • You may also define permissions for individual users and groups. When finished, click the “Save” button.
  • Now, you may begin deploying your remote Nessus Agents to connect to Tenable.io.
    • To obtain the installation packages, log into the Tenable Support Portal: https://support.tenable.com
    • Navigate to the “Downloads” area and click on “Nessus”. Choose the Nessus Agent that matches your operating system and architecture.
    • Once downloaded, you can deploy the installer package using your software deployment platform, or copy it manually to the desired system.
    • During a manual Windows installation, enter the key, IP address (cloud.tenable.com:443) and port, and the group in which to place the system. When complete, the Nessus Agent service starts and connects to Tenable.io. The service is configured to start automatically at system startup.
    • If you are deploying the Nessus Agent to many machines at once, you can automate the process by passing configuration settings automatically during the install. For example, you could create a group policy object that automatically pushes out and installs a Nessus Agent using Microsoft’s MSI installer. The parameters to use for this process are as follows.
      • msiexec.ext/q /l* agent_log.text /i NessusAgent64-6.10.0.msi NESSUS_SERVER=<IP or HOST>:8834 NESSUS_KEY=<key> NESSUS_GROUPS=<group1,group2>
      • The “q” switch quiets the installation so the end-user does not see any dialogs. The “L” switch creates a log file during installation. The “I” switch installs the desired package.
      • Next, you can specify the server and port, the key and the group in whch to place the system.
      • This process can help you in quickly deploying agents to a large number of systems.
    • The installed agent also has a command line tool you can use to configure the settings to the Agent, verify connectivity, and more.
      • Open a command prompt and navigate to the directory where the agent is installed (c:\>cd “c:\Program Files\Tenable\Nessus Agent”).
      • Run the ‘nessuscli.exe’ command to show all available options.
      • The local agent commands allow you to configure the link settings, unlink the agent, and obtain the agent’s current status.
      • Once the agent is installed, you can use the Tenable.io interface to configure additional agent related settings.
  • For Unix-based systems, you can obtain the installation packages by logging into the Tenable Support Portal (https://support.tenable.com).
    • Nagivate to the “Downloads” area and click on “Nessus”. Choose the Nessus Agent that matches your operating system and architecture.
    • Once downloaded, you can deploy the installer package using your software deployment platform, or copy it manually to the desired system.
    • rmp -ivh NessusAgent-6.4.0-es6.x86_64.rpm
    • After installation, you can link this agent to Tenable.io by using the following command (/opt/nessus_agent/sbin/nessuscli agent) and specifying the IP, port, and key.
    • /opt/nessus_agent/sbin/nessuscli agent link –host=cloud.tenable.com –port=443 –key=xxx
    • When finished, start the Nessus Agent service for use (service nessusagent start). The service is configured to start automatically at system startup.
    • The installed agent also provides a command line tool you can use to configure the agent’s settings, verify connectivity, and more. Open a command prompt and navigate the directory where the agent is installed.
    • Run the ‘nessuscli’ command to show all available options (/opt/nessus_agent/sbin/nessuscli). The local agent commands allow you to configure the link settings, unlink the agent, and obtain the agent’s current status (/opt/nessus_agent/sbin/nessuscli agent status).
    • Once you have installed and linked your agents to Tenable.io, they will begin communicating with Tenable.io.
    • Navigate to your agent groups.
      • Observe the number of agents in your group.
      • You also have an option to delete the group.
        • Click on the group and navigate to the “Manage Agents” section.
        • Here, you can add or remove agents from the group. It is possible for an agent to be a member of multiple agent groups. For example, if you have a Windows web server, you may wish to place it in a general “Windows” group, as well as a group for “Servers”.

Deploy and Link PVS

Let’s demonstrate adding a PVS sensor to Tenable.io. Tenable.io can retrieve data gathered by the Passive Vulnerability Scanner. You can analyze this data similarly to data gathered from other sensors.

To get started, navigate to the “Scanners” Page.

  • The Linking Key is the key that can link PVS sensors to Tenable.io. Copy it for later use when configuring PVS.
  • After installing PVS on your desired platform, navigate to the PVS user interface.
  • During the initial setup, provide the activation code “Cloud”. Cloud Host: cloud.tenable.com and Cloud Port: 443. In the “Cloud Key” field, paste the key that was copied earlier from Tenable.io.
  • Provide a descriptive name. PVS now connects to Tenable.io and begins reporting results.
  • If PVS is already installed and configured, you can change the settings by navigating to the “Configuration” page.
  • Once the PVS connects to Tenable.io, you can verify connectivity by navigating to the “Scanners” page.

Create and Lunch Scans

Tenable.io makes it easy to gather data from your public-facing assets. Start by logging into your Tenable.io account and creating a new scan (Scans -> New Scan).

The best scan template for this type of scan is the “Basic Network Scan”. This template uses cloud-based scanners to identify known vulnerabilities over a common set of ports. It also identifies running services and extracts other information, all without using credentials.

  • Enter a meaningful name, description, and destination folder.
  • Next, choose the appropriate scanner.
  • Choose target group that have already been defined and included a list of systems
  • You can also enter IP addresses and hostnames, or upload a list.
  • Next, set the scan to run once a day (Settings ->Basic -> Schedule -> Enabled -> Frequency).
  • Because this scan identifies vulnerabilities on public-facing, easy to access targets, you may want to be notified of certain vulnerabilities. To do this, create a new email notification (Settings -> Basic -> Notifications -> Email Recipient(s) ).
    • First, add the recipients.
    • Then, create filters for “High” and “Critical” vulnerabilities.
      • Result Filter: Match Any of the following:
      • Severity is equal to High
      • Severity is equal to Critical
  • Next, give the other security analysts on your team “view-only” access to these scan results (Settings -> Basic -> Permissions). Although you can customize a variety of additional settings for this scan, the defaults are sufficient for most reliable networks.
  • Save and lunch your scan.