Integrate Security Audit with Jenkins

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

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

Before you start, make sure that your Jenkins version is the same or newer than the minimum compatible version. If you are installing the integration plugin manually, not using the Update Center, make sure that you also install the dependencies.

For more details on Jenkins, see Jenkins User Documentation.

Create an API token for the Jenkins job

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

  1. Log in to 42Crunch Platform, and click next to your username.
  2. Select Tokens, and click Create new token.
  3. Enter a unique and descriptive name for the token, such as Security Audit token.
  4. Make sure the token type is API token, and 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 Jenkins credentials

Before you add the task to your Jenkins job, you must install the plugin and add the API token you created to your Jenkins credentials.

Installing the integration plugin also installs the credential type that the plugin uses for authentication, and in most cases no action is needed from you. However, if you have chosen to use credential types selectively on your Jenkins, you must enable this credential type for the plugin to work. After you have installed the plugin, go to Manage Jenkins > Configure Credential Providers, and make sure that the credential type 42Crunch API Token is enabled.

  1. Log in to your Jenkins account.
  2. If your Jenkins server does not yet have the REST API Static Security Testing plugin installed, install it from Jenkins Update Center. This needs to be done only once for each Jenkins server.
  3. Go to Manage Jenkins > Manage Credentials.
  4. Go to the domain you want and click Add Credentials.
  5. Set the following:
    • Kind: Select 42Crunch API Token.
    • ID: Enter a name for the credential. If you configure the Jenkins job using Jenkinsfile, this is the value you will use.
    • Description: Enter a description for the credential. If you configure the Jenkins job on the UI, this is the value you will use.
    • API Token: Enter the value of the API token you created for the Jenkins job.

    An example screenshot on adding the credential for the Jenkins job.

  6. Click OK.

The API token is added to your Jenkins credentials, and you can use it when you configure your Jenkins job.

Configure the Jenkins job

To integrate Security Audit with Jenkins, you must configure a build step in your Jenkins job.

To test integration, run your Jenkins pipeline. The build step will either succeed or fail 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. The summary of the run in the pipeline jobs provides you further details how the job went.

The build step uploads all discovered OpenAPI definitions to the specified 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 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 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 for the audit phase of the build task. The log shows the URLs to the audit reports of APIs that the build task discovered and audited.

Write summary of the plugin run in a file

If you want, you can set the plugin to write and store a report on the plugin run as a JSON file, so that it is easy, for example, to see and communicate the API UUIDs of the uploaded APIs.

This is not the audit report that provides details on the issues that Security Audit found in your APIs and how to remediate them, but a separate, optional summary providing some basic details on the APIs that the plugin processed. The full audit reports are not included in this summary, but are available in 42Crunch Platform.

Next time you run the pipeline, the integration writes a summary report as a JSON file in the location you specified. This report shows the details on discovered, such as:

  • Filename
  • API UUID assigned for the API when it was uploaded to 42Crunch Platform
  • Audit score
  • Did the pipeline task fail and if yes, why
  • Any errors that occurred when processing the API

Fine-tune the plugin configuration

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.

    The fail-on criteria you set in the CI/CD plugin, such as the minimum score, are independent from the acceptance criteria defined in security quality gates (SQGs). This means that your CI/CD build can fail either because the criteria of the plugin are not met, the criteria of a SQG are not met, or both.

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

Configure the integration to use HTTP or HTTPS proxy server

REST API Static Security Testing is powered by Security Audit and connects to 42Crunch platform when it runs. This is not an issue as long as your Jenkins runs on a machine with direct Internet access. However, if you Jenkins is behind an HTTP or HTTPS proxy server, additional configuration is needed.

  1. Find out and make a note of the address and port of your proxy server.
  2. In Jenkins, go to Manage Jenkins > Manage Plugins > Advanced.
  3. Fill in the following settings:
    • Server: Host name or address of the proxy server (like or
    • Port: The port that the proxy server listens on (for example, 8090)

  4. Click Submit.

Your proxy server configuration is saved. Any new jobs will use it when they run, and REST API Static Security Testing will report that it is using the proxy. If there is something wrong with your proxy configuration, the plugin will fail because requests are not going through.

For more details, see Jenkins Wiki.

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.

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.

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.

Use SQG criteria instead of plugin configuration

By default, the integration plugin configuration defines when the CI/CD task passes or fails, and there are some default values that the plugin uses if nothing else is specified. However, if you are using security quality gates (SQGs) in 42Crunch Platform for quality control, you might prefer SQGs to determine when the CI/CD task passes or fails. In this case, you can set the plugin to skip the locally defined fail-on conditions (such as minimum score, format validity, or forbidden issues) and only use those defined in the SQGs.

Next time you run the pipeline, the plugin will only check the status of all SQGs applied to the APIs it found in the repository when deciding if the build passes or fails, and ignore any fail-on conditions defined in the plugin itself, including the default plugin configuration.

Stop the plugin from failing a pipeline

Sometimes you might want the CI/CD plugin just to report the found issues, not block the pipeline from continuing. For example, your repository might have plenty of APIs in early stages of their lifecycle, or you have just introduced the CI/CD plugin to the pipeline and need time to adjust to the set quality criteria. In this case, you can temporarily switch off all fail-on conditions that the CI/CD plugin would impose on a CI/CD job. The plugin keeps reporting on the discovered APIs but does not block the pipeline from proceeding to subsequent stages.

Switching off the fail-on conditions in the CI/CD plugin means that the plugin will cease to work as a quality control as it will never prevent potential problems in your APIs. We recommend that you use this option only after a careful consideration and only for a limited time. Remember to remove this setting from the plugin as soon as possible.

Next time you run the pipeline, the integration plugin runs normally, uploading each discovered API definition and its audit report to 42Crunch Platform, but does not fail the CI/CD job because of the audit results or SQG status. However, the plugin still produces logs as per usual, so you can check them to see the status of the discovered APIs.

Ignore network errors

If you are worried that issues in connectivity — such as in the rare case of the CI/CD plugin not being able to communicate to 42Crunch Platform — could unduly hinder an important CI/CD pipeline by causing it to fail, you can set the plugin to ignore connectivity issues.

Setting the CI/CD plugin to ignore network errors lessens the plugin's effectivity as a quality control, because the task does not stop the CI/CD pipeline even though it could not complete successfully due to a connectivity issue. This means that APIs that have quality or security issues in their OpenAPI definitions could slip through upon a successful CI/CD job. We recommend that you use this option only after a careful consideration.

Next time you run the pipeline, if the integration plugin encounters a connectivity issue, it does not fail the CI/CD job and the pipeline proceed to subsequent steps. Errors that cannot be definitively deemed to be connectivity issues will still cause the plugin to fail the job. You can check the logs that the plugin produces to see if any errors occurred.