Submitting IBM Security AppScan Source assessments to the Cloud for analysis

If you have a subscription to IBM Application Security on Cloud at IBM Cloud Marketplace or to Application Security on Cloud for Bluemix, you can submit AppScan® Source assessments for analysis there. Assessments from AppScan Source Versions 9.0 or higher are supported - and the number of scans that you can submit depends on your Application Security on Cloud subscription.

About this task

When you use the static analysis feature of the Application Security on Cloud service, you can generate security analysis reports that make use of Intelligent Finding Analytics (IFA). IFA is a powerful machine-learning technology that does much of the triage work for you by, among other things, filtering out false positives and by grouping findings that can be remedied by a fix in one code point. To learn more about IFA, see this article.

If you are using AppScan Source Version 9.0 or higher and have an Application Security on Cloud subscription, you can benefit from this technology by uploading your AppScan Source assessment to Application Security on Cloud. In return, you will receive a new assessment that has been automatically triaged by IFA. This assessment can be in the form of an HTML report or an assessment that can be opened in your AppScan Source product.

If you have a paid Application Security on Cloud subscription, you can scan 10 additional AppScan Source assessments. For example, if your subscription includes 20 Application Security on Cloud scans, you can scan another 10 AppScan Source assessments - for a total of 30 scans. Concurrent scan limits, as outlined in your subscription, include scans of AppScan Source assessments. For example, if your subscription allows you 2 scans at the same time, scans of AppScan Source assessments would be included.
If you have a trial Application Security on Cloud subscription, scans of AppScan Source assessments count toward your total number of allowed scans.

Note: If you are scanning an AppScan Source assessment with a free trial of Application Security on Cloud, you can download a full HTML report, in addition to the AppScan Source assessment file that has been triaged by IFA. For all other scan types, you can only download a summary report when you have a free trial.

Procedure

Skip this step if you are already using Application Security on Cloud for static analysis:
1. If you do not have an Application Security on Cloud subscription, you can acquire one as follows:
  - IBM Cloud Marketplace: Go to https://appscan.ibmcloud.com/serviceui/home and sign in with your IBM ID. If you do not have an IBM ID, use the link for creating one. Then sign up for a free trial or paid subscription using the links at the service.
  - IBM® Bluemix®: Go to https://console.ng.bluemix.net/ and use the SIGN UP button and complete the form for signing up at Bluemix. Then create an Application Security on Cloud for Bluemix service instance.
2. IBM Cloud Marketplace only: In the Application Security on Cloud service, create an app and then click Create Scan.
3. In the What type of app are you scanning today? screen, select Desktop or Web > Static.
4. If you have not previously downloaded and set up the Static Analyzer Client Utility, do so now. See Setting up the Static Analyzer Client Utility for more information.
Generate an assessment (.ozasmt file) in the AppScan Source product or tool of your choice. Versions 9.0 or higher are supported.
Use the Client Utility command line interface (CLI) to generate an Intermediate Representation (IRX or .irx) file for the assessment (.ozasmt file):
1. After extracting the Client Utility to a local drive, add the location of its \bin directory to your PATH environment variable. If you do not do this, all Client Utility CLI commands will need to be qualified by using the \bin directory each time the command is issued. See Generating an IRX file by using the command line interface (CLI) for more information.
2. Issue this command on Windows:
```
appscan package -d <save_path> -f <assessment_file> -n <file_name>
```
  or this command on Linux and macOS:
```
appscan.sh package -d <save_path> -f <assessment_file> -n <file_name>
```
  The command arguments are optional:
  - -d: Specify -d <save_path>, where <save_path> is the directory that you want to save the IRX file to.
  - -f: Specify -f <assessment_file>, where <assessment_file> is the .ozasmt file that you want to package for scanning. If the <assessment_file> file is not in the current directory, use this option to specify the assessment file path and file name.
    Note: This option is only required if one or both of these statements are true:
    - You are issuing the command from a directory that contains more than one assessment file. If the directory contains only one assessment file, that file is packaged if the -f option is not used.
    - You are issuing the command from a directory that contains no assessment files. In this case, the -f option must be used to specify the path and file name of the assessment file to package.
  - -n: Specify -n <file_name>, where <file_name> is the IRX file name. You can specify the file name with or without the .irx file extension. If you specify it without the extension, it is automatically added for you when the file is generated.
  Additional information about this command, including usage examples, can be found at Configuration commands (Windows) or Configuration commands (Linux and macOS).
Use the CLI appscan queue_analysis (Windows) or appscan.sh queue_analysis (Linux and macOS) command to upload the IRX file:
1. Log in to the service from the CLI. The method for doing this is different at IBM Cloud Marketplace and IBM Bluemix. Detailed information about authenticating to the service in the CLI can be found at Authentication commands (Windows) or Authentication commands (Linux and macOS).
  - IBM Cloud Marketplace:
    Issue this command on Windows:
```
appscan scx_login -P <password> -u <user_name> -persist
```
    or this command on Linux and macOS:
```
appscan.sh scx_login -P <password> -u <user_name> -persist
```
    These arguments are required:
    - -P: Specify -P <password>, where <password> is the password that you specified when you registered for the ASoC service.
    - -u: Specify -u <user_name>, where <user_name> is the email address that you specified when you registered for the ASoC service.
    This argument is optional:
    - -persist: Automatically attempt to reauthenticate to the service when the login token file expires.
  - IBM Bluemix:
    Issue this command on Windows:
```
appscan login -P <password> -u <user_name> -persist
```
    or this command on Linux and macOS:
```
appscan.sh login -P <password> -u <user_name> -persist
```
    These arguments are required:
    - -P: Specify -P <password>, where <password> is the password indicated in the service credentials.
    - -u: Specify -u <user_name>, where <user_name> is binding ID indicated in the service credentials.
    To determine the Bluemix service credentials, select Service Credentials in the left navigation pane of the service Dashboard. See Enabling external apps to use Bluemix services.
    
    This argument is optional:
    - -persist: Automatically attempt to reauthenticate to the service when the login token file expires.
2. Upload the IRX file with the appscan queue_analysis (Windows) or appscan.sh queue_analysis (Linux and macOS) command:
  - Issue this command on Windows:
```
appscan queue_analysis -a <app_id> -f <irx_file> -n <scan_name>
```
    or this command on Linux and macOS:
```
appscan.sh queue_analysis -a <app_id> -f <irx_file> -n <scan_name>
```
    These arguments are required:
    - -f: Specify -f <irx_file>, where <irx_file> is the IRX file that you want to submit for scanning. If the IRX file is not in the current directory, use this option to specify the IRX file path and file name.
      Note: This option is only required if one or both of these statements are true:
      You are issuing the command from a directory that contains more than one IRX file. If the directory contains only one IRX file, that file is submitted if the -f option is not used.
      
      You are issuing the command from a directory that contains no IRX files. In this case, the -f option must be used to specify the path and file name of the IRX file to submit.
    - -n: Specify -n <scan_name>, where <scan_name> is the name of the scan that takes place on the cloud.
    - -a (IBM Cloud Marketplace only): If you are connected to the Application Security on Cloud service at IBM Cloud Marketplace, IRX files that you submit to the cloud must be associated with an existing Application Security on Cloud application. With this option, specify -a <app_id>, where <app_id> is the ID of the application to associate with. To determine the ID, use the list_apps command.
      Note: Application association does not apply when you are connected to the ASoC service on Bluemix.
  - When the command completes, an ID for the analysis job displays. If you want to receive the Application Security on Cloud analysis report by using the CLI, you will need to include this job ID in the appscan get_result (Windows) or appscan.sh get_result (Linux and macOS) command - and you should make note of the ID. If you use the CLI to receive the analysis report, you will have the option of receiving an archive (.zip) file that includes a .ozasmt file so that the analysis report can be opened in AppScan Source. If you are only interested in seeing an HTML report, you can use the CLI or the Application Security on Cloud web client to download the report.
  Details about using this command can be found at Analysis commands (Windows) or Analysis commands (Linux and macOS).
When analysis is complete, you will receive an email if you uploaded the IRX using the CLI - or if you selected the Email me when the scan is complete check box in the Application Security on Cloud web client.
Choose a method for retrieving the analysis report. You can use the CLI appscan get_result (Windows) or appscan.sh get_result (Linux and macOS) command - or you can use the Application Security on Cloud web client. If you use the CLI to receive the analysis report, you will have the option of receiving an archive (.zip) file that includes a .ozasmt file so that the analysis report can be opened in AppScan Source. If you are only interested in seeing an HTML report, you can use the CLI or the Application Security on Cloud web client to download the report.
Complete this step if you want to use the CLI appscan get_result (Windows) or appscan.sh get_result (Linux and macOS) command to retrieve the analysis report:
1. Ensure that you are logged in to the service from the CLI.
2. Issue this command on Windows:
```
appscan get_result -d <file_path> -i <job_id> -t <type>
```
  or this command on Linux and macOS:
```
appscan.sh get_result -d <file_path> -i <job_id> -t <type>
```
  This argument is required:
  - -i: Specify -i <job_id>, where <job_id> is the ID of the analysis job.
  Note: If you did not make note of the ID when issuing the appscan queue_analysis (Windows) or appscan.sh queue_analysis (Linux and macOS) command, you can use the appscan list (Windows) or appscan.sh list (Linux and macOS) command to see a list of all analysis jobs. See Analysis commands (Windows) or Analysis commands (Linux and macOS) for more information.
  
  These arguments are optional:
  - -d: Specify -d <file_path>, where <file_path> is the fully qualified path for the destination file and/or the file name of the destination file. If a file name is not specified, the file name is based on the scan job name. If a path is not specified, the file is saved to the current directory. If this option is not included, the file is saved to the current directory with a file name that is based on the scan job name.
  - -t: Specify -t <type>, where <type> is either html or zip. The results are saved as an HTML file or as a .zip file that contains the HTML results. If this option is not included, the results are saved as an HTML file.
    If the scan results are for an IRX file that was generated by the package command, specifying -t zip saves results that contain a new .ozasmt file that can be loaded into your AppScan Source Version 9.0 or higher product.
  Details about using this command can be found at Results commands (Windows) or Results commands (Linux and macOS).
Complete this step if you want to use the web client to retrieve the analysis report: If you are only interested in seeing an HTML report, you can use the Application Security on Cloud web client to download the report.
When you log in to the service, you should automatically see a list of your scans (if you have navigated to another section of the service, click the X icon at the top right to return to the list of scan). In the scan list, locate the scan and select the Download icon and then choose XML or HTML format.

To learn more about Application Security on Cloud scan results at IBM Cloud Marketplace, see this page. At IBM Bluemix, see this page.