improved

Vulnerability Management: Compliance Export Enhancements Phase 1

Tenable has made several enhancements to the compliance export API. These enhancements improve performance and provide additional functionality for the compliance export API.

  • New Filters—Added 10 new filters that can be applied to a compliance export. These new filters enable customers to more narrowly define their compliance export results; for example, to export only the compliance results for a certain time period or only the assets they're interested in. For more information about the new filters, see New Filters.
  • New Response Properties—Added 24 new properties to the compliance export data. These new properties were added to the response from the Download compliance chunk endpoint. For more information about the new response properties, see New Response Properties.
  • Performance Improvements—Added resumable exports and increased internal pagination count to increase the performance and reliability of compliance exports.
  • Chunks Download—You can now download chunks as they become available instead of waiting for the full export to complete.
  • Permissions—The compliance export API permissions have been updated to match the vulnerabilities export API and the asset export API. Instead of ADMINISTRATOR [64] user permissions, users can now export with BASIC [16] user permissions and Can View access control permissions for the asset objects to be exported.

These enhancements apply to the following endpoints:

EndpointName
POST /compliance/exportExport compliance data
GET /compliance/export/{export_uuid}/statusGet compliance export status
GET compliance/export/{export_uuid}/chunks/{chunk_id}Download compliance chunk
POST /compliance/export/{export_uuid}/cancelCancel compliance export

New Filters

In addition to the existing last_seen and first_seen filters, you can now use the following filters with the Export compliance data endpoint:

FilterData TypeDescription
last_observedIntegerReturns compliance data for assets that were last observed by a scan between the specified date (in Unix time) and now.
indexed_atIntegerReturns compliance data for assets that were indexed into Tenable Vulnerability Management at the specified date (in Unix time).
sinceIntegerThe start date for the range of compliance data you want to export. The date must be specified in Unix time format. Note that since is based on the indexed_at at timestamp. Use this filter in conjunction with the state filter as follows:

  • If the state filter is set to OPEN or REOPENED, the export includes compliance findings for assets that were seen on or after the since date you specify
  • If the state filter is set to FIXED, the export includes compliance findings for assets that were fixed on or after the since date you specify.
  • If you do not include the state filter in your request, the export includes data for OPEN and REOPENED findings that were seen on or after the since date you specify, and FIXED findings that were fixed on or after the since date you specify.
compliance_resultsArray of StringsReturns compliance findings with the specified compliance status. Supported values are:

  • PASSED—Returned if the asset has passed the compliance check.
  • FAILED—Returned if the asset has failed the compliance check.
  • WARNING—Returned in cases where there is no definable passing criteria; for example, an audit where you must verify that members of the administrator group are appropriate for your organization.
  • SKIPPED—Returned if the plugin determined that the check is not applicable to the asset. It can also be returned in other various cases; for example, if a check requires that a direct command be run to gather data on an offline network device or if a check contains commands that won't run on the specified OS.
  • ERROR—Returned if Tenable Vulnerability Management failed to complete the compliance check.
  • UNKNOWN—Returned when a status cannot be determined for the OVAL check. The OVAL engine sets this status.
ipv4_addressesArray of StringsA list of IPv4 addresses for which you want to return compliance findings.
ipv6_addressesArray of StringsA list of IPv6 addresses for which you want to return compliance findings.
audit_nameStringReturns compliance findings with the specified audit name. You can use an asterisk to match text. For example Ensure default *.
audit_file_nameStringReturns compliance findings with the specified audit file name. You can use an asterisk to match text, for example CIS_CentOS_8_Server_L1_v1*.
plugin_idArray of IntegersA list of plugin IDs for which you want to return compliance findings.
stateArray of StringsReturns compliance findings for assets that have the specified state. Supported values are:

  • OPEN—The compliance finding is currently present on a host.
  • REOPENED—The compliance finding was previously marked as fixed on a host but has returned.
  • FIXED—The compliance finding was present on a host but is no longer detected.

Note that the API uses different terms for states than the user interface. The new and active states in the user interface map to the open state in the API. The resurfaced state in the user interface maps to the reopened state in the API. The fixed state is the same.

New Response Properties

The Download compliance chunk endpoint now includes the following properties in the response:

PropertyData TypeDescription
asset.agent_nameStringThe name of the Nessus agent that scanned and identified the asset.
asset.agent_uuidStringThe unique identifier of the Nessus agent that identified the asset.
asset.fqdnsArray of StringsA list of fully-qualified domain names (FQDNs) that are associated with the asset.
asset.idStringThe UUID of the asset in Tenable Vulnerability Management. Use this value as the unique key for the asset.
asset.ipv4_addressesArray of StringsA list of IPv4 addresses that are associated with the asset.
asset.mac_addressesArray of StringsA list of MAC addresses that are associated with the asset.
asset.nameStringThe name of the asset.
asset.netbios_nameStringThe NetBIOS name that is associated with the asset.
asset.operating_systemsArray of StringsThe operating systems that scans have associated with the asset record.
asset.system_typeStringThe system type as reported by Plugin ID 54615. Possible values include router, general-purpose, scan-host, and embedded.
compliance_benchmark_nameStringThe name of the compliance benchmark. For example, CIS SQL Server 2019.
compliance_benchmark_versionStringThe version of the compliance benchmark. For example, 1.2.0.
compliance_control_idStringA unique identifier for the aggregation of multiple results to single recommendations in CIS and DISA audits. This identifier is a computed and hashed value for CIS and DISA content that enables customers to match checks that evaluate the same recommendation within a benchmark.
compliance_full_idStringA unique identifier that identifies a full compliance result in the context of an audit. The identifier is a hash of fields within the compliance check (excluding external references). The identifier changes if any of the fields within the compliance check change.
compliance_functional_idStringA unique identifier for aggregating or comparing compliance results that were tested the same way. The identifier is a hash of the code within the audit that actually performs the check. The identifier changes if functional evaluation of the audit changes.
compliance_informational_idStringA unique identifier for aggregating or comparing compliance results that have the same informational data. For example, the same solution text. The identifier is a hash of the info and solution fields within the compliance check. The identifier changes if either of these fields are updated.
descriptionStringA detailed description of the compliance check.
indexed_atStringThe ISO date when the audit for the asset was indexed into Tenable Vulnerability Management.
last_fixedStringThe ISO date when the compliance failure was last fixed on the asset.
last_observedStringThe ISO date when the compliance issue was last observed (whether active or fixed) on the asset.
plugin_nameStringThe name of the compliance check. For example, Database Compliance Checks.
stateStringThe state as determined by the Tenable Vulnerability Management state service. This field is NULL for findings last seen before December 2021. Possible values include:

  • OPEN—The compliance finding is currently present on an asset.
  • REOPENED—The compliance finding was previously marked as fixed on an asset but has been detected again by a new scan.
  • FIXED—The compliance finding was present on an asset but is no longer detected.

Note that the API uses different terms for states than the user interface. The new and active states in the user interface map to the open state in the API. The resurfaced state in the user interface maps to the reopened state in the API. The fixed state is the same.
synopsisStringA short summary of the compliance audit.
uname_outputStringThe output of the uname command on the asset. It typically contains the operating system type and version.