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,