CI/CD integration

You can integrate API Security Audit and API Scan with your CI/CD pipeline using the REST API Static Security Testing plugin to automate checking and testing API definitions from a simple Git push to your project repository. This safeguards the quality of the API definitions in your project and mitigates potential security issues, as any new files or changes that developers check in are continuously audited.

The integration plugin REST API Static Security Testing is available off-the-shelf for the following CI/CD solutions:

Azure Pipelines
Bamboo (API Scan and GraphQL are not yet supported)
Bitbucket Pipelines
GitHub Actions
GitLab Pipelines
Jenkins
Tekton

REST API Static Security Testing is also available as a generic Docker image.

You can find links to more details for all supported options from the 42Crunch Platform landing page.

Screenshot of the available integrations on the platform home page

Despite the name, you can use REST API Static Security Testing for both OpenAPI and GraphQL APIs, and for both audits (static) and scans (dynamic). GraphQL federation is not supported in CI/CD integration.

How the Security Audit integration works

CI/CD integration uses the REST API Static Security Testing plugin that adds the required build tasks or jobs to your CI/CD pipeline. The plugin checks the quality of the OpenAPI and GraphQL files present in your project. If the detected APIs do not meet the criteria you define in the plugins or in your security quality gates (SQGs) in 42Crunch Platform, the plugin fails and aborts the build, so that bad APIs are not included in your project.

The audit task has two phases:

Discovery: The task in your CI/CD pipeline checks your project for any OpenAPI definitions (.json, .yaml, and .yml) and GraphQL files (.graphql, .graphqls, .gql, .gqls, .sdl). For OpenAPI definitions, if the file is .yaml or .yml, it is automatically converted to JSON. The discovered APIs are automatically uploaded to an API collection in 42Crunch Platform.
Audit: Security Audit audits the uploaded APIs for their well-formedness and security. If the quality of the APIs meets your criteria, the task or job ends with a success, if they do not, the task fails. Your CI/CD pipeline processes the result as you have defined and the continues to the next task or job.

The plugin uses API tokens with specific access rights (scopes) to access 42Crunch Platform.

When the integration plugin runs, it uploads the API definitions it finds during the discovery phase to a particular API collection in your organization in 42Crunch Platform. By default when running on branch, the plugin uses the naming convention <shortened-source-control-uri> Branch:<branch-name> for the created API collection, for example, 42Crunch/sample Branch:sample.

On subsequent runs, the plugin synchronizes the contents of the API collection with the APIs in your source control repository:

APIs added to your repository are added to the collection.
APIs removed from your repository are removed from the collection
APIs found both in your repository and in the collection retain their API UUIDs in 42Crunch Platform but their contents are replaced with the contents of the files in your repository

Make sure that you do not accidentally overwrite things in the API definition that you would like to keep. The plugin will replace all contents in the APIs in 42Crunch Platform with the contents of the API files in your repository. Any changes that are not reflected in the OpenAPI file in your repository are lost from the platform.

For audit runtime, REST API Static Security Testing always connects to 42Crunch Platform. This allows the plugin to directly upload all API definitions it discovers to API collections in the platform.

How the API Scan integration works

In addition to importing and auditing API definitions, you can also automate scanning the discovered API definitions with the scan task.

The scan generates real traffic to the selected API endpoint and could incur costs depending on your setup.

For best results, make sure that your API definition is valid and well-formatted before you scan it. The API must be deployed so that the API endpoint is live, and the backend server your API uses must be accessible to API Scan. Otherwise the API cannot be scanned.

API Scan can have potential side effects: APIs can throw exceptions, fail, and data can be affected. As per our terms and conditions, you must only run invasive scans, such as conformance scan and fuzzing requests, against APIs that you own, and only against non-production systems and non-production data! Do not run other scan types except the non-invasive drift scan in production environment!

The REST API Static Security Testing plugin locates the APIs on the 42Crunch Platform, and uses the existing reference scan configuration (or creates one) for each API to run API Scan on it. When the scan finishes, the plugin uploads the scan report to the platform and checks the scan SQG to determine if the task on the pipeline should pass or fail.

The scan task on your pipeline depends on the audit task: while you can choose to only integrate Security Audit without API Scan to your CI/CD, you cannot integrate API Scan without Security Audit. As the scan task relies on the audit task to discover the APIs to be scanned, it must come after the audit task on your pipeline.

For scan runtime, REST API Static Security Testing always uses the 42Crunch API Security Testing, running on-premise scan in Docker or Scan Jobs Manager is not supported in the plugin.

Drift scan is not currently supported in CI/CD integration.

Further configuration with 42c-conf.yaml

You can further fine-tune how the CI/CD integration works by adding a configuration file called 42c-conf.yaml to the root directory of your source code repository where the CI/CD pipeline connects to. You can, for example:

Configure the plugin to run in the collection mode, applying predefined settings and sharing with teams in your organization on any API collections that it creates.
Control what happens in the discovery phase.
Map API definitions in your repository to API UUIDs of APIs in the platform.
Specify fail_on conditions to define what the plugin reports as failures in audit.
The fail-on criteria you set for audit in the CI/CD plugin, such as the minimum score, are independent from the acceptance criteria defined in security quality gates (SQGs). This means that your CI/CD build can fail either because the criteria of the plugin are not met, the criteria of a SQG are not met, or both.

You can specify different configurations for different branches, tags, or even pull requests. For more details, see the configuration examples in our Resources repository in GitHub.

What is...

Security quality gates