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

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.

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 192.168.0.117 or my.proxy.com)
    • 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.