Open

You will learn

How to obtain, configure, and schedule an OWASP ZAP Scan Agent.

Prerequisites

Audience: IT Professional
Difficulty: Intermediate
Time needed: Approximately 15 minutes
Tools required: scanagent.jar file (see below)

Downloading the Scan Agent

1. To download a copy of the Scan Agent, click the Help icon and select Download Tools.
   
   

   Open

   

    

2. Click on the Jar File link for the Scan Agent item in the list. This will download the scanagent.jar file.
   
   

    

3. ThreadFix recommends using the Scan Agent that corresponds with the user’s current version of ThreadFix. After upgrading the ThreadFix deployment, download the current .jar file from the Download Tools page and replace any deployed version with the new one.

Deploying the Scan Agent

Deploy the 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

Enter the following command to set up ThreadFix specific information for the Scan Agent: 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. For example: 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 refer to the Settings section of this guide.

Configure Scanner

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

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

2. Configure the login sequence for URL if necessary.
   
   

3. Crawl/Spider the site, allow this process to finish. Verify the endpoints are correct.
   
   

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.

     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 it 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 an active ThreadFix instance.

Configuring Scanner

There are two ways to setup the scanner:

Select a Scan Agent from a list:

Enter `java -jar scanagent.jar -cs`, then the Scan Agent will display a dialog to choose the Scanner from.

Or

Enter java -jar scanagent.jar -cs <Scanner Name>

Enter java -jar scanagent.jar -cs zap to directly enter configuration for OWASP. Below are details for OWASP Zed Attack Proxy:

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

• When prompted with 'Input ZAP API Key (in Tools/Options/API)' enter the API key that is located at Tools -> Options -> API (Note: When pasting the API key at the prompt, it will not be visible.)

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. An Add Scan Agent Task to Queue modal will appear.
   
   

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

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

Schedule Scan

1. Navigate to an application in ThreadFix that a scan should be scheduled for. This will tell ThreadFix to create a new Scan Queue Task everyday or every week. Click the Scheduled Scans 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 (not necessary if a config file was uploaded with the name format scanner.scanagtcfg, ThreadFix will automatically attach this config file).
   
   

   Note: Time zone is only selectable in ThreadFix versions 2.8.3/3.0.8 and newer.
   
   

3. Click the Add Scheduled Scan button. The task will be listed in the Scheduled Scans tab.
   
   

Run Scan Agent

Running java -jar scanagent.jar -r starts the scan agent running and polls for tasks from ThreadFix. Scan Agent tasks already in existence will be processed and the agent will then wait for any indefinitely; to stop polling it should be stopped manually by the user.

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