• Overview
• Implementation
• Block vs Warn
• Rollout At Scale

Overview

Secure Code Warrior® Trust Agent provides a CI check tool that can be run within your CI pipelines and triggered when a pull request is made. The check will succeed or fail depending on the compliance of the pull request contributors with your Trust Agent policy.

Implementation

The CI check tool is provided as a Docker container image that is published to GitHub and available from the container registry at ghcr.io/securecodewarrior/scw-policy-gate-ci.

The published container image is compatible with GitHub Actions, but can also be used within any CI system that supports running a container within its pipelines. Additional native compatibility with popular CI systems will be released over time.

We have adopted semantic versioning for the container image releases. Whilst in early access, we recommend using the minor version tag (e.g. 0.2) as there may be breaking changes (e.g. required configuration parameters) between early access minor versions. Once generally available, we recommend using the major version tag (e.g. 1).

GitHub Actions

An example GitHub Actions workflow file is provided below demonstrating how the CI check tool can be triggered off pull requests:

on:
  pull_request:

jobs:
  main:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # commit history is required
      - name: SCW Policy Gate CI Check
        uses: docker://ghcr.io/securecodewarrior/scw-policy-gate-ci:0.2
        with:
          api-token: ${{ secrets.SCW_TRUST_AGENT_API_KEY }}
          api-url: <API endpoint URL - see below>
          repository-path: .

The api-url that you specify will depend on which SCW instance you selected during onboarding:

• For US instance: https://trust-agent.prod-us.prod.securecodewarrior.com
• For EU instance: https://trust-agent.prod-eu.prod.securecodewarrior.com

You can also confirm your API endpoint URL from within Trust Agent by navigating to Administration > Trust Agent Configuration > Manage Policy > Policy Gating > Connect Repositories.

Other CI Systems

For other CI systems capable of running a Docker container, some additional configuration will be required depending on your specific setup. The CI check tool can be run from any CLI, with appropriate values passed in via environment variables or command line options, and the repository cloned into or mounted to the container.

Supported environment variables are listed below:

• SCW_API_KEY: Set the SCW API key. For security, the environment variable is preferred over the command line option. Follow this guide to create your Admin API key.
• SCW_API_URL: Set the SCW API endpoint URL to use for the gating check. The environment variable will be overridden by the command line option if both are provided. Please refer to the above section to determine the URL to use.

Supported command line options are listed below:

• --api-token string: (Required) Set the SCW API token. WARNING: For security, prefer using the SCW_API_KEY environment variable over the command line option. Follow this guide to create your Admin API key.
• --api-url string: (Required) Set the SCW API endpoint URL to use for the gating check. Overrides the SCW_API_URL environment variable. Please refer to the above section to determine the URL to use.
• --repository-path string: (Required) Set the relative path to the repository, e.g. '.' for the current directory.
• --base-ref string: (Required) Set the base ref to use for the check, e.g. 'main' or 'master'.
• --head-ref string: Set the head ref to use for the check, e.g. 'my-feature-branch'.
• --log-level string: Set the log level, one of: DEBUG, INFO, WARN, ERROR.
• --payload-only: Prepare request payload, output as JSON, and exit. If set, the api-token and api-url options are not required.
• --version: Display version information and exit. 

An example Docker run command that would perform the policy check against contributors of the my-feature-branch branch is as follows:

• docker run --rm -e SCW_API_KEY=YOUR_API_KEY -e SCW_API_URL=https://trust-agent.prod-us.prod.securecodewarrior.com -- ghcr.io/securecodewarrior/scw-policy-gate-ci:0.2 --base-ref main --head-ref my-feature-branch --repository-path .

Note the base-ref and head-ref values will typically need to be populated by the CI system based on the base and feature branches of the associated pull request. The base-ref value can also be set to a default trunk branch name such as main, depending on the branch naming convention used within your organization.

Block vs Warn

One important thing to note is that the CI check tool simply returns the result of the policy check and how failures are interpreted is configurable within your CI system. 

If a pull request failed check is configured in your CI system to be non-blocking then it will act as a warning only within the CI pipeline, providing the developer with notification that their training policy requirements have not been met and information on how they can address the gap. However, if it is configured to be a required check that must pass then it will act as a blocking check that can prevent the developer from merging their pull request until they have satisfied the training policy requirements. 

Secure Code Warrior strongly recommends configuring the CI check tool in warning mode for at least 6 months prior to consideration of making it a blocking check. Furthermore, we recommend checking the preview modelling in the Policy Gating section of the configuration screen to ensure a sufficiently high proportion (70+%) of allowed commits detected to minimise any disruption to development teams working on repositories in scope of your Policy Gating settings. You can limit the scope of the CI check tool to critical repositories only by configuring this in the Policy Gating settings. Please refer to this guide for more information.

Rollout At Scale

For organizations with large numbers of repositories, some form of template workflow that can be updated and automatically picked up by individual repositories is typically required to avoid requiring each repository needing to be configured with an additional workflow or job. 

For organizations on GitHub Enterprise, rulesets can be used to achieve this but your organization may also have a customized alternate method. For example, you can create an organization ruleset that targets a set of repositories or all repositories (please refer to the official documentation for more details), as well as specify the target branches of those repositories:

You can then set up a template workflow and set it as a required workflow using the Require workflows to pass before merging rule. Please refer to the official documentation for full configuration instructions.

IMPORTANT WARNING: This will automatically run the template workflow for all target repositories' pull requests and require the check to pass before branches can be merged, effectively putting the policy check in blocking mode. There does not currently appear to be a way to configure a GitHub ruleset that will automatically run the template workflow for all target repositories without requiring that the check must pass.

Related Articles:

• What is the Secure Code Warrior® Trust Agent?
• Trust Agent FAQs