endorctl sub-commands, flags and variables

Learn how to use and customize endorctl.

Endorctl is a command-line tool that allows you to scan and monitor your projects, import and export SBOMs, and interact with the API.

Use the following endorctl sub-commands, flags and/or environment variables to interact with your Endor Labs tenant and integrate it into your CI pipeline.

Each command-line flag has a corresponding environment variable that can be set instead of the flag, either directly in your environment or in a dedicated configuration file. See config-path description in Global Flags and Variables and Working with endorctl Environment Variables below for details.

To set a command-line flag on a sub-command you can specify the flag with a leading -- for full flag names or a leading - for short flag aliases. If applicable, input arguments are specified after the flag and separated from it with either a blank space or a = character. For example, to set the output-type specify --output-type json or -o=json. If the input argument is a list, then the list elements are separated by a , character, for example --languages=go,python.

endorctl sub-commands

Use the following commands to interact with endorctl:

  • api — Interact with the Endor Labs API

  • completion — Generate the autocompletion script for a specified shell

  • help — Help about any command

  • host-check — Validate host machine environment and configuration

  • init — Initialize or reinitialize endorctl

  • sbom — Import and Export SBOMs and VEXs

  • scan — Scan a source code repository

  • sync-org — Creates projects for all the repositories of the specified organization in GitHub.

  • validate — Validate a policy

Global flags and variables

The following Global flags are supported and configurable for any endorctl command:

Flag Environment Variable Description
api ENDOR_API Set the API URL for the Endor Labs Application (default https://api.endorlabs.com).
api-key ENDOR_API_CREDENTIALS_KEY Set the API key used to authenticate with Endor Labs.
api-secret ENDOR_API_CREDENTIALS_SECRET Set the secret corresponding to the API key used to authenticate with Endor Labs.
aws-role-arn ENDOR_AWS_CREDENTIALS_ROLE_ARN Set the target role ARN for AWS based authentication. AWS authentication is only enabled if this flag is set. See our AWS Keyless Authentication Docs for details.
bypass-host-check ENDOR_BYPASS_HOST_CHECK Bypass the check that verifies that the host machine is correctly setup to use endorctl.
config-path ENDOR_CONFIG_PATH Set the local filesystem path to the endor config directory containing your endor environment variables. By default set to $HOME/.endorctl/config.yaml.
enable-github-action-token ENDOR_GITHUB_ACTION_TOKEN_ENABLE Enable keyless authentication using Github action OIDC tokens. See the GitHub documentation on configuring OpenID Connect in cloud providers for details.
gcp-service-account ENDOR_GCP_CREDENTIALS_SERVICE_ACCOUNT Set the target service account for GCP based authentication. GCP authentication is only enabled if this flag is set.
log-level ENDOR_LOG_LEVEL Set the log level. Set to debug for debug logs. See also the --verbose flag.
namespace ENDOR_NAMESPACE Set to the namespace of the project that you are working with.
token ENDOR_TOKEN Set the authentication token used to authenticate with Endor Labs.
verbose ENDOR_LOG_VERBOSE Enable verbose logging.
version Display the endorctl client version.

endorctl init flags and variables

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

Flag Environment Variable Description
auth-mode ENDOR_INIT_AUTH_MODE Set authentication method for the initialization process (github, google, gitlab, or azureadv2).
headless-mode ENDOR_INIT_HEADLESS_MODE Run authentication and initialization without opening your browser.

endorctl host-check flags and variables

Verify that the host is appropriately configured to ensure successful execution of endorctl scans.

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

Flag Environment Variable Description
auth-check-only ENDOR_HOST_CHECK_AUTH_CHECK_ONLY Validate authentication credentials only.
droid-gpt ENDOR_HOST_CHECK_DROID_GPT Use DroidGPT to generate remediation advice.
path ENDOR_HOST_CHECK_PATH Set the path to the repository to scan on the local filesystem. Example: --path=/Users/endorlabs/github/myrepo.

endorctl scan flags and variables

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

Flag Environment Variable Description
as-default-branch ENDOR_SCAN_AS_DEFAULT_BRANCH Set this as the default branch.
bazel-targets-query ENDOR_SCAN_BAZEL_TARGETS Set this variable to query for a list of Bazel targets to include in a scan.
bazel-exclude-targets ENDOR_SCAN_BAZEL_EXCLUDE_TARGETS Set this variable to exclude a list of Bazel targets included in a provided Bazel query.
bazel-include-targets ENDOR_SCAN_AS_INCLUDE_TARGETS Set this variable to perform a scan on a list of targets using Bazel. Only the specified list of targets are scanned. If you do not specify bazel-include-targets, you must use identify targets using bazel-targets-query. If you specify targets, then the results from bazel-targets-query are ignored.
bazel-workspace-path ENDOR_SCAN_BAZEL_WORKSPACE_PATH Set this variable to specify the path of the Bazel workspace.
build ENDOR_SCAN_BUILD Enable the scan to build the project if needed.
call-graph-languages ENDOR_SCAN_CALLGRAPH_LANGUAGES Set programming languages for call graph generation (go, java, python, rust) (default [go,java,python,rust]).
dependencies ENDOR_SCAN_DEPENDENCIES Scan git commits and generate findings for all dependencies.
detached-ref-name ENDOR_SCAN_DETACHED_REF_NAME Set the name of the git reference to a user-provided name. Example: --detached-ref-name="$CI_DEFAULT_BRANCH". Use with CI environments that checkout commits, such as GitLab.
disable-private-package-analysis ENDOR_SCAN_DISABLE_PRIVATE_PACKAGE_ANALYSIS Disable the call graph analysis of private dependencies that are not part of the repository.
droid-gpt ENDOR_SCAN_DROID_GPT Use DroidGPT to interpret build errors and generate remediation advice.
exclude ENDOR_SCAN_EXCLUDE Set to a regex pattern such as ‘foo.*’ to exclude any files or directories, in the scan path, that match this pattern. For example, --exclude='*.py' will ignore the following: foo.py, src/foo.py, foo.py/bar.sh; and --exclude='tests' will ignore tests/foo.py as well as a/b/tests/c/foo.py. See also --include and --languages.
exit-on-policy-warning ENDOR_SCAN_EXIT_ON_POLICY_WARNING Return a non-zero exit code if there are policy violation warnings.
git-logs ENDOR_SCAN_GIT_LOGS Audit the historical git logs of the repository for all branches in the repository. Must be used together with --secrets.
github ENDOR_SCAN_GITHUB Fetch information from GitHub, scan git commits and generate findings for all dependencies, as well as any GitHub misconfigurations.
github-api-url GITHUB_API_URL Set the GitHub API URL used for API requests to Github Enterprise Cloud or GitHub Enterprise Server. This flag must be used for self-hosted source control systems such as GitHub Enterprise Server. (default https://api.github.com/)
github-ca-path GITHUB_CA_PATH Set the path to the CA certificate used by GitHub Enterprise Server if it is untrusted by your system.
github-token GITHUB_TOKEN Set the GitHub token used to authenticate with GitHub.
include ENDOR_SCAN_INCLUDE Set to a regex pattern to only scan files and directories, in the scan path, that match this pattern. For example, --include=src/bar will only scan files under src/bar. Note that there must be a manifest file at the root of the include directory for the scan to be successful. See also --exclude and --languages.
languages ENDOR_SCAN_LANGUAGES Set programming languages to scan. Used to limit scan to specific languages.
output-type ENDOR_SCAN_SUMMARY_OUTPUT_TYPE Set output format (json, yaml, table, or summary). Use summary to only display policy violations and not all findings. (default json)
path ENDOR_SCAN_PATH Set the path to the repository to scan on the local filesystem. Example: --path=/Users/endorlabs/github/myrepo.
pr ENDOR_SCAN_PR Set if this is a PR scan. PR scans are not used for reporting or monitoring and should be treated as point in time policy and finding test.
pr-baseline ENDOR_SCAN_PR_BASELINE Set to the git reference that you are merging to, such as your default branch. Action policies will only flag issues that do not exist in the baseline so that developers are only alerted to issues on the current changes. Example: --pr-baseline=main.
pre-commit-checks ENDOR_SCAN_PRE_COMMIT_CHECKS Perform Git pre-commit checks on the changeset about to be committed. Must be used together with --secrets.
quick-scan ENDOR_SCAN_QUICK_SCAN Perform a quick scan without call graph generation.
registries ENDOR_SCAN_REGISTRIES Registries that must be used in addition to public or namespace registries. Format: "user:password@ecosystem://registry#priority".
repository-http-clone-url ENDOR_SCAN_GITHUB_REPOSITORY_HTTP_CLONE_URL Set the GitHub repository http clone URL for --github scans.
sarif-file ENDOR_SCAN_SUMMARY_SARIF_FILE Set the path to a SARIF file to save the finding result summary to.
secrets ENDOR_SCAN_SECRETS Scan source code repository and generate findings for leaked secrets. See also --git-logs and --pre-commit-checks.
tags ENDOR_SCAN_TAGS Specify a list of user-defined tags to add to this scan. Tags can be used to search and filter scans later.
use-bazel ENDOR_SCAN_USE_BAZEL Uses Bazel to perform the endorctl scan.
use-local-repo-cache ENDOR_SCAN_USE_LOCAL_CACHE Uses the local cache for dependency resolution.
uuid ENDOR_SCAN_UUID Scan the specified project uuid.
pnpm ENDOR_PNPM_ENABLED Set to true to scan and detect dependencies for JavaScript projects that use PNPM package manager.

endorctl sync-org flags and variables

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

Flag Environment Variable Description
name ENDOR_SYNC_ORG_NAME Set the full name of the organization. Example: endorlabs
github-api-url ENDOR_SYNC_ORG_GITHUB_API_URL Set the URL for API requests to GitHub Enterprise Cloud or GitHub Enterprise Server (default https://api.github.com/).
platform-source ENDOR_SYNC_ORG_GITHUB_API_URL Set the platform source (default github).
uuid ENDOR_SYNC_ORG_UUID Set the uuid of the github installation.

endorctl api flags and variables

The endorctl api command allows users to interact directly with the Endor Labs API. See the API command for more details on using the Endor Labs API.

The following flags and environment variables are configurable for any endorctl api sub-command:

Flag Environment Variable Description
data ENDOR_API_DATA Set data to create or update in json format.
field-mask ENDOR_API_FIELD_MASK Set list of fields to return or update.
filter ENDOR_API_FILTER Set result filter.
header ENDOR_API_HEADER Set request header information in the following format: key:value
interactive ENDOR_API_INTERACTIVE Create or update the object interactively.
name ENDOR_API_NAME Set resource name.
output-type ENDOR_API_OUTPUT_TYPE Set output format (json, yaml, or table) (default json)
resource ENDOR_API_RESOURCE Set resource type. See API queries for more information on resource types. Example: --resource=Project
timeout ENDOR_API_TIMEOUT Set request timeout (default 20s). Example: --timeout=30s
uuid ENDOR_API_UUID Set resource uuid.

endorctl api sub-commands

  • create — Create a specified resource
  • delete — Delete a specified resource
  • get — Get a specified resource
  • list — List a specified group of resources
  • update — Update a specified resource

endorctl api list flags and variables

List a specified group of resources.

The endorctl api list command uses the following additional environment variables:

Flag Environment Variable Description
count ENDOR_API_COUNT Get the number of items in the list.
group-aggregation-paths ENDOR_API_GROUP_AGGREGATION_PATHS Specify one or more fields to group resources by.
group-show-aggregation-uuids ENDOR_API_GROUP_SHOW_AGGREGATION_UUIDS Get the uuids of the resources in each group as specified by --group-aggregation-paths.
group-unique-count-paths ENDOR_API_GROUP_UNIQUE_COUNT_PATHS Count the number of unique values, for these fields, in the group.
group-unique-value-paths ENDOR_API_GROUP_UNIQUE_VALUE_PATHS Get the unique values, for these fields, in the group.
list-all ENDOR_API_LIST_ALL List all resources (use -t/--timeout to increase timeout for big queries).
page-size ENDOR_API_PAGE_SIZE Set the page size to limit the number of results returned (default 100).
page-token ENDOR_API_PAGE_TOKEN Set the page token to start from.
pr-uuid ENDOR_API_PR_UUID Only list resources from a specific PR scan.
traverse ENDOR_API_TRAVERSE Get data from any child namespaces as well.

endorctl completion

Generate the autocompletion script for a specified shell.

endorctl sbom flags and variables

The following flags and environment variables are configurable for any endorctl sbom sub-command:

Flag Environment Variable Description
format ENDOR_SBOM_FORMAT Set the SBOM format (cyclonedx, or SPDX) (default cyclonedx)

endorctl sbom sub-commands

  • import — Import an SBOM
  • export — Generate and export an SBOM and, if applicable, the corresponding VEX

endorctl sbom export flags and variables

Export an SBOM per the specified options, including a VEX if the --with-vex flag is provided.

The endorctl sbom export command uses the following additional environment variables:

Flag Environment Variable Description
component-type ENDOR_SBOM_COMPONENT_TYPE Set the SBOM component type (application, or library). (default application)
output-format ENDOR_SBOM_OUTPUT_FORMAT Set the SBOM format (json, or xml) (default json).
package-version-name ENDOR_SBOM_PACKAGE_VERSION_NAME Name of the package version to create an SBOM for.
package-version-uuid ENDOR_SBOM_PACKAGE_VERSION_UUID UUID of the package version to create an SBOM for.
timeout ENDOR_SBOM_TIMEOUT Set the timeout for the SBOM generation (default 30s).
with-vex ENDOR_SBOM_WITH_VEX Also generate the corresponding VEX.

endorctl sbom import flags and variables

Import an SBOM.

The endorctl sbom import command uses the following additional environment variables:

Flag Environment Variable Description
sbom-file-path ENDOR_SBOM_FILE_PATH Set the file path to the SBOM to import.

endorctl validate

Validate a policy.

endorctl validate sub-commands

  • policy — Validate a specified Rego policy or policy template.

endorctl validate policy flags and variables

Validate a Rego policy against data for a specified project. Policies can be specified in a plain text file (.txt), as an endorpb.Policy object in json (.json), or as one or more endorpb.PolicyTemplate objects in a yaml file (.yaml). Matched findings are displayed per the specified output format (default table). Use --verbose and log-level=debug for detailed feedback.

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

Flag Environment Variable Description
input ENDOR_VALIDATE_POLICY_INPUT_FILE_PATH Path to a json file containing the input parameter values, if applicable.
output-type ENDOR_VALIDATE_POLICY_SUMMARY_OUTPUT_TYPE Set output format (json, yaml, or table) (default table).
policy ENDOR_VALIDATE_POLICY_FILE_PATH Path to a text (plain Rego rule), json (one Policy), or yaml (one or more Policies or PolicyTemplates) file containing the policy(ies) to be validated.
pr-baseline ENDOR_VALIDATE_POLICY_PR_BASELINE Name of baseline version to load data from.
pr-uuid ENDOR_VALIDATE_POLICY_PR_UUID PR scan to load data from.
query ENDOR_VALIDATE_POLICY_QUERY_STATEMENTS Query statement for this policy (e.g. data.packagename.allow) - Only needed for plain text Rego rules.
resource-kinds ENDOR_VALIDATE_POLICY_RESOURCE_KINDS Resource kinds required by this policy (e.g. PackageVersion,Metric) - Only needed for plain text Rego rules.
uuid ENDOR_VALIDATE_POLICY_PROJECT_UUID UUID of project to load data from.

Working with endorctl environment variables

Setting environment variables

To set an environment variable run the following command:

export <environment variable>=<value>

For example to set the environment variable ENDOR_TOKEN to “mytoken” run the following command:

export ENDOR_TOKEN=mytoken