Summary

Astra’s CI/CD integration is a production-ready solution designed to embed security scans directly into your development pipeline. It provides flexible control over how your pipeline responds to scan outcomes through a set of customizable environment variables, allowing you to maintain security without sacrificing deployment speed.

The primary value of the Astra CI/CD integration is its ability to transform security from a manual hurdle into an automated validation step. By configuring specific audit modes and exit strategies, teams can ensure that code updates are continuously checked for vulnerabilities, ranging from high-level misconfigurations to critical logic flaws.

Who Should Read This

• DevOps Engineers: To automate security feedback loops and configure pipeline failure conditions.

• Security Engineers: To ensure consistent scanning depth (e.g., Full vs. Lightning) across different stages of development.

• Developers: To understand how to interpret pipeline results and remediate findings identified during the build process.

Key Functions - Core Configuration Variables

To control scan behavior, you must define the following variables within your CI/CD tool’s UI or configuration files (e.g., .gitlab-ci.yml, Jenkinsfile):

• Scan Mode (ASTRA_AUDIT_MODE):

  • automated (Default): Fully automated scan for continuous security validation.

  • manual: Triggers a hybrid assessment involving Astra's security engineers.

  • web_crawl: Performs asset discovery and application mapping without security tests.

• Automated Scan Type (ASTRA_SCAN_TYPE):

  • lightning (Default): Subset of critical tests optimized for fast feedback during every run.

  • full: Comprehensive testing of all endpoints, best suited for nightly builds or pre-release.

  • emerging_threat: Focused on high-impact, newly discovered vulnerabilities (e.g., Log4Shell).

  • secret_scanning: Specifically detects committed secrets (keys, tokens) in the repository.

• Inventory Coverage (ASTRA_SCAN_INVENTORY_COVERAGE):

  • full: Scans the entire known inventory.

  • delta: Scans only newly discovered or changed endpoints since the last assessment.

Job Exit Strategy and Performance

The ASTRA_JOB_EXIT_STRATEGY variable determines how the pipeline behaves after a scan is triggered:

• always_pass: Triggers the scan and returns success immediately; best for non-blocking asynchronous tasks.

• fail_when_vulnerable: The pipeline fails if security findings meet your defined criteria.

• wait_for_completion: The pipeline waits for the scan to finish before proceeding, regardless of results.

For waiting modes, Astra enforces a soft limit of 10 minutes by default to prevent holding jobs indefinitely. You can tune the polling behavior using ASTRA_JOB_EXIT_REFETCH_INTERVAL (seconds between checks) and ASTRA_JOB_EXIT_REFETCH_MAX_RETRIES.

Defining Failure Criteria

You can specify exactly when a build should break using ASTRA_JOB_EXIT_CRITERION. For example, to fail only on high or critical findings: ASTRA_JOB_EXIT_CRITERION="severityCount[\\\"high\\\"] > 0 or severityCount[\\\"critical\\\"] > 0".

Best Practices

• Fast Feedback: Use lightning scans and delta coverage during standard CI/CD runs to maintain speed.

• Comprehensive Checks: Run full scans on a nightly schedule or prior to major production releases.

• Asynchronous Crawling: Web crawling can take up to an hour; do not wait for this step in your CI/CD pipeline. Instead, set the crawl to always_pass and follow up with a delta scan for modified endpoints.

• Secret Detection: Always include a secret_scanning step to prevent sensitive tokens from being pushed to your repository.

Supported Integrations

Astra provides pre-configured steps for the following platforms:

• GitHub, GitLab, Jenkins, Bitbucket, Azure Pipelines, and CircleCI.

• Generic support is available for other tools via CURL-based API calls.