Integrate Security Audit with SonarQube

You can integrate API Security Audit with SonarQube through the plugin REST API Static Security Testing.

Create an API token for SonarQube

You must add an API token that the plugin 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.

You must have an account in 42Crunch Platform that the SonarQube plugin can use to access Security Audit. If you do not yet have an account, click here to sign up.

Add the SonarQube plugin

Before you start, make sure you have already installed SonarQube and run it at least once. For more details on SonarQube, see SonarQube documentation.

  1. Log in to your SonarQube account and install the plugin REST API Static Security Testing from our GitHub repository. This needs to be done only once for each server: once the plugin is installed, it is applied to all SonarQube projects on your SonarQube server.
  2. Restart SonarQube, and click Administration > OpenAPI. The configuration tab for the plugin opens.

    An example screenshot of the configuration tab of the SonarQube plugin.

  3. In API token, add the value of the API token you created for the plugin, and click Save.

    Screenshot of adding the API token. The value of the previously created API token is pasted to the text field but hidden.

  4. 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.
  5. Go to Projects, and check that you have at least one SonarQube project. If you do not have any SonarQube projects, click , and follow the instructions to create one.
  6. Run SonarQube.

The REST API Static Security Testing plugin will run OpenAPI analysis on the as part of SonarQube analysis. By default, the plugin is automatically applied to each SonarQube project on the server. Click on a project to view the summary of the analysis:

An example screenshot of the overview of a SonarQube project.

The number of issues and ratings apply to the whole SonarQube project, not individual OpenAPI files. Issues in the OpenAPI format requirements are flagged as bugs. Issues in data definition quality and security of your APIs are flagged as vulnerabilities. The Issues view gives you a more detailed report:

The tags on the issues show which version of the OpenAPI Specification (OAS) the issue applies to, v2 or v3. If you click See Rule (or Why is this an issue? on the newer SonarQube UI), you can view the issue details and suggested remediation for it.

Fine-tune the plugin

You can further refine how the REST API Static Security Testing plugin works.

  1. In SonarQube, go to Administration > OpenAPI.
  2. If you have plenty of JSON or YAML files that are not API definitions, you can list the directories and filepaths you want to exclude from the discovery phase in Excluded filepaths.

    An example screenshot of excluded filepaths, default exclusions listed.

  3. By default, the plugin checks any .json, .yaml, and .yml files in for OpenAPI definitions. You can change which files types are checked during the discovery phase in OpenAPI file suffixes. The plugin will then only check the defined file types during the discovery.
  4. Save your changes and re-run SonarQube.

You can see how the configuration you added changes the behavior and the results of the SonarQube analysis.

Configure custom quality gate for the plugin

You can configure a custom quality gate with specific fail-on conditions and apply it to your SonarQube project to change how the plugin works. For example, you could define a minimum score that the discovered APIs must get for the quality gate to pass.

  1. In SonarQube, go to Quality Gates, and click Create.
  2. Enter a name for your quality gate, and click Create.
  3. Select to apply conditions On Overall Code. The REST API Static Security Testing plugin does not differentiate between existing unchanged code and new or changed code when it runs, so you cannot apply its fail-on conditions to new code only.
  4. Add the fail-on conditions that you want. The plugin offers three metrics that you can configure, all listed under Security:
    • Audit Score: The total audit score of your API (max. 100 points)
    • Audit Score (data): Audit score from the subcategory of data validation (max. 70/100 points)
    • Audit Score (security): Audit score from the subcategory of security analysis (max. 30/100 points)

    An example screenshot on configuring the fail on conditions showing the metrics specific to the REST API Static Security Testing plugin in the metrics dropdown. Above the dropdown, the radio button "On Overall Code" is selected.

    The quality gate automatically saves your changes as you make them.

  5. Once your custom quality gate is ready, go to the SonarQube project where you want to apply it, and click Project Settings > Quality Gate.
  6. Select Always use a specific Quality Gate, and select your custom quality gate.
  7. Save your changes and re-run SonarQube to verify them.

Stop Security Audit running on a SonarQube project

By default, when you install the REST API Static Security Testing plugin, it is applied to all SonarQube projects on your SonarQube server. However, if you have some SonarQube projects that you want to exclude from the plugin, you can switch Security Audit off in the project settings.

  1. Go to the SonarQube project you want, and click Project Settings > General Settings > OpenAPI.
  2. Switch on the setting Switch audit off.

    An example screenshot on the setting to switch Security Audit off in the SonarQube project settings.

  3. Save your changes and re-run SonarQube to verify them.

You can also configure other settings, such as which files to include or filepaths and directories to exclude, independently for each project as required.