Commands

• 1: api
• 1.1: create
• 1.2: delete
• 1.3: get
• 1.4: list
• 1.5: update
• 2: artifact sign
• 3: completion
• 4: help
• 5: host-check
• 6: init
• 7: sbom
• 7.1: export
• 7.2: import
• 8: scan
• 9: sync-org
• 10: toolchains
• 11: validate policy
• 12: recommend

1 - api

The endorctl api command allows you to interact with the Endor Labs API directly through the command line interface.

Usage

The syntax of the endorctl api command is:

endorctl api [subcommand] [flags]

The following subcommands are supported:

• create creates a specified object in a namespace.
• delete deletes a specified object in a namespace.
• get gets a specified object in a namespace.
• list lists a specified group of objects in a namespace.
• update updates a specified object in a namespace.

Flags and variables

The following flags are supported for all endorctl api subcommands, unless specified otherwise:

Commonly used resource types

The following table lists resource types that are commonly used in the API. For more information, see the resource kind documentation.

1.1 - create

Usage

The endorctl api create command creates an object of a specified resource type.

endorctl api create -r [resource] [flags]

Interactive Mode

• Use --interactive or -i to create an object with an interactive code editor.
  • Define your editor using export EDITOR=<editor> where the editor is defined as the command used to edit files. For example, export EDITOR=vi allows you to edit in vi and export EDITOR=code opens the file with the code command in VS Code.

Examples

To create a package manager integration that uses the repository https://example.replaceme.com for dependency resolution in Python with the top priority for dependency resolution use the following command:

endorctl api create -r PackageManager \
    --data '{"meta":{"name":"pypi PackageManager"},"spec":{"pypi":{"url":"https://example.replaceme.com ","priority":0}}}'

1.2 - delete

Usage

The endorctl api delete command deletes a given object of a specified resource type.

endorctl api delete -r [resource] [flags]

Examples

Use the following command to delete the project with the UUID, ‘62aa1cfadfa47d9ccb754d22’, that is no longer needed.

endorctl api delete -r Project --uuid 62aa1cfadfa47d9ccb754d22

1.3 - get

Usage

The endorctl api get command retrieves a given object of a specified resource type.

endorctl api get -r [resource] [flags]

Examples

• Get a specific project by its UUID:

endorctl api get -r Project --uuid <UUID>

• Get a specific package version:

endorctl api get --resource "PackageVersion" --name "<ecosystem>://<name>@<version>"

1.4 - list

Usage

The endorctl api list command lists all objects of a specified resource type, based on the specified filters, field-masks and/or other options.

endorctl api list -r [resource] [flags]

Flags and variables

The endorctl api list command supports the following additional flags and environment variables:

Examples

Use the --filter flag to customize your query and the --field-mask flag to limit the fields returned. For example, run the following command to list the description and the target dependency name for all findings in a given project:

endorctl api list \
  --resource Finding \
  --filter "spec.project_uuid==<uuid>" \
  --field-mask "meta.description,spec.target_dependency_package_name"

For more information on filters and field-masks, see Filters. and Masks.

Useful API commands

• Get a count of the number of projects hosted in your Endor Labs tenant:

endorctl api list \
  --resource Project \
  --count \
  | jq -r '.count_response.count'

• List all projects in the namespace and only return the name of each project:

endorctl api list \
  --resource Project \
  --list-all \
  --field-mask meta.name \
  | jq '.list.objects[].meta.name'

• List all package versions at a given source code Git reference:

endorctl api list \
  --resource "PackageVersion" \
  --output-type "yaml" \
  --filter "spec.project_uuid==<uuid> and spec.source_code_reference.version.ref==<git-reference>"

• List all direct dependencies of a specific package given its UUID.

endorctl api list \
  --resource DependencyMetadata \
  --filter "spec.importer_data.package_version_uuid==<UUID> and spec.dependency_data.direct==true"

• Return a count of findings associated with the default branch for a given project:

endorctl api list \
  --resource Finding \
  --filter "context.type==CONTEXT_TYPE_MAIN and spec.project_uuid==<project-uuid>" \
  --count

• Return a count of unique vulnerabilities found in non-test dependencies where there is an upstream patch available and the function associated with the vulnerability is reachable in the context of the application for a given project:

endorctl api list \
  --resource Finding \
  --filter "context.type==CONTEXT_TYPE_MAIN and spec.project_uuid==<project-uuid> and spec.finding_categories contains [FINDING_CATEGORY_VULNERABILITY] and spec.finding_tags contains [FINDING_TAGS_NORMAL] and spec.finding_tags contains [FINDING_TAGS_REACHABLE_FUNCTION] and spec.finding_tags contains [FINDING_TAGS_FIX_AVAILABLE]" \
  --group-aggregation-paths "spec.finding_metadata.vulnerability.meta.name"

• Return the count of the number of scans run on the default branch since a given point in time:

endorctl api list \
  --resource ScanResult \
  --filter "context.id==default and meta.create_time >= date(2023-11-14)" \
  --count

For more examples, see Use cases.

1.5 - update

Usage

endorctl api update -r [resource] [flags]

Interactive Mode

• Use --interactive or -i to update an object with an interactive code editor.
  • Define your editor using export EDITOR=<editor> where the editor is defined as the command used to edit files. For example, export EDITOR=vi allows you to edit in vi and export EDITOR=code opens the file with the code command in VS Code.
  • Specify which fields you want to update using the --field-mask parameter. If this is not set, endorctl will try to update all fields.

Examples

To interactively update a project with the UUID 6549886f0dd828140b4a477b:

endorctl api update -r Project -i --uuid 6549886f0dd828140b4a477b --field-mask meta.tags

To add a tag “CrownJewel” to a project named https://github.com/endorlabs/github-action use the following command:

endorctl api update -r Project \
  --name https://github.com/endorlabs/github-action \
  --data "{ \"meta\": {\"tags\": [ \"CrownJewel\" ] }}" \
  --field-mask 'meta.tags'

2 - artifact sign

Use the artifact [ sign \| verify ] command to sign and verify container images and other build artifacts.

Usage

To sign an artifact, use the following command:

endorctl artifact sign --name <artifact> --source-repository-ref <ref> --certificate-oidc-issuer <issuer>

To verify a signed artifact, use the following command:

endorctl verify --name <artifact> --certificate-oidc-issuer <issuer>`

To revoke a signature, use the following command:

endorctl artifact revoke-signature --name <artifact> --source-repository-ref <ref>

Options

You can use the following flags and environment variables:

For endorctl artifact sign

For endorctl artifact verify

For endorctl artifact [revoke-signature ]

3 - completion

The completion command for endorctl outputs a completion script that may be added to your local environment. Once run this script will enable tab autocompletion for endorctl.

Supported command completion environments are Zsh, PowerShell, bash and fish.

Command completion for Zsh shells

To enable command completion for a macOS based Zsh environment:

echo "source $(endorctl completion zsh)" >> ~/.zshrc
source ~/.zshrc

You will need to start a new shell for this setup to take effect.

Command completion for bash shells

To enable command completion for a Linux bash based shell:

echo "source $(endorctl completion zsh)" >> ~/.bashrc
source ~/.bashrc

You will need to start a new shell for this setup to take effect.

Command completion for PowerShell

To load completions in your current shell session:

endorctl completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your PowerShell profile.

Command completion for Fish shells

To load completions in your current shell session:

endorctl completion fish | source

To load completions for every new session, execute once:

endorctl completion fish > ~/.config/fish/completions/endorctl.fish

You will need to start a new shell for this setup to take effect.

Usage

There are no flags that apply to endorctl completion.

4 - help

The help command lists all available commands for endorctl scan.

Examples

endorctl help

Usage

endorctl help
Endorctl is a command-line tool that allows you to scan and monitor your projects, import and export SBOMs, and interact with the API. Using endorctl you can connect to your Endor Labs tenant and integrate it into your CI pipeline.

Usage:
  endorctl [flags]
  endorctl [command]

Available Commands:
  api         Interact with the Endor Labs API
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  host-check  Validate host machine environment and configuration
  init        Initialize or reinitialize endorctl
  recommend   Recommendations for dependency maintenance
  sbom        SBOM operations
  scan        Scan a source code repository
  sync-org    Sync GitHub repositories for a specified organization
  validate    Validate a policy

Flags:
  -a, --api string                   Set the API URL for the Endor Labs Application (default "https://api.endorlabs.com")
      --api-key string               Set the API key used to authenticate with Endor Labs
      --api-secret string            Set the secret corresponding to the API key used to authenticate with Endor Labs
      --aws-role-arn string          Set the target role ARN for AWS based authentication. AWS authentication is only enabled if this flag is set
      --bypass-host-check            Bypass the check that verifies that the host machine is correctly setup to use endorctl
      --config-path string           Set the local filesystem path to the endor config directory containing your endor environment variables
      --enable-github-action-token   Enable keyless authentication using Github action OIDC tokens
      --gcp-service-account string   Set the target service account for GCP based authentication. GCP authentication is only enabled if this flag is set
  -h, --help                         help for endorctl
      --log-level string             Set the log level (default "info")
  -n, --namespace string             Set to the namespace of the project that you are working with
      --pre-commit-checks            Perform Git pre-commit checks on the changeset about to be committed
      --token string                 Set the authentication token used to authenticate with Endor Labs
      --verbose                      Enable verbose logging
  -v, --version                      version for endorctl

Use "endorctl [command] --help" for more information about a command.

5 - host-check

The command endorctl host-check allows you to quickly verify if your system is setup with the appropriate tools to perform a successful scan.

Usage

To verify that your local host is appropriately configured to scan a given repository:

1. Clone the repository you’d like to verify system setup for. The following instructions should be updated to the repository of your selection.

    ```shell
    git clone https://github.com/endorlabs/app-java-demo.git
    ```
   

2. Navigate to the root of the repository you’ve cloned:

    ```shell
    cd ./app-java-demo
    ```
   

3. Run the host check command:

    ```shell
    endorctl host-check
    ```
   

To verify that your local host is appropriately configured with AI recommendations on how to address any issues perform the following procedure and add the --droid-gpt flag to the host check command:

    ```shell
    endorctl host-check --droid-gpt
    ```

Options

The endorctl host-check command uses the following flags and environment variables:

6 - init

The command endorctl init allows you to quickly authenticate your client to Endor Labs using an external identity provider.

Supported authentication providers for endorctl init are:

• google - Used to create an API key and API key secret when you sign in with Google Workspaces as your external identity provider.
• github - Used to create an API key and API key secret when you sign in with GitHub Cloud as your external identity provider.
• gitlab - Used to create an API key and API key secret when you sign in with GitLab Cloud as your external identity provider.
• email - Used to create an API key and API key secret when you sign in with an email link.
• sso - Used to sign in with a Custom Enterprise Identity Provider, such as Okta.

Usage

To login with your supported authentication provider:

• Google
• GitHub
• GitLab
• Email
• SSO

endorctl init --auth-mode=google

endorctl init --auth-mode=github

endorctl init --auth-mode=gitlab

endorctl init --auth-email=<insert_email_address>

endorctl init --auth-mode=sso --auth-tenant=<insert-your-tenant>

To login with your supported authentication provider in environments without a browser you can use headless mode:

• Google
• GitHub
• GitLab
• Email
• SSO

endorctl init --auth-mode=google --headless-mode

endorctl init --auth-mode=github --headless-mode

endorctl init --auth-mode=gitlab --headless-mode

endorctl init --auth-email=<insert_email_address> --headless-mode

endorctl init --auth-mode=sso --auth-tenant=<insert-your-tenant> --headless-mode

Once you’ve issued the command in headless mode please navigate to an internet/browser accessible computer and follow the instructions provided in your terminal.

Options

The following flags and environment variables are available for the init command.

7 - sbom

The endorctl sbom command allows you to import or export SBOMs to or from Endor Labs.

Usage

The syntax of endorctl sbom is as follows:

endorctl sbom [subcommand] [flags]

The following subcommands are supported as part of endorctl api:

• endorctl sbom import imports an SBOM to be managed by Endor Labs.
• endorctl sbom export allows you to export an SBOM from Endor Labs.

Options

7.1 - export

The sbom export command allows you to export an SBOM for a specified package from Endor Labs.

Usage

To export an SBOM for a specified package version named go://github.com/Dreamacro/clash@main in Endor Labs.

endorctl sbom export --package-version-name=go://github.com/Dreamacro/clash@main

To export an SBOM for a specified package version given its UUID with the UUID of “653c625cd44ec559e19349dc” to a file called “sbom.json”

endorctl sbom export --package-version-uuid=653c625cd44ec559e19349dc >> sbom.json

Options

7.2 - import

The sbom import command allows you to import SBOMs to Endor Labs to track your third party risk.

Usage

To import an SBOM to Endor Labs use the following command:

• CycloneDX Format
• SPDX Format

endorctl sbom import --sbom-file-path=/path/to/your/sbom.json

endorctl sbom import --format=spdx --sbom-file-path=/path/to/your/sbom.json

Options

8 - scan

Use the scan command to perform scans against a repository.

Usage

To perform a full scan including reachability analysis for the open source software of the packages you build in a repository and monitor the checked out version of your code run the command:

endorctl scan

To scan leaked secrets and monitor all results in the checked out version of your repository:

endorctl scan --secrets

To scan for leaked secrets in all branches of your repository use the command:

endorctl scan --secrets --git-logs

To scan for misconfigurations in a GitHub repository (i.e https://github.com/endorlabs/app-java-demo):

export GITHUB_TOKEN=<insert-your-github-token>
endorctl scan --github --repository-http-clone-url=https://github.com/endorlabs/app-java-demo

To scan for CI/CD tools run the following command:

export GITHUB_TOKEN=<insert-your-github-token-with-read:org-access>
endorctl scan --tools --github

To include GitHub application data you must also set the --github flag and provide a GitHub token with read:org access.

To run a scan as a test in a pull request without monitoring the version of your code over time run the command:

endorctl scan --pr

To scan and discover GitHub action workflows (Beta) in your CI/CD pipeline run the command:

endorctl scan --ghactions

Along with performing the regular dependency analysis on your repository, it discovers the GitHub actions configured in your CI/CD pipeline and maps them as GitHub action dependencies in your package.

To scan binaries and artifacts run the following command:

endorctl scan --package --path --project-name

You must provide the path of your file using --path and specify a name for your project using --project-name.

Options

The command endorctl scan uses the following flags and environment variables:

9 - sync-org

Use the endorctl sync-org command to create projects for all the unscanned repositories in your GitHub organization. This does not automatically scan the projects. It creates projects in Endor Labs, measures scan coverage across a GitHub organization, and gives you visibility into your source control repository.

Usage

To sync your GitHub organization to Endor Labs:

• Export a GitHub token that can read all projects in your GitHub organization. To run the sync-org command you need at least repo and read:org permissions.

export GITHUB_TOKEN=<insert-github-token>

• Run the sync-org command

endorctl sync-org --name=endorlabs

Options

The endorctl sync-org command uses the following flags and environment variables:

10 - toolchains

Use the endorctl toolchains command to detect the current tools used in your repository. You can also create a scan profile.

Usage

• Use the help argument to see the options associated with toolchains command.

endorctl toolchains --help

Detect tools in your repository

Use endorctl detect to identify the tools currently used in your repository. The following arguments can help you refine your scan:

• Use the -p argument to define the local filesystem path to the repository you want to scan.

endorctl toolchains detect -p <path_to_repository>

• Use the --exclude-path argument to exclude specific file paths or directories.

endorctl toolchains detect -p <path_to_repository> --exclude-path 'python/**'

• Use the --include-path argument to limit the scan to a specific file path or directory.

endorctl toolchains detect -p <path_to_repository> --include-path 'developement/**'

Create a scan profile

Use endorctl generate to create a scan profile. See Manage build tools for more details.

• Use the profile-name argument to assign a name to your profile. This command creates a .endorctl/scanprofile.yaml file with the tools in the repository.

endorctl toolchains generate -p <path_to_repository>  --profile-name <profile-name>

• Use the output-type argument to specify the format of the output file.

endorctl toolchains generate -p <path_to_repository> --profile-name <profile-name> --output-type <output-type>

• Use the --output-path argument to set the location where the output file will be saved.

endorctl toolchains generate -p <path_to_repository> --profile-name <profile-name> --output-type json --output-path <output-path>

• Use the --create-profile argument to create and save the scan profile using the specified options.

endorctl toolchains generate -p <path_to_repository> --profile-name <profile-name> --create-profile

Options

The endorctl toolchains command uses the following flags and environment variables:

11 - validate policy

Usage

Use the command endorctl validate policy to validate one or more policies against data from one or more projects. If the policy is valid, the command returns all matches for the given projects, in the requested format, with the corresponding exit code.

endorctl validate policy [policies] [flags]

Flags and variables

The endorctl validate policy command uses the following flags and environment variables:

Specify one or more policies

Use one of the following formats to specify one or more policies:

Specify a project or a project filter

Use one of the following formats to specify one or more projects from which to load data:

Specify output format

As with the other endorctl commands, you can specify if you prefer the output as a table, or in json or yaml format. If the output format is json or yaml the matching findings are listed under "matching_findings" and the results for all other resource kinds are listed under "matching_resources".

For example, endorctl validate policy --policy-uuid 6418dc7a55afcfb7b0d0e025 --uuid 6699c827cd89accb3a017536 --output-type json.

Exit Codes

If the policy is valid and there are no matches the command returns 0. The following table lists the non-zero exit codes returned by the endorctl validate policy command:

For a complete list of endorctl exit codes, see endorctl CLI exit codes.

Example

Below is an example on how to verify that a Rego policy is correctly formatted.

1. First, define a Rego policy. Let’s take the example policy below that searches for dependencies with an Endor Labs overall score of less than 7. You can save this to a file called “test_policy.rego”.

   package example
   
   match_package_version_score[result] {
     some i
     data.resources.Metric[i].meta.name == "package_version_scorecard"
     data.resources.Metric[i].meta.parent_kind == "PackageVersion"
     data.resources.Metric[i].meta.parent_uuid == data.resources.PackageVersion[_].uuid
     score := data.resources.Metric[i].spec.metric_values.scorecard.score_card.overall_score
     score < 7
   
     result = {
       "Endor" : {
         "PackageVersion" : data.resources.Metric[i].meta.parent_uuid
       },
       "Score" : sprintf("%v", [score])
     }
   }
   

2. Next, validate that the policy is correctly formatted.

   endorctl validate policy \
     --policy test_policy.rego \
     --query data.example.match_package_version_score
   

3. Add a project UUID to validate the policy against real data.

   endorctl validate policy \
     --policy test_policy.rego \
     --query data.example.match_package_version_score \
     --uuid $PROJECT_UUID \
     --output-type json > output.json
   

4. Inspect the policy output.

   {
     "matching_resources": {
       "6553132357b462874261f054": {
         "Policy 1": {
           "PackageVersion": [
             {
               "resource_name": "pypi://astunparse@1.6.3",
               "resource_uuid": "63f599e177cf1f3d7f286ea1",
               "result": {
                 "None": [
                   {
                     "Score": "6"
                   }
                 ]
               }
             },
   

Troubleshooting

• Set --output-type to json or yaml for formatted output
• Add the --verbose flag for detailed output
• Set --log-level debug for more information

12 - recommend

The command endorctl recommend fetches prioritized and recommended updates to address findings across your tenant, projects, or packages. All recommendations are based on the number of issues and complexity of a given upgrade.

Usage

To recommend dependency updates across all projects in your namespace:

endorctl recommend dependency-upgrades

To recommend dependency updates across a specific project in your namespace:

1. First, retrieve the UUID of your project. In the following example, we are retrieving the UUID of the project “https://github.com/endorlabs/app-java-demo” and saving it as an environment variable.

UUID=$(endorctl api list -r Project --filter="meta.name matches https://github.com/endorlabs/app-java-demo" --field-mask=uuid | jq -r '.list.objects[].uuid')

2. Execute the recommend dependency-upgrades command.

endorctl recommend dependency-upgrades --project-uuid=$UUID

To recommend dependency updates across a specific package in your namespace:

1. Retrieve the UUID of your package version. The following example looks for a project with the name “https://github.com/endorlabs/app-java-demo” and saves it as an environment variable.

UUID=$(endorctl api list -r PackageVersion --filter="meta.name==mvn://com.endor.webapp:endor-java-webapp-demo@4.0-SNAPSHOT AND context.type==CONTEXT_TYPE_MAIN" --field-mask=uuid | jq -r '.list.objects[].uuid')

2. Execute the recommend dependency-upgrades command

endorctl recommend dependency-upgrades --package-version-uuid=$UUID

Options

The following flags and environment variables are available for the init command.