List Compliance Posture Information

action=list

(Required)

echo_request={0|1}

(Optional) Specify 1 to view (echo) input parameters in the XML output. By default these are not included.

policy_id={value}

(policy_id or policy_ids is required)  Show compliance posture info records for a specified policy. A valid policy ID is required.

The parameters policy_id and policy_ids cannot be specified in the same request.

policy_ids={value}

(policy_id or policy_ids is required)  Show compliance posture info records for multiple policies - up to 10 policies may be requested. Provide a comma-separated list of valid policy IDs. When this parameter is specified, all posture data is downloaded (and the “truncation_limit” parameter is invalid).

The parameters policy_id and policy_ids cannot be specified in the same request. When policy_ids is specified, truncation_limit is invalid. For CSV output, policy_id must be specified (and policy_ids is invalid).

control_ids={value}

(Optional)  Show only compliance posture info records for controls which have certain control IDs and/or ranges. One or more control IDs/ranges may be specified. Multiple entries are comma separated. An control ID range entry is specified with a hyphen (for example, 1200-1300). Valid control IDs are required.

output_format={value}

(Optional) The output format. A valid value is: xml (default), csv (posture data and metadata, i.e. summary and warning data), csv_no_metadata (posture data only, no metadata). For CSV output, you can include only one policy. For this reason, policy_id is required.

details={Basic|All|None|Light}

(Optional)  Show a certain amount of information for each compliance posture info record. A valid value is:

None - show posture info and minimum exception information (assignee and status) if appropriate Basic (default) - show posture info, full exception information if appropriate, and a minimum glossary (basic info for hosts and controls)

Light - show posture info, exception info if appropriate, and a limited glossary (host info and last scan date/time, control ID, and evidence info

All - show posture info (including the percentage of controls that passed for each host), exception info if appropriate, posture summary (the number of assets, controls, and control instances evaluated) and a glossary (host info and last scan date/time), control info, technology info, evidence info

When hide_evidence=1 is specified in the same request as details=All or details=Light, then evidence info will not be shown in the output.

hide_evidence={0|1}

(Optional when details=All or details=Light) Set to 1 to hide the evidence information in the output. When set to 0 or unspecified, evidence information is shown in the output.

include_dp_name={value}

(Optional) Show the name and ID for each data point in the XML output. This is useful for uniquely identifying data points.

show_remediation_info={0|1}

(Optional) Set to 1 to show remediation information in the XML or CSV output. By default, the output does not include the remediation information. When not specified, the remediation information is not included in the output.

cause_of_failure={0|1}

(Optional) Set flag to 1 to display the cause of failure of Directory Integrity Monitoring UDCs (user defined controls). When set to 0 or unspecified, cause of failure is not displayed for these UCDs. When set to 1 and Directory Integrity Monitoring UDC control failed assessment, cause of failure info is shown in XML response, i.e. added, removed directories, directories where content changed, permissions changed etc.

truncation_limit={value}

(Optional) The parameter is valid only when the API request is for a single policy and the policy_id parameter is specified.

By default, a limit of 5,000 posture info records are returned per request (when “policy_id” is specified). You may specify a value less than the default (1-4999) or greater than the default (5001-1000000) to configure the number records returned per request.

If the requested list identifies more records than the truncation limit, then the XML output includes the <WARNING> element and the URL for making another request for the next batch of records.

You can specify truncation_limit=0 for no truncation limit. This means that the output is not paginated and all the records are returned in a single output. WARNING: This can generate very large output and processing large XML files can consume a lot of resources on the client side. In this case it is recommended to use the pagination logic and parallel processing. The previous page can be processed while the next page is being downloaded.

Hosts

ips={value}

(Optional)  Show only compliance posture info records for compliance hosts which have certain IP addresses/ranges. One or more IP addresses/ranges may be specified. Multiple IPs/ranges are comma separated.

host_ids={value}

(Optional)  Show only compliance posture info records for compliance hosts which have certain host IDs and/or ID ranges. One or more host IDs/ranges may be specified. Multiple entries are comma separated. A host ID range entry is specified with a hyphen (for example, 123-125). Valid host IDs are required.

asset_group_ids={value}

(Optional)  Show only hosts in certain asset groups. Provide a comma-separated list of asset group IDs for the asset groups you want to download compliance posture data for. The asset groups specified do not need to be assigned to the one or more policies requested. Posture data will be returned as long as there are common hosts specified by “asset_group_ids” and asset groups that are assigned to the policies requested.

filter_hosts={0|1}

(Optional) A Manager or Auditor user can specify filter_hosts=1 to improve performance. The API will skip calling the tag resolution service and directly check the host IDs for the policy. The default value is 0.

Posture IDs

ids={value}

(Optional) Show only compliance posture info records for certain compliance posture IDs and/or ID ranges. One or more posture IDs/ranges may be specified. Multiple entries are comma separated. A posture ID range entry is specified with a hyphen (for example, 1-10). Valid posture IDs are required.

id_min={value}

(Optional) Show only compliance posture info records which have a minimum ID value. A valid posture ID is required.

id_max={value}

(Optional) Show only compliance posture info records which have a maximum ID value. A valid posture ID is required.

Status

status_changes_since={date}

(Optional) Show compliance posture info records when the compliance status was changed since a certain date and time (optional). If the policy itself was changed, a warning message is generated.

The date/time is specified in YYYY-MM-DD[THH:MM:SSZ] format (UTC/GMT), like “2008-05-01” or “2008-05-01T23:12:00Z”.

evaluation_date={date}

(Optional) Show compliance posture info records when the posture evaluation date is equal to or greater than a certain date and time (optional). The date/time is specified in YYYY-MMDD[THH:MM:SSZ] format (UTC/GMT), like “2021-04-01” or “2021-04-01T23:12:00Z”.

status={Passed|Failed|Error}

(Optional) Show only compliance posture info records which have a posture status of Passed, Failed or Error. By default, records with the status Passed, Failed and Error are listed.

criticality_labels={value}

(Optional) Show only compliance posture info records for controls which have certain criticality labels. One or more criticality labels (e.g. SERIOUS, CRITICAL, URGENT) may be specified. Multiple entries are comma separated.

The parameters criticality_labels and criticality_values cannot be specified in the same request.

Note

This parameter is not available to VMDR SCA customers using this API. This is because SCA customers do not have access to the Controls tab in the UI.

criticality_values={value}

(Optional) Show only compliance posture info records for controls which have certain criticality values. One or more criticality values (0-5) may be specified. Multiple entries are comma separated.

The parameters criticality_labels and criticality_values cannot be specified in the same request.

Tags

tag_set_by={id|name}

(Optional) Specify “id” (the default) to select a tag set by providing tag IDs. Specify “name” to select a tag set by providing tag names.

tag_include_selector={all|any}

(Optional) Select “any” (the default) to include hosts that match at least one of the selected tags. Select “all” to include hosts that match all of the selected tags.

tag_exclude_selector={all|any}

(Optional) Select “any” (the default) to exclude hosts that match at least one of the selected tags. Select “all” to exclude hosts that match all of the selected tags.

tag_set_include={value}

(Optional) Specify a tag set to include. Hosts that match these tags will be included. You identify the tag set by providing tag name or IDs. Multiple entries are comma separated.

tag_set_exclude={value}

(Optional) Specify a tag set to exclude. Hosts that match these tags will be excluded. You identify the tag set by providing tag name or IDs. Multiple entries are comma separated.