Integrate Security Audit with Azure Pipelines
You can integrate API Contract Security Audit in Microsoft Azure Pipelines through a custom build task in the extension REST API Static Security Testing.
NoteYou 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.
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 your profile.
- Click Settings > API Tokens, and click Create New Token.
- Enter a unique and descriptive name for the token, such as
- In token access rights, select API Contract Security Audit, List Resources, and Delete Resources.
- Click Generate Token.
- Copy the token value, you will need it when you configure the task on the pipeline.
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
- Click the cursor under
stepswhere you want to add the build task, and then find and click on the task called 42CrunchAPI Contract Security Audit.
- Click Variables > New variable.
- Create the variable
42C_API_TOKENwhere 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.
- Choose the API collection where the discovered OpenAPI definitions are stored. By default, the build task will use the repository name combined with the branch name:
You can leave the name as the default one, or enter a name you want.
- If the API collection with the specified name does not exist in your organization in 42Crunch Platform, the build task creates the collection.
- If the API collection with the specified name does already exist, the build task first removes any existing API definitions (along with their IDs) from that collection before storing the discovered OpenAPI definitions in it. Each discovered API definition also gets a new ID on the platform.
- 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 will fail. The default is 75.
- Click Add. The build task is added to your pipeline and you can see its definition under
- 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 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 the specified API collection in 42Crunch Platform:
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 build task
In addition to the basic configuration in
azure-pipelines.yml, you can further refine how your build task works by adding a configuration file to the root of your repository.
- Add a file called
42c-conf.yamlto the root level of your source code repository where the pipeline connects to.
- Open the file for editing and paste in the following sample code:
audit: # map filenames to IDs of APIs already in 42Crunch Platform mapping: foo/bar/petstore-v3.json: a193b82d-5833-47f8-81d2-cfc4fe175914 # define what files to check in discovery phase OpenAPI files # exclude directories from the search # disable the whole discovery phase by specifying 'discovery: false' discovery: search: - '**/*.json' - '**/*.yaml' - '**/*.yml' - '!node_modules/**' # specify more fail conditions to be checked in addition to the minimum score fail_on: # fail if the API does not have a valid OpenAPI definition invalid_contract: true # fail if any issues with the defined severity or higher are detected # possible severity levels: critical, high, medium, low, info severity: medium
mapping, you can map IDs (here
a193b82d-5833-47f8-81d2-cfc4fe175914) of APIs that you have in another API collection in 42Crunch Platform to OpenAPI files in your source code repository (here
foo/bar/petstore-v3.json). When the build runs, this replaces the API definition associated with the mapped ID with the contents of the OpenAPI file from your repository.
NoteMake sure that do not accidentally overwrite things in the API definition you want to keep. If you map a file in your repository to an API ID in 42Crunch Platform, the build will replace all contents in the file associated with that ID. Any changes that are not reflected in the OpenAPI file in your repository are lost from the platform.
The task always cleans the API collection you have specified to be used before starting the discovery phase, so you cannot map APIs in your repository to the IDs in that API collection.
discovery, you can control what kind of files the build checks during the discovery phase:
- By default, the task checks any
.ymlfiles in any directory in your repository for OpenAPI definitions. If all your APIs are in a particular directory, or have a particular name pattern, you can refine the paths in search conditions to match. The task will then only check the defined file paths during the discovery.
- To exclude directories (like directories with plenty of JSON or YAML files that are not API definitions) from the discovery phase, you can list the directories preceded by
!. In the example, the directory
node_modulesis excluded from discovery phase.
- By default, the task checks any
fail_on, you can refine what kind of audit results cause the task to fail:
invalid_contract: By default, this is set to
true. The task fails if any of the audited APIs does not have a valid OpenAPI definition. If you set this to
false, the task allows APIs that do not have a valid OpenAPI definition.
severity: The severity limit for found issues. If the audit finds any issues of this severity or higher, the task fails.
- When you are ready, save the file and push it to your repository.
Pushing changes to your repository triggers your CI/CD pipeline, and you can see how the configuration you added changes the behavior and the results of the build.