Automated Pull from Database in Tenable One Open Connector

The following is not supported in Tenable FedRAMP Moderate environments. For more information, see the Tenable FedRAMP Product Offering.

You can use the Tenable One Open Connector to pull asset and finding data directly from a relational database into Tenable Exposure Management. You provide the connection details and a SQL query, and the connector runs that query on every scheduled sync.

This method removes the export step that file-based ingestion requires. You do not export your database records to a file, and you do not stage a file in cloud storage. As a result, enrichment data that lives only in your database reaches your risk scoring without a custom data pipeline. Examples include asset ownership, application mapping, and business criticality.

Note: To pull a file from cloud storage or upload a file manually instead of running a SQL query, see Automated Pull from Cloud Storage in Tenable One Open Connector and Static File Upload in Tenable One Open Connector.

You can connect the Tenable One Open Connector to the following database providers:

• Configure Automated Pull from BigQuery (GCP)

• Configure Automated Pull from Oracle

You select the database provider in the Data pulling configuration section, and then type that provider's connection details, authentication details, and SQL query.

Note: The query execution, validation, mapping, and synchronization logic are the same for both providers. Only the connection and authentication fields differ.

Prerequisites

Before you begin, make sure you have the following:

Requirement	Details
Tenable Exposure Management access	A user account with the Connector Manager or Administrator role.
Database access	A database user with read access to every table or view that your query targets, including any in another schema or dataset. The permissions of this user are the only limit on what your query can return. The connector reads data only. It does not write, update, or delete records in your database.
SQL query	A query that returns a single flat table. For more information, see SQL Query Requirements.
Asset type decision	Determine which asset type matches your data. You cannot change the asset type after you set up the connector. To ingest more than one asset type, create a separate connector for each one.

SQL Query Requirements

The connector executes the query you provide and ingests the result as a flat table. JOIN clauses, WHERE clauses, and subqueries are supported.

The connector places no restriction on which objects your query reads. The permissions of the account that you configure are the only limit, so your query can join tables across schemas or datasets when that account can read them.

Important: The connector does not validate or build queries. It executes the query you provide, read-only, on every scheduled sync.

The result must be a single flat table. Tenable Exposure Management does not support multi-level nested structures, and rejects a result that contains any of the following column types:

Database Provider	Unsupported Column Types
BigQuery (GCP)	Nested types (RECORD and STRUCT), array types (REPEATED), and the native JSON type.
Oracle	Object types, collection types (nested table and VARRAY), REF CURSOR, and the native JSON type.

Note: Scalar column types, such as VARCHAR, NUMBER, DATE, and CLOB, are supported. A JSON value stored in a plain text column is scalar, so the connector accepts it.

Tip: To flatten an unsupported column, cast it to a text value or select its individual attributes as separate columns in your query.

Query Preview and Validation

Tenable Exposure Management validates your query in two stages:

• Preview: When you click Continue, Tenable Exposure Management runs your query with a 10-row limit and displays the returned columns and up to 10 sample rows. You map your fields against those columns. A row limit does not change which columns the query returns, so the preview columns match the columns of the full result.

• Sync start: At the start of every sync, Tenable Exposure Management runs the same 10-row query and confirms that the result is not empty and that it contains every mandatory and unique column in your mapping. If either check fails, the sync fails before the connector fetches your data.

Note: The 2 GB file size limit that applies to file-based sources does not apply to a database result set.

Configure Automated Pull from Database

Set Asset Retention and Complete the Configuration

A database source runs a full sync every time. Tenable Exposure Management replaces the connector data with the result of your query on each synchronization.

Note: A database source has no Data Update Mode selection. You do not choose between Full Fetch and Incremental Fetch, and the Additive Only, Strict Inventory, and Dynamic Remediation reconciliation modes do not apply.

To complete the data configuration:

1. In the Asset Retention section, type the number of days after which Tenable Exposure Management removes assets. The default is 460 days.

   Tip: To learn more, see How does Asset Retention work in the Tenable One Open Connector?.

2. In the Test connectivity section, click Test connectivity. Tenable Exposure Management opens a connection to your database and validates the credentials. You must pass this test before you can create the connector.

   Note: The connectivity test does not run your query, and a successful test does not guarantee a successful sync. The connector can still fail later during syncing or processing.

   Important: If you change the connection details, the authentication details, or the SQL query, test the connectivity and preview the result again. You must do this before you can save the connector. If you change only the connector name, the description, or the schedule, you can save and sync without testing again.

3. In the Connector scheduling section, configure the time and day(s) on which you want connector syncs to occur.

   Tip: For more information, see Connector Scheduling.

4. Click Continue.

   Tenable Exposure Management runs your query with a 10-row limit and displays the returned columns and up to 10 sample rows.

5. From the Asset type drop-down, select the category that matches your data, for example, Devices.

   Important: You cannot change the asset type after you save the connector. To ingest a different asset type, create a new connector instance.

6. Click Continue.

   Note: This selection defines the mapping attributes available in the next step.

   The mapping page appears.

7. Define how the connector interprets and aligns your query result with the Tenable Exposure Management standardized data model:

   1. Review the auto-suggested mappings, and adjust them as needed. You must map the mandatory fields, such as Asset Name or Finding Name, to continue.

   2. (Optional) Use the + button to add new mappings.

      TIP: To learn about the expected behavior and logic rules for how Tenable Exposure Management maps your source columns, see Tenable One Open Connector Mapping .

   3. Click Save and continue.

      The Data Aggregation and Uniqueness page appears.

8. On the Data Aggregation and Uniqueness page, fill in the answers for the required questions to define how Tenable Exposure Management identifies unique assets, weaknesses, and findings.

   Note: Tenable One Open Connector lets you define custom uniqueness criteria. You can tailor the Data Aggregation and Uniqueness settings to make sure Tenable Exposure Management correctly identifies your specific assets and findings as new records or updates.

   Tenable Exposure Management also asks which Tenable Exposure Category best describes your data, and suggests a category based on the asset type you selected. If you select Other, Tenable Exposure Management cannot calculate an Asset Exposure Score (AES) for those assets.

   Tip: These settings control uniqueness inside this connector. To understand how your database rows deduplicate against assets that other sources already discovered, see How Your Database Data Merges with Existing Assets.

9. Click Save.

   The main setup page appears.

10. Click Create & Sync.

    Tenable Exposure Management runs your full query, ingests the result, and reflects the changes after processing completes.

11. (Optional) On the main connector setup page, view the Connector Logs to review any changes. For more information, see Tenable One Open Connector Logs.

Remap Columns

With the Remap Columns option, you can revise the field mappings or the uniqueness criteria for your existing database data source.

To remap columns:

1. On the Connectors page, click the Tenable One Open Connector instance you want to edit.
2. At the bottom right of the screen, click Remap Columns.

   The Map Attributes page appears.

3. Remap the query result columns to the Tenable Exposure Management attributes as needed.
4. Click Next.

   The Data Aggregation and Uniqueness page appears.

5. On the Data Aggregation and Uniqueness page, identify and apply any required changes to your unique identifiers.
6. Click Update & Sync.

Note: If you change your SQL query, Tenable Exposure Management previews the new result and revalidates your mapping against the returned columns. Map any column that your previous mapping no longer matches.

Tenable One Open Connector Data in Tenable Exposure Management

Locate Connector Assets in Tenable Exposure Management

As the connector discovers assets, Tenable Exposure Management ingests those devices for reporting.

To view assets by connector:

1. In Tenable Exposure Management, navigate to the Assets page.

2. In the Filters section, under Custom, click the connector name for which you want to view assets.

   The asset list updates to show only assets from the selected connector.

3. Click any asset to view Asset Details.

Locate Connector Weaknesses in Tenable Exposure Management

As the connector discovers weaknesses, Tenable Exposure Management ingests those weaknesses for reporting.

To view weaknesses by connector: 

1. In Tenable Exposure Management, navigate to the Weaknesses page.

2. In the Filters section, under Custom, click the connector name for which you want to view weaknesses.

   The weaknesses list updates to show only weaknesses from the selected connector.

3. Click any weakness to view Weakness Details.

Locate Connector Findings in Tenable Exposure Management

As the connector discovers individual findings, Tenable Exposure Management ingests those findings for reporting.

To view findings by connector:

1. In Tenable Exposure Management, navigate to the Findings page.

2. In the Filters section, under Custom, click the connector name for which you want to view findings.

   The findings list updates to show only findings from the selected connector.

3. Click any finding to view Finding Details.

How Your Database Data Merges with Existing Assets

The connector ingests your query result as asset and finding data. It does not enrich an existing asset in place. Instead, when the asset it ingests matches one that another source already discovered, Tenable Exposure Management presents the data from both sources under a single deduplicated asset in your inventory.

Two separate mechanisms control this, and each one operates at a different level:

• Data Aggregation and Uniqueness: You configure these settings during setup. They tell Tenable Exposure Management which columns identify a unique asset, weakness, and finding inside this connector. Multiple query rows that describe the same asset then consolidate into one record.

• Third-party asset deduplication: Tenable Exposure Management applies this automatically across sources. It matches each incoming asset against the assets that your other connectors and Tenable sensors already discovered. When the criteria match, the records deduplicate into one multi-source asset, and your inventory shows the data from every contributing source under it. When the criteria do not match, the asset appears on its own.

Note: You cannot configure the third-party deduplication criteria. Tenable Exposure Management applies a fixed set of matching field combinations for each asset class.

For your database rows to deduplicate against assets that already exist, include and map the columns that the deduplication criteria use for your asset class. For a device, map a value such as an external identifier, a MAC address, or a consistent hostname, fully qualified domain name (FQDN), and IP address. A query that returns only ownership or business context, with no identifier that the criteria recognize, produces separate assets rather than data attached to your existing inventory.

Tip: For the criteria for each asset class, the property merge order, and the known limitations, see Asset Deduplication in Tenable Exposure Management and the Asset Deduplication FAQ.

Expected Post-Sync Behavior

After a successful synchronization, Tenable Exposure Management performs the following actions:

• Data replacement: Replaces all existing asset records and findings for the connector instance with the content of the new query result. Tenable Exposure Management archives assets and marks findings as Fixed if they are missing from the latest result.

• Uniqueness and mapping changes: Applies updated uniqueness criteria or field mappings from the next sync onward. Tenable Exposure Management does not retroactively modify data already ingested with previous uniqueness logic.

• Data cleanup: Disregards previous values for any non-mandatory fields removed from the latest mapping.

Synchronization Logic

The Tenable One Open Connector applies the following logic during automated database syncs:

• Query execution: Every sync runs your query again. Tenable Exposure Management compares no files and skips no syncs, so a database connector never reports "No new file detected".

• Result processing: Tenable Exposure Management stores each query result as a CSV file internally, and then processes that file through the same mapping and normalization pipeline as a file-based source.

• Result validation: An empty result fails the sync. A result that omits a mandatory or unique mapped column also fails the sync.

• Finding status: Tenable Exposure Management moves findings not included in the new result to the Fixed state.

• Credentials or query modification: If you change the credentials or the query, you must test the connectivity and preview the result before you can save and sync the connector.

• On-demand sync: To run a sync outside the schedule, open the connector and click Sync now.

Connectivity and Sync Errors

If a sync or connectivity test fails, review the error messages to troubleshoot configuration issues.

Scenario	Message
Authentication failure	"Failed test 1 out of 2: the credentials are not correct."
Missing mandatory columns	"File is missing mandatory columns and the data cannot be synced."
Empty result detected	"Sync Failed: No Records Found."
Nested or structured column in the result	The sync fails because the query result is not a single flat table.

Related topics: