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.

Before you begin

To learn about prerequisites for the plug-in, see System requirements.

About this task

Procedure

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.
After restarting Jenkins, add credentials so that your build project can connect to AppScan on Cloud:
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 on Cloud/HCL AppScan 360° Credentials in the Kind list.
4. Specify an AppScan on Cloud server URL for the connection. By default, the URL is https://cloud.appscan.com.
5. When you generate an API key in the AppScan on Cloud 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.
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 on Cloud 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 on Cloud 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 in the AppScan on Cloud service, distinguishing the scan and results. In addition, the name will be used to differentiate results in various Jenkins views.
6. In the Test Type section:
  - Select Dynamic Analysis (DAST) to perform analysis of an application that runs in a browser.
    - Rescan: Select this option to rescan the same application, updating and overwriting the previous scan results with the latest findings.
      Note:
      To use the Auto Close feature, ensure it has been enabled by your AppScan on Cloud organization administrator. Learn more about rescanning here.
    - Scan ID: Enter the Scan ID of the parent scan based on the application and technology you selected earlier. You can retrieve Scan ID from the AppScan on Cloud server.
    - Incremental Scan: An incremental scan saves time by examining only the changed parts of your application. It uses a base scan for comparison and scans only the new data. Learn more.
      
      Base Scan: Select a base scan from the dropdown. Scans are imported from AppScan on Cloud and listed with their date and time.
    - Starting URL: Enter the URL from where you want the scan to start exploring the site.
    - Additional options: If selected, these optional settings also are available:
      
      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).
      
      Presence ID: If your app is not on the internet, enter your AppScan Presence ID. Information about creating an AppScan Presence is available here.
      
      Scan File: If you have an AppScan Standard scan file, enter its full path and file name in this field. To learn more about AppScan Standard scan files, see this topic.
    - Application login:Specify login information that will allow AppScan on Cloud 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 dast.config file type for such files.
    To learn more about these settings, see this topic.
  - Select Software Composition Analysis (SCA) to scan open source libraries.
    - Rescan: Select this option to rescan the same application, updating and overwriting the previous scan results with the latest findings.
      Note:
      To use the Auto Close feature, ensure it has been enabled by your AppScan on Cloud organization administrator. Learn more about rescanning here.
    - Scan ID: Enter the Scan ID of the parent scan based on the application and technology you selected earlier. You can retrieve Scan ID from the AppScan on Cloud server.
    - Target Directory: Enter the full path to the directory that contains the files or an IRX file that you want to scan.
    Note:
    AppScan on Cloud now performs static analysis (SAST) and open source analysis (SCA) analysis as separate scans. To run an open source-only scan, use the Software Composition Analysis (SCA) scan type. The open source-only option will be removed from SAST scans in a future release.
    For information on open source testing, see, About Software Composition Analysis (SCA).
  - Select Static Analysis (SAST) to run static analysis security testing against your build artifacts.
    - Rescan: Select this option to rescan the same application, updating and overwriting the previous scan results with the latest findings.
      Note:
      To use the Auto Close feature, ensure it has been enabled by your AppScan on Cloud organization administrator. Learn more about rescanning here.
    - Scan ID: Enter the Scan ID of the parent scan based on the application and technology you selected earlier. You can retrieve Scan ID from the AppScan on Cloud server.
    - Target Directory: Enter the full path to the directory that contains the files or an IRX file 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. Additional option
      
      Source Code Only: Select whether if you want to analyze the source code only.
      
      Include SCA: Include analysis of open source packages. Include SCA creates an SCA scan in addition to a SAST scan.
      
      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. If you select the Additional Options check box, this optional setting also is available:
      
      Include SCA: Include analysis of open source packages. Include SCA creates an SCA scan in addition to a SAST scan.
7. Optional: Email Notification: Select this check box if you want to receive an email when analysis is complete.
8. Optional: Run as a personal scan: A personal scan does not affect the application data and compliance until it is promoted.
9. 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.
10. 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.
11. 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.
12. 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.