Adding security analysis to your Jenkins automation server

The HCL AppScan Jenkins plug-in allows you to add security scan support to your Jenkins projects. The plug-in allows you to connect to HCL AppScan 360° on HCL AppScan 360°.

About this task

Procedure

  1. In Jenkins, install the HCL AppScan plug-in:
    1. Select Manage Jenkins and then Manage Plugins.
    2. Select the Available tab and then select the check box next to HCL AppScan.
    3. Click one of the installation buttons at the bottom of the page. After installing the HCL AppScan plug-in, you must restart Jenkins before using it. However, you may want to install it and then restart Jenkins later (for example, if you have running jobs).
    Note: Depending on the version of Jenkins that you are running, these steps may vary slightly.
  2. After restarting Jenkins, add credentials so that your build project can connect to AppScan 360°:
    1. In the Jenkins dashboard, select Credentials.
    2. In the Credentials page, add new global credentials. To do this, select the arrow icon next to the (global) link and then select Add credentials.
    3. In the credentials page, select HCL AppScan 360° Credentials in the Kind list.
    4. Specify an AppScan 360° server URL for the connection. By default, the URL is https://cloud.appscan.com.
    5. When you generate an API key in the AppScan 360° service, you receive a Key Id and Key Secret. Enter these values in the ID and Secret fields. If you have not yet generated an API key, follow the link for creating one.
    6. Optional: Use the Label field to add an identifier for the credentials.
  3. In the Jenkins dashboard, select your Jenkins project to edit it and then click Configure. Complete these steps in the project's General tab:
    1. In the Build section, select the arrow icon next to the action for adding a build step. The label on this action will vary depending on the type of project. Examples include Add Build Step and Add Post-Build Step.
    2. Select Run AppScan on Cloud/AppScan 360° Security Test.
    3. In the Credentials list, select the credentials that you added in the above step. If you added a label identifier for the credentials, it will appear in the list. If you did not add a label, your Key Id and hidden Key Secret will display.
    4. Security scans must be associated with an existing AppScan 360° application. Select the application in the Application list.
      Note: The Application list is populated based on your credentials. The application must already exist in the AppScan 360° service. The list will be empty if no applications have been created in the service.
    5. Optional: In the Test Name field, enter a name for the scan. If you complete this field, the scan will have that name (with timestamp appended) in the AppScan 360° service. In addition, the name will be used to differentiate results in various Jenkins views.
    6. In the Test Type section:
      • Select Static Analysis (SAST) to run static analysis security testing against your build artifacts. If this test type is selected, use the required Target Directory field to enter the full path to the directory that contains the files that you want to scan. For supported file types, see Static analysis language support.
        • Scan method:
          • Generate IRX: Generate an IRX archive locally from the specified files and folders.
            • Source Code Only: Select whether if you want to analyze the source code only.
            • Scan Speed: Optimize scan speed and results according to development stage. Choose faster scans early in the development lifecycle to identify basic security issues; choose thorough scans later in the cycle to ensure complete coverage for your application.
              • Normal: Performs a complete analysis of the code, identifying vulnerabilities in detail and differentiating issues that could be reported as false positives. This scan takes the longest to complete.
              • Fast: Performs a comprehensive analysis of your files to identify vulnerabilities, taking longer to complete than “Faster” or “Fastest” scans.
              • Faster: Provides a medium level of detail of analysis and identification of security issues. This scan takes more time to complete than the “Fastest” option.
              • Fastest: Performs a surface-level analysis of your files to identify the most pressing issues for remediation, taking the least amount of time to complete.
          • Upload files and folders: Upload files and folders directly to AppScan for immediate scanning preparation, and faster processing.
        Note: Software Composition Analysis (SCA) is available for AppScan on Cloud only.
    7. Optional: Email Notification: Select this check box if you want to receive an email when analysis is complete.
    8. Optional: Allow intervention by scan enablement team: When selected, our scan enablement team will step in if the scan fails, or if no issues are found, and try to fix the configuration. This may delay the scan result. This option is selected by default.
    9. Optional: Suspend job until security analysis completes: Select this check box if you want the Jenkins build to wait for security analysis results to be available before moving on to the next step in the project.
    10. Optional: Select the Fail build if check box to enable build failure criteria. Once selected, add at least one build failure condition. To do this, select Add Condition and then complete its criteria. You can set the build to fail if:
      • the Total number of security issues is greater than the number that you specify in the field.
      • the total number of Critical severity security issues is greater than the number that you specify in the field.
      • the total number of High severity security issues is greater than the number that you specify in the field.
      • the total number of Medium severity security issues is greater than the number that you specify in the field.
      • the total number of Low severity security issues is greater than the number that you specify in the field.
      Note:
      • If multiple conditions are added, they will be treated as though they are separated by a logical OR.
      • If Fail build if is selected, the Suspend job until security analysis completes option will automatically become selected and required.
      • If the Fail build if check box is deselected, any conditions that you have added will persist but not be in effect. Conditions are only removed if you manually delete them.
    11. Click Save to add the build step and to stop configuring your Jenkins project. Click Apply to add the build step but continue configuring the project.
      After adding a build step, you can add more Run Security Test build steps to your project.
  4. After you run your Jenkins project, if you open the build, you will see a snapshot of security findings. In addition, Results links for the security tests will be available. Clicking on these will open the non-compliant security report. In the project's main status page, you will see a trending graph of security analysis results when you have more than one set of results.