Coana Guardrail (beta)

Coana Guardrail is a feature you can enable to prevent code changes from introducing new reachable vulnerabilities.

When the guardrail is active, it runs Coana on both the main/master branch and the current branch. It then compares the results and fails the pipeline if any new reachable vulnerabilities are found in the current branch, allowing the pipeline to continue if the vulnerabilities already exist in production.

To ensure efficiency, the guardrail requires you to specify a list of changed files. This way, Coana only scans the files that have been modified, keeping the analysis fast enough to run on every new commit.

Notice, it may be beneficial to use the --lightweight-reachability flag when running Coana in the guardrail mode. This flag enables a faster reachability analysis that ensures the check terminates quickly. In rare scenarios, some reachable vulnerabilities may not be caught in this mode, but it's a good trade-off for the guardrail use case. (Should a reachable vulnerability slip through the lightweight reachability analysis, it will be caught in the next scheduled full analysis scan.) Learn more about the lightweight reachability analysis on the Reachability Analysis page.

GitHub Workflows Configuration

The example below demonstrates how to configure the Coana Guardrail in a GitHub workflow.

Generate an API key

Go to Settings → API Keys (opens in a new tab) to generate an API key.

Add the generated API key as a repository secret

Add the generated API key to your repository by creating a repository action secret with the name COANA_API_KEY at the following URL: https://github.com/org/repoName/settings/secrets/actions (opens in a new tab). Make sure to replace 'org' and 'repoName' with your organization's name and your repository's name.

You can also add an organization-wide secret in your organization settings. The organization-wide secret will be available to all repositories in the organization, making it a better option if you need to run Coana across many repositories.

Create the workflow file

Create the folders .github/workflows at the root of the repository if they don't already exist and copy the template provided below into a new file named coana-guardrail.yml inside .github/workflows.

coana-guardrail.yml

name: Coana Guardrail
 
on: pull_request
 
jobs:
  guardrail:
    runs-on: ubuntu-latest
 
    steps:
      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v44
        with:
          separator: ' '
 
      - name: Checkout the ${{github.base_ref}} branch
        uses: actions/checkout@v4
        with:
          ref: ${{github.base_ref}} ## checkout the base branch (usually master/main).
 
      - name: Use Node.js 20.x
        uses: actions/setup-node@v4
        with:
          node-version: 20.x
 
      - name: Run Coana on the ${{github.base_ref}} branch
        run: |
          npx @coana-tech/cli run . \
            --api-key ${{ secrets.COANA_API_KEY }} \
            -o /tmp/main-branch \
            --changed-files ${{ steps.changed-files.outputs.all_changed_files }} \
            --lightweight-reachability \
            --disable-report-submission
 
      - name: Checkout the current branch
        uses: actions/checkout@v4
 
      - name: Run Coana on the current branch
        run: |
          npx @coana-tech/cli run . \
            --api-key ${{ secrets.COANA_API_KEY }} \
            -o /tmp/current-branch \
            --changed-files ${{ steps.changed-files.outputs.all_changed_files }} \
            --lightweight-reachability \
            --disable-report-submission
 
      - name: Run Report Comparison
        run: |
          npx @coana-tech/cli compare-reports \
            --api-key ${{ secrets.COANA_API_KEY }} \
            /tmp/main-branch/coana-report.json \
            /tmp/current-branch/coana-report.json
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The GITHUB_TOKEN secret is required for Coana to post comments on the PR. You can add the --no-pr-comment flag to the compare-reports command if you want to disable PR comments.

Other CI systems

If you're using a different CI system, you can still implement the Coana Guardrail by following these steps:

Create an API following the step above and store it in the env variable COANA_API_KEY.
Get the changed files relative to the main branch using git.

CHANGED_FILES=`git diff --name-only main`

Checkout the main/master branch.
Run Coana on the main/master branch and save the results to some folder, e.g., /tmp/main-branch.

npx @coana-tech/cli run . \
  --api-key ${COANA_API_KEY} \
  -o /tmp/main-branch \
  --changed-files ${CHANGED_FILES} \
  --lightweight-reachability \
  --disable-report-submission

Checkout the current/PR branch.
Run Coana on the current/PR branch and save the results to some folder, e.g., /tmp/current-branch.

npx @coana-tech/cli run . \
  --api-key ${COANA_API_KEY} \
  -o /tmp/old-report \
  --changed-files ${CHANGED_FILES} \
  --lightweight-reachability \
  --disable-report-submission

Run the report comparison.

npx @coana-tech/cli compare-reports \
  --api-key ${COANA_API_KEY} \
  /tmp/main-branch/coana-report.json \
  /tmp/current-branch/coana-report.json

Compare reports options

$ coana compare-reports --help
Usage: coana-cli compare-reports [options] <baselineReportPath> <newReportPath>

Arguments:
  baselineReportPath                    Path to the baseline report
  newReportPath                         Path to the new report

Options:
  --api-key <key>                       Set the Coana dashboard API key.
  -d, --debug                           Enable debug logging (default: false)
  --no-pr-comment                       Disable pull request comments (only relevant when run from a PR)
  --no-block                            Do not fail with a non-zero exit code when new reachable vulnerabilities are detected
  --ignore-undeterminable-reachability  Ignore vulnerabilities with undeterminable reachability (default: false)
  -h, --help                            display help for command

Reachability Analysis CircleCI