Open

You will learn

How to get started with the ThreadFix Scan Agent.

Prerequisites

Audience: IT Professional, or End User
Difficulty: Intermediate
Time needed: Approximately 10 minutes
Tools required: Please see Requirements list

Requirements

• Running instance of ThreadFix

• Application with URL set

• API key generated

• ThreadFix Scan Agent jar

• Supported scanner

• Config file for scanner

Supported Scanners

• AppScan Standard

• Burp Suite

• OWASP Zed Attack Proxy

• Acunetix Web Vulnerability Scanner

• WebInspect

• AppSpider

Downloading the Scan Agent

To download a copy of the Scan Agent, click on the Help icon and select Download Tools, then click on the 'Jar File' link for the Scan Agent item in the list. This will download the scanagent.jar file.

Open

Deploying the Scan Agent

Deploy scanagent.jar wherever it can access the scanning tool's executable, which would typically be on the server running the scanning tool. Additionally, the Scan Agent needs to be able to access the ThreadFix server, so it can poll it for tasks and upload scan results to it.

Usage

Configure ThreadFix

java -jar scanagent.jar -s

• ThreadFix base Url: enter the URL that the agent will use to connect to ThreadFix.

  Be sure to include at least /rest so the agent can use ThreadFix's API. ThreadFix recommends including /latest at the end so the scan upload is queued (e.g., http://my.tf.server:8080/threadfix/rest/latest).

• ThreadFix API Key can be generated in ThreadFix.

• "Input working directory" refers to the directory that the scans will be saved by the scan agent (e.g., an xml file); the results get sent to the ThreadFix server via REST API call. 

This process will update the scanagent.properties file in the working directory to include the entered configuration information. If the file does not exist, it will be generated. There are additional properties which can be set or altered. For further information, consult the comments in the scanagent.properties file, or see the Settings section of this guide.

Configure Scanners

Creating config file

This file is created in order for the scanner to have access to an appropriate login sequence, and other relevant data for scanning an application.

Base Setup for Each Scanner

1. Connect scanner to application URL (ZAP and Burp require proxy setup).
   
   

2. Configure login sequence for URL if necessary.
   
   

3. Crawl/Spider the site. Allow the process to finish and review the endpoints.
   
   

4. If the scanner automatically kicks off crawling/scanning, pause/stop the scanner once the scanning process has begun.
   
   

5. Save the state of the scanner and name the config file:

   • <scanner>.scanagtcfg (e.g., zap.scanagtcfg). The name must be all lower-case or ThreadFix will not recognize the file.
     
     This is required for AppScan but is optional for ZAP.

     Note: In ZAP save scanner state via File > Persist Session... option or ZAP startup menu. ZAP will output a series of files. The file with extension .session should be compressed into a zip file. Then you can rename to zap.scanagtcfg.
     For an Acunetix configuration file, choose the 'Save Scan Results' option and change the name of the resulting file to acunetix.scanagtcfg.
     
     

6. Upload the config file under the Files tab on the application page in the active ThreadFix instance.

Configuring Scanner

There are two ways to setup scanners:

• `java -jar scanagent.jar -cs`, then Scan Agent will display a dialog to choose a scanner.

• `java -jar scanagent.jar -cs <Scanner Name>`. Below are details for each scanner.

OWASP Zed Attack Proxy

java -jar scanagent.jar -cs zap

When prompted "Input OWASP Zed Attack Proxy port" enter the port that is located at Tools->Options->Local Proxy.

Acunetix

java -jar scanagent.jar -cs acunetix

AppScan Standard

java -jar scanagent.jar -cs appscan

Burp Suite

java -jar scanagent.jar -cs burp

WebInspect

java -jar scanagent.jar -cs webinspect

Running Scan Agent on Mac

On a Mac environment users will also need to configure hosts, proxies, license keys and gather the necessary API keys from the .jar/.sh file the Scan Agent is being configured to use directly. Note: trying to gather these from the .app will end with a different set of API keys and possibly messages regarding invalid licenses, unauthorized access or refused connections when trying to run a job. Run the following, referring to the OWASP Zed Attack Proxy Scan Agent and/or Burp Suite Scan Agent as needed:

Queue Scan

1. Navigate to the application in ThreadFix for which a scan should be queued up.
   
   

    

2. Click the Scan Agent Tasks tab and click the Add New Task button. Choose the scanner type, enter the Target URL to scan and choose or upload the scanner config file, if needed*. Click the Add Scan Queue Task button.
   _{* not necessary if a config file was uploaded with the name format of scanner.scanagtcfg as ThreadFix will automatically attach this config file.}
   
   

The task will be listed in the Scan Agent Task tab with a "QUEUED" status.

Schedule Scan

1. Navigate to the application in ThreadFix that a scan should be scheduled up for. This will tell ThreadFix to create a new Scan Queue Task everyday or every week. Click the scheduled scan tab and click the Schedule New Scan button.
   
   

    

2. In the New Scheduled Scan modal, select the frequency, time and scanner type, enter the Target URL to scan and choose or upload the scanner config file, if needed*. Click the Add Scheduled Scan button.
   _{* not necessary if a config file was uploaded with the name format of scanner.scanagtcfg as ThreadFix will automatically attach this config file.}
   
   

    

3. The task will be listed in the Scheduled Scans tab.

Run Scan Agent

java -jar scanagent.jar -r

Settings

In addition to the properties set during configuration, there are other fields in scanagent.properties that can be modified by manually editing the file.

Additional Scan Agent Properties

• scanagent.pollInterval: time in seconds to wait between polling for new tasks

• scanagent.maxTasks: max number of tasks that can be executed each time the scan agent is run

Additional ZAP properties

• zap.maxSpiderWaitInSeconds: time in seconds to wait for ZAP spider to complete

• zap.maxScanWaitInSeconds: time in seconds to wait for ZAP scans to complete

• zap.spiderPollWaitInSeconds: time in seconds between checks for the ZAP spider's progress

• zap.scanPollWaitInSeconds: time in seconds between checks for the ZAP scan's progress

• zap.zapStartupWaitTime: time in seconds to wait for ZAP to start

Optional - Home Directory File Loading

As of 3.3, the ESAPI.properties and validation.properties files can load from the home directory. For this, within the home directory, create an additional directory named "esapi" and store the esapi.properties and validation.properties files provided below.

NOTE: This is an optional step and if not used in this way the scan agent tool will load the files using the default options.

Open

Open

Table of Contents