Scanning with GitHub Actions
GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can use GitHub Actions to seamlessly include Endor Labs into your CI pipeline.
Using this pipeline, developers can view and detect:
- Policy violations in the source code
- Secrets inadvertently included in the source code
The Endor Labs verifications are conducted as automated checks and help you discover violations before pushing code to the repository. Information about the violations can even be included as comments on the corresponding pull request (PR). This enables developers to easily identify issues and take remedial measures early in the development life cycle.
- For policy violations, the workflow is designed to either emit a warning or return an error based on your action policy configurations.
- For secrets discovered in the commits, developers can view the PR comments and take necessary remedial measures.
To start using Endor Labs with GitHub:
- Install Software Pre-requisites
- Example GitHub Action Workflow
- Authenticate with Endor Labs
- Configure Endor Labs Action Policies
- View PR Comments
- Endor Labs GitHub Action Configuration Parameters
Install Software Pre-requisites
To ensure the successful execution of the Endor Labs GitHub action, the following pre-requisites must be met:
- The GitHub action must be able to authenticate with the Endor Labs API.
- You must have the value of the Endor Labs namespace handy for authentication.
- You must have access to the Endor Labs API.
- If you are using keyless authentication, you must set an authorization policy in Endor Labs. See Authorization policies for details.
Example GitHub Action Workflow
Here is an example Endor Labs scanning workflow using GitHub actions that accomplishes the following tasks in your CI environment:
- Tests PRs to the default branch and monitors the most recent push to the default branch.
- Builds a Java project and sets up the Java build tools. If your project is not on Java, then configure this workflow with your project-specific steps and build tools.
- Authenticates to Endor Labs with GitHub Actions keyless authentication.
- Scan with Endor Labs.
- Comments on PRs if any policy violations occur.
- Generates findings and uploads results to GitHub in SARIF format.
Below is an example workflow to scan with Endor Labs for a Java application using the recommended keyless authentication for GitHub actions:
name: Endor Labs Dependency and Secrets Scan
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
scan:
permissions:
security-events: write # Used to upload Sarif artifact to GitHub
contents: read # Used to check out a private repository
actions: read # Required for private repositories to upload Sarif files. GitHub Advanced Security licenses are required.
id-token: write # Used for keyless authentication with Endor Labs
issues: write # Required to automatically comment on PRs for new policy violations
pull-requests: write # Required to automatically comment on PRs for new policy violations
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v3
- name: Setup Java
uses: actions/setup-java@v3
with:
distribution: 'microsoft'
java-version: '17'
- name: Build Package
run: mvn clean install
- name: Endor Labs Scan Pull Request
if: github.event_name == 'pull_request'
uses: endorlabs/github-action@v1.1.2
with:
namespace: 'example' # Replace with your Endor Labs tenant namespace
scan_dependencies: true
scan_secrets: true
pr: true
enable_pr_comments: ${{ env.ENDORCTL_PR }}
github_token: ${{ secrets.GITHUB_TOKEN }} # Required for PR comments on new policy violations
scan-main:
permissions:
id-token: write
repository-projects: read
pull-requests: read
contents: read
name: endorctl-scan
steps:
- name: Checkout Repository
uses: actions/checkout@v3
- name: Setup Java
uses: actions/setup-java@v3
with:
distribution: 'microsoft'
java-version: '17'
- name: Build Package
run: mvn clean install
- name: 'Endor Labs Scan Push to main'
if: ${{ github.event_name == 'push' }}
uses: endorlabs/github-action@v1.1.2
with:
namespace: 'example' # Replace with your Endor Labs tenant namespace
scan_dependencies: true
scan_secrets: true
pr: false
scan_summary_output_type: 'table'
sarif_file: 'findings.sarif'
- name: Upload findings to github
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: 'findings.sarif'
Authenticate with Endor Labs
Endor Labs recommends using keyless authentication in CI environments. Keyless authentication is more secure and reduces the cost of secret rotation. To set up keyless authentication see Keyless Authentication.
If you choose not to use keyless authentication, you can configure an API key and secret in GitHub for authentication as outlined in Managing API keys.
Authentication Without Keyless Authentication for GitHub
If you are not using keyless authentication for GitHub Actions, you must not provide id-token: write
permissions to your GitHub token unless specifically required by a step in this job. You must also set enable_github_action_token: false
in your Endor Labs GitHub action configuration.
The following example configuration uses the Endor Labs API key for authentication:
- name: Scan with Endor Labs
uses: endorlabs/github-action@v1.1.2
with:
namespace: 'example'
api_key: ${{ secrets.ENDOR_API_CREDENTIALS_KEY }}
api_secret: ${{ secrets.ENDOR_API_CREDENTIALS_SECRET }}
enable_github_action_token: false
The following example configuration uses a GCP service account for keyless authentication to Endor Labs:
- name: Scan with Endor Labs
uses: endorlabs/github-action@v1.1.2
with:
namespace: 'example'
gcp_service_account: '<Insert_Your_Service_Account>@<Insert_Your_Project>.iam.gserviceaccount.com'
enable_github_action_token: false
Enable PR Comments
Make sure that your GitHub action workflow includes the following:
- The workflow must have a
with
clause including:enable_pr_comments
totrue
to publish new findings as review comments andgithub_token: ${{ secrets.GITHUB_TOKEN }}
. This token is automatically provisioned by GitHub when using GitHub actions. See GitHub configuration parameters for more information. - To grant Endor Labs the ability to comment on PRs you must include the permissions
issues: write
andpull-requests: write
.
The following example configuration comments on PRs if a policy violation is detected.
- name: Endor Labs Scan PR to Default Branch
if: github.event_name == 'pull_request'
uses: endorlabs/github-action@v1.1.2
with:
namespace: 'example' # Update with your Endor Labs namespace
scan_summary_output_type: 'table'
scan_dependencies: true
scan_secrets: true
pr: true
enable_pr_comments: ${{ env.ENDORCTL_PR }}
github_token: ${{ secrets.GITHUB_TOKEN }}
Configure Endor Labs Action Policies
Configure an action policy in the Endor Labs UI to perform an action when a rule is triggered. See Action Policies for details on action policies.
- Set the Policy Template to Detected Secrets and select the Template Parameters as desired.
- Choose Enforce Policy and
- Select Warn as the recommended action.
- Select Break the Build to fail the build CI pipeline.
View PR Comments
You can now proceed to check out the code, install the build toolchain and build the code. When you raise a PR, Endor Labs will scan and detect any policy violations and add PR comments accordingly. The CI pipeline will either warn you or fail the build based on your action policy configuration. The PR comments will also include recommendations to help you take necessary remedial actions.
Endor Labs GitHub Action Configuration Parameters
The following input configuration parameters are supported for the Endor Labs GitHub Action:
Common parameters
The following input global parameters are supported for the Endor Labs GitHub action:
Flags | Description |
---|---|
api_key |
Set the API key used to authenticate with Endor Labs. |
api_secret |
Set the secret corresponding to the API key used to authenticate with Endor Labs. |
enable_github_action_token |
Set to false if you prefer to use another form of authentication over GitHub action OIDC tokens. (Default: true ) |
endorctl_checksum |
Set to the checksum associated with a pinned version of endorctl. |
endorctl_version |
Set to a version of endorctl to pin this specific version for use. Defaults to the latest version. |
log_level |
Set the log level. (Default: info ) |
log_verbose |
Set to true to enable verbose logging. (Default: false ) |
namespace |
Set to the namespace of the project that you are working with. (Required) |
gcp_service_account |
Set the target service account for GCP based authentication. GCP authentication is only enabled if this flag is set. Cannot be used with api_key . |
Scanning parameters
The following input parameters are also supported for the Endor Labs GitHub action when used for scanning:
Flags | Description |
---|---|
additional_args |
Use additional_args with endorctl scan for advanced scenarios. However, no example use-case currently exists as standard options suffice for typical needs. |
phantom_dependencies |
Set to true to enable phantom dependency analysis. (Default: false ) |
enable_pr_comments |
Set to true to publish new findings as review comments. Must be set together with pr and github_token . Additionally, the issues: write and pull-requests: write permissions must be set in the workflow. (Default: false ) |
export_scan_result_artifact |
Set to false to disable the JSON scan result artifact export. (Default: true ) |
github_token |
Set the token used to authenticate with GitHub. Must be provided if enable_pr_comments is set to true |
pr |
Set to false to track this scan as a monitored version within Endor Labs, as opposed to a point in time policy and finding test for a PR. (Default: true ) |
pr_baseline |
Set to the git reference that you are merging to, such as the default branch. Enables endorctl to compare findings so developers are only alerted to issues un the current changeset. Example: pr_baseline: "main" . Note: Not needed if enable_pr_comments is set to true . |
run_stats |
Set to false to disable reporting of CPU/RAM/time scan statistics via time -v (may be required on Windows runners). (Default: true ) |
sarif_file |
Set to a location on your GitHub runner to output the findings in SARIF format. |
scan_dependencies |
Scan git commits and generate findings for all dependencies. (Default: true ) |
scan_git_logs |
Perform a more complete and detailed scan of secrets in the repository history. Must be used together with scan_secrets . (Default: false ) |
scan_path |
Set the path to the directory to scan. (Default: . ) |
scan_secrets |
Scan source code repository and generate findings for secrets. See also scan_git_logs . (Default: false ) |
scan_summary_output_type |
Set the desired output format to table , json , yaml , or summary . (Default: json ) |
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 |
Enable the usage of Bazel for the scan. (Default: false ) |
bazel_exclude_targets |
Specify a list of Bazel targets to exclude from scan. |
bazel_include_targets |
Specify a list of Bazel targets to scan. If bazel_targets_include is not set the bazel_targets_query value is used to determine with bazel targets to scan. |
bazel_targets_query |
Specify a Bazel query to determine with Bazel targets to scan. Ignored if bazel_targets_include is set. |
Feedback
Was this page helpful? Send your feedback to support@endor.ai