Skip to main content
Buildkite runs CI/CD pipelines on agents that you host. Use the Endor Labs Buildkite plugin to scan your code from any Buildkite step. The plugin runs as a single Buildkite post-command hook. Your step’s command runs first, then the plugin installs endorctl, authenticates to Endor Labs, and runs the scan. The plugin supports the same scan options and outputs as the Endor Labs GitHub Action. To integrate Endor Labs into your Buildkite pipelines:
  1. Install the plugin
  2. Authenticate to Endor Labs
  3. Configure your pipeline

​
Before you begin

Ensure that you complete the following prerequisites before you proceed.
  • Have the value of your Endor Labs tenant namespace handy.
  • Generate an Endor Labs API key and secret, or use a cloud identity for keyless authentication. See Managing API keys to create credentials.
  • Install jq on your agents if you turn on build annotations.
  • On Windows agents, install Git Bash. The plugin hooks delegate to Bash.
The plugin installs endorctl only. Install your build toolchain, such as Java, Node.js, or Bazel, on the agent image or in your step’s command.

​
Install the plugin

You can vendor the plugin into your repository or reference the public Git repository in your pipeline. Vendoring gives you a reviewed, pinned copy that also works in air-gapped environments.

​
Vendor the plugin

  1. Clone the plugin repository at the latest release tag. 
    git clone --depth 1 --branch <release-tag> \
  https://github.com/endorlabs/endorlabs-buildkite-plugin.git /tmp/endorlabs-buildkite-plugin
  2. Copy the sync script into your repository. 
    cp /tmp/endorlabs-buildkite-plugin/scripts/sync-vendor-endorlabs-plugin.sh scripts/
  3. Run the sync script from your repository root. 
    ENDORLABS_PLUGIN_SRC=/tmp/endorlabs-buildkite-plugin ./scripts/sync-vendor-endorlabs-plugin.sh
    The script copies the plugin runtime files into .buildkite/vendor/endorlabs-buildkite-plugin and writes a VENDOR_SOURCE.json record with the source commit.
  4. Commit the vendored plugin and the sync script. 
    git add scripts/sync-vendor-endorlabs-plugin.sh .buildkite/vendor/endorlabs-buildkite-plugin
  5. Reference the vendored plugin in your pipeline steps. 
    plugins:
  - ./.buildkite/vendor/endorlabs-buildkite-plugin:
      namespace: "${ENDOR_NAMESPACE}"
To update the plugin, run the sync script again from a newer checkout and commit the changes.

​
Reference the public Git repository

Reference the plugin directly from GitHub, pinned to a release tag. Copy the current pinned reference from the card above. 
plugins:
  - https://github.com/endorlabs/endorlabs-buildkite-plugin.git#<release-tag>:
      namespace: "${ENDOR_NAMESPACE}"

​
Authenticate to Endor Labs

The plugin reads credentials from environment variables on the agent. You pass the variable names, not the values, so secrets never appear in your pipeline YAML or on the endorctl command line.

​
Use API credentials

Store your credentials as Buildkite cluster secrets:
  1. In Buildkite, go to Agents > your cluster > Secrets.
  2. Create a secret named ENDOR_API_CREDENTIALS_KEY with your API key as the value.
  3. Create a secret named ENDOR_API_CREDENTIALS_SECRET with your API key secret as the value.
  4. Optional: Create a secret named ENDOR_NAMESPACE with your tenant namespace to keep it out of your pipeline YAML.
Expose the secrets to your build and pass the variable names to the plugin: 
secrets:
  - ENDOR_NAMESPACE
  - ENDOR_API_CREDENTIALS_KEY
  - ENDOR_API_CREDENTIALS_SECRET

steps:
  - label: "Build and scan"
    command: "make build"
    plugins:
      - ./.buildkite/vendor/endorlabs-buildkite-plugin:
          namespace: "${ENDOR_NAMESPACE}"
          api_key_env: ENDOR_API_CREDENTIALS_KEY
          api_secret_env: ENDOR_API_CREDENTIALS_SECRET
For more information, refer to Buildkite cluster secrets.

​
Use keyless authentication

If your agents run in AWS, GCP, or Azure, you can authenticate without storing Endor Labs API credentials:
  • Set aws_role_arn on agents with ambient AWS credentials, such as an EC2 instance profile or EKS IRSA.
  • Set gcp_service_account to your Endor Labs federation service account on GCP agents.
  • Set enable_azure_managed_identity: true on Azure agents with a managed identity.
Each cloud option is mutually exclusive with API credentials. See Keyless authentication to set up an authorization policy for your cloud identity.
endorctl doesn’t accept Buildkite OIDC tokens for authentication, and GitHub keyless authentication works only in GitHub Actions. On Buildkite, use API credentials or cloud keyless authentication on the agent.
Buildkite agents can issue OIDC tokens with buildkite-agent oidc to federate with cloud providers. On AWS, you can exchange that token for AWS credentials and then set aws_role_arn, so the AWS identity authenticates to Endor Labs. For more information, refer to OIDC with AWS in Buildkite.

​
Configure your pipeline

The following example builds a project and scans it for dependency and secrets findings, with a build annotation for the results. 
secrets:
  - ENDOR_NAMESPACE
  - ENDOR_API_CREDENTIALS_KEY
  - ENDOR_API_CREDENTIALS_SECRET

steps:
  - label: ":hammer: Build and scan"
    command: "mvn clean install"
    plugins:
      - ./.buildkite/vendor/endorlabs-buildkite-plugin:
          namespace: "${ENDOR_NAMESPACE}"
          api_key_env: ENDOR_API_CREDENTIALS_KEY
          api_secret_env: ENDOR_API_CREDENTIALS_SECRET
          scan_dependencies: true
          scan_secrets: true
          annotate: true
Customize the example for your project:
  1. Replace command with your project’s build steps. The scan starts after the command completes.
  2. Replace the plugin reference with the pinned public Git reference if you don’t vendor the plugin.
  3. Turn on the scan types you need, such as scan_sast or scan_secrets.
To verify the integration, run the pipeline and confirm that the build log shows Running endorctl scan.

​
Set up PR scans and branch tracking

The plugin reads the Buildkite build environment and passes branch and pull request context to endorctl automatically: Buildkite agents often check out commits in a detached HEAD state. You don’t need to configure branch tracking manually because the plugin passes the branch name from BUILDKITE_BRANCH. Builds for pull requests run as PR scans. On other builds, Buildkite sets BUILDKITE_PULL_REQUEST to false and the scan records a monitored version. Set pr: false to record a monitored scan even on a pull request build, or set pr_baseline to force a PR scan without one. See PR scans to learn how Endor Labs tracks point-in-time scans. To post new findings as pull request comments, set enable_pr_comments: true and set scm_token_env to the name of an environment variable that holds your SCM token. The token must be a personal access token or bot token from your SCM provider. See PR comments to learn how comments appear on pull requests.

​
Annotate builds with scan results

Set annotate: true to post a build annotation when the scan completes. The annotation shows severity counts, admission policy status, and a findings table scoped to the scan types enabled on that step. Annotations require jq on the agent and the default JSON output. Use annotate_findings_limit to control the table size. The value -1 lists all critical and high findings, 0 shows severity counts only, and a positive number adds up to that many medium and low rows. Buildkite build with parallel Endor Labs scan steps and a job-scoped dependencies scan annotation showing severity counts, admission policy status, and a findings table In pipelines that run scan types in parallel steps, set annotate_scope: job to attach each annotation to its own step. Job-scoped annotations require Buildkite agent v3.112 or later.

​
Control build failures

When a blocking admission policy matches, endorctl exits with code 128 and the step fails. This is the default behavior, controlled by fail_on_policy: true.
  • Set fail_on_policy: false to treat a blocking admission policy as success.
  • Set soft_fail: true to soften other nonzero exits. It doesn’t bypass exit 128 while fail_on_policy is true.
  • Set exit_on_policy_warning: true to also fail the step on warning policies.
See endorctl exit codes for the full list of exit codes.

​
Run SAST scans

Set scan_sast: true to scan your source code for security weaknesses. To enable AI SAST analysis, set additional_args to --ai-sast-analysis=agent-fallback. 
plugins:
  - ./.buildkite/vendor/endorlabs-buildkite-plugin:
      namespace: "${ENDOR_NAMESPACE}"
      api_key_env: ENDOR_API_CREDENTIALS_KEY
      api_secret_env: ENDOR_API_CREDENTIALS_SECRET
      scan_sast: true
      additional_args: "--ai-sast-analysis=agent-fallback"
See SAST scans to learn about rules and findings.

​
Scan container images

Container scans run in a separate step from repository scans. Set scan_container: true with an image or image_tar, and turn off scan_dependencies. 
  - label: ":docker: Scan container image"
    command: "docker build -t my-app:latest ."
    plugins:
      - ./.buildkite/vendor/endorlabs-buildkite-plugin:
          namespace: "${ENDOR_NAMESPACE}"
          api_key_env: ENDOR_API_CREDENTIALS_KEY
          api_secret_env: ENDOR_API_CREDENTIALS_SECRET
          scan_container: true
          scan_dependencies: false
          image: "my-app:latest"
          project_name: "my-app"
Set os_reachability: true to identify which packages in the image are used at runtime. See Scan container images and Container reachability for details.

​
Sign and verify artifacts

Set mode: sign or mode: verify with an artifact_name to run artifact signing workflows instead of a scan. Scan options aren’t valid in these modes. See Artifact signing to learn about signing and verification.

​
Plugin configuration reference

The following tables load directly from the plugin’s plugin.yml at the latest release, so they always reflect the current plugin version.

​
Common options

These options apply to every plugin invocation. Only namespace is required.

​
Authentication options

Use one authentication method per step: API credentials or one cloud keyless option.

​
Scan types

Turn on at least one scan type when mode is scan.

​
Scan configuration options

These options adjust what a scan covers and how projects are named and tagged.

​
Container scan options

These options apply when scan_container is true.

​
PR scan options

These options control PR scan detection.

​
Annotation and output options

These options control build annotations, output formats, and uploaded artifacts.

​
Build failure options

These options decide when a scan fails the step.

​
Artifact signing options

These options apply when mode is sign or verify.