Using saved queries

The Endor Labs REST API provides the Query Service for flexible requests for resources. The Endor Labs REST API also provides the ability to save and manage queries for your own use cases through the Saved Query Service. See Using the Query Service for examples on using the Query Service to specify and request resources from the Endor Labs REST API.

Creating a saved query

To create a saved query, embed a Query object specifying the request in a SavedQuery object.

endorctl
curl
HTTP

saved_query_data=$(cat << EOF
{
  "meta": {
    "name": "Saved Query for Recent Vulnerabilities"
  },
  "spec": {
    "query": {
      "meta": {
        "name": "Query for Recent Vulnerabilities"
      },
      "spec": {
        "query_spec": {
          "kind": "Finding",
          "list_parameters": {
            "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
            "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level"
          }
        }
      },
      "tenant_meta": {
        "namespace": "$ENDOR_NAMESPACE"
      }
    }
  }
}
EOF
)

endorctl api create --resource SavedQuery \
  --data "$saved_query_data"

saved_query_data=$(cat << EOF
{
  "meta": {
    "name": "Saved Query for Recent Vulnerabilities"
  },
  "spec": {
    "query": {
      "meta": {
        "name": "Query for Recent Vulnerabilities"
      },
      "spec": {
        "query_spec": {
          "kind": "Finding",
          "list_parameters": {
            "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
            "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level"
          }
        }
      },
      "tenant_meta": {
        "namespace": "$ENDOR_NAMESPACE"
      }
    }
  },
  "tenant_meta": {
    "namespace": "$ENDOR_NAMESPACE"
  }
}
EOF
)

curl "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/saved-queries" \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --request POST \
  --data "$saved_query_data"

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

###
POST {{baseUrl}}/v1/namespaces/{{namespace}}/saved-queries HTTP/1.1
Authorization: Bearer {{token}}

{
  "meta": {
    "name": "Saved Query for Recent Vulnerabilities"
  },
  "spec": {
    "query": {
      "meta": {
        "name": "Query for Recent Vulnerabilities"
      },
      "spec": {
        "query_spec": {
          "kind": "Finding",
          "list_parameters": {
            "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
            "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level"
          }
        }
      },
      "tenant_meta": {
        "namespace": "{{namespace}}"
      }
    }
  },
  "tenant_meta": {
    "namespace": "{{namespace}}"
  }
}

Updating a saved query

The following example updates the Query specified in the SavedQuery to add additional list parameters.

endorctl
curl
HTTP

saved_query_uuid="`<insert-uuid>`"
saved_query_data=$(cat << EOF
{
  "spec": {
    "query": {
      "spec": {
        "query_spec": {
          "kind": "Finding",
          "list_parameters": {
            "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
            "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level",
            "page_size": 10,
            "sort": {
              "order": "SORT_ENTRY_ORDER_DESC",
              "path": "meta.create_time"
            }
          }
        }
      }
    }
  }
}
EOF
)

endorctl api update --resource SavedQuery \
  --uuid "$saved_query_uuid" \
  --field-mask "spec.query.spec.query_spec" \
  --data "$saved_query_data"

saved_query_uuid="`<insert-uuid>`"
saved_query_data=$(cat << EOF
{
  "request": {
    "update_mask": "spec.query.spec.query_spec"
  },
  "object": {
    "uuid": "$saved_query_uuid",
    "spec": {
      "query": {
        "spec": {
          "query_spec": {
            "kind": "Finding",
            "list_parameters": {
              "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
              "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level",
              "page_size": 10,
              "sort": {
                "order": "SORT_ENTRY_ORDER_DESC",
                "path": "meta.create_time"
              }
            }
          }
        }
      }
    }
  }
}
EOF
)

curl "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/saved-queries" \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --request PATCH \
  --data "$saved_query_data"

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

###
PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/saved-queries HTTP/1.1
Authorization: Bearer {{token}}

{
  "request": {
    "update_mask": "spec.query.spec.query_spec"
  },
  "object": {
    "uuid": "{{uuid}}",
    "spec": {
      "query": {
        "spec": {
          "query_spec": {
            "kind": "Finding",
            "list_parameters": {
              "filter": "meta.create_time > now(-24h) and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY]",
              "mask": "uuid,meta.create_time,meta.update_time,meta.description,spec.level",
              "page_size": 10,
              "sort": {
                "order": "SORT_ENTRY_ORDER_DESC",
                "path": "meta.create_time"
              }
            }
          }
        }
      }
    }
  }
}

See also interactive mode for managing updates to a SavedQuery with endorctl api update:

endorctl api update --interactive --resource SavedQuery \
  --name "Saved Query for Recent Vulnerabilities"

Evaluating saved queries

After you create a Saved Query, you can evaluate the request specified by its Query on demand.

endorctl
curl
HTTP

endorctl api get --resource SavedQuery --uuid `<insert-uuid>`

base_url="https://api.endorlabs.com"
uuid="`<insert-uuid>`"

curl "$base_url/v1/namespaces/$ENDOR_NAMESPACE/saved-queries/$uuid/evaluate" \
  --header "Authorization: Bearer $ENDOR_TOKEN"

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/saved-queries/{{uuid}}/evaluate HTTP/1.1
Authorization: Bearer {{token}}

The response returns the resulting data in a nested field under the Query specification. Use the jq command to extract the nested data. For the example queries given above, the following command will evaluate the given saved query, and extract the list of Finding objects from the Query response:

endorctl api get --resource SavedQuery --uuid <insert-uuid> \
  | jq '.spec.query.spec.query_response.list.objects[]'

Developers & API

endorctl CLI

REST API

Creating a saved query

Updating a saved query

Evaluating saved queries

​Creating a saved query

​Updating a saved query

​Evaluating saved queries

Creating a saved query

Updating a saved query

Evaluating saved queries