This is the multi-page printable view of this section. Click here to print.
Commands
- 1: api
- 2: artifact sign
- 3: completion
- 4: help
- 5: host-check
- 6: init
- 7: sbom
- 8: scan
- 9: sync-org
- 10: validate policy
- 11: 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:
Flag | Environment Variable | Description |
---|---|---|
data |
ENDOR_API_DATA |
Define the object you want to create or update in json format. |
field-mask |
ENDOR_API_FIELD_MASK |
Specify a list of fields to return or update. |
header |
ENDOR_API_HEADER |
Specify request header information in the following format: key:value |
interactive |
ENDOR_API_INTERACTIVE |
Create or update an object interactively. Requires the environment variable EDITOR to be set (for example, export EDITOR=vim ). |
name |
ENDOR_API_NAME |
Specify the name of the resource that you want to interact with. |
output-type |
ENDOR_API_OUTPUT_TYPE |
Specify the output format of the response. The default output type is json , but can also be set to yaml or table . |
resource |
ENDOR_API_RESOURCE |
Specify the resource type that you want to interact with. See commonly used resource types below for a list of supported resource types. |
timeout |
ENDOR_API_TIMEOUT |
Set the timeout limit for the command. The default is 20s , but larger or more complex requests might need additional time, which might lead to a “context deadline exceeded” error. |
| uuid
| ENDOR_API_UUID
| Specify the UUID of the resource that you want to interact with. |
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.
Resource Kind | Description |
---|---|
Project |
A project represents a configuration for ingesting source control repositories. List all projects by calling endorctl api list -r Project . |
Repository |
A repository represents information about a source control repository where source code is hosted. List all repositories for a project by filtering on meta.parent_uuid==<project-uuid> . |
RepositoryVersion |
A repository version represents information about a specific version of code in source control, such as commit SHAs, tags or branches. List all repository versions for a project by filtering on meta.parent_uuid==<project-uuid> . |
PackageVersion |
A package version represents information about a named version of a package. List all package versions for a project by filtering on spec.project_uuid==<project-uuid> . |
DependencyMetadata |
A dependency metadata object represents the relationship between the root package version (importer) and a given dependency. List all dependency metadata objects for a project by filtering on spec.importer_data.project_uuid==<project-uuid> . |
Metric |
A metric object contains the output of a given analytic. List all metric objects for a project by filtering on spec.project_uuid==<project-uuid> . |
Finding |
A finding represents a result of an evaluation method used to evaluate code against a rule. List all findings for a project by filtering on spec.project_uuid==<project-uuid> . |
ScanResult |
A scan result contains metadata about a particular scan (configuration, results etc.). List all scan results for a project by filtering on meta.parent_uuid==<project-uuid> . |
AuthorizationPolicy |
An authorization policy represents a policy for access control. List all authorization policies by calling endorctl api list -r AuthorizationPolicy . |
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 andexport EDITOR=code
opens the file with the code command in VS Code.
- Define your editor using
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:
Flag | Environment Variable | Description |
---|---|---|
count |
ENDOR_API_COUNT |
Get the number of items in the list. |
filter |
ENDOR_API_FILTER |
Specify query parameters used to filter resources. |
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-id |
ENDOR_API_PAGE_ID |
Set the page id to start from. |
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. |
sort-order |
ENDOR_API_SORT_ORDER |
Sort resources in the specified order, ascending or descending (default ascending ). |
sort-path |
ENDOR_API_SORT_PATH |
Specify a field to sort resources by. |
traverse |
ENDOR_API_TRAVERSE |
Get data from any child namespaces as well. |
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 andexport EDITOR=code
opens the file with the code command in VS Code.
- Define your editor using
Examples
To interactively update a project with the UUID 6549886f0dd828140b4a477b:
endorctl api update -r Project -i --uuid 6549886f0dd828140b4a477b
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
artifact sign
command to sign container images and build artifacts in the CI pipeline.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
Flags | Environment Variables | Description |
---|---|---|
--name string |
ENDOR_ARTIFACT_NAME |
Name of the artifact. For example, ghcr.io/org/image@sha256:digest . |
--build-config-digest string |
ENDOR_ARTIFACT_BUILD_CONFIG_DIGEST |
Specific version of top-level/initiating build instructions. For example, workflow sha . |
--build-config-name |
ENDOR_ARTIFACT_BUILD_CONFIG_NAME |
Name of top-level/initiating build instructions. For example, workflow . |
--certificate-oidc-issuer |
ENDOR_ARTIFACT_CERTIFICATE_OIDC_ISSUER |
Name of the OIDC issuer present in a valid certificate. |
--certificate-identity |
ENDOR_ARTIFACT_CERTIFICATE_IDENTITY |
Name of the identity present in a valid certificate. |
--runner-environment string |
ENDOR_ARTIFACT_RUNNER_ENVIRONMENT |
Name of platform-hosted or self-hosted infrastructure. For example, self-hosted . |
--source-repository string |
ENDOR_ARTIFACT_SOURCE_REPOSITORY |
Source repository that the build was based upon. For example, org/repo . |
--source-repository-digest string |
ENDOR_ARTIFACT_SOURCE_REPOSITORY_DIGEST |
Specific version of the source code that the build was based upon. For example, commit sha . |
--source-repository-owner string |
ENDOR_ARTIFACT_SOURCE_REPOSITORY_OWNER |
Owner of the source repository that the build was based upon. For example, my-org . |
--source-repository-ref string (mandatory) |
ENDOR_ARTIFACT_SOURCE_REPOSITORY_REF |
Source repository ref that the build run was based upon. |
For endorctl artifact verify
Flags | Environment Variables | Description |
---|---|---|
--name <name> |
ENDOR_ARTIFACT_NAME |
The name of the artifact to verify. |
--certificate-oidc-issuer <issuer> |
ENDOR_ARTIFACT_CERTIFICATE_OIDC_ISSUER |
The issuer of the OIDC certificate used for verification. |
For endorctl artifact [revoke-signature ]
Flags | Environment Variables | Description |
---|---|---|
--name string |
ENDOR_ARTIFACT_NAME |
The name of the artifact whose signature needs to be revoked. |
--source-repository-ref string (mandatory) |
ENDOR_ARTIFACT_SOURCE_REPOSITORY_REF |
Reference to the source repository of the artifact. |
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:
-
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 ```
-
Navigate to the root of the repository you’ve cloned:
```shell cd ./app-java-demo ```
-
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:
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 . |
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:
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:
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.
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. |
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
Flag | Environment Variable | Description |
---|---|---|
format |
ENDOR_SBOM_FORMAT |
Set the SBOM format (cyclonedx , or SPDX ) (default cyclonedx ) |
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
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 document. |
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:
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
Flag | Environment Variable | Description |
---|---|---|
format |
ENDOR_SBOM_FORMAT |
Set the SBOM format (cyclonedx , or SPDX ) (default cyclonedx ) |
sbom-file-path |
ENDOR_SBOM_FILE_PATH |
Set the file path to the SBOM to import. |
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:
Flag | Environment Variable | Description |
---|---|---|
as-default-branch |
ENDOR_SCAN_AS_DEFAULT_BRANCH |
Set this as the default branch. |
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-targets-query |
ENDOR_SCAN_BAZEL_TARGETS |
Set this variable to query for a list of Bazel targets to include in a scan. |
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 value is: [go , java , python , rust ]). |
container |
ENDOR_SCAN_CONTAINER |
Set this to the container image:tag to perform a scan on containers. |
container-as-ref |
ENDOR_SCAN_CONTAINER_AS_REF |
Scan container in a persistent context and keep the version. Use the --project-name argument to specify the name of the project and --path argument to specify its path. |
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-path |
ENDOR_SCAN_EXCLUDE_PATH |
Specify one or more file paths or directories to exclude from the scan using Glob style expressions. For example, --exclude-path="src/java/**" will exclude all files under src/java , including any sub-directories, while --exclude-path="src/java/*" will only exclude the files directly under src/java . Paths must be relative to the root of the repository. Use quotes to ensure that your shell does not expand wild cards. |
exit-on-policy-warning |
ENDOR_SCAN_EXIT_ON_POLICY_WARNING |
Return a non-zero exit code if there are policy violation warnings. |
ghactions |
ENDOR_SCAN_GHACTIONS |
Scan and discover GitHub action workflows in your CI/CD pipeline. |
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-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. |
github |
ENDOR_SCAN_GITHUB |
Fetch information from GitHub and generate findings for any GitHub misconfigurations (see also SCPM policies). |
include-path |
ENDOR_SCAN_INCLUDE_PATH |
Limit the scan to the specified file paths or directories using Glob style expressions. For example, --include-path="src/java/**" will scan all the files under src/java , including any sub-directories, while --include-path="src/java/*" will only include the files directly under src/java . Paths must be relative to the root of the repository. Use quotes to ensure that your shell does not expand wild cards. |
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 table ) |
package |
ENDOR_SCAN_PACKAGE |
Scan binaries and artifacts. You must provide the path of your file using --path and specify a name for your project using --project-name parameters. |
path |
ENDOR_SCAN_PATH |
Set the path to the repository to scan on the local filesystem. Example: --path=/Users/endorlabs/github/myrepo . |
pnpm |
ENDOR_PNPM_ENABLED |
Set to true to scan and detect dependencies for JavaScript projects that use PNPM package manager. |
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 . |
pr-incremental |
ENDOR_SCAN_PR_INCREMENTAL |
Only scan packages with dependencies that have changed compared to the baseline scan. Must be set together with --pr-baseline or --enable-pr-comments . |
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. |
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 . |
project-name |
ENDOR_SCAN_PROJECT_NAME |
Give a name for the project while scanning binaries and artifacts. It is used with the --package parameter. |
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. |
tools |
ENDOR_SCAN_TOOLS |
Scan source code repository for CI/CD tools. To include GitHub application data you must also set the --github flag and provide a GitHub token with read:org access. |
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. * Make sure that mvn install -U is successful and include mvn dependency and mvn help plugins in the local m2 cache. For Gradle complete gradle assemble --refresh-dependencies . |
uuid |
ENDOR_SCAN_UUID |
Scan the specified project UUID. |
install-build-tools |
ENDOR_SCAN_INSTALL_BUILD_TOOLS |
Install build tools in a runtime sandbox. |
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
andread: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:
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. |
10 - 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:
Flag | Environment Variable | Description |
---|---|---|
filter |
ENDOR_VALIDATE_POLICY_PROJECT_FILTER |
Filter projects to load data from. For example, "meta.tags contains sanity" . |
input |
ENDOR_VALIDATE_POLICY_INPUT_FILE_PATH |
Path to a json file containing the input parameter values, if applicable. Input parameters are sometimes used for policy templates. |
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 file containing the policies to be validated. Supported formats: Text (plain Rego rules), json (one or more policies), or yaml (one or more policies or policy templates). |
policy-uuid |
ENDOR_VALIDATE_POLICY_UUID |
UUIDs of policies to be validated. |
pr-baseline |
ENDOR_VALIDATE_POLICY_PR_BASELINE |
Name of the baseline version from which to load data. For example, main . |
pr-uuid |
ENDOR_VALIDATE_POLICY_PR_UUID |
PR scan from which to load data. |
query |
ENDOR_VALIDATE_POLICY_QUERY_STATEMENTS |
Query statements for this policy (for example, data.packagename.match_finding ). This option is only needed for plain text Rego rules. |
resource-kinds |
ENDOR_VALIDATE_POLICY_RESOURCE_KINDS |
Resource kinds required by this policy (for example, PackageVersion,Metric ). This option is only needed for plain text Rego rules. |
uuid |
ENDOR_VALIDATE_POLICY_PROJECT_UUID |
UUID of the project from which to load data. |
Specify one or more policies
Use one of the following formats to specify one or more policies:
Input format | Description |
---|---|
Plain text Rego | Provide the file path to a file containing just the Rego rules. The query statement is provided as a separate parameter. For example, endorctl validate policy --policy policy.txt --query data.example.match_package_version_score . |
json | Provide the file path to a json file containing one or more Policy objects (see Policy , Policies , and ListPoliciesResponse ). For example, endorctl validate policy --policy policy.json . |
yaml | Provide the file path to a yaml file containing one or more policy or policy template definitions (see Policies and PolicyTemplates ). For example, endorctl validate policy --policy policy.yaml . |
UUID | Provide one or more UUIDs of existing Policy objects. For example, endorctl validate policy --policy-uuid 6418dc7a55afcfb7b0d0e025 . |
Specify a project or a project filter
Use one of the following formats to specify one or more projects from which to load data:
Input format | Description |
---|---|
Filter | Load data from all projects matching a given filter. For example, endorctl validate policy --policy policy.rego --query data.example.match_package_version_score --filter "meta.tags contains release" . |
UUID | Provide the UUID of the project from which to load data. For example, endorctl validate policy --policy-uuid 6418dc7a55afcfb7b0d0e025 --uuid 6699c827cd89accb3a017536 . |
PR UUID | Provide the UUID of a PR from which to load data. Add the baseline version name to match only new findings. For example, endorctl validate policy --policy-uuid 6418dc7a55afcfb7b0d0e025 --uuid 6699c827cd89accb3a017536 --pr-uuid 43064105-1fd7-42fe-a380-bd5e36657d39 --pr-baseline main . |
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:
Value | Exit Code Name | Description |
---|---|---|
3 | ENDORCTL_RC_INVALID_ARGS | An invalid argument was provided. |
18 | ENDORCTL_RC_POLICY_ERROR | There was an error evaluating one or more policies. See log for details. |
128 | ENDORCTL_RC_POLICY_VIOLATION | One or more policies had matching findings for the given projects. |
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.
-
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]) } }
-
Next, validate that the policy is correctly formatted.
endorctl validate policy \ --policy test_policy.rego \ --query data.example.match_package_version_score
-
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
-
Inspect the policy output.
{ "matching_resources": { "6553132357b462874261f054": { "Policy 1": { "PackageVersion": [ { "resource_name": "pypi://astunparse@1.6.3", "result": { "None": [ { "Score": "6" } ] } },
11 - 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:
- 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')
- Execute the recommend dependency-upgrades command.
endorctl recommend dependency-upgrades --project-uuid=$UUID
To recommend dependency updates across a specific package in your namespace:
- 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')
- 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.
Flag | Environment Variable | Description |
---|---|---|
package-version-uuid |
ENDOR_RECOMMEND_PACKAGE_VERSION_UUID |
Set the UUID of the package version for which you want to recommend dependency upgrades. |
project-uuid |
ENDOR_RECOMMEND_PROJECT_UUID |
Set to the UUID of the project to recommend dependency upgrades for. |
persist |
N/A | Enable to persist upgrade recommendations to Endor Labs. |