Astra’s CI/CD integration is designed to be flexible and production-ready, allowing you to embed security scans directly into your pipeline while maintaining control over how and when the pipeline should respond to scan outcomes. By configuring a set of environment variables, you can customize:

• The scan type and audit mode,

• The pipeline exit strategy (e.g., fail on vulnerabilities or continue regardless),

• The polling logic for long-running scans, and

• The exit conditions based on severity of findings.

This article explains each of these variables in detail, helping you configure Astra to meet your CI/CD security and performance requirements.

Setting Environment Variables in Your CI/CD Pipeline

To integrate Astra with your CI/CD pipeline, you'll need to define the environment variables in your CI/CD configuration file or within the environment settings of your CI/CD tool. These variables control the scan behavior and exit strategy.

Typically, you would set them in one of the following places:

• Pipeline Configuration File: This could be a .gitlab-ci.yml, Jenkinsfile, or any other pipeline configuration file specific to your CI/CD tool. Add the variables under the environment or variables section of the file.

• CI/CD Tool's UI or Settings: Many CI tools provide a user interface for configuring environment variables at the project or job level. You can set them globally or specifically for individual jobs.

Once the variables are set, your pipeline will automatically use these configurations when initiating Astra scans, providing you with control over scan behavior, polling, and exit conditions.

Variables

Scan Mode (ASTRA_AUDIT_MODE)

Controls the type of assessment Astra runs when a scan is triggered. This helps differentiate between fully automated scans, manual pentesting workflows, or just web crawling without actual testing.

Default:

ASTRA_AUDIT_MODE="automated"

Options:

• automated – Runs a fully automated scan with no human intervention. Ideal for CI/CD pipelines and continuous security validation.

• manual – Triggers a hybrid assessment that includes automated scanning followed by manual pentesting by Astra's security engineers. Used when you've scheduled or requested a manual audit.

• web_crawl – Performs only web crawling and application mapping, without launching any security tests. Useful for asset discovery or validating application reachability.

Recommended Usage:

• Use automated for CI/CD integrations and API-triggered scans.

• Use manual if you're integrating with Astra’s manual pentest workflows or need full coverage before a major release.

• Use web_crawl for staging environments or asset inventory use cases, where testing is not desired.

Automated Scan Type (ASTRA_SCAN_TYPE)

Defines the depth and speed of the scan to be performed.

Default:

ASTRA_SCAN_TYPE="lightning"

Options:

• full – Runs all test cases across all discovered endpoints.
  Best suited for thorough, release-level assessments. Expect longer scan times.

• lightning – Runs a subset of critical test cases on all endpoints.
  Optimized for CI/CD workflows to quickly catch major issues without slowing down deployments.

• emerging_threat – Targets only high-impact, emerging vulnerabilities (e.g., CVEs, zero-days).
  Ideal when responding to new threat advisories or doing rapid security triage.

• secret_scanning - Runs the Astra git secret detection in your repository and identifies any kind of secrets present in your repository. Secrets detected can be viewed in Astra Dashboard.

Recommended Usage:

• Use lightning during each CI/CD run for fast feedback.

• Run full on nightly builds or prior to production releases.

• Use emerging_threat as a scheduled job or in response to security alerts.

• Use secret-scanning as a standalone step in your CI pipeline to detect the secrets getting committed in the repository.

Inventory Coverage Mode (ASTRA_SCAN_INVENTORY_COVERAGE)

Controls the inventory scope for the scan — whether Astra should scan the entire known inventory or only newly discovered parts. Useful for large, continuously evolving applications.

Default:

ASTRA_SCAN_INVENTORY_COVERAGE="full"

Options:

• full – Scans the entire inventory (all endpoints discovered so far).
  Ideal for comprehensive periodic scans to ensure full coverage.

• delta – Scans only newly discovered or changed endpoints since the last scan.
  Optimized for fast, incremental security feedback on what's changed.

Recommended Usage:

• Use delta in CI/CD pipelines for faster iteration with minimal scan load.

• Use full for nightly or scheduled compliance scans, or when the application has seen significant changes.

CI/CD Job Exit Strategy (ASTRA_JOB_EXIT_STRATEGY)

Define how your CI/CD pipeline should behave based on scan results:

• Trigger a scan without waiting for results:

  This will trigger the scan but return success immediately without waiting for vulnerabilities to be found.

ASTRA_JOB_EXIT_STRATEGY='always_pass'

• Fail the pipeline if vulnerabilities are detected:

  This ensures the pipeline fails when vulnerabilities are found. You can configure the exit criterion by setting ASTRA_JOB_EXIT_CRITERION as described in the section below.

  The scan runs for a maximum duration determined by ASTRA_JOB_EXIT_REFETCH_INTERVAL and ASTRA_JOB_EXIT_REFETCH_MAX_RETRIES.

    ASTRA_JOB_EXIT_STRATEGY='fail_when_vulnerable' 

• Wait until the scan finishes:

  The pipeline waits until the scan completes before proceeding. This will not fail the pipeline even if vulnerabilities are found.

ASTRA_JOB_EXIT_STRATEGY='wait_for_completion' 

For the fail_when_vulnerable and wait_for_completion modes, Astra enforces a soft limit to prevent CI/CD jobs from being held indefinitely. The default timeout is 10 minutes. If the scan does not complete in this timeframe, Astra stops checking for status updates and logs a message.

Configuring the Refetch Interval and Maximum Retries (ASTRA_JOB_EXIT_REFETCH_INTERVAL and ASTRA_JOB_EXIT_REFETCH_MAX_RETRIES)

For fail_when_vulnerable and wait_for_completion modes, Astra periodically checks the scan status before deciding on the next action in the pipeline. You can adjust the following environment variables:

# How often the CI/CD job should check for a status update
ASTRA_JOB_EXIT_REFETCH_INTERVAL=30

#How many times should we check for the status
ASTRA_JOB_EXIT_REFETCH_MAX_RETRIES=50

Example Calculation

If ASTRA_JOB_EXIT_REFETCH_INTERVAL=30 and ASTRA_JOB_EXIT_REFETCH_MAX_RETRIES=50, the pipeline will check for status 50 times with a 30-second interval, totaling 1500 seconds (25 minutes).

You can modify these values as needed to fit your pipeline execution time.

Defining the Exit Criterion (ASTRA_JOB_EXIT_CRITERION)

You can specify a condition for when the pipeline should fail, based on vulnerability severity:

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

This ensures the pipeline fails if any high or critical severity vulnerabilities are found.

Full Example Configuration

By following these steps, your CI/CD pipeline will automatically fail if vulnerabilities meeting the defined severity criteria are detected during the Astra scan.

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"

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