Plug-in Documentation

IBM AppScan Enterprise

Overview

The IBM AppScan Enterprise plug-in includes steps that run security scans and retrieve reports.

To add the IBM AppScan Enterprise plug-in steps to processes, click Security > AppScan Enterprise in the step palette of the process editor.

Compatibility

Supports IBM Security AppScan Enterprise version 9.0.3 and greater.
The webhook beta functionality was added in IBM Security AppScan Enterprise version 9.0.3.9

This plug-in requires version 6.0 or later of IBM UrbanCode Deploy.

Installation

No special steps are required for installation. See Installing plug-ins in UrbanCode products.

History

Version 14

  • Added beta feature of AppScans Webhook configuration.
  • Added Delete Folder Item step to enable the deletion of a Scan or Report.

Version 13

Retrieve PDF Report changes:

  • Added the pdfReportFilePath and detailsLink (reportURL) output properties to the Retrieve PDF Report step.

Retrieve Report changes:

  • Specify report using the Report Name property. The issue counts are identified using the report name.
  • Step now waits for Retrieve Report to enter READY state.
  • Added the criticalSevIssuesCount, lowSevIssuesCount, detailsLink (reportsURL), reportSpecificURL, and scanStatus output properties to the Retrieve Report step.
  • isReadyForDeployment output variable has been removed. Because each count is set to an output variable, implement a short script to set a personalized isReadyForDeployment logic.
  • Output file now has a .xml extension to match the contents of the file.
  • By default, the output file will be sent to the working directory.
  • Hidden checkbox to print the output files contents to the output logs.
  • Summary file is now created containing all general information of the report back. (Saved as FIID-Summary.xml)

Run Step changes:

  • If Wait for Completion and FIID are specified and the timeout is exceed, the step will not look for the report.
  • If retrieving the report in the Run Scan step, a default value of 0 issues is given for the Issues Allowed.
  • ScanStatus output property has been changed to scanStatus.

Wait For Scan or Report Pack changes:

  • Because the Retrieve Report step will wait for READY state, this step has been renamed to Wait for Scan.
  • ScanStatus output property has been changed to scanStatus.

Version 12

  • New Wait for Scan or Report Pack step.

Version 11

  • The Wait for Scan Completion hidden property has been added to the Run Scan step. If selected, the step will wait for the scans completion status.
  • The Stop Scan on Failure hidden property has been added to the Run Scan Step. If selected, the step will stop the scan if the scan fails or exceeds timeout.
  • New output property ScanStatus will be specified on success or failure of the Run Scan Step.

Version 10

Version 10 includes the following features:

  • Fixes APAR PI84034 If Run Scan exceeds timeout, the plugin will properly stop the scan.
  • Updated logic to vary sleep time based on the amount of timeout left remaining. Maximum sleep interval is 2 minutes.
  • Updated timeout to have a minimum of 5 minutes.

Version 9

Version 9 includes the following features:

  • Fixes APAR PI83388 Set Automatic Login, HTTP Authentication, and Disable Certificate Validation properties now follow their specified configuration.
  • Set Automatic Login and HTTP Authentication properties have been updated to a drop down selection allowing to enable, disable, or leave as default.

Version 8

Fixes error when trying to create scan with a hyphen or period in the name.

Version 7

Version 7 includes the following features:

  • Added output properties reportFilePath, highSevIssues, mediumSevIssues, and isReadyForDeployment to Retrieve Reports step.
  • Added required port input property to Retrieve PDF Report step.

Version 6

Version 6 includes the following features:

  • Fixed bug in Retrieve PDF Reports step. Step now allows retrieval of either an entire applications report, or the report of a single scan associated with an application.

Version 5

Version 5 includes the following features:

  • The Run Scan, Retrieve Reports, and Retrieve PDF Report steps were added.
  • An error when setting Basic Authentication was fixed.
  • Now supports property file encryption.

Version 4

Version 4 includes the following features:

  • Added option to Configure Job Options step which allows for a .htd recorded traffic file to be uploaded.
  • Added option to rerun scan in case of failure.
  • Added step to download PDF file(s) of an applications report.

Version 3

Version 3 includes the following features:

  • Added option to Configure Job Options step which allows for the login sequence type to be set.
  • Fixed error when setting Basic Authentication for scan.

Version 2

Version 2 includes the following features:

  • The Create Scan, Configure Job Options, and List Available Templates steps were added.
  • The base URL is now checked to ensure correct syntax.
  • The Run Scan step output was edited.
  • The Retrieve Reports step now saves reports as text files.

Version 1

Initial release of the plug-in.

Steps

Process steps in the AppScan plug-in

Configure Job Options

Configure scan job options.

Input properties for the Configure Job Options step
Name Type Description Required
AppScan Enterprise URL String AppScan Enterprise Control Center URL. For example, https://localhost/ Yes
HTTP Authentication Enumeration:

  • default
  • true
  • false
  • ${p?:component/appscan.httpAuth}
Check this field to enable Basic/NTLM authentication. No
HTTP Password Password No
HTTP User String No
Password Password Password to log into ASE. Yes
Recorded Traffic .htd File String No
Scan FIID String FIID of the scan to configure. This is found in the scans URL. Yes
Scan Limit String No
Scan Site Password Password Password to use when logging into the site. Input here will overwrite the password
if there is already one set in the scan.
No
Scan Site User String User to log into the site as. Input here will overwrite the username if there is already
one set in the scan.
No
Set Automatic Login Enumeration:

  • default
  • true
  • false
  • ${p?:component/appscan.setAuto}
Set to true to automatically login with the given Scan Site User and Scan Site Password. No
Site URL String URL of site to scan. If there is already at least one starting URL associated with
the scan, input here will add to the list of URLs.
No
User String Username to log into ASE. Yes

Create Scan

Create an AppScan security scan.

Input properties for the Create Scan step
Name Type Description Required
AppScan Enterprise URL String AppScan Enterprise Control Center URL. For example, https://localhost/ Yes
Application ID String The application ID. Used to associate the job with an application. No
Folder ID String ID of the specific folder in which to create the scan and report pack. If this is
left blank, the scan and report pack will be created in the root folder.
No
Password Password Password to log into ASE. Yes
Scan Description String The description to give to the newly created scan. Yes
Scan Name String The name to give to the newly created scan. Yes
Template Name String Name of the template to use to create the scan and report pack. Must be a valid template
that you have access to in the Templates directory or any of its subfolders.
Yes
User String Username to log into ASE. Yes

Delete Folder Item

Delete a folder item, such as a Scan or Report, from the AppScan Scans view.

Input properties for the Delete Folder Item step
Name Type Description Required
AppScan Enterprise URL String AppScan Enterprise Control Center URL, For example, https://localhost/ Yes
Folder Item FIID String Specify a Folder Item FIID to delete. Example: Scan or Folder FIID. Yes
Password Password Password to log into ASE. Yes
User String Username to log into ASE. Yes

List Templates

Retrieve and print a list of available job templates.

Input properties for the List Templates step
Name Type Description Required
AppScan Enterprise URL String AppScan Enterprise Control Center URL. For example, https://localhost/ Yes
Password Password Password to log into ASE. Yes
User String Username to log into ASE. Yes

Retrieve PDF Report

Retrieve report from AppScan Enterprise. Reports are saved as a PDF file named AppScanReportOutput-[date]-[time].zip

Input properties for the Retrieve PDF Report step
Name Type Description Required
AppScan Enterprise Port String AppScan Enterprise Port number. Yes
AppScan Enterprise URL String AppScan Enterprise Control Center URL, For example, https://localhost/ Yes
Application ID String ID of the application report to retrieve. Yes
File Path String Path of file to write report info to. For example, C:/reports/ Yes
Password Password Password to log into ASE. Yes
Scan Name String The name of the scan within the application. The format is {scanName} ({scanFIID}).
For example, Test Scan (171).
No
User String Username to log into ASE. Yes

Retrieve Report

Retrieve report pack summary and specific report information from AppScan Enterprise.
Reports are saved as a xml files named [reportFIID]-Summary.xml and [reportFIID]-[reportName].xml

Input properties for the Retrieve Report step
Name Type Description Required
AppScan Enterprise URL String AppScan Enterprise Control Center URL. For example, https://localhost/ Yes
Password Password Password to log into ASE. Yes
Report Destination String Folder path to save the report file. Default location is the working directory.
Example: C:/reports/. The full file path will be saved as an output property.
No
Report FIID String FIID of the report pack to retrieve. This is found in the reports URL. Yes
Report Name String The name of the report within the report pack to retrieve the issue counts.
If empty, then no report counts will be retrieved.
No
User String Username to log into ASE. Yes

Run Scan

Run an AppScan security scan.

Input properties for the Run Scan step
Name Type Description Required
AppScan Enterprise URL String AppScan Enterprise Control Center URL. For example, https://localhost/ Yes
Password Password Password to log into ASE. Yes
Reports FIID String FIID of the report pack associated with the scan. If
not given, step may finish before waiting for report pack to complete.
This is found in the reports URL.
No
Retries String The number of times to retry running the scan, in case of failure. No
Scan FIID String FIID of the scan to run. This is found in the scans URL. Yes
Timeout String Timeout, in minutes, at which the step will fail if the scan is not yet complete.
Minimum is 5 minutes.
No
User String Username to log into ASE. Yes

Wait for Scan

Wait for an AppScan Scan to complete.

Input properties for the Wait for Scan step
Name Type Description Required
AppScan Enterprise URL String AppScan Enterprise Control Center URL, For example, https://localhost/ Yes
Password Password Password to log into ASE. Yes
Scan FIID String FIID of the scan to wait for. This is found in the scan URL. Yes
Timeout String Timeout, in minutes, at which the step will fail if the scan is not yet complete.
Leave empty to wait indefinitely.
No
User String Username to log into ASE. Yes