Technical Information

Tenable to NetBox Object Mapping

This page describes how Nessus scan results are mapped to NetBox objects by the integration.

Data flows in one direction only, from Nessus to NetBox. The integration never writes to Nessus.

On each run, the integration makes these read-only calls to the Nessus API:

The host details call is made once for every host in every scan, so a run makes at least one request per host.

Object Type Mapping Table

The integration creates no devices, virtual machines, interfaces, or prefixes. IP addresses are created in the global table (no VRF) and are not assigned to an interface.

IP Address Mapping

Each host in a scan's results becomes one IP address:

Which scans are read

• Every scan is read. The integration reads every scan that the API keys' user can access. There is no setting to include or exclude scans.
• Only completed runs are used. For each scan, the integration reads the results of its newest completed run. While a scan is running again, paused, or canceled, the integration keeps reading the previous completed run until the new one completes.
• Imported scans are read as completed.
• A scan that has never completed is skipped. Its hosts appear after its first run completes.

Which hosts are recorded

• The address comes from the host's details. The integration reads each host's host-ip from the host details in the same run. This works for scans that target IP addresses and for scans that target host names. If the host details cannot be read, the integration uses the host's entry in the scan's host list, which holds the IP address only for scans that target IP addresses.
• A host with no IP address is skipped, and the integration logs a warning naming the host and scan.
• IPv4 and IPv6 addresses are both recorded. IPv6 addresses are recorded in their canonical form, so the same address written in different ways produces one IP address.

Description format

The description is built from these parts, in this order:

1. Discovered by Tenable scans: followed by the names of every scan that found the host, sorted by name (uppercase before lowercase), with a name that two scans share listed once, separated by commas
2. - Hostname: <fqdn>, when the host has a DNS name
3. - Vulnerabilities: <n> critical, <n> high, <n> medium, <n> low, <n> info, when the host has at least one critical, high, medium, or low finding

Examples:

Discovered by Tenable scans: Internal Network Scan - Hostname: host1.internal.example.com - Vulnerabilities: 2 critical, 5 high, 1 medium, 0 low, 3 info

Discovered by Tenable scans: DMZ Scan

A host with only info findings, or none, has no Vulnerabilities part.

Hosts found by more than one scan

When the same IP address appears in more than one scan, the integration records it once:

• Scan names - all of the scans are listed in the description.
• Finding counts - taken from the one scan whose completed run finished most recently. Counts are not added together across scans. When two runs finished at the same time, the scan with the higher ID is used.
• Severity custom fields - set from the same counts.
• DNS name - taken from the most recently completed scan that reported one. A scan that reports no DNS name for the host does not clear one from another scan.

Because the counts describe one scan, a newer scan that does not check for vulnerabilities, such as a host discovery scan, sets a host's severity to none and its counts to zero, even if an older scan found vulnerabilities on it.

DNS names

The DNS name comes from the host-fqdn property in the host's details, from the same completed run that the scan's counts are read from. NetBIOS names are not used, because they are not DNS names. For a host found by more than one scan, see Hosts found by more than one scan.

A host has no DNS name in NetBox when no scan reports a host-fqdn for it, or when its host details could not be read.

When USE_DNS_FALLBACK is true, the integration does a reverse DNS lookup for each IP address that no scan reported a host-fqdn for. A name from host details always takes precedence over the lookup. The lookup is made from the agent container, using its DNS configuration. A lookup that fails, or returns the IP address itself, leaves the DNS name empty. Lookups are made one host at a time, so enabling this can lengthen runs with many hosts.

Severity Custom Fields

The integration records each host's severity in five custom fields on the IP address. All five are created during bootstrap, are assigned to IP addresses only, appear in a Tenable group on the IP address page, and are read-only in the NetBox UI.

Every run sets all five fields on every IP address it records, including none and zero counts. When findings on a host are fixed, the fields show the host's current state after the next run.

Info findings, such as open ports and operating system detection, are not treated as vulnerabilities. They do not affect tenable_max_severity and have no custom field. The info count appears only in the description, and only when the host has another finding.

Only the number of findings at each severity is recorded. Individual findings, plugin IDs, CVEs, and CVSS scores are not recorded.

Tags

Every IP address the integration records is tagged:

• tenable and discovered
• nbl-tenable-tenable-<scanner-host>, where <scanner-host> is the hostname from TENABLE_URL with dots and colons replaced by hyphens. For example, https://nessus.example.com:8834 gives nbl-tenable-tenable-nessus-example-com. Use this tag to tell apart addresses recorded from different scanners

Configuration Parameters

Configure these under the config key in the policy definition.

* Not required in bootstrap mode.

The integration has no scope parameters.

Authentication and Connection

The integration authenticates to Nessus with the access key and secret key of a Nessus user, set in TENABLE_ACCESS_KEY and TENABLE_SECRET_KEY. It reads every scan that user can access. See Generate Nessus API keys.

The integration does not verify the Nessus scanner's TLS certificate. A scanner using its default self-signed certificate works, and there is no setting to turn verification on or to provide a CA certificate.

Bootstrap Mode

When BOOTSTRAP is set to True, the integration creates the following without connecting to Nessus:

• Custom fields: tenable_max_severity, tenable_critical_count, tenable_high_count, tenable_medium_count, tenable_low_count

TENABLE_URL, TENABLE_ACCESS_KEY, and TENABLE_SECRET_KEY are not required. If TENABLE_URL is set, it must still include a scheme and hostname.

Use bootstrap mode on the initial setup only, then set it to False for all subsequent runs.

Sync Behavior

• Direction: One-way, Nessus to NetBox. The integration does not write to Nessus.
• Object deletion: The integration does not delete NetBox objects. IP addresses for hosts that no longer appear in any scan remain in NetBox, with the values from the last run that recorded them. Handle these removals manually.
• Idempotency: Subsequent runs update existing NetBox objects rather than creating duplicates. The Diode SDK handles conflict resolution.
• Multiple scanners: Each policy reads one Nessus scanner. Run a separate policy for each scanner.

Known Limitations

• Existing values on matching IP addresses are replaced. Every run sets the description and the active status on each IP address it records, replacing the values already in NetBox for that address.
• Results are recorded against IP addresses only. The integration does not create devices or virtual machines, and does not link an IP address to an existing device, virtual machine, or interface.
• Individual vulnerabilities are not recorded. Only the most severe level and the number of findings at each severity are recorded. Plugin IDs, CVEs, and CVSS scores are not recorded.
• Every scan is read. There is no setting to select which scans are synced. Limit the scans the API keys' user can access instead.
• Severity describes one scan. For a host found by several scans, the values come from the scan that completed most recently, not from every finding known for the host. A newer discovery-only scan shows the host as none.
• Running scans are not read until they complete. A host first found by a scan that is still running appears after that run completes.
• DNS names depend on Nessus. A DNS name is recorded only when a scan's host details include host-fqdn for the host, or when USE_DNS_FALLBACK finds one.
• IP addresses are in the global table. They are not placed in a VRF.
• The Nessus TLS certificate is not verified.
• Tenable Nessus only. Other Tenable products, such as Tenable Vulnerability Management and Tenable Security Center, are not supported in this release.