Selecting Return Fields with Vulnerability Management Data Export API

AdvocateRick · ‎08-07-2023

Are your vulnerability or asset export files getting too large? Well help is here. There is way to reduce the export file size by specifying which fields are to be in the response in the export file. By reducing the number of fields in the response, the export file size will be smaller.

The "Request Data Export" API documentation discusses "Pick Your Fields" feature; and this blog will discuss how to use it. Just remember, this feature is currently only for asset and vulnerability exports.

I think the best way to understand this feature is by looking at the code.

Vulnerability Code Example

There is new code sample, `blog_get_vuln_details.py` that uses this new feature:

 68 # Invoke the data_exports API to request an vuln export.
 69 def request_vuln_exports(base_url, headers, selected_fields):
 70     request_export_url = f"{base_url}/data_exports"
 71 
 72     filter_params = {
 73         'status' : ['open'],
 74         'export_settings': {
 75             'format': 'jsonl',
 76             'model': 'vulnerability',
 77             "fields": selected_fields
 78         }
 79     }
 80 
 81     response = requests.post(request_export_url, headers=headers, data=json.dumps(filter_params))
 82     if response.status_code != 200:
 83         process_http_error(f"Request Data Export API Error", response, request_export_url)
 84         sys.exit(1)
 85

The `fields` field in the `export_settings` object contains the selected fields to be return. The variable, `selected_fields` is a string array. It is defined here:

235     # Seleted fields to be returned.
236     selected_fields = [
237         "cve_description",
238         "cve_id",
239         "description",
240         "details", 
241         "id",
242         "scanner_score", 
243         "solution",
244         "risk_meter_score",
245     ]

This is a simple in-line example, but feel free to download it and modify it to read the selected fields from a file.

Valid Fields

Where do you obtain the list of valid fields? The valid fields are actually the responses of the "Retrieve Data Export" API documentation. You will have to match the `model` in "Request Data Export" to the response option in "Retrieve Data Export". The asset `model` maps to responses option 1, and the vulnerability `model` maps to responses option 3. The `id` field is always returned whether it is specified or not.

Details Object Field

With respect to vulnerability fields, the `details` object field is special, because it is only in the response when specified in the selected fields. The `details` field is an object comprised of two fields, `connector_name` and `value`. Note that the `value` field can be lengthly and may contain HTML formatted data.

Custom Fields

Another item to note with vulnerability fields, is that custom fields can only be specified individually by name. There is no way to specify all custom fields. Here is an example on how to specify a custom field:

    # Seleted fields to be returned with custom fields.
    selected_fields = [
        "custom_fields:CISA",
        "custom_fields:support escalted"
        "cve_description", 
        "cve_id",
        "description",
        "id",
        "scanner_score",
        "risk_meter_score", 
    ]

Summary

To summarize:

What fields to be returned in a asset and vulnerability exports can be specified. This reduces the size of the export file.
The `details` field has to be specified to be in the export file.
Only individual custom fields can be specified.
There is a new code example.

Until next time,

Rick Ehrhart

Developer Advocate