Getting Started

This guide walks you through setting up the Tenable Nessus Integration for NetBox.

• Prerequisites
• Host Requirements
  • System
  • Network
• Tenable Setup
  • Generate Nessus API keys
• NetBox Setup
  • Generate Diode Client Credentials
• Agent Setup and Configuration
  • Step 1: Authenticate to the NetBox Labs Image Registry
  • Step 2: Configure the Agent
  • Bootstrap Mode (First-Time Setup)
  • Optional - Dry Run Mode
  • Step 3: Run the Agent
    • Method 1: Set Environment Variables Manually
    • Method 2: Use a .env File (Recommended)
• Expected Output
• View and Apply Discovered Data in NetBox Assurance
  • Accessing NetBox Assurance
  • Explore Deviation Types
  • View Active Deviations
  • Apply Deviations
• View the Tenable Data in NetBox
• Additional Resources
  • Related Documentation
  • Support

Prerequisites

Before you begin, ensure you have the following:

• NetBox Cloud or NetBox Enterprise with NetBox Assurance
• Orb Agent Pro credentials (required to download the integration agent image)
• A Tenable Nessus scanner. Other Tenable products, such as Tenable Vulnerability Management and Tenable Security Center, are not supported in this release
• A Nessus user account that can access the scans you want to sync
• Host system with Docker support
• Network connectivity between your host and both your NetBox instance and the Nessus scanner

Host Requirements

System

• Operating System: Linux, macOS, or Windows with Docker support
• Memory: Minimum 2 GB RAM (4 GB recommended)
• Storage: 1 GB free disk space
• Docker: Version 20.10 or later

Network

• Outbound gRPC/gRPCS access to Diode on your NetBox instance (typically port 443 for gRPCS)
• Outbound HTTPS access to the Nessus scanner, on the port in its URL (Nessus uses 8834 by default)
• DNS resolution for both NetBox and the Nessus hostname, if you use one
• Firewall rules configured to allow the above connections from your agent host

The integration does not verify the Nessus scanner's TLS certificate, so a scanner using its default self-signed certificate works without extra configuration.

Tenable Setup

Generate Nessus API keys

The integration authenticates to Nessus with an access key and a secret key belonging to a Nessus user.

1. Log in to the Nessus web interface as the user whose scans you want to sync.
2. Open My Account and select API Keys.
3. Click Generate.
4. Copy the Access Key and the Secret Key. You will use them as TENABLE_ACCESS_KEY and TENABLE_SECRET_KEY.

Store the keys securely. The integration reads every scan this user can access.

NetBox Setup

Generate Diode Client Credentials

1. Log in to your NetBox instance.
2. Navigate to Diode → Client Credentials.
3. Click + Add a Credential.
4. Enter a descriptive name (for example, "Tenable Integration").
5. Click Create.

6. Important: Copy and securely store the Client ID and Client Secret - you will need them in the agent configuration.

7. Navigate to Diode → Settings.
8. Copy the Diode target value - you will use this in the agent configuration file.

Agent Setup and Configuration

Step 1: Authenticate to the NetBox Labs Image Registry

From your host machine, authenticate to the NetBox Labs registry using the CUSTOMER-IDENTIFIER and token provided by the NetBox Labs team:

docker login quay.io -u netboxlabs+<CUSTOMER-ID> -p <TOKEN>

Example session:

% docker login quay.io -u netboxlabs+org-abc123def456 -p <token>
Login Succeeded

Then pull the agent image:

docker pull quay.io/netboxlabs/orb-agent-pro:develop

Step 2: Configure the Agent

1. Create the configuration file (you can name the file anything you like):

touch agent.yaml

2. Edit the configuration file and add the following. Replace grpcs://your-instance.netboxcloud.com/diode with the value from Diode → Settings → Diode target in the NetBox UI:

orb:
  config_manager:
    active: local
  backends:
    worker:
    common:
      diode:
        target: grpcs://your-instance.netboxcloud.com/diode # Get this value from Diode > Settings > Diode target
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: tenable_01  # Use a meaningful name to identify this agent
  policies:
    worker:
      tenable_worker:
        config:
          package: nbl_tenable_tenable
          schedule: "0 2 * * *" # Daily at 2:00 AM. Set your desired schedule (see examples below)
          TENABLE_URL: ${TENABLE_URL}
          TENABLE_ACCESS_KEY: ${TENABLE_ACCESS_KEY}
          TENABLE_SECRET_KEY: ${TENABLE_SECRET_KEY}
          BOOTSTRAP: True  # Set to True for initial setup, False for regular operation
          # USE_DNS_FALLBACK: false  # Optional: look up a DNS name for hosts that Nessus has none for (default: false)

The integration has no scope settings. It always reads every scan the API keys can access.

Bootstrap Mode (First-Time Setup)

Bootstrap mode creates the static content in NetBox that the integration requires before the first full sync. Run it once on initial setup, then disable it for all subsequent runs. In bootstrap mode the integration makes no Nessus API calls, so the URL and API keys are not required.

What bootstrap mode creates:

• Custom fields on IP addresses: tenable_max_severity, tenable_critical_count, tenable_high_count, tenable_medium_count, tenable_low_count

Configuration:

config:
  BOOTSTRAP: true  # Set to true for initial setup, false for regular operation

First-time run process:

1. Set BOOTSTRAP: true in your configuration.
2. Run the agent and monitor the output for executed successfully.
3. Stop the agent by pressing Ctrl+C once you see executed successfully.
4. Apply the deviations in NetBox Assurance (see Apply Deviations below).
5. Set BOOTSTRAP: false for all future runs.

Optional - Dry Run Mode

The agent can run in dry run mode, which writes discovered data to a JSON file instead of sending it to NetBox. This is useful for checking what the integration will create before the first real sync, or for sharing data with the NetBox Labs support team.

Add the following to the diode section of your configuration:

      diode:
        dry_run: true
        dry_run_output_dir: /opt/orb/  # Output file is written to this directory

Step 3: Run the Agent

Run the agent to synchronize Nessus scan results into NetBox. The current directory, containing agent.yaml, is mounted into the container at /opt/orb/.

Method 1: Set Environment Variables Manually

1. Export Diode credentials:

export DIODE_CLIENT_ID="your-client-id"
export DIODE_CLIENT_SECRET="your-client-secret"

2. Export Nessus connection details:

export TENABLE_URL="https://nessus.example.com:8834"
export TENABLE_ACCESS_KEY="your-access-key"
export TENABLE_SECRET_KEY="your-secret-key"

3. Run the agent:

docker run \
  -v $PWD:/opt/orb/ \
  -e DIODE_CLIENT_SECRET \
  -e DIODE_CLIENT_ID \
  -e TENABLE_URL \
  -e TENABLE_ACCESS_KEY \
  -e TENABLE_SECRET_KEY \
  quay.io/netboxlabs/orb-agent-pro:develop \
  run -c /opt/orb/agent.yaml

Method 2: Use a .env File (Recommended)

1. Create a .env file:

touch .env

2. Edit the .env file and add the following:

## NetBox Diode credentials (from NetBox Setup)
DIODE_CLIENT_ID=your-client-id
DIODE_CLIENT_SECRET=your-client-secret

## Nessus connection
TENABLE_URL=https://nessus.example.com:8834
TENABLE_ACCESS_KEY=your-access-key
TENABLE_SECRET_KEY=your-secret-key

3. Run the agent:

docker run \
  -v $PWD:/opt/orb/ \
  --env-file .env \
  quay.io/netboxlabs/orb-agent-pro:develop \
  run -c /opt/orb/agent.yaml

echo ".env" >> .gitignore

Expected Output

After starting the agent, you will see log output as the integration reads the scans and sends data to NetBox:

{"time":"2026-10-08T15:15:01.123456789Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_tenable_tenable.tenable_diode:Connecting to Tenable Nessus at https://nessus.example.com:8834"}
{"time":"2026-10-08T15:15:01.234567890Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_tenable_tenable.tenable_diode:Connected to Tenable Nessus version unknown"}
{"time":"2026-10-08T15:15:01.345678901Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_tenable_tenable.builders.ip_addresses:Processing 2 scan(s) from Tenable"}
{"time":"2026-10-08T15:15:04.456789012Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_tenable_tenable.builders.ip_addresses:Built 3 IP address entity/entities"}
{"time":"2026-10-08T15:15:05.567890123Z","level":"INFO","msg":"worker stderr","log":"INFO:worker.policy.runner:Policy tenable_worker: Successful ingestion"}
{"time":"2026-10-08T15:15:05.678901234Z","level":"INFO","msg":"worker stderr","log":"INFO:apscheduler.executors.default:Job \"PolicyRunner.run\" executed successfully"}

View and Apply Discovered Data in NetBox Assurance

After the agent runs, work with the discovered Tenable data in NetBox Assurance.

NetBox Assurance identifies deviations between data already in NetBox and the actual operational state discovered by the integration.

Accessing NetBox Assurance

1. Navigate to your NetBox instance UI.
2. Click on Assurance in the main navigation menu.

Explore Deviation Types

1. Click on Deviation Types to view the categories of deviations discovered.

2. Click the Name of a deviation type to view deviations of that type.

3. Click the Name of an individual deviation to view its details.

View Active Deviations

1. Click on Active Deviations to view all deviations that have not yet been applied or ignored.

2. Click the Name of a deviation to view its details.

Apply Deviations

1. Select the deviations you want to apply. For large result sets, set Per Page to 500 first.

2. Select the first deviation, hold SHIFT, select the last one, then click Apply Selected.

3. Click Apply X Deviations to write the data to NetBox.

View the Tenable Data in NetBox

After running the integration and applying discovered data, you can view the scan results in NetBox:

1. Navigate to IPAM → IP Addresses and filter by the tenable tag to see every address the integration recorded.
2. Filter by the Tenable Max Severity custom field, for example critical, to see the addresses whose most severe finding is at that level.
3. Open an IP address to see its severity and counts in the Tenable custom fields group, and the scans that found it in the description.

Additional Resources

Related Documentation

• NetBox Assurance Documentation
• Orb Agent Documentation
• Tenable Nessus Integration - Technical Information

Support

Email support@netboxlabs.com for support.