Integrating CI/CD tools with Astra ensures that your security vulnerabilities are automatically scanned during your development pipeline, helping keep your projects secure with minimal effort.

Available CI/CD Integrations

GitHub
GitLab
Jenkins
Bitbucket
Azure
CircleCI

If you use a a different CI/CD tool, you can refer to the generic steps for starting audits via a simple API call via curl

You can configure your CI/CD pipeline to fail if high severity vulnerabilities are found

Step-by-Step Guide to CI/CD Integration

To get started with an integration:

Login to your Astra Dashboard
Navigate to the Pentest menu item, and open the project you want to audit from your CI/CD
Go to the Integrations, and click on the icon of the CI/CD tool you use
Activate the Integration, and follow the steps on the screen (or below)

GitHub

Select GitHub app
Choose the mode for the audit - Automated or Manual
Sign in to your GitHub account and open the repository for the chosen project
Go to Settings, select secrets and click on New repository secret
Set name as ASTRA_ACCESS_TOKEN = <can be copied from dashboard> and set the value as the token you copied from the dashboard
Add a new step in your YAML file. We recommend to add this after the deploy step:

- shell: bash
  name: Run an Astra Pentest
  env:
    ASTRA_ACCESS_TOKEN: ${{ secrets.ASTRA_ACCESS_TOKEN }}
    ASTRA_PROJECT_ID: COPY-FROM-DASHBOARD
    ASTRA_AUDIT_MODE: automated
  run: |
    wget -O - https://git.io/JSHtC | bash

Gitlab

Select the GitLab app
Choose the mode for the audit - Automated or Manual
Sign in to your GitLab account and open the repository for the chosen Astra project
Go to Settings & choose CI/CD from the left navigation bar
Go to Variables, click on Expand and click on Add variable
Set ASTRA_ACCESS_TOKEN = <can be copied from dashboard> and ASTRA_PROJECT_ID = <can be copied from dashboard> variables, uncheck Mask Variable & Protect variable both
Add the following step in your YAML file

pentest-job:
  stage: .post
  variables:
    ASTRA_AUDIT_MODE: automated
  script:
    - wget -O - https://git.io/JSHtC | bash

Jenkins

Select the Jenkins app
Choose the mode for the audit - Automated or Manual
Add the following variables and stages to the Jenkins file of your repository (replace the values in ASTRA_PROJECT_ID and ASTRA_ACCESS_TOKEN as seen in the dashboard):

pipeline {
  agent any
  environment {
    ASTRA_PROJECT_ID = 'redacted'
    ASTRA_ACCESS_TOKEN = 'redacted'
    ASTRA_AUDIT_MODE = 'automated'
  }
  stages {
    stage('build') {
      steps {
        sh 'wget -O - https://git.io/JSHtC | bash'
      }
    }
}
}

BitBucket

Select the BitBucket app
Choose the mode for the audit - Automated or Manual
Sign in to your Bitbucket account
Click on Repositories and open the repository for the chosen project
Click on Repository settings. Then, scroll down in the left navbar till Pipelines & click on Repository variables
Add ASTRA_ACCESS_TOKEN = <can be copied from dashboard> and ASTRA_PROJECT_ID = <can be copied from dashboard> variables, uncheck Secured for both
Add a new step in the pipeline YAML file. We recommend to add this after the deploy stage.

- step:
    name: 'Astra Pentest Job'
    script:
      - export ASTRA_AUDIT_MODE="automated"
      - wget -O - https://git.io/JSHtC | bash

Azure

Select the Azure app
Choose the mode for the audit - Automated or Manual
Go to https://dev.azure.com and sign in to your account
Choose your organization and choose your project from the Projects tab
Click on Pipelines in the left navbar, and click on the pipeline for which you want to set up the pentest. Then Click on Edit
In the pipeline YAML page, click on Variables
Add ASTRA_ACCESS_TOKEN = <can be copied from dashboard> and ASTRA_PROJECT_ID = <can be copied from dashboard> variables, do not select Keep this value secret
Add a new step in the pipeline YAML file. We recommend to add this after the deploy stage.

variables:
  ASTRA_AUDIT_MODE: "automated"
steps:
  - script: |
      wget -O - https://git.io/JSHtC | bash
    displayName: 'Run an Astra Pentest'

CircleCI

Select the CircleCI app
Choose the mode for the audit - Automated or Manual
Sign in to your CircleCI account and open the repository for the chosen Astra project
Add the environment variables to the CircleCI project, as provided in the Astra dashboard.

Click on Mechanical Wheel Icon

Navigate to Environment Variables and click on Add Variable
Ensure the variable names are named as follows : `ASTRA`95ACCESS_TOKEN*, ASTRA_PROJECT_ID (values can be copied from the dashboard)
Configure your config.yml in .circleci folder as follows:

Add the following snippet to jobs: section

astra-pentest-trigger:
    machine:
      image: ubuntu-2004:202008-01
    environment:
      ASTRA_AUDIT_MODE: automated
    steps:
        - run:
            command: wget -O - https://git.io/JSHtC | bash

Add the `astra`45pentest-trigger* line to jobs: of workflow: section

Example:

workflows:
    version: x
    workflow-name:
        jobs:
            - job 1
            - job 2
            - astra-pentest-trigger

How to Configure Your Pipeline to Fail When Vulnerabilities are Found

To ensure that your pipeline fails when vulnerabilities are detected during the Astra scan, follow these steps:

Set the ASTRA_JOB_EXIT_STRATEGY:
Set ASTRA_JOB_EXIT_STRATEGY='always_pass' if you want to just trigger a scan. Your CI/CD pipeline will not have to wait until vulnerabilities are found. It will return a success as soon as the scan is launched successfully.
Alternatively, set ASTRA_JOB_EXIT_STRATEGY='fail_when_vulnerable' in your pipeline configuration to make the pipeline fail when vulnerabilities are found. In case of a long running scan, this will return true after a maximum duration determined by the ASTRA_JOB_EXIT_REFETCH_INTERVAL and ASTRA_JOB_EXIT_REFETCH_MAX_RETRIES. You can also set ASTRA_JOB_EXIT_STRATEGY='wait_for_completion' to make the pipeline wait until the scan finishes. *

Configure the Refetch Interval and Max Retries:
The following variables need to be set if you are using ASTRA_JOB_EXIT_STRATEGY='fail_when_vulnerable':
ASTRA_JOB_EXIT_REFETCH_INTERVAL=30 :This specifies the interval (in seconds) at which the pipeline checks for the scan status.
*ASTRA_JOB_EXIT_REFETCH_INTERVAL=30 :This sets the maximum number of retries the pipeline will attempt to check the scan status before failing.

Define the Exit Criterion:
Set the exit criterion to determine when the pipeline should fail based on vulnerability severity. Use the following example as a guide:

ASTRA_JOB_EXIT_CRITERION="severityCount[\\\"high\\\"] > 0 or severityCount[\\\"critical\\\"] > 0"

This criterion specifies that the pipeline should fail if there are any high or critical severity vulnerabilities detected during the scan.

Full example:

ASTRA_JOB_EXIT_STRATEGY='fail_when_vulnerable'
ASTRA_JOB_EXIT_REFETCH_INTERVAL=10
ASTRA_JOB_EXIT_REFETCH_MAX_RETRIES=10
ASTRA_JOB_EXIT_CRITERION="severityCount[\\\"high\\\"] > 0 or severityCount[\\\"critical\\\"] > 0"

By following these steps and configuring the appropriate settings, your pipeline will automatically fail if vulnerabilities meeting the defined severity criteria are found during the Astra scan.

For further assistance or troubleshooting, please contact our support team.**

Updated on: 19/12/2024