Integrate Security Audit with Bitbucket Pipelines

You can integrate API Security Audit in Atlassian Bitbucket Pipelines through a custom pipe REST API Static Security Testing.

You 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 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:
    • Name: SECURED_42C_API_TOKEN
    • 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 fails. The default is 75:
    script: # Modify the commands below to build your repository.
        - npm install
        - npm test
        - pipe: 42crunch/api-security-audit:2.0.0
            variables:
                MIN_SCORE: "85"
  5. 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.
    script: # Modify the commands below to build your repository.
        - npm install
        - npm test
        - pipe: 42crunch/api-security-audit:2.0.0
            variables:
                MIN_SCORE: "85"
                PLATFORM_URL: https://<your platform URL here>
  6. By default, the level of detail in the logs that the pipe produces is INFO. If you want more or less detail, you can use log-level to specify the level of detail. The possible values are FATAL, ERROR, WARN, INFO, DEBUG):
    script: # Modify the commands below to build your repository.
        - npm install
        - npm test
        - pipe: 42crunch/api-security-audit:2.0.0
            variables:
                MIN_SCORE: "85"
                LOG_LEVEL: DEBUG
  7. If you want to automatically share any new API collections that the pipe creates with other users in your organization, add the variable SHARE_EVERYONE. The variable has two possible values:
    • READ_ONLY: Other users have read-only access
    • READ_WRITE: Other users have also write access

    If you do not define SHARE_EVERYONE at all, the API collections are not shared and remain private to you.

    script: # Modify the commands below to build your repository.
        - npm install
        - npm test
        - pipe: 42crunch/api-security-audit:2.0.0
            variables:
                MIN_SCORE: "85"
                LOG_LEVEL: DEBUG
                SHARE_EVERYONE: READ_ONLY

    You can also change the sharing of the API collections later. For more details, see Sharing APIs and access level.

  8. 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 plugin uses the naming convention repository path--branch name for the created API collection, for example, https://github.com/42Crunch/sample--sample. The exact name and pattern depends on your CI/CD system.

An example screenshot showing the collection the build task created in 42Crunch Platform.

The Bitbucket pipe uses the build variables BITBUCKET_REPO_FULL_NAME and BITBUCKET_BRANCH to get the details directly from your source control.

The API definitions in the collection show the filepaths they have in the repository:

The example screenshot shows the Petstore API imported to 42Crunch Platform from CI/CD, showing the filepath the API definition file has in the repository.

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.

You can specify different plugin configurations for different branches. For more details, see the configuration examples in our Resources repository in GitHub.