Integrate Security Audit with Bamboo

You can integrate API Security Audit in Atlassian Bamboo through the app REST API Static Security Testing.

You 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.

Create an API token for the app

You must add an API token that the Bamboo plan 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 the API token in global variables

Your Bamboo plan must authenticate to 42Crunch Platform to run Security Audit. You can add the API token you just created as a global variable in Bamboo and use it when you configure your Bamboo plan.

  1. Log in to your Bamboo account, and click > Bamboo administration > Global variables.
  2. Enter a variable name (such as SECRET_42C_API_TOKEN).
  3. Add the API token as the value for the global variable, and click Add.

The API token is now added to your global variables in Bamboo and your Bamboo plan can 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.

  1. 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.
  2. Go to the Bamboo project and the plan that you want, and click Actions > Configure plan.
  3. Click the job you want to integrate with API Security Audit, and add the task REST API Static Security Testing.

  4. Set API token to access 42Crunch Platform to the global Bamboo variable you added.

    An example screenshot showing the task configuration.

  5. Enter the minimum audit score that the audited OpenAPI definitions must get from the audit for the task to succeed. If any API definitions score lower than the minimum score you set, the task fails. The default is 75.
  6. 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.
  7. Set the level of detail (FATAL, ERROR, WARN, INFO, DEBUG) for the logs that the task produces.
  8. Select if you want to automatically share any new API collections that the task creates with other users in your organization (off by default). You can also change the sharing of the API collections later.
  9. Click Save to finish configuring the task. To test the integration, run your Bamboo plan.

The task either succeeds or fails depending on the minimum score. The plugin also automatically checks the status of all SQGs applied to the APIs it found in the repository. If any of the SQGs fails, the build automatically fails too.

In either case, the task uploads all discovered OpenAPI definitions to an API collection in 42Crunch Platform. By default when running on branch, the plugin uses the naming convention <shortened-source-control-uri> Branch:<branch-name> for the created API collection, for example, 42Crunch/sample Branch:sample.

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

The Bamboo app uses the build variables bamboo.planRepository.repositoryUrl and bamboo.planRepository.branchName 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 summary of the build provides you further details on the issues that the task found. 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.

A screenshot of a job log. The log shows the URLs to the audit reports of the discovered APIs.

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:

An example screenshot of a build result summary in Bamboo.

These failures are also automatically added to tests in your build job:

A screenshot of the tests added for two APIs that failed the build task.

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 works by adding a configuration file called 42c-conf.yaml to the root directory of your source code repository where the CI/CD pipeline connects to. You can, for example:

  • Map OpenAPI files in your repository 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 configurations for different branches, tags, or even pull requests. For more details, see the configuration examples in our Resources repository in GitHub.

Configurations for branches and tags is matched based on the name of the branch or tag. Configurations for pull requests is matched based on the target branch.

Change the default collection name

By default when running on branch, the plugin uses the naming convention <shortened-source-control-uri> Branch:<branch-name> for the created API collection, for example, 42Crunch/sample Branch:sample. However, you can specify a different syntax for the new collections that the plugin uses by default.

  1. Go to the pipeline you want and open the settings of the integration plugin for editing.
  2. In Default collection name, enter the syntax for the default collection name you want to use. You can use text (like foo), reference to variables (${repository}), or a combination of the two (foo ${repository}). You can use the following variables that are populated from your repository details:
    • repository: The full repository URL.
    • repo_short_path: A shortened path of the repository URL (the leading / and the trailing .git are omitted).
    • repo_hostname: The hostname from the repository URL.
    • branch_info:The syntax Branch:<branch name>, or an empty string if this information is not available.
    • tag_info: The syntax Tag:<tag name>, or an empty string if this information is not available.
    • pr_info: The syntax PR:<pr id>, or an empty string if this information is not available.
  3. When ready, save your changes.

Next time you run the pipeline, the integration plugin uses the syntax you defined and creates new API collections in 42Crunch Platform (if collections with the same names do not yet exist) where it loads the discovered APIs.

You can also define collection names for specific branches, tags, and pull requests using the property collection_name in the configuration file 42c-conf.yaml.

Set the root directory for the plugin

By default, the integration plugin uses the root directory of your repository as its starting point. However, you can also set a specific directory that the plugin will use as its root.

If you have configured 42c-conf.yaml for your plugin, make sure it is located in the root directory that you want the plugin to use. Otherwise, the configuration file is ignored.

  1. Go to the CI/CD pipeline you want and open the settings of the integration plugin for editing.
  2. In Root directory, enter the path of the directory you want to use as the root directory.
  3. Save your changes.

Next time you run the pipeline, the integration plugin will start the discovery phase from the directory path you defined and check that directory and any subdirectories under it for OpenAPI files.