Integrate Security Audit with Bamboo
You can integrate API Contract Security Audit in Atlassian Bamboo through the app REST API Static Security Testing.
NoteYou must have an account in 42Crunch Platform that the app in your Bamboo plan can use to access Security Audit. If you do not yet have an account, click here to sign up.
For more details on Bamboo, see Bamboo 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 app
You must add an API token that the Bamboo plan 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 the API token in Bamboo credentials
Before you add the task to your Bamboo plan, you must add the API token you created to your Bamboo credentials.
- Log in to your Bamboo account, and click > Bamboo administration > Shared credentials.
- Click Add new credentials > Username and password.
- Enter a name and username for the credential and set the value of the API token as the password.
- Click Save credentials.
You now have credentials that your Bamboo plan can use to authenticate to Security Audit.
Configure the Bamboo plan
To integrate Security Audit with Bamboo, you must add the app REST API Static Security Testing to your Bamboo server and add a task in your Bamboo plan.
- If your Bamboo server does not yet have the app REST API Static Security Testing installed, install it from Atlassian Marketplace. This needs to be done only once for each Bamboo server.
- Go to the Bamboo project and the plan that you want, and click Actions > Configure plan.
- Click the job you want to integrate with API Contract Security Audit, and add the task REST API Static Security Testing.
- Set API token to access 42Crunch Platform to the credential you added in Bamboo credentials.
- Choose the API collection where the discovered OpenAPI definitions are stored. By default, the task will use the plan 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 API 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.
- Enter the minimum API score that the audited OpenAPI definitions must get from the audit for the task to succeed. If any API definitions scores lower than the minimum score you set, the task will fail. The default is 75.
- Click Save to finish configuring the task. To test the integration, run your Bamboo plan.
The task will either succeed or fail depending on the minimum score. The summary of the build provides you further details. In either case, 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.
If the build fails because one or more APIs do not meet the criteria you set, these APIs are shown as failures is the build summary:
These failures are also automatically added to tests in your build job:
As issues found in the audit are fixed in the API definitions so that they pass your criteria, they are moved from failed tests to passed tests in the job. This makes it easy to keep track of progress and spot regressions.
For a practical example, check out the following video on configuring the REST API Static Security Testing task for a Bamboo plan:
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.