Adding security analysis to your Jenkins automation server

The IBM Application Security on Cloud Jenkins plug-in allows you to add security scan support to your Jenkins projects. The plug-in allows you to connect to IBM Application Security on Cloud on IBM Application Security on Cloud.

1. In Jenkins, install the IBM Application Security on Cloud plug-in:
   1. Select Manage Jenkins and then Manage Plugins.
   2. Select the Available tab and then select the check box next to IBM Application Security on Cloud
   3. Click one of the installation buttons at the bottom of the page. After installing the IBM Application Security on Cloud 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.
2. After restarting Jenkins, add credentials so that your build project can connect to Application Security 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 IBM Application Security on Cloud Credentials in the Kind list.
   4. When you generate an API key in the Application Security 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.
   5. 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 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 Application Security 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 Application Security 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 (with timestamp appended) in the Application Security on Cloud 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).
        • Login User and Login Password: If your app requires login, enter valid user credentials so that Application Security on Cloud can log in to the site.
        • Extra Field: If your app requires a third credential, enter it in this field.
        • 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.

        To learn more about these settings, see this topic.

      • Select Mobile Analyzer to run security analysis of your Android or iOS mobile application. In the Application File field, enter the full path and file name of the .apk or .ipa file that you want to scan. If you select the Additional Options check box, these optional settings are also available:
        • Login User and Login Password: If your app requires login, enter valid user credentials so that Application Security on Cloud can log in to the site.
        • Extra Field: If your app requires a third credential, enter it in this field.
        • Presence ID: If your app is not on the internet, enter your AppScan Presence ID. Information about creating an AppScan Presence is available here.

        For more information about mobile analysis, see the documentation for scanning Scanning an Android mobile app and Scanning an iOS mobile app.

      • 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 Language support. If you select the Additional Options check box, these optional settings are also available:
        • Open Source Only: Select whether your app includes Open Source packages. For information on Open Source testing, see, Open Source testing.
   7. Optional: Email Notification: Select this check box if you want to receive an email when analysis is complete.
   8. 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.
   9. 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 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.
   10. 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 a full 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.