Analysis commands (Linux™ and macOS)

Analysis commands are used for submitting scan requests for analysis - or for working with scan requests that are already submitted. 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 are logged in to the analysis service (see Authentication commands).

appscan.sh status

Syntax:

appscan.sh 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.sh 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.sh list

Syntax:

appscan.sh 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.

appscan.sh list_apps

Syntax:

appscan.sh 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. 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.sh cancel

Syntax:

appscan.sh 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.sh cancel -i 12345

appscan.sh queue_analysis

Syntax:

appscan.sh queue_analysis -a <app_id> -f <file> -n <scan_name>

Description:

Submit a file for analysis (IRX or non-IRX archive). 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 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 <file>, where <file> is the IRX file or non-IRX archive that you want to submit for scanning. If the file is not in the current directory, use this option to specify the 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 target file. If the directory contains only one target file, that file is submitted if the -f option is not used.
    • You are issuing the command from a directory that contains no target files. In this case, the -f option must be used to specify the path and file name of the file to submit.
  • -a : Files that you submit to the for analysis (IRX file or non-IRX archive) 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:
  • -n: Specify -n <scan_name>, where <scan_name> is the name of the submitted scan.
  • -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:

To submit my_irx.irx, which is in the current directory, 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 user interface or the list command to see all current scans, my_scan appears in the list.

appscan.sh info

Syntax:

appscan.sh 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.sh 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