This page walks you through getting started with the ThreadFix Scan Agent.
Running instance of ThreadFix
Application with URL set
API key generated
ThreadFix Scan Agent jar
Supported scanner
Config file for scanner
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.
We recommend using the Scan Agent that corresponds with your current version of ThreadFix. After you upgrade your ThreadFix deployment, you should download the current .jar file from the Download Tools page and replace any deployed version with the new one. You may be able to use the existing configuration, but if it no longer works, you will need to step through the config once again. |
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.
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 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'.
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.
Connect scanner to application URL (ZAP and Burp require proxy setup).
Configure login sequence for URL if necessary.
Crawl/Spider the site. Let this process finish. Make sure that the endpoints look correct.
If scanner automatically kicks off crawling/scanning, pause/stop the scanner once the scanning process has begun.
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
.
Upload the config file under the 'Files' tab on the application page in your active ThreadFix instance.
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.
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.
java -jar scanagent.jar -cs acunetix
java -jar scanagent.jar -cs appscan
java -jar scanagent.jar -cs burp
java -jar scanagent.jar -cs webinspect
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:
1. OWASP ZAP: sh /Path To/Applications/OWASP ZAP.app/Contents/Java/zap.sh 2. BURP: java -jar /Path To/Applications/Burp Suite Professional.app/Contents/Resources/app/burpsuite_pro.jar |
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.
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.
java -jar scanagent.jar -r
In addition to the properties set during configuration, there are other fields in scanagent.properties
that can be modified by manually editing the file.
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
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