Open

This page walks you through getting started with the ThreadFix Scan Agent.

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 Help (  ) → Download Tools, then click on the 'Jar File' link for the Scan Agent item in the list. This will download the scanagent.jar file.

Deploying the Scan Agent

You should 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 your ThreadFix server, so it can poll it for tasks and upload scan results to it.

Usage

Configure ThreadFix

java -jar scanagent.jar -s

Open

• 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 your 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 bottom of this page under 'Settings'.

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. Let this process finish. Make sure that the endpoints look correct.

4. If 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 your active ThreadFix instance.

Configuring Scanner

There are two ways to setup scanners:

java -jar scanagent.jar -cs, then Scan Agent will display a menu from which to choose the scanner.

java -jar scanagent.jar -cs <Scanner Name> will bypass the above menu and go straight to the setup for the specified scanner.

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

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

Click the Scan Agent Tasks tab and click the Add New Task button.

Choose the scanner type, enter the Target URL you wish to scan and choose or upload the scanner config file, if needed (not necessary if you uploaded a config file with name format scanner.scanagtcfg, ...ThreadFix will automatically attach this config file), and click the Add Scan Queue Task button.

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

Schedule Scan

Navigate to the application in ThreadFix that a scan should be scheduled up for. This will tell ThreadFix to create new Scan Queue Task everyday or every week.

Click the scheduled scan tab and click the Schedule New Scan button.

In the New Scheduled Scan modal, select the frequency, time and scanner type, enter the Target URL you wish to scan and choose or upload the scanner config file, if needed (not necessary if you uploaded a config file with name format scanner.scanagtcfg, ...ThreadFix will automatically attach this config file), and click the Add Scheduled Scan button.

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

Table of Contents