Adding security analysis to your Jenkins automation server

The HCL AppScan 360° 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

In Jenkins, install the HCL AppScan 360° 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 360°
3. Click one of the installation buttons at the bottom of the page. After installing the HCL AppScan 360° plug-in, you will need to 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.
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. 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.
5. Optional: Use the Label field to add an identifier for the credentials.
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 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 Dynamic Analyzer to perform analysis of an application that runs in a browser. If this test type is selected, use the required Starting URL field to enter the URL from where you want the scan to start exploring the site. If you select the Additional Options check box, these optional settings are also available:
    - Scan Type: Select whether your site is a Staging site (under development) or a Production site (live and in use).
    - Optimization: Specify whether to scan with No Optimization (regular in-depth scan with longer scan time and maximum vulnerability coverage, the default), Fast (up to twice as fast, ~97% vulnerability coverage), Faster (up to five times as fast, ~85% vulnerability coverage), or Fastest (up to ten times as fast, ~70% vulnerability coverage).
    - Scan File: If you have an AppScan Standard scan file, enter its full path and file name in this field.
    - Application login:Specify login information that will allow AppScan 360° to scan pages that require authentication:
      
      Select Login not required if additional authentication is unnecessary.
      
      Select Login required: Username and Password to provide valid user credentials for the page:
      
      Login User: A valid user name.
      
      Login Password: A valid password.
      
      Extra Credential: A third login credential, if required by the site.
      
      Select Login required: Record login to provide a recorded login sequence for the page. Detail the path of the login sequence data file in Login Sequence File. AppScan supports the .CONFIG file type for such files.
  - Select Static Analyzer 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.
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.
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.