Getting started - Endor Labs Documentation

Introduction

This article describes how to use the Endor Labs REST API. For a quickstart guide, see Quickstart for Endor Labs REST API. The Endor Labs command line tool endorctl is a convenient wrapper around the Endor Labs REST API and allows you to interact with Endor Labs without having to worry about the REST protocol details. For more information, see Making a request below and the Endor Labs CLI documentation. For a complete list of Endor Labs REST API endpoints, see the Endor Labs OpenAPI documentation.

About requests to the REST API

This section describes the elements that make up an API request:

HTTP method
Path
Headers
Parameters

Every request to the REST API includes an HTTP method and a path. Depending on the REST API endpoint, you might also need to specify request headers, authentication information, list parameters, or body parameters. The REST API reference documentation describes the HTTP method, path, and parameters for every endpoint. It also displays example requests and responses for each endpoint. For more information, see the Endor Labs REST API documentation.

HTTP method

The HTTP method of an endpoint defines the type of action it performs on a given resource. Some common HTTP methods are GET, POST, DELETE, and PATCH. The REST API reference documentation provides the HTTP method for every endpoint. For example, the HTTP method for the List Findings endpoint is GET. Where possible, the Endor Labs REST API strives to use an appropriate HTTP method for each action.

Path

Each endpoint has a path. The Endor Labs REST API reference documentation gives the path for every endpoint. For example, the path for the List Findings endpoint is https://api.endorlabs.com/v1/namespaces/{tenant_meta.namespace}/findings and the path for the Get Finding endpoint is https://api.endorlabs.com/v1/namespaces/{tenant_meta.namespace}/findings/{uuid}. The curly brackets in a path denote path parameters that you need to specify. Path parameters modify the endpoint path and are required in your request. For example, the path parameter for the List Findings endpoint is {tenant_meta.namespace}. To use this path in your API request, replace {tenant_meta.namespace} with the name of the namespace where you want to request a list of findings. To get a specific finding object, add the object UUID to the end of the path.

Headers

Headers provide extra information about the request and the desired response. Following are some examples of headers that you can use in your requests to the Endor Labs REST API. For an example of a request that uses headers, see Making a request.

Authentication

All endpoints require authentication. Use the endorctl init command to authenticate with Endor Labs. For more information, see Authentication. For examples, see Making a request.

Accept-Encoding

You may optionally use the Accept-Encoding header to enable compression of HTTP responses for performance optimization. The following encodings are supported: gzip, br (Brotli), and zstd. If you specify multiple encodings, gzip takes priority. Ensure that the client can correctly handle the specified encoding. You can provide the Accept-Encoding header in the following format: Accept-Encoding: gzip, br, zstd.

Content-Type

To improve API performance, set the Content-Type header to application/jsoncompact. This prevents Endor Labs APIs from returning null or empty values, which is the default behavior.

Request-timeout

Use the Request-timeout header to specify the amount of time, in seconds, that you are willing to wait for a server response. For example: --header "Request-Timeout: 10". The corresponding option for endorctl requests is -t/--timeout, for example: -t 10s.

Parameters

Many API methods require or allow you to send additional information in parameters in your request. There are a few different types of parameters: Path parameters, list parameters, and body parameters.

Path parameters

Path parameters modify the endpoint path. These parameters are required in your request. For more information, see Path.

List parameters

List parameters allow you to control what data is returned for a request. These parameters are usually optional. The documentation for each Endor Labs REST API endpoint describes any list parameters that it supports. For example, all Endor Labs endpoints return one hundred objects by default. You can set page_size=2 to return two objects instead of 100. You can set count=true to just return the number of objects. You can use the filter list parameter to only list objects that match a specified list of criteria (see filters). For examples of requests that use list parameters, see Making a request and Use cases.

Body parameters

Body parameters allow you to pass additional data to the API. These parameters can be optional or required, depending on the endpoint. The documentation for each Endor Labs REST API endpoint describes the body parameters that it supports. For more information, see the Endor Labs OpenAPI documentation. For example, the Create Policy endpoint requires that you specify a name, rule, query statement, and resource kinds for the new policy in your request. It also allows you to optionally specify other information, such as a description, actions, or tags to apply to the new policy. For an example of a request that uses body parameters, see Making a request.

Making a request

The following example retrieves all findings for reachable functions. For more examples, see Use cases.

endorctl
curl
HTTP

Setup

Install the Endor Labs CLI on macOS, Windows, or Linux. For more information, see Install Endor Labs on your local system.

Authenticate

Run endorctl init and your browser window will open automatically. Select your authentication provider from the available options and complete the authentication process.You can also specify your supported authentication provider manually.endorctl init --auth-mode google

Make a request

endorctl api list --resource Finding --filter "spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION"Note that you do not have to provide the access token or the namespace when using endorctl to access the Endor Labs REST API.

Setup
You must have curl installed on your machine. To check if curl is already installed, run curl --version- on the command line.
- If the output provides information about the version of curl, that means curl is installed.
- If you get a message similar to command not found: curl, that means curl is not installed. Download and install curl. For more information, see the curl download page.
Install the Endor Labs CLI on macOS, Windows, or Linux. For more information, see Install Endor Labs on your local system.
Authenticate
Run endorctl init and your browser window will open automatically. Select your authentication provider from the available options and complete the authentication process. You can also specify your supported authentication provider manually. endorctl init --auth-mode google
Store the Endor Labs access token Run the following command from your terminal to get the Endor Labs access token. endorctl auth --print-access-token
Choose an endpoint for your request

Choose an endpoint to make a request to. You can explore the Endor Labs REST API documentation to discover endpoints that you can use to interact with Endor Labs.Identify the HTTP method and path of the endpoint. You will send these with your request. For more information, see HTTP method and Path.For example, the List Findings endpoint uses the HTTP method POST and the path /v1/namespaces/{tenant_meta.namespace}/findings.Identify any required path parameters. Required path parameters appear in curly brackets in the path of the endpoint. Replace each parameter placeholder with the desired value. For more information, see Path.For example, the List Findings endpoint uses the path /v1/namespaces/{tenant_meta.namespace}/findings, and the path parameter is {tenant_meta.namespace}. To use this path in your API request, replace {tenant_meta.namespace} with the name of the namespace where you want to list the findings.

Choose options for your request

Use the curl command to make your request. For more information, see the curl documentation.Specify the following options and values in your request:

--request or -X followed by the HTTP method as the value. For more information, see HTTP method.
Note: You can also use the shorthand curl options --get and --post for GET and POST requests respectively.
--header or -H:
- Authorization: Pass your authentication token in an Authorization header. You must use Authorization: Bearer with the Endor Labs REST API. For more information, see Authentication.
- Accept-Encoding: Provide the Accept-Encoding header in the following format: Accept-Encoding: gzip to avoid performance bottlenecks. For more information, see Accept-Encoding.
- Content-Type: Set the header as Content-Type: application/jsoncompact to prevent Endor Labs APIs from returning null or empty value. For more information, see Content-Type.
- Request-timeout: Specify the amount of time, in seconds, that you are willing to wait for a server response. For more information, see Request-timeout.
--url followed by the full path as the value. The full path is a URL that includes the base URL for the Endor Labs REST API (https://api.endorlabs.com) and the path of the endpoint, like this: https://api.endorlabs.com/{PATH}. Replace {PATH} with the path of the endpoint. For more information, see Path. To use list parameters, add a ? to the end of the path, then append your list parameter name and value in the form list_parameter.parameter_name=value. Separate multiple list parameters with &. For example, to count the number of “Outdated Release” findings, use ?list_parameters.filter=meta.name==outdated_release&list_parameters.count=true. For more information, see List parameters.
Note: Filters with spaces must be encoded when using curl. Replace spaces with %20 or use the --data-urlencode option for filters containing spaces.
--data or -d followed by any body parameters within a json object. If you do not need to specify any body parameters in your request, omit this option. For more information, see Body parameters.

Make request

Using --url

curl --request GET \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --compressed \
  --header "Content-Type: application/jsoncompact" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.filter=spec.finding_tags%20contains%20FINDING_TAGS_REACHABLE_FUNCTION"

Using --data-urlencode

curl --request GET \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --compressed \
  --header "Content-Type: application/jsoncompact" \
  --data-urlencode "spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION" \
  "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings"

Setup

Install the Endor Labs CLI on macOS, Windows, or Linux. For more information, see Install Endor Labs on your local system.

Authenticate
Run endorctl init and your browser window will open automatically. Select your authentication provider from the available options and complete the authentication process. You can also specify your supported authentication provider manually. endorctl init --auth-mode google
Store the Endor Labs access token Run the following command from your terminal to get the Endor Labs access token. endorctl auth --print-access-token
Choose an endpoint for your request

Make a request

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION HTTP/1.1
Authorization: Bearer {{token}}

Developers & API

​Introduction

​About requests to the REST API

​HTTP method

​Path

​Headers

​Authentication

​Accept-Encoding

​Content-Type

​Request-timeout

​Parameters

​Path parameters

​List parameters

​Body parameters

​Making a request