Analysis commands (Windows™)

Analysis commands are used for submitting scan requests to the cloud - or for working with scan requests that are already submitted to the cloud. Using the commands, you can also receive information about scans. This information can be useful for automation scripts.

Before you use these commands, ensure that you log in to the analysis service (see Authentication commands).

appscan status

Syntax:

appscan status -i <job_id>

Description:

Return one of these status codes for an analysis job:

0 = Pending
1 = Starting
2 = Running
3 = FinishedRunning
4 = FinishedRunningWithErrors
5 = PendingSupport
6 = Ready
7 = ReadyIncomplete
8 = FailedToScan
9 = ManuallyStopped
10 = None
11 = Initiating
12 = MissingConfiguration
13 = PossibleMissingConfiguration

Required options:

  • -i: Specify -i <job_id>, where <job_id> is the ID of the analysis job.
Tip: For all commands, options can be used in any order.

Examples:

To see the status of job ID 12345, specify this:

appscan status -i 12345

If the return code is 0, the job is pending. If the return code is 1, the job is starting, and so on.

appscan list

Syntax:

appscan list

Description:

List all analysis jobs, including those jobs that are queued, running, and completed. The ID for every job is returned so that you can use the ID for other commands. For example, the ID can be used with the info command in the command prompt or in scripts.

Note: This command returns a maximum of 2000 scans.

appscan list_apps

Syntax:

appscan list_apps

Description:

HCL Cloud Marketplace only: If you are connected to the AppScan on Cloud service at HCL Cloud Marketplace, IRX files that you submit to the cloud must be associated with an existing AppScan on Cloud application.

This command allows you to see the AppScan on Cloud applications that you have access to. To use the command, you must be authenticated to the service on Cloud Marketplace. After issuing the command, a list of AppScan on Cloud applications displays with application names followed by their IDs in parentheses. Use the ID values in this list when using the -a option of the queue_analysis command.

appscan cancel

Syntax:

appscan cancel -i <job_id>

Description:

Cancel an analysis job that is running or queued.

Required options:

  • -i: Specify -i <job_id>, where <job_id> is the ID of the analysis job.
Tip: For all commands, options can be used in any order.

Examples:

To cancel job ID 12345, specify this:

appscan cancel -i 12345

appscan queue_analysis

Syntax:

appscan queue_analysis -a <app_id> -f <irx_file> -n <scan_name>

Description:

Submit an IRX file to the cloud for analysis. When the scan is complete, you receive an email notification (at the email address that is associated with the account that was used to log in to the analysis service). The email includes a link to the cloud so that you can log in to download your scan.

Note: When you scan code or generate an IRX file, you might receive a message about updating to the latest Static Analyzer Command Line Utility. See Command Line Utility (CLI) support.

Required options:

  • -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 : If you are connected to the AppScan on Cloud service at HCL Cloud Marketplace, IRX files that you submit to the cloud must be associated with an existing AppScan 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.
Optional flags/settings:
  • -nen: Disable email notification on analysis completion. If this flag is not specified, email notification occurs by default.
    Note: The -e flag has been deprecated and replaced by -nen.
  • -ps: Run the scan as a personal scan. If this flag is not specified, a regular scan occurs by default.
Tip: For all commands, options can be used in any order.

Examples:

appscan queue_analysis -f my_irx.irx 12345 -n my_scan
To submit my_irx.irx, which is in the current directory, to the cloud for scanning, use 
appscan queue_analysis -f my_irx.irx -a 12345 -n my_scan
Where 12345 is the ID of the application to associate the scan with (the application ID can be determined using the list_apps command). When you use the cloud user interface or the list command to see all current scans, my_scan appears in the list.

appscan info

Syntax:

appscan info -i <job_id>

Description:

Display the information for a specified analysis job.

The information that is provided can be used for automation scripts.

Required options:

  • -i: Specify -i <job_id>, where <job_id> is the ID of the analysis job.
Tip: For all commands, options can be used in any order.

Examples:

To receive information about job ID 12345, specify this:

appscan info -i 12345

An example of the information that is returned is:

NLowIssues=0
ReadStatus=2
NHighIssues=0
Name=appscan.zip
ScanEndTime=2014-11-20T13:56:04.497Z
Progress=0
RemainingFreeRescanMinutes=0
ParentJobId=00000000-0000-0000-0000-000000000000
EnableMailNotifications=false
JobStatus=6
NInfoIssues=0
JobId=9b344fc7-bc70-e411-b922-005056924f9b
NIssuesFound=0
CreatedAt=2014-11-20T13:54:49.597Z
UserMessage=Scan completed successfully. The report is ready.
NMediumIssues=0
Result=1