Integrate Security Audit with Jenkins

Security Audit is integrated through a plugin that adds a build task or job to your CI/CD pipeline. The plugin checks the quality of the OpenAPI files present in your project. If the detected APIs do not meet the criteria you define in the plugins or in your security quality gates in 42Crunch Platform, the plugin fails and aborts the build, so that bad APIs are not included in your project.

The process has two phases:

• Discovery: The task in your CI/CD pipeline checks your project for any .json, .yaml, and .yml files. When it finds a file, it checks if the file states that it is an OpenAPI file. If the file is .yaml or .yml, it is automatically converted to JSON. The discovered APIs are automatically uploaded to an API collection in 42Crunch Platform.
• Audit: Security Audit audits the uploaded APIs for their well-formedness and security. If the quality of the APIs meets your criteria, the task or job ends with a success, if they do not, the task fails. Your CI/CD pipeline processes the result as you have defined and the continues to the next task or job.

The plugin uses API tokens with specific access rights (scopes) to access 42Crunch Platform.

When the integration plugin runs, it uploads the API definitions it finds during the discovery phase to a particular API collection in your organization 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.

On subsequent runs, the plugin synchronizes the contents of the API collection with the APIs in your source control repository:

• APIs added to your repository are added to the collection.
• APIs removed from your repository are removed from the collection
• APIs found both in your repository and in the collection retain their API UUIDs in 42Crunch Platform but their contents are replaced with the contents of the files in your repository

Make sure that you do not accidentally overwrite things in the API definition that you would like to keep. The plugin will replace all contents in the APIs in 42Crunch Platform with the contents of the API files in your repository. Any changes that are not reflected in the OpenAPI file in your repository are lost from the platform.

You can log into your Jenkins account, and configure the settings for the integration on the Jenkins UI.

1. Open the Jenkins job that you want to integrate with API Security Audit.
2. Go to the Build phase, and add a step called API Security Audit.

   

3. In API Token, select the API token you added to your Jenkins credentials.

   

4. Enter the minimum audit score that the audited OpenAPI definitions must get from the audit for the build step to succeed. If any API definitions score lower than the minimum score you set, the build step fails. The default is 75.

   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.

5. If you are an enterprise customer not accessing 42Crunch Platform at https://platform.42crunch.com, click Advanced and 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.

   

6. Set the level of detail (FATAL, ERROR, WARN, INFO, DEBUG) for the logs that the build step produces.
7. If you are using other plugins in your Jenkins pipeline, make sure that the build variables match the variables those plugins use. These variables tell the build step how to name any new API collections it creates in 42Crunch Platform.
   • The build variable for the repository is always required. In most cases, the default value ${GIT_URL} is fine.
   • Depending on how you want to trigger the build, define one of the following:
     • To run builds on branches, define the branch name. In most cases, the default value ${GIT_LOCAL_BRANCH} is fine. This is the most common case.

       If the other plugins in your pipeline use the variable GIT_BRANCH instead of GIT_LOCAL_BRANCH, the resulting branch name usually contains origin (like in origin/main) that must be removed. To do this, use the value ${env.GIT_BRANCH.replaceFirst(/^.*\//, '')}

     • To run builds on tags, define the tag name. In most cases, the default value ${TAG_NAME} is fine.
     • To run builds on PRs, define the PR ID and PR target branch. In most cases, the default values ${CHANGE_ID} and ${CHANGE_TARGET}are fine.
8. Select if you want to automatically share any new API collections that the build task creates with other users in your organization (off by default). You can also change the sharing of the API collections later in 42Crunch Platform.

   You cannot share API collections if your account belongs to the free community organization. In this case, make sure this setting is off.

9. Click Save to save your changes to the Jenkins job.

If you are using Jenkinsfiles to manage your Jenkins jobs, you can configure the integration directly in a Jenkinsfile.

The REST API Static Security Testing plugin supports both declarative and scripted pipeline syntax. For more details, see Jenkins Pipeline documentation.

1. Go to the Jenkinsfile at the root level of your source code repository where the CI/CD pipeline connects to, and open it for editing.
2. Under stages, add a new stage called, for example, Audit OpenAPI files:

   stages {
       ...
       stage('Audit OpenAPI files') {
   

3. Under your new stage, add a step called audit. This tells your Jenkins job to use the REST API Static Security Testing plugin.

   stages {
       ...
       stage('Audit OpenAPI files') {
           steps {
               audit 
           }
       }
       ...
   }

4. Define build variables that tell the build step how to name any new API collections it creates in 42Crunch Platform. If you are using other plugins in your Jenkins pipeline, make sure that the build variables match the variables those plugins use.
   • The build variable repositoryName is always required. In most cases, the default value ${GIT_URL} is fine.
   • Depending on how you want to trigger the build, define one of the following:
     • To run builds on branches, define branchName. In most cases, the default value ${GIT_LOCAL_BRANCH} is fine. This is the most common case.

       If the other plugins in your pipeline use the variable GIT_BRANCH instead of GIT_LOCAL_BRANCH, the resulting branch name usually contains origin (like in origin/main) that must be removed. To do this, use the value ${env.GIT_BRANCH.replaceFirst(/^.*\//, '')}

     • To run builds on tags, define tagName. In most cases, the default value ${TAG_NAME} is fine.
     • To run builds on PRs, define prIdandprTargetBranch. In most cases, the default values ${CHANGE_ID} and ${CHANGE_TARGET}are fine.

   stages {
       ...
       stage('Audit OpenAPI files') {
           steps {
               audit repositoryName: "${env.GIT_URL}", branchName: "${env.GIT_LOCAL_BRANCH}"
           }
       }
       ...
   }

5. To finalize the configuration, specify the following:
   • credentialsId: The ID you specified for the API token you added to your Jenkins credentials.
   • minScore: The minimum audit score that the audited OpenAPI definitions must get from the audit for the build step to succeed. If any API definitions score lower than the minimum score you set, the build step fails. The default is 75.

     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.

   • platformUrl (optional): If you are an enterprise customer not accessing 42Crunch Platform at https://platform.42crunch.com, enter the URL you use to access the platform. 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.
   • logLevel (optional): By default, the level of detail in the logs that the build step produces is INFO. If you want more or less detail, you can change it here. The possible values are FATAL, ERROR, WARN, INFO, DEBUG.
   • shareEveryone: This variable lets you automatically share any new API collections that the plugin creates with other users in your organization in 42Crunch Platform. The variable has two possible values: READ_ONLY or READ_WRITE, depending on the access level you want to give to them. If you do not define shareEveryone at all, the API collections are not shared and remain private to you. You can also change the sharing of the API collections later. For more details, see Sharing APIs and access level.

   You cannot share API collections if your account belongs to the free community organization. In this case, make sure this setting is off.

   stages {
       ...
       stage('Audit OpenAPI files') {
           steps {
               audit repositoryName: "${env.GIT_URL}", branchName: "${env.GIT_LOCAL_BRANCH}", credentialsId: '42crunch-token-id', minScore: 75, platformUrl: 'https://<your platform URL here>', logLevel: 'DEBUG'
           }
       }
       ...
   }

6. Save your changes to the Jenkinsfile.

1. Go to the Jenkins job you want and open the settings of the integration plugin for editing.
2. In Write JSON report to, enter the filename or path that you want to use for report file. The report is in JSON format, so ensure that you either specify .json as the file extension (as in test/myReport.json) or omit the extension completely (test/myReport).
   • If you specify only the filename, the plugin creates the file in the root directory that it is pointed to start from.
   • If you specify a path, the path must be under the root directory and all specified directories must exist. The plugin only generates the JSON file, not directories.

   The plugin does not delete or overwrite any summaries from previous runs, so if a file with the same name exists, you see an error. To avoid this, you can create a separate workspace for each pipeline pass, add a task to clear the workspace before starting, or include a variable to the filename (such as the build number or timestamp) to ensure that each filename is unique.

3. Save your changes.

1. Go to the Jenkinsfile you want, and open it for editing.
2. Add the build variable jsonReport to the audit stage, and, enter the filename or path that you want to use for report file. The report is in JSON format, so ensure that you either specify .json as the file extension (as in test/myReport.json) or omit the extension completely (test/myReport).
   • If you specify only the filename, the plugin creates the file in the root directory that it is pointed to start from.
   • If you specify a path, the path must be under the root directory and all specified directories must exist. The plugin only generates the JSON file, not directories.

   The plugin does not delete or overwrite any summaries from previous runs, so if a file with the same name exists, you see an error. To avoid this, you can create a separate workspace for each pipeline pass, add a task to clear the workspace before starting, or include a variable to the filename (such as the build number or timestamp) to ensure that each filename is unique.

3. Save your changes.

1. Go to the Jenkins job 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. Save you changes to the settings and to the pipeline.

1. Go to the Jenkinsfile you want, and open it for editing.
2. Add the build variable defaultCollectionName to the audit stage, and 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.

1. Go to the Jenkins job 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.

1. Go to the Jenkinsfile you want, and open it for editing.
2. Add the build variable rootDirectory to the audit stage, and enter the path of the directory you want to use as the root directory.
3. Save your changes.

1. Go to the Jenkins job you want and open the settings of the integration plugin for editing.
2. Select Skip local checks, and save your changes.

1. Go to the Jenkinsfile you want, and open it for editing.
2. Add the build variable skipLocalChecks to the audit stage, and set it to true.
3. Save your changes.

1. Go to the Jenkins job you want and open the settings of the integration plugin for editing.
2. Select Force ignore all failures, and save your changes.

1. Go to the Jenkinsfile you want, and open it for editing.
2. Add the build variable IgnoreFailures to the audit stage, and set it to true.
3. Save your changes.

1. Go to the Jenkins job you want and open the settings of the integration plugin for editing.
2. Select Force ignore network failures, and save your changes.

1. Go to the Jenkinsfile you want, and open it for editing.
2. Add the build variable ignoreNetworkErrors to the audit stage, and set it to true.
3. Save your changes.