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.

Create an API token for the pipe

You must add an API token that the pipe uses to authenticate to Security Audit.

  1. Log in to 42Crunch Platform, and click next to your username.
  2. Select API Tokens, and click Create New Token.
  3. Enter a unique and descriptive name for the token, such as Security Audit token.
  4. In token access rights, select API Contract Security Audit, List Resources, and Delete Resources.

    A screenshot of Create API Token Wizard with the required access rights marked as selected.

  5. Click Generate Token.
  6. Copy the token value, you will need it when you configure REST API Static Security Testing.

    Create API Token Wizard showing the generated token and the buttons for showing the token value and copying it.

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.

  1. Log in to your Bitbucket account, and go to your repository.
  2. Click > Repository settings > Repository variables.
  3. Enter the following:
    • Value: The value of the API token you created
  4. Make sure Secured is selected, and click Add.

    An example screenshot of adding a secured repository variable in Bitbucket. The API token is shown as dots in the value field.

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.

  1. In Bitbucket, go to the pipeline you want.
  2. Open the pipeline configuration file bitbucket-pipelines.yml for editing, and go under script.
  3. In Pipelines templates, search for the pipe 42Crunch REST API Static Security Testing, copy the code template, and paste it in your bitbucket-pipelines.yml.

    An example screenshot from Bitbucket showing adding the pipe to the Bitbucket pipeline.

  4. 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:

    An example screenshot showing defining a new minimum score for the pipe. Variable MIN_SCORE with the value of 85 has been added in the variables of the pipe.

  5. 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:

    An example screenshot showing defining a new minimum score for the pipe. Variable COLLECTION_NAME with the value of "Test Collection" has been added in the variables of the pipe.

    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.

  6. 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:

An example screenshot showing the collection the build task created 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.

A screenshot of a report of the pipe run. The report shows the links to the audit reports of five APIs that the pipe discovered and audited.

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.
  • Specify fail_on conditions 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.