Masks

Learn how to use field masks with the Endor Labs REST API.

This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Learn how to use field masks with the Endor Labs REST API.

Field masks allow you to specify a subset of fields that each returned object includes. Similar to filter keys, a field-mask key specifies the field to return, using a dot-delimited path.

The following example shows how to get just the description and severity for all findings:

endorctl api list --resource Finding \
  --field-mask "meta.description,spec.level"

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.mask=meta.description,spec.level"

@baseUrl = https://api.endorlabs.com
@token = <insert-access-token>
@namespace = <insert-namespace>

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.mask=meta.description,spec.level HTTP/1.1
Authorization: Bearer {{token}}

jq

The Endor Labs REST API returns results in json format so it is often convenient to use the jq command-line json processor to parse or format the results.

The following example shows how to use jq to extract just the description value from the above request:

endorctl api list --resource Finding \
  --field-mask "meta.description,spec.level" \
  | jq '.list.objects[].meta.description'

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.mask=meta.description,spec.level" \
  | jq '.list.objects[].meta.description'

Note

Lists of objects are always nested under .list.objects[], but endorctl api get returns a single object directly. To extract the object UUID from an object returned by an endorctl api get command, the jq command is jq '.uuid', as opposed to jq '.list.objects[].uuid'.

For more information, see the jq documentation.