PR and Release Gating Using Local Image Scanner

In addition to using the local scanner for identifying and reporting security issues in your images, you can also use the Aikido Local Scanner for gating in your CI. We provide two types of gating, release gating and PR gating.

Release Gating

You can also run the scanner in release gating mode by using the --fail-on <severity> flag. This feature is helpful when scanning your image prior to publishing it to an image library, as it ensures there are no open issues before release. When running in release gating mode, the scanner process will fail when there are any open issues of the chosen severity or higher after the scan is finished.

Example release gating command:

./aikido-local-scanner image-scan your-image-name --apikey AIK_CI_xxx --fail-on critical

PR Gating

The PR gating mode ensures that the new code meets specific security criteria before merging into your default branch. This mode scans the changes introduced in the PR. If any new issues that match or exceed your chosen severity are introduced, the CI pipeline will fail.

To enable release gating, add the --fail-on <severity> option to select your preferred severity level. Then, add the --gating-mode pr option to signify that you wish to perform PR gating. You must also specify the base (--base-commit-id <commit-id>) and head commit (--head-commit-id <commit-id>). If there a scan was previously performed on the base commit id, the scan results will be compared to those. If not, the results will be compared to the most recent scan on your image.

Example PR gating command:

./aikido-local-scanner image-scan your-image-name --apikey AIK_CI_xxx --fail-on critical --gating-mode pr --base-commit-id abc123 --head-commit-id def456 

Examples

GitHub

For general information about setting up the Local Scanner in a GitHub environment, check out this article. Example .github/workflows/aikido-scan.yml for release gating:

name: Aikido Docker build and scan

on:
  push:
    branches:
      - main

jobs:
  build-and-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build Docker image
        run: docker build -t your-local-image-name .

      - name: Run Aikido image scan
        run: |
          docker run --rm \
            -v /var/run/docker.sock:/var/run/docker.sock \
            aikidosecurity/local-scanner \
            image-scan your-local-image-name \
            --apikey ${{ secrets.AIKIDO_API_KEY }} \
            --fail-on critical

Example .github/workflows/aikido-scan.yml for PR gating:

name: Aikido Docker build and scan

on:
  pull_request:
    branches:
      - main

jobs:
  build-and-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build Docker image
        run: docker build -t your-local-image-name .

      - name: Run Aikido image scan
        run: |
          docker run --rm \
            -v /var/run/docker.sock:/var/run/docker.sock \
            aikidosecurity/local-scanner \
            image-scan your-local-image-name \
            --apikey ${{ secrets.AIKIDO_API_KEY }} \
            --fail-on critical \
            --gating-mode pr \
            --base-commit-id ${{ github.event.pull_request.base.sha }} \
            --head-commit-id ${{ github.event.pull_request.head.sha }} 

Azure DevOps Server

For general information about setting up the Local Scanner in a Azure DevOps environment, check out this article. Example for release gating:

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- script: docker build -t my-image .
  displayName: 'Build docker image'  
- script: |
    docker run --rm -v /var/run/docker.sock:/var/run/docker.sock aikidosecurity/local-scanner image-scan my-image \
    --apikey $(AIKIDO_API_KEY) \
    --fail-on critical
  displayName: 'Run Aikido scan'

Example for PR gating:

trigger: none

pr:
  branches:
    include:
      - 'main'

pool:
  vmImage: ubuntu-latest

steps:
- script: docker build -t my-image .
  displayName: 'Build docker image'  
- script: | 
    docker run --rm -v /var/run/docker.sock:/var/run/docker.sock aikidosecurity/local-scanner image-scan my-image \
        --apikey $(AIKIDO_API_KEY) \
        --fail-on critical \
        --gating-mode pr \
        --base-commit-id abc123 \
        --head-commit-id def456
  displayName: 'Run Aikido scan'

Make sure to add this pipeline as a Build Validation to your main branch:

1. Go to Project Settings → Repositories → Policies → Branch Policies

2. Select your main branch

3. Add Build Validation

4. Choose this pipeline

5. Set:

   • Trigger: Automatic