Running ASH in CI

This guide explains how to integrate ASH v3 into various CI/CD platforms.

Continuous Integration (CI) Execution

ASH supports running in CI environments as an executable container (e.g., via docker run) as well as via Container Job mechanisms, depending on CI platform support.

Building ASH Container Images for CI Usage

Building ASH images for use in CI platforms requires targeting the ci stage of the Dockerfile:

# Via ash CLI
ash build-image --build-target ci

# Via docker or other OCI CLI
docker build --tag automated-security-helper:ci --target ci .

GitHub Actions

Basic Integration

name: ASH Security Scan

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install ASH
        run: pip install git+https://github.com/awslabs/automated-security-helper.git@v3.0.0
      - name: Run ASH scan
        run: ash --mode local
      - name: Upload scan results
        uses: actions/upload-artifact@v3
        with:
          name: ash-results
          path: .ash/ash_output

Using Container Mode

name: ASH Security Scan (Container)

on:
  push:
    branches: [ main ]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install ASH
        run: pip install git+https://github.com/awslabs/automated-security-helper.git@v3.0.0
      - name: Run ASH scan
        run: ash --mode container
      - name: Upload scan results
        uses: actions/upload-artifact@v3
        with:
          name: ash-results
          path: .ash/ash_output

Adding Scan Results to PR Comments

name: ASH Security Scan with PR Comments

on:
  pull_request:
    branches: [ main ]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install ASH
        run: pip install git+https://github.com/awslabs/automated-security-helper.git@v3.0.0
      - name: Run ASH scan
        run: ash --mode local
      - name: Add PR comment
        uses: actions/github-script@v6
        if: always()
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const fs = require('fs');
            const reportPath = '.ash/ash_output/reports/ash.summary.md';

            if (fs.existsSync(reportPath)) {
              const reportContent = fs.readFileSync(reportPath, 'utf8');
              const issueNumber = context.issue.number;

              github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: issueNumber,
                body: reportContent
              });
            }

GitLab CI

Basic Integration

ash-scan:
  image: python:3.10
  script:
    - pip install git+https://github.com/awslabs/automated-security-helper.git@v3.0.0
    - ash --mode local
  artifacts:
    paths:
      - .ash/ash_output

Using Container Mode

ash-scan-container:
  image: docker:20.10.16
  services:
    - docker:20.10.16-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  script:
    - apk add --no-cache python3 py3-pip git
    - pip3 install git+https://github.com/awslabs/automated-security-helper.git@v3.0.0
    - ash --mode container
  artifacts:
    paths:
      - .ash/ash_output

AWS CodeBuild

Basic Integration

version: 0.2

phases:
  install:
    runtime-versions:
      python: 3.10
    commands:
      - pip install git+https://github.com/awslabs/automated-security-helper.git@v3.0.0

  build:
    commands:
      - ash --mode local

artifacts:
  files:
    - .ash/ash_output/**/*

Using Container Mode

version: 0.2

phases:
  install:
    runtime-versions:
      python: 3.10
    commands:
      - pip install git+https://github.com/awslabs/automated-security-helper.git@v3.0.0

  pre_build:
    commands:
      - nohup /usr/local/bin/dockerd --host=unix:///var/run/docker.sock --host=tcp://127.0.0.1:2375 --storage-driver=overlay2 &
      - timeout 15 sh -c "until docker info; do echo .; sleep 1; done"

  build:
    commands:
      - ash --mode container

artifacts:
  files:
    - .ash/ash_output/**/*

Jenkins

Jenkinsfile (Declarative Pipeline)

pipeline {
    agent {
        docker {
            image 'python:3.10'
        }
    }
    stages {
        stage('Install ASH') {
            steps {
                sh 'pip install git+https://github.com/awslabs/automated-security-helper.git@v3.0.0'
            }
        }
        stage('Run ASH Scan') {
            steps {
                sh 'ash --mode local'
            }
        }
    }
    post {
        always {
            archiveArtifacts artifacts: '.ash/ash_output/**/*', allowEmptyArchive: true
        }
    }
}

Using Container Mode

pipeline {
    agent {
        docker {
            image 'docker:20.10.16'
            args '-v /var/run/docker.sock:/var/run/docker.sock'
        }
    }
    stages {
        stage('Install ASH') {
            steps {
                sh 'apk add --no-cache python3 py3-pip git'
                sh 'pip3 install git+https://github.com/awslabs/automated-security-helper.git@v3.0.0'
            }
        }
        stage('Run ASH Scan') {
            steps {
                sh 'ash --mode container'
            }
        }
    }
    post {
        always {
            archiveArtifacts artifacts: '.ash/ash_output/**/*', allowEmptyArchive: true
        }
    }
}

CircleCI

Basic Integration

version: 2.1
jobs:
  scan:
    docker:
      - image: cimg/python:3.10
    steps:
      - checkout
      - run:
          name: Install ASH
          command: pip install git+https://github.com/awslabs/automated-security-helper.git@v3.0.0
      - run:
          name: Run ASH scan
          command: ash --mode local
      - store_artifacts:
          path: .ash/ash_output
          destination: ash-results

workflows:
  version: 2
  scan-workflow:
    jobs:
      - scan

Using Container Mode

version: 2.1
jobs:
  scan:
    machine:
      image: ubuntu-2204:current
    steps:
      - checkout
      - run:
          name: Install ASH
          command: pip install git+https://github.com/awslabs/automated-security-helper.git@v3.0.0
      - run:
          name: Run ASH scan
          command: ash --mode container
      - store_artifacts:
          path: .ash/ash_output
          destination: ash-results

workflows:
  version: 2
  scan-workflow:
    jobs:
      - scan

Best Practices for CI Integration

Fail builds on critical findings:
```
ash --mode local --fail-on-findings
```

Use specific scanners for faster CI runs:

ash --mode local --scanners bandit,semgrep,detect-secrets

Generate CI-friendly reports:

ash --mode local --output-formats sarif,markdown,json

Cache container images to speed up builds:

# GitHub Actions example
- name: Cache ASH container
  uses: actions/cache@v3
  with:
    path: /var/lib/docker
    key: ${{ runner.os }}-ash-container

Set severity thresholds appropriate for your CI pipeline:

ash --config-overrides 'global_settings.severity_threshold=HIGH'

ASH Execution Environment Viability

If you are unsure whether ASH will run in your CI environment, the primary requirement is the ability to run Linux containers for container mode. For local mode, you only need Python 3.10+.

For container mode, ensure your CI environment: 1. Has a container runtime installed (Docker, Podman, etc.) 2. Has permissions to run containers 3. Has sufficient disk space for container images

For local mode, ensure your CI environment: 1. Has Python 3.10+ installed 2. Has permissions to install Python packages