Integrate Security Audit with Azure Pipelines
You can integrate API Security Audit in Microsoft Azure Pipelines through a custom build task in the extension REST API Static Security Testing.
You must have an account in 42Crunch Platform that the build task in Azure Pipelines can use to access Security Audit. If you do not yet have an account, click here to sign up.
For more details on Azure Pipelines, see Azure Pipelines documentation.

Security Audit is integrated through a plugin that adds a build task or job to your CI/CD pipeline. The plugin checks the quality of the OpenAPI 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 in 42Crunch Platform, the plugin fails and aborts the build, so that bad APIs are not included in your project.
The CI/CD plugin works in two phases:
- Discovery: The plugin checks your project for any
.json
,.yaml
, and.yml
files. When it finds a file, it checks if the file states that it is an OpenAPI file. 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.
Create an API token for the build task
You must add an API token that the build task uses to authenticate to Security Audit.
- Log in to 42Crunch Platform, and click next to your username.
- Select Tokens, and click Create new token.
- Enter a unique and descriptive name for the token, such as
Security Audit token
. - In token access rights, select API Security Audit, List resources, and Delete resources.
- Click Generate token.
- Copy the token value, you will need it when you configure REST API Static Security Testing.
Add the build task to your Azure pipeline
To run the build task, you must add it to your Azure pipeline.
- Log in to your Azure DevOps account.
- If your organization in Azure DevOps does not yet have the extension REST API Static Security Testing installed, install it from Visual Studio Marketplace. This needs to be done only once for each organization: once the task is installed, it is available for the whole organization.
- Go to the pipeline where you want to add the build task, and click Edit. The file
azure-pipelines.yml
opens. - Click the cursor under
steps
where you want to add the build task, and then find and click on the task called 42Crunch API Security Audit. - Click Variables > New variable, and create the variable
42C_API_TOKEN
where the value is the API token you created for the build task, and mark it as a secret, then click OK. The token is stored in the secrets of your Azure pipeline. - Enter the minimum API score that the audited OpenAPI definitions must get from the audit for the build task to succeed. If any API definitions scores lower than the minimum score you set, the build task fails. The default is
75
.The fail-on criteria you set 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.
- If you are an enterprise customer not accessing 42Crunch Platform at
https://platform.42crunch.com
, enter your platform URL. This step is optional and most users do not have to do this. If you are not sure what your platform URL is, contact our support. - Set the level of detail (
FATAL
,ERROR
,WARN
,INFO
,DEBUG
) for the logs that the task produces. - Select if you want to automatically share any new API collections that the build task creates with other users in your organization (off by default). You can also change the sharing of the API collections later in 42Crunch Platform.
You cannot share API collections if your account belongs to the free community organization. In this case, make sure this setting is off.
- Click Add. The build task is added to your pipeline and you can see its definition under
steps
inazure-pipelines.yml
. - Click Save to save your changes to the pipeline. To test the build task, run your Azure pipeline.
The build task will either succeed or fail depending on the minimum score. The plugin also automatically checks the status of all SQGs applied to the APIs it found in the repository. If any of the SQGs fails, the build automatically fails too. The summary of the run in the pipeline jobs provides you further details on how the job went.
The task uploads all discovered OpenAPI definitions to an API collection 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
.
The build task uses the build variables Build.Repository.Uri
and Build.SourceBranch
to get the details directly from your source control.
The API definitions in the collection show the filepaths they have in the repository:
The logs of the run include the URL of each discovered API in the platform. You can copy the URL and paste it to your browser to view the detailed audit report of the corresponding API.
Fine-tune the plugin configuration
You can further fine-tune how the 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:
- Map OpenAPI files in your repository to API UUIDs of APIs in the platform.
- Specify
fail_on
conditions to define what the plugin reports as failures.The fail-on criteria you set 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.
- Control what happens in the discovery phase.
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.
Configurations for branches and tags is matched based on the name of the branch or tag. Configurations for pull requests is matched based on the target branch.
Change the default collection name
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
. However, you can specify a different syntax for the new collections that the plugin uses by default.
- Go to the pipeline you want and open the settings of the integration plugin for editing.
- In Default collection name, enter the syntax for the default collection name you want to use. You can use text (like
foo
), reference to variables (${repository}
), or a combination of the two (foo ${repository}
). You can use the following variables that are populated from your repository details:repository
: The full repository URL.repo_short_path
: A shortened path of the repository URL (the leading/
and the trailing.git
are omitted).repo_hostname
: The hostname from the repository URL.branch_info
:The syntaxBranch:<branch name>
, or an empty string if this information is not available.tag_info
: The syntaxTag:<tag name>
, or an empty string if this information is not available.pr_info
: The syntaxPR:<pr id>
, or an empty string if this information is not available.
- When ready, save your changes.
Next time you run the pipeline, the integration plugin uses the syntax you defined and creates new API collections in 42Crunch Platform (if collections with the same names do not yet exist) where it loads the discovered APIs.
You can also define collection names for specific branches, tags, and pull requests using the property collection_name
in the configuration file 42c-conf.yaml
.
Next time you run the pipeline, the integration plugin will start the discovery phase from the directory path you defined and check that directory and any subdirectories under it for OpenAPI files.
Set the root directory for the plugin
By default, the integration plugin uses the root directory of your repository as its starting point. However, you can also set a specific directory that the plugin will use as its root.
If you have configured 42c-conf.yaml
for your plugin, make sure it is located in the root directory that you want the plugin to use. Otherwise, the configuration file is ignored.
- Go to the CI/CD pipeline you want and open the settings of the integration plugin for editing.
- In Root directory, enter the path of the directory you want to use as the root directory.
- Save your changes.
Next time you run the pipeline, the integration plugin will start the discovery phase from the directory path you defined and check that directory and any subdirectories under it for OpenAPI files.
Use SQG criteria instead of plugin configuration
By default, the integration plugin configuration defines when the CI/CD task passes or fails, and there are some default values that the plugin uses if nothing else is specified. However, if you are using security quality gates (SQGs) in 42Crunch Platform for quality control, you might prefer SQGs to determine when the CI/CD task passes or fails. In this case, you can set the plugin to skip the locally defined fail-on conditions (such as minimum score, format validity, or forbidden issues) and only use those defined in the SQGs.
- Go to the CI/CD pipeline you want and open the settings of the integration plugin for editing.
- In Skip local checks, type
true
, and save your changes.
Next time you run the pipeline, the plugin will only check the status of all SQGs applied to the APIs it found in the repository when deciding if the build passes or fails, and ignore any fail-on conditions defined in the plugin itself, including the default plugin configuration.
Stop the plugin from failing a pipeline
Sometimes you might want the CI/CD plugin just to report the found issues, not block the pipeline from continuing. For example, your repository might have plenty of APIs in early stages of their lifecycle, or you have just introduced the CI/CD plugin to the pipeline and need time to adjust to the set quality criteria. In this case, you can temporarily switch off all fail-on conditions that the CI/CD plugin would impose on a CI/CD job. The plugin keeps reporting on the discovered APIs but does not block the pipeline from proceeding to subsequent stages.
Switching off the fail-on conditions in the CI/CD plugin means that the plugin will cease to work as a quality control as it will never prevent potential problems in your APIs. We recommend that you use this option only after a careful consideration and only for a limited time. Remember to remove this setting from the plugin as soon as possible.
- Go to the CI/CD pipeline you want and open the settings of the integration plugin for editing.
- In Ignore failures, type in
true
, and save your changes.
Next time you run the pipeline, the integration plugin runs normally, uploading each discovered API definition and its audit report to 42Crunch Platform, but does not fail the CI/CD job because of the audit results or SQG status. However, the plugin still produces logs as per usual, so you can check them to see the status of the discovered APIs.
Ignore network errors
If you are worried that issues in connectivity — such as in the rare case of the CI/CD plugin not being able to communicate to 42Crunch Platform — could unduly hinder an important CI/CD pipeline by causing it to fail, you can set the plugin to ignore connectivity issues.
Setting the CI/CD plugin to ignore network errors lessens the plugin's effectivity as a quality control, because the task does not stop the CI/CD pipeline even though it could not complete successfully due to a connectivity issue. This means that APIs that have quality or security issues in their OpenAPI definitions could slip through upon a successful CI/CD job. We recommend that you use this option only after a careful consideration.
- Go to the CI/CD pipeline you want and open the settings of the integration plugin for editing.
- In Ignore network errors, type in
true
, and save your changes.
Next time you run the pipeline, if the integration plugin encounters a connectivity issue, it does not fail the CI/CD job and the pipeline proceed to subsequent steps. Errors that cannot be definitively deemed to be connectivity issues will still cause the plugin to fail the job. You can check the logs that the plugin produces to see if any errors occurred.
What is...
How to...
Integrate CI/CD solutions with 42Crunch Platform
Integrate Security Audit with Bamboo
Integrate Security Audit with Bitbucket Pipelines
Integrate Security Audit with CI/CD using a Docker image
Integrate Security Audit with GitHub Actions