REST API

• 1: Quickstart
• 2: About the REST API
• 2.1: API Versions
• 2.2: OpenAPI description
• 3: Using the REST API
• 3.1: Getting started
• 3.2: Data model
• 3.2.1: Common fields
• 3.2.2: Resource kinds
• 3.3: Filters
• 3.4: Masks
• 3.5: Pagination
• 3.6: Sorting
• 3.7: Grouping
• 3.8: Best practices
• 3.9: Use cases
• 3.10: Advanced use cases
• 3.10.1: Using the query service
• 3.10.2: Using saved queries
• 3.11: Postman
• 3.12: Errors
• 3.13: Troubleshooting
• 4: Authentication

Quickstart

Start using the Endor Labs REST API immediately.

Read more

About the REST API

Get oriented with the Endor Labs REST API documentation.

Read more

Using the REST API

Learn how to use the API to build your solutions.

Read more

Authentication

Learn how to authenticate to the Endor Labs REST API.

Read more

Use Cases

Explore use cases with Endor Labs REST API.

Read more

Resource Kinds

Learn about the Endor Labs data model.

Read more

Best Practices

Best practices when using the Endor Labs REST API.

Read more

Troubleshooting

Diagnose and resolve issues with the Endor Labs REST API.

Read more

REST API Reference

View the Endor Labs REST API reference.

Read more

1 - Quickstart

This article describes how to quickly get started with the Endor Labs REST API using the Endor Labs command line tool endorctl or curl. For a more detailed guide, see Getting started with the REST API.

The following is an example request to get the number of findings in your namespace:

• endorctl
• curl

For more examples of common use cases, see Use cases.

2 - About the REST API

Introduction

You can use the Endor Labs API to build scripts and applications that automate processes, integrate with Endor Labs, and extend Endor Labs. For example, you can use the API to triage findings, build an analytics dashboard, or manage releases.

Each REST API endpoint is documented individually, and the endpoints are categorized by the resource that they primarily affect. For example, you can find endpoints relating to findings in FindingService.

Getting started with the REST API

If you are new to REST APIs, you may find it helpful to refer to the Quickstart or Getting Started guide for an introduction. For more information, see:

• Quickstart
• Getting started

If you are familiar with REST APIs but new to the Endor Labs REST API, you may find it helpful to refer to the authentication documentation. For more information, see:

• Authentication

Further reading

• Best practices
• Troubleshooting

2.1 - API Versions

About API versioning

The Endor Labs REST API is versioned. Any breaking changes will be released in a new API version.

New endpoints, fields, and enum values are backwards compatible within the same version.

For every new version of the API that is released, the major version is specified in the URL. For example, https://api.endorlabs.com/v1/namespaces/my_namespace/projects uses version 1 of the endpoint, per the v1 path segment.

Each resources have their versions specified in the field meta.version. For example the following resource has version 1 per the v1 value for the field meta.version.

{
  "meta": {
    "create_time": "2023-12-05T00:04:21.853Z",
    "kind": "Project",
    "name": "https://github.com/my_organization/my_repository.git",
    "update_time": "2024-05-01T16:50:03.830911988Z",
    "version": "v1"
  },
  "uuid": "656e69058032bf0abaaeb681"
}

When using the endorctl command-line tool to access the API, new endpoints, fields, or enum values are not available if your version of endorctl is older than the API version. Make sure to keep endorctl up-to-date to access the latest features and endpoints. For more information, see Install and configure endorctl.

Check latest API version using curl

To check the latest API version using curl, run the following command:

curl -s https://api.endorlabs.com/meta/version | jq .Service.Version

Example request using curl

curl -s https://api.endorlabs.com/meta/version | jq .Service.Version
"v1.6.322"

Check latest endorctl version

To get both the current and the latest version of endorctl, run the following command:

endorctl --version

In addition to your current version of endorctl you will also see a notification such as the following if a newer version of endorctl is available.

Example request using endorctl

endorctl --version
endorctl version v1.6.293
A newer version of endorctl is available v1.6.317 - currently v1.6.293

2.2 - OpenAPI description

About OpenAPI

OpenAPI is a specification for describing REST API interfaces. It describes the API as an open standard to act as a dictionary for an API. OpenAPI enables developers to easily find and discover how to use your API. For more information, see the OpenAPI specification documentation.

Using the Endor Labs OpenAPI description

Because the OpenAPI description is machine readable, you can use it to do things like:

• Generate libraries to facilitate using the REST API
• Validate and test an integration that uses the REST API
• Explore and interact with the REST API using third-party tools, such as Postman

For example, Endor Labs uses the OpenAPI description to generate the REST API reference documentation for each endpoint.

For more information, see the Endor Labs OpenAPI documentation.

3 - Using the REST API

3.1 - Getting started

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

Use the Accept-Encoding header to compress the data in the HTTP request to improve performance. If you use a json or REST client, you must always provide the Accept-Encoding header in the following format: Accept-Encoding: gzip, deflate, br, zstd. You must provide the header if you use any default HTTP clients to avoid performance bottlenecks.

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

3.2 - Data model

Objects are persistent entities within the Endor Labs system that represent the results of your scans. Specifically, they can describe:

• The projects and/or package versions that were scanned.
• The results of the scans, including ScanResults, Findings, and Metrics.
• The context used for the scan (for example, main branch vs. pull request).
• The policies used for the scans.

To create, modify, or delete objects, you need to use the Endor Labs REST API - Either indirectly with the endorctl command-line tool or directly with the REST API.

3.2.1 - Common fields

All objects adhere to the same high-level structure as outlined below. Object specific fields are defined in Spec. For more information, see Resource kinds.

UUID

All objects have a unique UUID. You can use UUID to retrieve objects individually through the API.

Meta

All objects include a common nested object called Meta. This mandatory object contains common fields for each object, including:

TenantMeta

Most objects include a common nested object called TenantMeta. TenantMeta contains the following field:

OSS tenant

There is a common tenant for all OSS projects called oss, to which customers have read access.

Spec

All objects include a common nested object called Spec. This mandatory object contains the specification of the object, representing its current state. For more information, see Resource kinds.

Context

Most objects include a common nested object called Context. Contexts keep objects from different scans separated. The context object has the following fields:

Context types

Each context has a type and an id. For example, objects created during a scan of the default branch belong to the main context, while objects for non-default branches have the context type ref.

Processing status

Project and PackageVersion objects include a common nested object called ProcessingStatus, which contains fields about the processing status of the object (when it was/will be scanned). The processing status object has the following fields:

Scan state

The following scan states are supported:

Example

The following is an example of a Project object:

{
  "meta": {
    "create_time": "2023-12-05T00:04:21.853Z",
    "kind": "Project",
    "name": "https://github.com/my_organization/my_repository.git",
    "update_time": "2024-05-01T16:50:03.830911988Z",
    "version": "v1"
  },
  "processing_status": {
    "analytic_time": "2024-05-01T16:45:06.483972413Z",
    "disable_automated_scan": true,
    "scan_state": "SCAN_STATE_IDLE",
    "scan_time": "2024-03-18T14:38:31.899249002Z"
  },
  "spec": {
    "git": {
      "full_name": "endorlabs/monorepo",
      "git_clone_url": "git@github.com:my_organization/my_repository.git",
      "http_clone_url": "https://github.com/my_organization/my_repository.git",
      "organization": "endorlabs",
      "path": "monorepo",
      "web_url": "https://api.github.com/my_organization/my_repository"
    },
    "internal_reference_key": "https://github.com/my_organization/my_repository.git",
    "platform_source": "PLATFORM_SOURCE_GITHUB"
  },
  "tenant_meta": {
    "namespace": "my_namespace"
  },
  "uuid": "656e69058032bf0abaaeb681"
}

3.2.2 - Resource kinds

Here is an overview diagram of the Endor Labs data model for the most commonly used resource kinds. Lighter shading identifies the objects that are re-computed on every scan.

This section describes the most commonly used resource kinds. For a complete list of supported resource kinds, see the Endor Labs OpenAPI documentation.

All objects contain a reference to the project UUID, either as the parent object (meta.parent_uuid) or a specific field in the object-specific data if the project is not the direct parent (spec.project_uuid if not specified otherwise).

Use the following command to get a list of all objects of a given resource kind in your tenant.

Here are a few useful options:

• --count
• --page-size=1
• --list-all
• --filter="meta.parent_uuid==<uuid>"
• --filter="spec.project_uuid==<uuid>"

endorctl api list -r <resource-kind>

Project

• This is the logical root of all the other information for a given project.
• Contains information about the source code location of a project, such as a Git repository, or a package manager package name.
• Does not have a parent and is not associated with a context.
• The object name is the HTTP clone URL, for example: "https://github.com/definitelytyped/definitelytyped.git".

For more information, see the ProjectService REST API documentation.

Repository

• Contains information about the source code for a project.
• Child of a Project and, just like the Project, does not belong to a context.
• There is at most one Repository per Project, but a Project may not have a Repository if there is no source code.
• The object name is the same as the Project.

For more information, see the RepositoryService REST API documentation.

RepositoryVersion

• Contains information about a specific version of a Repository.
• Has the Project as the parent.
• There are often multiple RepositoryVersions per project.
• Each RepositoryVersion is associated with a Context.
• The object name is the corresponding branch name, tag, or SHA, for example: "main".

For more information, see the RepositoryVersionService REST API documentation.

PackageVersion

• Contains information about a specific version of a package and its dependencies.
• Does not have a parent (for historical reasons), but is associated with a Context and connected to the Project via spec.project_uuid.
• The object name is the corresponding package version name in the format <ecosystem>://<package-name>@<version>, for example: "mvn://org.webjars.npm:types__json-schema@1.2.3".

For more information, see the PackageVersionService REST API documentation.

Resolution errors

Details about any dependency resolution or call graph generation errors for a package version are stored in spec.resolution_errors. There are three categories of resolution errors, each with a separate field that can contain up to one resolution error:

1. Unresolved - Details in spec.resolution_errors.unresolved if there was an error computing the unresolved dependencies.
2. Resolved - Details in spec.resolution_errors.resolved if there was an error resolving the dependency versions.
3. Call graph - Details in spec.resolution_errors.call_graph if there was an error generating the call graph.

Each resolution error has a status_error field and may also contain details about the target, the operation that failed, and a description of the error. The following status errors are supported:

Below is an example resolution error in the Resolved category:

{
  "spec": {
    "resolution_errors": {
      "resolved": {
        "description": "failed to discover dependency: unable to resolve dependencies for 'requirements': unable to get direct dependencies: unable to install modules to extract dependencies: unable to resolve package version: ResolveModuleVersion: error in pypi json api for: torch, exact version: 1.9.0+cpu, err: package not found in the repository: unable to resolve dependency version: unable to discover dependencies, unable to discover dependencies",
        "operation": "python:resolvedDependencies:discover",
        "status_error": "STATUS_ERROR_DEPENDENCY",
        "target": "pypi://requirements@main"
      }
    }
  }
}

DependencyMetadata

• Different from other common resource kinds as it represents the relationship between two PackageVersions: The importer and the dependency.
• There is one DependencyMetadata object for every dependency for every PackageVersion.
• Has the importer PackageVersion as the parent and exists in the same Namespace and Context as the parent.
• The object name is the same as the dependency PackageVersion.
• Combine the object name (meta.name) and the parent UUID (meta.parent_uuid) to get a unique key.
• Connected to the Project via spec.importer_data.project_uuid.
• Details about the relationship are stored in spec.dependency_data, for example:
  • spec.dependency_data.direct
  • spec.dependency_data.reachable
  • spec.dependency_data.scope

For more information, see the DependencyMetadataService REST API documentation.

LinterResult

• Contains the results of scans using 3rd party programs such as gitleaks or Semgrep.
• Has a RepositoryVersion or PackageVersion as the parent.
• Belongs to the same Context as the parent.
• Connected to the Project through spec.project_uuid.
• The object name is the name of the rule that created the result, for example: "gen-shady-links".
• The result origin is stored in spec.origin, for example: "LINTER_RESULT_ORIGIN_SECRETS_SCANNER".

For more information, see the LinterResultService REST API documentation.

Metric

• Contains the output of the analytics processing.
• Has a PackageVersion, RepositoryVersion, or Repository as the parent.
• Belongs to the same Context as the parent.
• Connected to the Project via spec.project_uuid.
• The object name is the name of the analytic that created the metric, for example: "package_version_scorecard".

For more information, see the MetricService REST API documentation.

Metric types

There are many different types of Metrics. The specifics are stored under spec.metric_values.<key>.<value>, for example: spec.metric_values.scorefactor.score_factor_list. Some Metrics have more than one key-value field under spec.metric_values. The following table lists all supported Metric types along with the corresponding paths to the Metric specific data under spec.metric_values.

Finding

• Contains details of a problem that needs to be fixed.
• Has a PackageVersion, RepositoryVersion, or Repository as the parent.
• Belongs to the same Context as the parent.
• Connected to the Project via spec.project_uuid.
• There are many different types of Findings and new types can be created by custom Finding Policies.
• The object name is the Finding type, for example: "outdated_release". For more information, see Finding names and metadata below.
• The object description contains a more specific description of the Finding, for example: "Outdated Dependency @babel/plugin-syntax-async-generators@7.8.4".
• Additional finding type specific data is stored in spec.finding_metadata, for example: spec.finding_metadata.vulnerability.
• PackageVersion Findings often involve both the root PackageVersion and a dependency PackageVersion. The following details about the dependency PackageVersion are available directly in the Finding object:
  • spec.target_dependency_name, for example: "@babel/plugin-syntax-async-generators"
  • spec.target_dependency_package_name, for example: "npm://@babel/plugin-syntax-async-generators@7.8.4"
  • spec.target_dependency_version, for example: "7.8.4"
  • spec.finding_metadata.dependency_package_version_metadata
• The UUID of the DependencyMetadata for the dependency is stored in spec.target_uuid.
• There is one Finding object for every PackageVersion that includes a dependency with a given problem. If 10 PackageVersions include a dependency with a vulnerability then there will be 10 findings for the vulnerability.

For more information, see the FindingService REST API documentation.

Finding names and metadata

The following table lists all supported values for the Finding meta.name field along with an example value for the corresponding meta.description and an explanation.

Finding categories

The following finding categories are supported as possible values in the spec.finding_categories list. All findings must have at least one category.

Finding tags

The following finding tags are supported as possible values in the spec.finding_tags list.

Exceptions

There are two ways that a finding can be exempt from triggering action policies (a.k.a. admission and notification policies).

1. Dismiss finding

   Set the spec.dismiss field to true to exclude the specific finding from action policies. This value persists as long as the finding exists, which is as long as the parent object remains the same. If this is a PackageVersion finding and the root package version number changes, then a new PackageVersion object is created and it gets a new set of findings, so the value of dismiss does not persist.

2. Add an exception policy

   Exception policies allow you to set any criteria you want to mark findings as exempt and can be applied across all projects, a sub-set of projects, or a specific project, within a tenant. Based on the criteria you set, the exception can persist across multiple package versions.

   Findings matched by one or more exception policies have the FINDING_TAGS_EXCEPTION tag and the corresponding policy object uuids are listed under spec.exceptions.policy_uuids.

Action policies

Findings matched by one or more action policies (a.k.a. admission and notification policies) contain the corresponding policy object uuids in spec.actions.policy_uuids. They also carry a tag corresponding to the specific action, for example, FINDING_TAGS_CI_WARNING, FINDING_TAGS_CI_BLOCKER, or FINDING_TAGS_NOTIFICATION.

ScanResult

• Contains details of a scan such as:
  • Configuration
  • Host environment details
  • Runtime statistics
  • Findings
  • Policies triggered
  • Error logs
  • Exit code
  • Scan status
• Has the Project as the parent.
• Belongs to the same Context as the scan.

For more information, see the ScanResultService REST API documentation.

Scan status

The following scan statuses are supported:

3.3 - Filters

Filters allow you to specify a subset of objects to be returned by a request, for example:

• endorctl
• curl
• HTTP

endorctl api list --resource Finding \
  --filter "meta.name==dependency_with_critical_vulnerabilities" \
  --count

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --data-urlencode "list_parameters.filter=meta.name==dependency_with_critical_vulnerabilities" \
  --data-urlencode "list_parameters.count=true" \
  https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=meta.name==dependency_with_critical_vulnerabilities&list_parameters.count=true HTTP/1.1
Authorization: Bearer {{token}}

Keys

A filter key is used to specify the field of the object to match against using a dot-delimited path. For example, given an object:

{
  "uuid": "63ef202d090b62ecf3f6655b",
  "meta": {
    "name": "Example Object",
    "tags": ["dev"]
  },
  "spec": {
    "dependencies": [
      {
        "name": "mvn://org.slf4j:slf4j-api@2.0.0",
      },
      {
        "name": "mvn://ch.qos.logback:logback-access@1.3.0",
      }
    ],
    "version": {
      "ref": "v1.6.333",
      "timestamp": "2024-05-31TT21:04:55.799Z"
    }
  }
}

• uuid specifies the root field with the value "63ef202d090b62ecf3f6655b"
• meta.name specifies the nested field with the value "Example Object"
• meta.tags specifies the nested list field containing the values ["dev"]
• spec.dependencies.name specifies the nested fields within the list with the values: "mvn://org.slf4j:slf4j-api@2.0.0" and "mvn://ch.qos.logback:logback-access@1.3.0"
• spec.version.ref specifies the nested field with the value "v1.6.333"

For more information, see Data model.

Operators

The following filter operators are supported:

Contains

Use contains or not contains to filter on the content of a list field. Multiple values are treated as an OR operation, for example:

• To get all findings for vulnerabilities that have a fix available OR are in a reachable function use:

  spec.finding_tags contains [FINDING_TAGS_FIX_AVAILABLE, FINDING_TAGS_REACHABLE_FUNCTION]

• To get all findings for vulnerabilities that have a fix available AND are in a reachable function use:

  spec.finding_tags contains [FINDING_TAGS_FIX_AVAILABLE] and spec.finding_tags contains [FINDING_TAGS_REACHABLE_FUNCTION]

• To get all projects that do not have the meta tags “sanity” or “test” use:

  meta.tags not contains [sanity, test]

In

Use in or not in to filter on the value of a field against one ore more given values. Multiple values are treated as an OR operation, for example:

• To get all findings with a “Critical” or “High” severity level use:

  spec.finding_level in [FINDING_LEVEL_CRITICAL, FINDING_LEVEL_HIGH]

• To get all findings that are not from the “Maven” or “npm” ecosystems use:

  spec.ecosystem not in [ECOSYSTEM_MAVEN, ECOSYSTEM_NPM]

Matches

Use matches to filter on a regex pattern. Due to the nature of regex evaluation, this is much slower than using for example == or !=. Also due to the nature of regex evaluation, not matches is not supported.

Exists

If a field does not exist then it can’t be equal to anything, so we use exists and not exists instead of != null or == null. This also covers {}, [], etc.

Values

A filter value is used in combination with the operator to match against the values at the specified field.

Use double quotes to escape string or regex values in a filter, for example:

• uuid in ["64a3b8326dda5fb62bfcceea", "658323c91aa208f231cc7eff", "658323c963ca516ef02d1b02"]
• meta.name matches "validation bypass"

NOTE: filters are case-sensitive by default.

To filter with case-insentive values a regex modifier may be used, for example:

• meta.description matches "(?i)django"

Date/Time Values

Use date to encode date values in a filter, for example:

• To filter for objects created after a given date, use a date value with the format YYYY-MM-DD:

  meta.update_time >= date(2024-05-01)

• To filter for objects created between specific times, use a timestamp values with the RFC 3339 format:

  meta.create_time >= date(2024-05-01T13:30:00.000Z) and meta.create_time < date(2024-05-01T23:30:00.000Z)

Use now to encode relative date values in a filter by a given duration offset, for example:

• To filter for objects created in the last 15 minutes, use:

  meta.create_time >= now(-12h)

• To filter for objects created in the last 72 hours, use:

  meta.create_time >= now(-72h)

Combinations

Use and or or to combine multiple filters, for example:

• spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY] and meta.create_time >= date(2024-05-31)
• meta.name==archived_source_code_repo or meta.name==outdated_release

Nesting filters

Multiple filters may also be nested together into a single filter with the use of parentheses (), for example:

• (spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY] and spec.level==FINDING_LEVEL_CRITICAL) or (spec.finding_categories contains [FINDING_CATEGORY_SECRETS] and spec.level in [FINDING_LEVEL_CRITICAL, FINDING_LEVEL_HIGH])

3.4 - Masks

Field masks allow you to specify a subset of fields to be returned for each object by a request. Similar to filter keys, a field-mask key is used to specify 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
• curl
• HTTP

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
• curl

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'

For more information, see the jq documentation.

3.5 - Pagination

About Pagination

When a response from the REST API includes many results, Endor Labs paginates the results and returns a subset of the results. For example, GET /v1/namespaces/{tenant_meta.namespace}/findings only returns 100 findings from the given namespace even if the namespace has more than 100 findings. This makes the response easier to handle for servers and for people.

You can use the additional data from the list response to request additional pages of data.

This article explains how to request additional pages of results for paginated responses and how to change the number of results returned on each page.

Using page_size

The page_size field allows you to control the number of elements returned. By default, this value is 100, with a maximum of 500. It should be noted that the higher this value is, the longer it will take to get a result from Endor Labs.

• endorctl
• curl

endorctl api list --resource Finding \
  --page-size=50

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.page_size=50"

Using page_token

When a response is paginated, the response includes a value for the field next_page_token. This value can then be used to fetch additional pages of results.

For example, the response to the above request contains the first 50 elements in the objects field along with the following values in the response field:

{
  "list": {
    "objects": [
        ...
    ],
    "response": {
      "next_page_id": "633dd86976186a89d64628c1",
      "next_page_token": 50
    }
  }
}

To access the next page of results, you can use the next_page_token value as the value of page_token in the next request. For example:

• endorctl
• curl

endorctl api list --resource Finding \
  --page-size=50 \
  --page-token=50

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.page_size=50&list_parameters.page_token=50"

This returns 50 elements starting from the 50th element in the list. In this case, it returns elements 50 to 100.

Using page_id

The fields page_id and next_page_id provide the same capabilities as page_token and next_page_token. However, we recommend using page_id and next_page_id as they offer better performance for the request.

endorctl and the flag list-all

The CLI endorctl provides the flag --list-all that allows you to fetch all resources. Internally, the command sends multiple requests to get all resources.

endorctl api list --resource Finding --list-all

3.6 - Sorting

Sort allows you to sort objects in ascending (default) or descending order. Similar to filter keys, a sort-path key is used to specify the field to sort the objects by, using a dot-delimited path.

The following example shows how to sort findings based on create time, in descending order:

• endorctl
• curl
• HTTP

endorctl api list --resource Finding \
  --sort-path "meta.create_time" \
  --sort-order descending

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings?list_parameters.sort.path=meta.create_time&list_parameters.sort.order=SORT_ENTRY_ORDER_DESC"

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.sort.path=meta.create_time7list_parameters.sort.order=SORT_ENTRY_ORDER_DESC HTTP/1.1
Authorization: Bearer {{token}}

Sort order

The following sort orders are supported:

• endorctl
• curl / HTTP

3.7 - Grouping

There are many scenarios where it is useful to group the objects returned by the Endor Labs REST API in different ways. Like filter keys, a group-aggregation-paths key is used to specify the field, or fields, by which to group the objects, using a dot-delimited path. For example, the following request returns the count of findings for each severity level:

• endorctl
• curl
• HTTP

endorctl api list --resource Finding \
  --filter "spec.finding_categories contains FINDING_CATEGORY_VULNERABILITY" \
  --group-aggregation-paths "spec.level" \
  --timeout 60s

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Request-Timeout: 60" \
  --data-urlencode "list_parameters.filter=spec.finding_categories contains FINDING_CATEGORY_VULNERABILITY" \
  --data-urlencode "list_parameters.group.aggregation_paths=spec.level" \
  https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings \
  | jq '.'

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter?list_parameters.filter=spec.finding_categories contains FINDING_CATEGORY_VULNERABILITY&list_parameters.group.aggregation_paths=spec.level HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
Request-Timeout: 60

{
  "group_response": {
    "groups": {
      "[{\"key\":\"spec.level\",\"value\":\"FINDING_LEVEL_CRITICAL\"}]": {
        "aggregation_count": {
          "count": 49
        }
      },
      "[{\"key\":\"spec.level\",\"value\":\"FINDING_LEVEL_HIGH\"}]": {
        "aggregation_count": {
          "count": 166
        }
      },
      "[{\"key\":\"spec.level\",\"value\":\"FINDING_LEVEL_LOW\"}]": {
        "aggregation_count": {
          "count": 31
        }
      },
      "[{\"key\":\"spec.level\",\"value\":\"FINDING_LEVEL_MEDIUM\"}]": {
        "aggregation_count": {
          "count": 202
        }
      }
    }
  }
}

Group by path

The following options are available to group objects based on the value of a field in a given path.

• endorctl
• curl / HTTP

Group by path example

Here is an example using all options simultaneously to group package versions by call graph resolution error, list the uuids of the package versions in each group, return the number of different ecosystems of the package versions in each group, and list the different ecosystems of the package versions in each group:

• endorctl
• curl
• HTTP

endorctl api list --resource PackageVersion \
  --filter "spec.resolution_errors.call_graph exists" \
  --group-aggregation-paths "spec.resolution_errors.call_graph.status_error" \
  --group-show-aggregation-uuids \
  --group-unique-count-paths "spec.ecosystem" \
  --group-unique-value-paths "spec.ecosystem" \
  --timeout 60s

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Request-Timeout: 60" \
  --data-urlencode "list_parameters.filter=spec.resolution_errors.call_graph exists" \
  --data-urlencode "list_parameters.group.aggregation_paths=spec.resolution_errors.call_graph.status_error" \
  --data-urlencode "list_parameters.group.show_aggregation_uuids=true" \
  --data-urlencode "list_parameters.group.unique_value_paths=spec.ecosystem" \
  --data-urlencode "list_parameters.group.unique_count_paths=spec.ecosystem" \
  https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/package-versions \
  | jq '.'

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/package-versions?list_parameters.filter?list_parameters.filter=spec.resolution_errors.call_graph exists&list_parameters.group.aggregation_paths=spec.resolution_errors.call_graph.status_error&ist_parameters.group.show_aggregation_uuids=true&list_parameters.group.unique_value_paths=spec.ecosystem&list_parameters.group.unique_count_paths=spec.ecosystem HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
Request-Timeout: 60

{
  "group_response": {
    "groups": {
      "[{\"key\":\"spec.resolution_errors.call_graph.status_error\",\"value\":\"STATUS_ERROR_CALL_GRAPH\"}]": {
        "aggregation_count": {
          "count": 10
        },
        "aggregation_uuids": [
          "6494c13cdcb266d2af02804f",
          "64ace2dd05228d0041488208",
          "64ace2dc05228d00414881eb",
          "64af3a042efc155e48304bf2",
          "65b86b4a0f460309eac456b5",
          "64ace2dc832ee78dd03d85b0",
          "64c190aa17e6bfc2548f7a48",
          "64af39d2bebf530905411327",
          "64c190a817e6bfc2548f7a19",
          "64cc2b68727cd13ec36860c8"
        ],
        "unique_counts": {
          "spec.ecosystem": {
            "count": 2
          }
        },
        "unique_values": {
          "spec.ecosystem": [
            "ECOSYSTEM_MAVEN",
            "ECOSYSTEM_PYPI"
          ]
        }
      },
      "[{\"key\":\"spec.resolution_errors.call_graph.status_error\",\"value\":\"STATUS_ERROR_INTERNAL\"}]": {
        "aggregation_count": {
          "count": 2
        },
        "aggregation_uuids": [
          "6632e2d6b7765d736fac1865",
          "664ba7986fafc782b3cda1f6"
        ],
        "unique_counts": {
          "spec.ecosystem": {
            "count": 1
          }
        },
        "unique_values": {
          "spec.ecosystem": [
            "ECOSYSTEM_NPM"
          ]
        }
      },
      "[{\"key\":\"spec.resolution_errors.call_graph.status_error\",\"value\":\"STATUS_ERROR_MISSING_ARTIFACT\"}]": {
        "aggregation_count": {
          "count": 23
        },
        "aggregation_uuids": [
          "65c3e90ae2dd352a18b6f852",
          "64b99a3b3d5f8dc732555200",
          "64c190a921d68642091aa015",
          "650a2457204ab859367160a2",
          "650a245780113616f95f770e",
          "65d6840edb5cf8c9839c3d47",
          "65e8c21647aae08e2a4e5f5c",
          "64c190a921d68642091aa027",
          "64c190a958d2eff448df09e1",
          "650a2457204ab859367160a6",
          "64c190aa58d2eff448df09f0",
          "64af0879c41c606cbcef6288",
          "64c190ab17e6bfc2548f7a4d",
          "64c190aa17e6bfc2548f7a41",
          "64c190a958d2eff448df09ec",
          "64c190ab21d68642091aa033",
          "64c190ab58d2eff448df09f3",
          "64b99a3b6883c0ec1c456c3a",
          "64c190aa21d68642091aa02f",
          "64b99a3ce3b06b2f8a465bdc",
          "64c190a917e6bfc2548f7a35",
          "64b99a3b6883c0ec1c456c39",
          "650a24573e183ec1be29adc6"
        ],
        "unique_counts": {
          "spec.ecosystem": {
            "count": 1
          }
        },
        "unique_values": {
          "spec.ecosystem": [
            "ECOSYSTEM_MAVEN"
          ]
        }
      },
      "[{\"key\":\"spec.resolution_errors.call_graph.status_error\",\"value\":\"STATUS_ERROR_VENV\"}]": {
        "aggregation_count": {
          "count": 10
        },
        "aggregation_uuids": [
          "64c41863da2fbc7700d12a0e",
          "64c845aca83e181b82ef9041",
          "64dd4f61177264d779e203f3",
          "64c418647146e5738bf0af2d",
          "64c845ac41f581de1a6592d1",
          "64c845ac41f581de1a6592d0",
          "664be4bc6fafc782b363d8e3",
          "652e0bcb1d4d2ceedc87a376",
          "66311e48bf25e232ab24b68c",
          "64d6ce776e5804222a2726de"
        ],
        "unique_counts": {
          "spec.ecosystem": {
            "count": 1
          }
        },
        "unique_values": {
          "spec.ecosystem": [
            "ECOSYSTEM_PYPI"
          ]
        }
      }
    }
  }
}

Group by time

The Endor Labs REST API also provides options to group objects by a given time interval. Common time fields include meta.create_time and meta.update_time, but you can sort objects based on any time field.

For example, to group objects based on create time in 2 week intervals, set the aggregation path to meta.create_time, the time interval to GROUP_BY_TIME_INTERVAL_WEEK and the group size to 2.

The following options are available to group objects based on the value of a time field in a given path:

• curl / HTTP

Time intervals

The following time intervals are supported:

• curl / HTTP

Group by time example

The following example requests the uuids of all critical findings, grouped by create time in two week intervals:

• curl
• HTTP

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Request-Timeout: 60" \
  --data-urlencode "list_parameters.filter=spec.level==FINDING_LEVEL_CRITICAL" \
  --data-urlencode "list_parameters.group_by_time.aggregation_paths=meta.create_time" \
  --data-urlencode "list_parameters.group_by_time.interval=GROUP_BY_TIME_INTERVAL_WEEK" \
  --data-urlencode "list_parameters.group_by_time.group_size=2" \
  --data-urlencode "list_parameters.group_by_time.show_aggregation_uuids=true" \
  https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings \
  | jq '.'

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.level==FINDING_LEVEL_CRITICAL&list_parameters.group_by_time.aggregation_paths=meta.create_time&list_parameters.group_by_time.interval=GROUP_BY_TIME_INTERVAL_WEEK&list_parameters.group_by_time.group_size=2&list_parameters.group_by_time.show_aggregation_uuids=true HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
Request-Timeout: 60

{
  "group_response": {
    "groups": {
      "\"2024-01-28T00:00:00Z\"": {
        "aggregation_count": {
          "count": 7
        },
        "aggregation_uuids": [
          "65c02da021a5d767fc147ec0",
          "65c02da021a5d767fc147ec3",
          "65c02da0aa4b66fa5009eaec",
          "65c02da0056f94b6129aa209",
          "65c02da021a5d767fc147eca",
          "65c02da1aa4b66fa5009eaf9",
          "65c02daa056f94b6129aa46f"
        ],
        "unique_counts": {},
        "unique_values": {}
      },
      "\"2024-03-10T00:00:00Z\"": {
        "aggregation_count": {
          "count": 2
        },
        "aggregation_uuids": [
          "65faf8ec357952c8eda2d36b",
          "65fcdcedd40334d9e0065748"
        ],
        "unique_counts": {},
        "unique_values": {}
      },
      "\"2024-03-24T00:00:00Z\"": {
        "aggregation_count": {
          "count": 2
        },
        "aggregation_uuids": [
          "660728d190fdb066027d07bb",
          "660728d8bddd7358d570ce9c"
        ],
        "unique_counts": {},
        "unique_values": {}
      },
      "\"2024-04-07T00:00:00Z\"": {
        "aggregation_count": {
          "count": 15
        },
        "aggregation_uuids": [
          "6615c531bb58b077e43cbb16",
          "6615c531e2a0c32733a7d50b",
          "6615c531e2a0c32733a7d514",
          "66216bb723ebef7ca3f4571a",
          "66216bb7c28c6f37b51cd0e8",
          "66216bb723ebef7ca3f4571d",
          "66216bc62c21fa9407eda175",
          "66216bc6c28c6f37b51cd2d4",
          "66216bc62c21fa9407eda17b",
          "66216bd72c21fa9407eda210",
          "66216bd823ebef7ca3f459a8",
          "66216bd823ebef7ca3f459ab",
          "66216bd8c28c6f37b51cd381",
          "66216be623ebef7ca3f45a8a",
          "66216be6c28c6f37b51cd465"
        ],
        "unique_counts": {},
        "unique_values": {}
      },
      "\"2024-04-21T00:00:00Z\"": {
        "aggregation_count": {
          "count": 1
        },
        "aggregation_uuids": [
          "66341d55f9aa19f4b730a74c"
        ],
        "unique_counts": {},
        "unique_values": {}
      },
      "\"2024-05-19T00:00:00Z\"": {
        "aggregation_count": {
          "count": 19
        },
        "aggregation_uuids": [
          "664be2cc6fafc782b35fdc89",
          "664be2cc6fafc782b35fdceb",
          "664be2d56fafc782b35ff0d8",
          "664be2d56fafc782b35ff0e0",
          "664be2d5f420988edd47792d",
          "664be2dd67636bf844aedcae",
          "664be2dd6fafc782b36000a8",
          "664be2dd6fafc782b36000aa",
          "664be2ddf420988edd4788eb",
          "664be2e867636bf844aef4e9",
          "664be2e8f420988edd47a140",
          "664be2e8f420988edd47a148",
          "6656ababd2d288f1981ea2ba",
          "6656ababce82b72012f10bbc",
          "6656ababce82b72012f10bbd",
          "6656abab252554c986334a6b",
          "6656ababd2d288f1981ea2bd",
          "6656abab252554c986334a6d",
          "6656abacce82b72012f10bbf"
        ],
        "unique_counts": {},
        "unique_values": {}
      },
      "\"2024-06-02T00:00:00Z\"": {
        "aggregation_count": {
          "count": 5
        },
        "aggregation_uuids": [
          "665fa482c980f9f8157e08c3",
          "6660a9f0e238ad93ad92089e",
          "6660a9f05728ef99cf0c8535",
          "6660a9f0b70974e544ccd05a",
          "6660a9f05728ef99cf0c853f"
        ],
        "unique_counts": {},
        "unique_values": {}
      }
    }
  }
}

3.8 - Best practices

Using endorctl

• Enable tab-completion.
• Use interactive mode for creates and updates.

Optimize queries

• Use field-masks to return only the fields you need.
• Filter on common fields such as uuid or meta.name before resource kind specific fields.

3.9 - Use cases

Get list of projects

• endorctl
• curl
• HTTP

endorctl api list --resource Project

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects"

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/projects HTTP/1.1
Authorization: Bearer {{token}}

Get project UUID

The project UUID connects all the objects for a given project. One way to get the project UUID is to extract it from the uuid field in the Project object. For more information, see Resource kinds.

• endorctl
• curl
• HTTP

endorctl api get --resource Project --name <project-name> | jq '.uuid'

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects?list_parameters.filter=meta.name==<project-name>" \
  | jq '.list.objects[].uuid'

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/projects?list_parameters.filter=meta.name==<project-name> HTTP/1.1
Authorization: Bearer {{token}}

Get list of findings for a project

Use the following filter to get a list of findings for a given project:

spec.project_uuid==<project-uuid>

• endorctl
• curl
• HTTP

endorctl api list --resource Finding --filter "spec.project_uuid==<project-uuid>"

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --data-urlencode "list_parameters.filter=spec.project_uuid==<project-uuid>" \
  https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.project_uuid==<project-uuid> HTTP/1.1
Authorization: Bearer {{token}}

Get list of findings for reachable functions

Use the following filter to get a list of findings for reachable functions:

spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION

For a list of all finding attributes, see Finding tags.

• endorctl
• curl
• HTTP

endorctl api list --resource Finding \
  --filter "spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION"

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --data-urlencode "list_parameters.filter=spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION" \
  https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings

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

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

Get list of findings for reachable functions for a project

Combine the previous filters to get a list of findings for reachable functions for a given project:

spec.project_uuid==<project-uuid> and spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION

• endorctl
• curl
• HTTP

endorctl api list --resource Finding \
  --filter "spec.project_uuid==<project-uuid> and spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION"

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --data-urlencode "list_parameters.filter=spec.project_uuid==<project-uuid> and spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION" \
  https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.project_uuid==<project-uuid> and spec.finding_tags contains FINDING_TAGS_REACHABLE_FUNCTION HTTP/1.1
Authorization: Bearer {{token}}

Get list of findings in a category

Use the following filter to get a list of findings in the RSPM category:

spec.finding_categories contains FINDING_CATEGORY_SCPM

For a list of all finding categories, see Finding categories.

• endorctl
• curl
• HTTP

endorctl api list --resource Finding \
  --filter "spec.finding_categories contains FINDING_CATEGORY_SCPM"

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --data-urlencode "list_parameters.filter=spec.finding_categories contains FINDING_CATEGORY_SCPM" \
  https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/findings?list_parameters.filter=spec.finding_categories contains FINDING_CATEGORY_SCPM HTTP/1.1
Authorization: Bearer {{token}}

Get Endor Labs scores for an OSS package

1. Set the namespace to "oss" as the data for OSS packages are stored in the OSS tenant.

2. Endor Labs scores for package versions are stored in the "package_version_scorecard" Metric object, in the spec.metric_values.scorecard.score_card.category_scores field, so you need to get this Metric object for the given OSS package. For more information, see the Metric resource kind documentation.

3. To get Metric objects belonging to a given package version, get the UUID of the corresponding PackageVersion object. The PackageVersion object name must be in the format <ecosystem>://<name>@<version>, for example: "mvn://ch.qos.logback:logback-core@1.3.3". For more information, see the PackageVersion resource kind documentation. Once you have the PackageVersion object, use the following jq command to extract the UUID:

   jq '.list.object[].uuid'

4. Get the Metric object corresponding to the PackageVersion UUID using the following two filters:

   1. meta.name==package_version_scorecard
   2. meta.parent_uuid==<package-version-uuid>

5. Use the following jq command to extract just the Endor Labs scores from the Metric object:

   jq '.list.objects[].spec.metric_values.scorecard.score_card.category_scores'

• endorctl
• curl
• HTTP

# Get the PackageVersion and extract the uuid
UUID=$(endorctl api list \
  --namespace oss \
  --resource PackageVersion \
  --filter "meta.name==mvn://ch.qos.logback:logback-core@1.3.3" \
  | jq '.list.objects[].uuid')

# Get the Metric and extract the Endor Labs scores
endorctl api list \
  --namespace oss \
  --resource Metric \
  --filter "meta.name==package_version_scorecard and meta.parent_uuid==$UUID" \
  | jq '.list.objects[].spec.metric_values.scorecard.score_card.category_scores'

# Get the PackageVersion and extract the uuid
UUID=$(curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --data-urlencode "list_parameters.filter=meta.name==mvn://ch.qos.logback:logback-core@1.3.3" \
  https://api.endorlabs.com/v1/namespaces/oss/package-versions \
  | jq '.list.objects[].uuid')

# Get the Metric and extract the Endor Labs scores
curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --data-urlencode "list_parameters.filter=meta.name==package_version_scorecard and meta.parent_uuid==$UUID" \
  https://api.endorlabs.com/v1/namespaces/oss/metrics \
  | jq '.list.objects[].spec.metric_values.scorecard.score_card.category_scores'

@baseUrl = https://api.endorlabs.com
@token = <endor-token>

###
GET {{baseUrl}}/v1/namespaces/oss/package-versions?list_parameters.filter=meta.name==mvn://ch.qos.logback:logback-core@1.3.3 HTTP/1.1
Authorization: Bearer {{token}}

###
GET {{baseUrl}}/v1/namespaces/oss/metrics?list_parameters.filter=meta.name==package_version_scorecard and meta.parent_uuid==<package-version-uuid> HTTP/1.1
Authorization: Bearer {{token}}

Below is an example response to the request.

[
  {
    "category": "SCORE_CATEGORY_ACTIVITY",
    "centered_score": 6.956522,
    "description": "Captures the level of activity associated with the repository. Activity information is based on GitHub metadata. Higher levels of activity can mean that the repository is well maintained and will continue to be in the future.",
    "raw_score": 7.0212765,
    "score": 7
  },
  {
    "category": "SCORE_CATEGORY_POPULARITY",
    "centered_score": 8.076923,
    "description": "Captures how popular is the repository. Popularity information is based on GitHub metadata. Popular repositories are more likely to be maintained.",
    "raw_score": 7.368421,
    "score": 9
  },
  {
    "category": "SCORE_CATEGORY_CODE_QUALITY",
    "centered_score": 4.2105265,
    "description": "Provides a view of code quality and adherence to best practices in a repository. This information is based on from both GitHub metadata  and the source code in the repository.",
    "raw_score": 4.848485,
    "score": 4
  },
  {
    "category": "SCORE_CATEGORY_SECURITY",
    "centered_score": 4.7297297,
    "description": "Captures the level of compliance with security best practices as well as vulnerability information for the repository including currently open as well as fixed vulnerabilities.  Analysis only considers vulnerabilities associated with this repository and not its dependencies. Vulnerability information is based on OSV.dev data and Endor's vulnerability database",
    "raw_score": 8.333333,
    "score": 4
  }
]

Get license text from a license finding

1. Look up a license-related Finding object for a dependency using the following filter:

   spec.finding_categories contains [FINDING_CATEGORY_LICENSE_RISK] and spec.finding_tags not contains [FINDING_TAGS_SELF]

2. Get the name of the corresponding PackageVersion object from the spec.target_dependency_package_name field. If we have a list of Finding objects, we can use the following jq command to get the PackageVersion name:

   jq '.list.objects[].spec.target_dependency_package_name'

3. Look up the PackageVersion object and store the UUID.

   Note: If this is an OSS dependency we must use the “oss” namespace.

4. Look up the corresponding pkg_version_info_for_license Metric object using the following filter:

   meta.name==pkg_version_info_for_license&meta.parent_uuid==$UUID

   Note: The Metric is in the same namespace as the PackageVersion.

5. Use the following jq command to extract the license text from the Metric object:

   jq '.list.objects[].spec.metric_values.licenseInfoType.license_info.all_licenses[].matched_text'

For more information, see the Metric resource kind documentation.

• endorctl
• curl

# Get the target dependency PackageVersion name from a license-related finding
NAME=$(endorctl api list --resource Finding \
  --filter "spec.finding_categories contains [FINDING_CATEGORY_LICENSE_RISK] and spec.finding_tags not contains [FINDING_TAGS_SELF]" \
  --page-size 1 \
  | jq '.list.objects[].spec.target_dependency_package_name')

# Get the target dependency PackageVersion uuid
UUID=$(endorctl api list --resource PackageVersion \
  --namespace oss \
  --filter "meta.name==$NAME" \
  | jq '.list.objects[].uuid')

# Get the corresponding pkg_version_info_for_license Metric and extract the license text
endorctl api list --resource Metric \
  --namespace "oss" \
  --filter "meta.name==pkg_version_info_for_license and meta.parent_uuid==$UUID" \
  | jq '.list.objects[].spec.metric_values.licenseInfoType.license_info.all_licenses[].matched_text'

# Get the target dependency PackageVersion name from a license-related finding
NAME=$(curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --data-urlencode "list_parameters.filter=spec.finding_categories contains [FINDING_CATEGORY_LICENSE_RISK] and spec.finding_tags not contains [FINDING_TAGS_SELF]" \
  --data-urlencode "list_parameters.page_size=1" \
  https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings \
  | jq '.list.objects[].spec.target_dependency_package_name')

# Get the target dependency PackageVersion uuid
UUID=$(curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --data-urlencode "list_parameters.filter=meta.name==$NAME" \
  https://api.endorlabs.com/v1/namespaces/oss/package-versions \
  | jq '.list.objects[].uuid')

# Get the corresponding pkg_version_info_for_license Metric and extract the license text
curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --data-urlencode "list_parameters.filter=meta.name==pkg_version_info_for_license and meta.parent_uuid==$UUID" \
  https://api.endorlabs.com/v1/namespaces/oss/metrics \
  | jq '.list.objects[].spec.metric_values.licenseInfoType.license_info.all_licenses[].matched_text'

Get list of projects using a given tool

1. CI/CD tool metrics are stored in the version_cicd_tools Metric object, in the spec.metric_values.CiCdTools.ci_cd_tools.tools list. Use the following filter to get all such Metrics with entries for the given tool name (GitHub Actions in this example). For more information, see the Metric resource kind documentation.

   meta.name==version_cicd_tools and spec.metric_values.CiCdTools.ci_cd_tools.tools.name=='GitHub Actions'

2. Use the following jq command to get the uuids of the corresponding Project objects:

   .list.objects[].spec.project_uuid

3. Remove duplicate Project uuids (a Project can have multiple repository versions).

4. Use the uuids to get the corresponding Project objects.

• endorctl
• curl

# Get list of Project uuids
PROJECT_UUIDS=$(endorctl api list --resource Metric \
  --filter "meta.name==version_cicd_tools and spec.metric_values.CiCdTools.ci_cd_tools.tools.name=='GitHub Actions'" \
  | jq -r '.list.objects[].spec.project_uuid')

# Remove duplicate uuids
UNIQUE_UUIDS=$(echo $PROJECT_UUIDS | sort | uniq)

# Get Project for each uuid and extract the name
for uuid in $UNIQUE_UUIDS
do
  endorctl api get --resource Project --uuid $uuid | jq '.meta.name'
done

# Get list of Project uuids
PROJECT_UUIDS=$(curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --data-urlencode "list_parameters.filter=meta.name==version_cicd_tools and spec.metric_values.CiCdTools.ci_cd_tools.tools.name=='GitHub Actions'" \
  https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/metrics \
  | jq -r '.list.objects[].spec.project_uuid')

# Remove duplicate uuids
UNIQUE_UUIDS=$(echo $PROJECT_UUIDS | sort | uniq)

# Get Project for each uuid and extract the name
for uuid in $UNIQUE_UUIDS
do
  curl --get \
    --header "Authorization: Bearer $ENDOR_TOKEN" \
    --header "Accept-Encoding: gzip, deflate, br, zstd" \
    --url https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects/$uuid \
    | jq '.meta.name'
done

See also List Projects, with Repository Versions and CI/CD Tool Metrics for an example of how to use the Query Service to get the CI/CD tool Metric objects for a list of projects.

Get the latest scan result

1. To get the latest object, first sort the objects in descending order, based on the meta.create_time field:

   list_parameters.sort.order=SORT_ENTRY_ORDER_DESC&list_parameters.sort.path=meta.create_time

2. Then, to get only the latest object, set the page size to 1:

   list_parameters.page_size=1

• endorctl
• curl
• HTTP

endorctl api list --resource ScanResult \
  --sort-order descending \
  --sort-path meta.create_time \
  --page-size=1

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/scan-results?list_parameters.sort.order=SORT_ENTRY_ORDER_DESC&list_parameters.sort.path=meta.create_time&list_parameters.page_size=1"

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/scan-results?list_parameters.sort.order=SORT_ENTRY_ORDER_DESC&list_parameters.sort.path=meta.create_time&list_parameters.page_size=1 HTTP/1.1
Authorization: Bearer {{token}}

Create a policy

The following example uses the Create Policy endpoint to create a new policy.

• endorctl
• curl
• HTTP

endorctl api create --resource Policy \
  --data '{
    "meta": {
      "description": "Disable action policies for CVE-2020-7677",
      "kind": "Policy",
      "name": "Ignore CVE-2020-7677"
    },
    "propagate": true,
    "spec": {
      "exception": {
        "reason": "EXCEPTION_REASON_RISK_ACCEPTED"
      },
      "policy_type": "POLICY_TYPE_EXCEPTION",
      "query_statements": [
        "data.exceptions.match_finding"
      ],
      "resource_kinds": [
        "Finding"
      ],
      "rule": "package exceptions\n\nmatch_finding[result] {\n\tsome i\n  data.resources.Finding[i].spec.finding_metadata.vulnerability.spec.aliases[_] = \"CVE-2020-7677\"\n  result = { \"Endor\" : { \"Finding\" : data.resources.Finding[i].uuid } }\n}"
    },
    "tenant_meta": {
      "namespace": "$ENDOR_NAMESPACE"
    }
  }'

curl --request POST \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/policies" \
  --data '{
    "meta": {
      "description": "Disable action policies for CVE-2020-7677",
      "kind": "Policy",
      "name": "Ignore CVE-2020-7677"
    },
    "propagate": true,
    "spec": {
      "exception": {
        "reason": "EXCEPTION_REASON_RISK_ACCEPTED"
      },
      "policy_type": "POLICY_TYPE_EXCEPTION",
      "query_statements": [
        "data.exceptions.match_finding"
      ],
      "resource_kinds": [
        "Finding"
      ],
      "rule": "package exceptions\n\nmatch_finding[result] {\n\tsome i\n  data.resources.Finding[i].spec.finding_metadata.vulnerability.spec.aliases[_] = \"CVE-2020-7677\"\n  result = { \"Endor\" : { \"Finding\" : data.resources.Finding[i].uuid } }\n}"
    },
    "tenant_meta": {
      "namespace": "$ENDOR_NAMESPACE"
    }
  }' | jq '.'

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

###
POST {{baseUrl}}/v1/namespaces/{{namespace}}/policies HTTP/1.1
Authorization: Bearer {{token}}

{
    "meta": {
        "name": "Detect Apache-2.0 License",
        "description": "Raise findings for dependencies using the Apache-2.0 license"
    },
    "spec": {
        "policy_type": "POLICY_TYPE_USER_FINDING",
        "finding_level": "FINDING_LEVEL_CRITICAL",
        "finding": {
            "explanation": "One or more of the licenses associated with this package or package dependency violates organizational license policy.",
            "external_name": "License Compliance Violation",
            "level": "FINDING_LEVEL_CRITICAL",
            "remediation": "Please consult with legal for further instructions or to request an exception.",
            "summary": "Package uses the \"Apache-2.0\" license."
        },
        "query_statements": [
            "data.license.match_license"
        ],
        "resource_kinds": [
            "Metric",
            "PackageVersion"
        ],
        "rule": "package license\n\nmatch_license[result] {\n  some i\n  data.resources.Metric[i]\n  data.resources.Metric[i].meta.name == \"pkg_version_info_for_license\"\n  data.resources.Metric[i].meta.parent_kind == \"PackageVersion\"\n  lower(data.resources.Metric[i].spec.metric_values.licenseInfoType.license_info.all_licenses[_].name) == lower(\"Apache-2.0\")\n  data.resources.PackageVersion[_].uuid == data.resources.Metric[i].meta.parent_uuid\n\n  result = {\n    \"Endor\": {\n      \"PackageVersion\": data.resources.Metric[i].meta.parent_uuid,\n    }\n  }\n}"
    },
    "tenant_meta": {
      "namespace": "{{namespace}}"
    }
}

Update a policy to include a given project

The following example uses the Update Policy endpoint to apply a policy to a given project by updating the spec.project_selector tag list.

• endorctl
• curl
• HTTP

endorctl api update --resource Policy --uuid <policy-uuid> \
  --field-mask "spec.project_selector" \
  --data '{ "spec" : { "project_selector" : [ "$uuid=<project-uuid>" ] } }'

curl --request PATCH \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/policies" \
  --data '{
    "request" : {
      "update_mask": "spec.project_selector"
    },
    "object" : {
      "uuid" : "<policy-uuid>",
      "spec" : {
        "project_selector": [
          "$uuid=<project-uuid>"
        ]
      }
    }
  }' | jq '.'

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

###
PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/policies HTTP/1.1
Authorization: Bearer {{token}}

{
    "request" : {
      "update_mask": "spec.project_selector"
    },
    "object" : {
      "uuid" : "<policy-uuid>",
      "spec" : {
        "project_selector": [
          "$uuid=<project-uuid>"
        ]
      }
    }
}

Update a policy to exclude a given project

The following example uses the Update Policy endpoint to exclude a given project from a policy by updating the spec.project_exceptions tag list.

• endorctl
• curl
• HTTP

endorctl api update --resource Policy --uuid <policy-uuid> \
  --field-mask "spec.project_exceptions" \
  --data '{ "spec" : { "project_exceptions" : [ "$uuid=<project-uuid>" ] } }'

curl --request PATCH \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/policies" \
  --data '{
    "request" : {
      "update_mask": "spec.project_exceptions"
    },
    "object" : {
      "uuid" : "<policy-uuid>",
      "spec" : {
        "project_exceptions": [
          "$uuid=<project-uuid>"
        ]
      }
    }
  }' | jq '.'

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

###
PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/policies HTTP/1.1
Authorization: Bearer {{token}}

{
    "request" : {
      "update_mask": "spec.project_exceptions"
    },
    "object" : {
      "uuid" : "<policy-uuid>",
      "spec" : {
        "project_exceptions": [
          "$uuid=<project-uuid>"
        ]
      }
    }
}

Upgrade a policy to use the latest template version

The following example uses the Update Policy endpoint to upgrade a given policy to use the latest template version.

• endorctl
• curl
• HTTP

endorctl api update --resource Policy --uuid <policy-uuid> \
  --field-mask "spec.template_version" \
  --data '{ "spec" : { "template_uuid" : "<template-uuid>", "template_version" : "2.0.0" } }'

curl --request PATCH \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/policies" \
  --data '{
    "request" : {
      "update_mask": "spec.template_version"
    },
    "object" : {
      "uuid" : "<policy-uuid>",
      "spec" : {
        "template_uuid" : "<template-uuid>",
        "template_version" : "2.0.0"
      }
    }
  }' | jq '.'

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

###
PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/policies HTTP/1.1
Authorization: Bearer {{token}}

{
    "request" : {
      "update_mask": "spec.template_version"
    },
    "object" : {
      "uuid" : "<policy-uuid>",
      "spec" : {
        "template_uuid" : "<template-uuid>",
        "template_version" : "2.0.0"
      }
    }
}

Delete a policy

The following example uses the Delete Policy endpoint to delete a policy.

• endorctl
• curl
• HTTP

endorctl api delete --resource Policy --uuid <policy-uuid>

curl --request DELETE \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/policies/<policy-uuid>"

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

###
DELETE {{baseUrl}}/v1/namespaces/{{namespace}}/policies/<policy-uuid> HTTP/1.1
Authorization: Bearer {{token}}

Add meta tags to an object

The following example uses the Update Finding endpoint to add custom tags to a finding by updating the meta.tags field.

• endorctl
• curl
• HTTP

endorctl api update --resource Finding --uuid <finding-uuid> \
  --field-mask "meta.tags" \
  --data '{ "meta" : { "tags" : [ "tag1", "tag2", "tag3" ] } }'

curl --request PATCH \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/findings" \
  --data '{
    "request" : {
      "update_mask": "meta.tags"
    },
    "object" : {
      "uuid" : "<finding-uuid>",
      "meta" : {
        "tags": [
          "tag1",
          "tag2",
          "tag3"
        ]
      }
    }
  }' | jq '.'

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

###
PATCH {{baseUrl}}/v1/namespaces/{{namespace}}/findings HTTP/1.1
Authorization: Bearer {{token}}

{
    "request" : {
      "update_mask": "meta.tags"
    },
    "object" : {
      "uuid" : "<finding-uuid>",
      "meta" : {
        "tags": [
          "tag1",
          "tag2",
          "tag3"
        ]
      }
    }
}

Get data from child namespaces

Use the traverse option to include data from child namespaces as well as the parent namespace.

• endorctl
• curl
• HTTP

endorctl api list --resource Project --traverse

curl --get \
  --header "Authorization: Bearer $ENDOR_TOKEN" \
  --header "Accept-Encoding: gzip, deflate, br, zstd" \
  --url "https://api.endorlabs.com/v1/namespaces/$ENDOR_NAMESPACE/projects?list_parameters.traverse=true"

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

###
GET {{baseUrl}}/v1/namespaces/{{namespace}}/projects?list_parameters.traverse=true HTTP/1.1
Authorization: Bearer {{token}}

3.10 - Advanced use cases

3.10.1 - Using the query service

In addition to REST API endpoints for individual Resource Kinds, the Endor Labs REST API exposes a generic graph API capability through the Query Service endpoint. This Query Service may be used to retrieve resources and their related resources in a single call.

Requests for resources through the Query Service are sent with a Query that specifies a Resource Kind and optional list parameters to control the data returned from the request for that resource. The Query may also specify nested references, connecting related Resource Kinds, and returning all corresponding data in the response.

List Projects, with Package Version counts

The following Query returns the number of package versions in the default branch of each project.

1. Request a list of Projects, but only return the uuid, meta.name and processing_status fields for each Project.
2. Connect the Project uuid to the corresponding child PackageVersion spec.project_uuid field.
3. Set additional parameters to filter to only resources from the Project’s default branch, and to return the count of resources.©

• endorctl
• curl
• HTTP

endorctl api create --resource Query \
  --data '{
    "meta": {
      "name": "Projects with Package Version Counts"
    },
    "spec": {
      "query_spec": {
        "kind": "Project",
        "list_parameters": {
          "mask": "uuid,meta.name,processing_status"
        },
        "references": [
          {
            "connect_from": "uuid",
            "connect_to": "spec.project_uuid",
            "query_spec": {
              "kind": "PackageVersion",
              "list_parameters": {
                "filter": "context.type==CONTEXT_TYPE_MAIN",
                "count": true
              }
            }
          }
        ]
      }
    }
  }'

query_data=$(cat << EOF
{
  "meta": {
    "name": "Projects with Package Version Counts"
  },
  "spec": {
    "query_spec": {
      "kind": "Project",
      "list_parameters": {
        "mask": "uuid,meta.name,processing_status"
      },
      "references": [
        {
          "connect_from": "uuid",
          "connect_to": "spec.project_uuid",
          "query_spec": {
            "kind": "PackageVersion",
            "list_parameters": {
              "filter": "context.type==CONTEXT_TYPE_MAIN",
              "count": true
            }
          }
        }
      ]
    }
  },
  "tenant_meta": {
    "namespace": "$ENDOR_NAMESPACE"
  }
}
EOF
)

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

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

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

{
  "meta": {
    "name": "Projects with Package Version Counts"
  },
  "spec": {
    "query_spec": {
      "kind": "Project",
      "list_parameters": {
        "mask": "uuid,meta.name,processing_status"
      },
      "references": [
        {
          "connect_from": "uuid",
          "connect_to": "spec.project_uuid",
          "query_spec": {
            "kind": "PackageVersion",
            "list_parameters": {
              "filter": "context.type==CONTEXT_TYPE_MAIN",
              "count": true
            }
          }
        }
      ]
    }
  },
  "tenant_meta": {
    "namespace": "{{namespace}}"
  }
}

The response for the example above includes the query request that was sent, along with the list response data added under the spec.query_response field.

For each Project in the list response, response data for each reference is added under the meta.references field.

{
  "meta": {
    "name": "Projects with Package Version Counts"
  },
  "spec": {
    "query_spec": {
      "kind": "Project",
      "list_parameters": {
        "mask": "uuid,meta.name,processing_status"
      }
    },
    "query_response": {
      "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListProjectsResponse",
      "list": {
        "objects": [
          {
            "meta": {
              "name": "https://github.com/example/app.git",
              "references": {
                "PackageVersion": {
                  "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListPackageVersionsResponse",
                  "count_response": {
                    "count": 12
                  }
                }
              }
            },
            "processing_status": {
              "analytic_time": "2023-10-28T03:41:40.824366382Z",
              "disable_automated_scan": false,
              "scan_state": "SCAN_STATE_IDLE",
              "scan_time": "2024-06-03T17:43:33.994191285Z"
            },
            "uuid": "633cbce48c4eb448a44d717b"
          },
          {
            "meta": {
              "name": "https://github.com/example/go-uuid.git",
              "references": {
                "PackageVersion": {
                  "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListPackageVersionsResponse",
                  "count_response": {
                    "count": 8
                  }
                }
              }
            },
            "processing_status": {
              "analytic_time": "2023-06-21T02:06:43.081498151Z",
              "disable_automated_scan": false,
              "scan_state": "SCAN_STATE_IDLE",
              "scan_time": "2024-06-03T17:43:47.098976874Z"
            },
            "uuid": "633cbce48c4eb448a44d717e"
          },
          {
            "meta": {
              "name": "https://github.com/example/go-lru.git",
              "references": {
                "PackageVersion": {
                  "@type": "type.googleapis.com/internal.endor.ai.endor.v1.ListPackageVersionsResponse",
                  "count_response": {
                    "count": 28
                  }
                }
              }
            },
            "processing_status": {
              "analytic_time": "2023-06-21T02:08:44.727640782Z",
              "disable_automated_scan": false,
              "scan_state": "SCAN_STATE_IDLE",
              "scan_time": "2024-06-03T17:43:52.028934453Z"
            },
            "uuid": "633cbce48c4eb448a44d7181"
          }
        ],
        "response": {
          "next_page_token": null
        }
      }
    }
  }
}

List Projects, with Repository Versions and CI/CD Tool Metrics

The following Query requests a list of Projects, with a reference for the related RepositoryVersion resources for the default branch, and the corresponding CI/CD tool Metric resources.

1. Request a list of Projects, but only return the uuid and meta.name fields for each Project.
2. Connect the Project uuid to the corresponding child RepositoryVersion meta.parent_uuid field.
3. Set additional parameters to filter to only resources from the Project’s default branch, and an additional nested reference for Metric objects related to the RepositoryVersions, with a filter to return only Metrics for the CI/CD tools.

• endorctl
• curl
• HTTP

endorctl api create --resource Query \
  --data '{
    "meta": {
      "name": "Projects with RepositoryVersions and CI/CD Tool Metrics"
    },
    "spec": {
      "query_spec": {
        "kind": "Project",
        "list_parameters": {
          "mask": "uuid,meta.name"
        },
        "references": [
          {
            "connect_from": "uuid",
            "connect_to": "meta.parent_uuid",
            "query_spec": {
              "kind": "RepositoryVersion",
              "list_parameters": {
                "filter": "context.type==CONTEXT_TYPE_MAIN",
                "mask": "uuid,meta.name,scan_object"
              },
              "references": [
                {
                  "connect_from": "uuid",
                  "connect_to": "meta.parent_uuid",
                  "query_spec": {
                    "kind": "Metric",
                    "list_parameters": {
                      "filter": "spec.analytic==\"version_cicd_tools\""
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    }
  }'

query_data=$(cat << EOF
{
  "meta": {
    "name": "Projects with RepositoryVersions and CI/CD Tool Metrics"
  },
  "spec": {
    "query_spec": {
      "kind": "Project",
      "list_parameters": {
        "mask": "uuid,meta.name"
      },
      "references": [
        {
          "connect_from": "uuid",
          "connect_to": "meta.parent_uuid",
          "query_spec": {
            "kind": "RepositoryVersion",
            "list_parameters": {
              "filter": "context.type==CONTEXT_TYPE_MAIN",
              "mask": "uuid,meta.name,scan_object"
            },
            "references": [
              {
                "connect_from": "uuid",
                "connect_to": "meta.parent_uuid",
                "query_spec": {
                  "kind": "Metric",
                  "list_parameters": {
                    "filter": "spec.analytic==\"version_cicd_tools\""
                  }
                }
              }
            ]
          }
        }
      ]
    }
  },
  "tenant_meta": {
    "namespace": "$ENDOR_NAMESPACE"
  }
}
EOF
)

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

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

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

{
  "meta": {
    "name": "Projects with RepositoryVersions and CI/CD Tool Metrics"
  },
  "spec": {
    "query_spec": {
      "kind": "Project",
      "list_parameters": {
        "mask": "uuid,meta.name"
      },
      "references": [
        {
          "connect_from": "uuid",
          "connect_to": "meta.parent_uuid",
          "query_spec": {
            "kind": "RepositoryVersion",
            "list_parameters": {
              "filter": "context.type==CONTEXT_TYPE_MAIN",
              "mask": "uuid,meta.name,scan_object"
            },
            "references": [
              {
                "connect_from": "uuid",
                "connect_to": "meta.parent_uuid",
                "query_spec": {
                  "kind": "Metric",
                  "list_parameters": {
                    "filter": "spec.analytic==\"version_cicd_tools\""
                  }
                }
              }
            ]
          }
        }
      ]
    }
  },
  "tenant_meta": {
    "namespace": "{{namespace}}"
  }
}