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.

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
    container: coana/coana: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: Run Coana on the ${{github.base_ref}} branch
        run: |
          coana run . \
            --api-key ${{ secrets.COANA_API_KEY }} \
            -o /tmp/main-branch \
            --changed-files ${{ steps.changed-files.outputs.all_changed_files }} \
            --disable-report-submission
 
      - name: Checkout the current branch
        uses: actions/checkout@v4
 
      - name: Run Coana on the current branch
        run: |
          coana run . --api-key ${{ secrets.COANA_API_KEY }} \
            -o /tmp/current-branch \
            --changed-files ${{ steps.changed-files.outputs.all_changed_files }} \
            --disable-report-submission
 
      - name: Run Report Comparison
        run: coana compare-reports /tmp/main-branch/coana-report.json /tmp/current-branch/coana-report.json

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.

coana run . \
  --api-key ${COANA_API_KEY} \
  -o /tmp/main-branch \
  --changed-files ${CHANGED_FILES} \
  --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.

coana run . \
  --api-key ${COANA_API_KEY} \
  -o /tmp/old-report \
  --changed-files ${CHANGED_FILES} \
  --disable-report-submission

Run the report comparison.

coana compare-reports /tmp/main-branch/coana-report.json /tmp/current-branch/coana-report.json

Reachability Analysis CircleCI