Integrate Security Audit with Bitbucket Pipelines
You can integrate API Contract Security Audit in Atlassian Bitbucket Pipelines through a custom pipe REST API Static Security Testing.
NoteYou must have an account in 42Crunch Platform that the pipe in Bitbucket Pipelines can use to access Security Audit. If you do not yet have an account, click here to sign up.
For more details on Bitbucket Pipelines, see Bitbucket 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, the plugin fails and aborts the build, so that bad APIs are not included in your project.
The plugin works in two phases:
- Discovery: The plugin checks your project for any
.ymlfiles. When it finds a file, it checks if the file states that it is an OpenAPI file. If the file is
.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 for CI/CD integration 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. You can either specify a name for the collection yourself, or use the default name (pattern depends on your CI/CD system).
By default, the integration plugin starts with an empty collection. If the API collection with the specified name does not yet exist in your organization in 42Crunch Platform, the plugin creates the collection. This is usually the case when you run the plugin the first time.
To avoid the plugin creating a new API collection each time it runs and flooding your organization with them, on subsequent runs (if/when the API collection with the specified name already exists) the plugin first clears the API collection: The plugin removes any existing API definitions from the collection before uploading the discovered OpenAPI definitions in it. Removing the APIs also removes their API UUIDs, and each discovered API definition gets a new API UUID on the upload platform. This in turn means that any information tied to the API UUIDs, such as previous audit reports, scan reports, or protection configuration and logs, is also removed.
If you would like to retain the history of an API in the platform, you can use add a configuration file
42c-conf.yaml to the root level of your source code repository where the CI/CD pipeline connects to, and map OpenAPI files from your project to API UUIDs of APIs that you have in another API collection in 42Crunch Platform. When the plugin runs, it replaces the contents of the API definition associated with the mapped UUID line by line with the contents of the OpenAPI file from your repository.
In the following example, the file
foo/bar/petstore-v3.json has been mapped to the API UUID
audit: # map filenames to IDs of APIs already in 42Crunch Platform mapping: foo/bar/petstore-v3.json: a193b82d-5833-47f8-81d2-cfc4fe175914
The integration plugin always cleans the API collection it uses for the upload before it starts the discovery phase, so you cannot map APIs from your project to the API UUIDs in that API collection.
Caution Make sure that you do not accidentally overwrite things in the API definition that you would like to keep. If you map a file in your repository to an API UUID in 42Crunch Platform, the plugin will replace all contents in the file associated with that API UUID with the contents of the mapped file 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 pipe
You must add an API token that the pipe uses to authenticate to Security Audit.
- Log in to 42Crunch Platform, and click next to your username.
- Select API 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 Contract 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 a Bitbucket variable for the API token
Before you add the pipe to your Bitbucket pipeline, you must add the API token you created as a secured repository variable.
- Log in to your Bitbucket account, and go to your repository.
- Click > Repository settings > Repository variables.
- Enter the following:
- Value: The value of the API token you created
- Make sure Secured is selected, and click Add.
You have now created the variable that your pipeline can use to authenticate to Security Audit.
Add the pipe to your Bitbucket pipeline
To run the pipe, you must add it to your Bitbucket pipeline.
- In Bitbucket, go to the pipeline you want.
- Open the pipeline configuration file
bitbucket-pipelines.ymlfor editing, and go under
- In Pipelines templates, search for the pipe 42Crunch REST API Static Security Testing, copy the code template, and paste it in your
- Enter the minimum API score that the audited OpenAPI definitions must get from the audit for the pipe to succeed. If any API definitions scores lower than the minimum score you set, the pipe will fail. The default is 75:
- If you want, define the API collection where the discovered OpenAPI definitions are stored. By default, the pipe 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 pipe creates the collection.
- If the API collection with the specified name does already exist, the pipe first removes any existing API definitions (along with their UUIDs) from that collection before storing the discovered OpenAPI definitions in it. Each discovered API definition also gets a new API UUID on the platform.
Caution The plugin always starts by clearing the API collection you specify for it. Removing APIs and their API UUIDS also permanently removes any information tied to the API UUIDs, such as previous audit reports, scan reports, or protection configuration and logs. For more details on how to avoid this, see Mapping OpenAPI files to APIs in the platform.
- Click Commit to save your changes to the pipeline. To test the pipe, run your pipeline.
The pipe will either succeed or fail depending on the minimum score. The summary of the run in the pipeline reports provides you further details on how the job went.
The pipe uploads all discovered OpenAPI definitions to the specified API collection in 42Crunch Platform:
The report of the run includes a link to each discovered API. You can click on the link to view the detailed audit report of the corresponding API in 42Crunch Platform.
You can further fine-tune how the integration plugin works by adding a configuration file called
42c-conf.yaml to the root level of your source code repository where the CI/CD pipeline connects to. For example:
- Map OpenAPI files to API UUIDS of APIs in the platform.
fail_onconditions to define what the plugin reports as failures.
- Control what happens in the discovery phase.
For more details, see the configuration examples in our Resources repository in GitHub.