Open

You will learn

How to obtain the Command Line Interface API Client and utilize a library of commands to gather various kinds of data.

Prerequisites

Audience: IT Professional
Difficulty: Intermediate
Time needed: Approximately 15 minutes
Tools required: ThreadFix Command Line Interface (CLI)

ThreadFix Command Line Interface

To download the ThreadFix Command Line Interface (CLI), a tfcli.jar file, click the Help icon and select Download Tools from the drop-down list then click the corresponding Jar File link.

Open

Details

In order to use most of the methods, users must set the API key and potentially the URL as well if not using http://localhost:8080/threadfix/.

To do so, issue the following commands, substituting the ThreadFix API key and URL:

For example:

All of the rest of the commands should be prefaced with java -jar tfcli.jar.

Create

Team

Use the desired name for the team:

-ct, --create-team <Team Name>

Example:

INFO [main] CommandLineParser.main(112) | Creating a Team with the name TeamName. INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":{"id":30,"infoVulnCount":0,"lowVulnCount":0,"mediumVulnCount":0,"highVulnCount":0,"criticalVulnCount":0,"totalVulnCount":0,"name":"TeamName","applications":null}} ```

Application

Get the Team ID either by looking at the returned JSON from the create team method, the browser's URL after organization/ or by using the search-team method.

-ca, --create-app <Team ID> <Application Name> <Application Url>

Example:

INFO [main] CommandLineParser.main(129) | Creating an Application with the name Application. INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":{"id":30,"name":"Application","url":"http://test.com","uniqueId":null,"applicationCriticality":{"id":1,"name":"Low"},"scans":[],"infoVulnCount":0,"lowVulnCount":0,"mediumVulnCount":0,"highVulnCount":0,"criticalVulnCount":0,"totalVulnCount":0,"tags":[],"waf":null,"organization":{"name":"TeamName","id":30}}} ```

Tag

Use a desired name for new tag. tagType is optional, it should be one of Application, Vulnerability, or Comment. By default ThreadFix will create Application tag.

-ctg, --create-tag <Tag Name> <[tagType]>

Example:

INFO [main] CommandLineParser.processTagRequest(392) | Creating a tag with the name AppTag INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":{"id":6,"name":"AppTag","type":"APPLICATION"}} ```

Search

Team

These methods allow team lookup by id or name.

• -st, --search-team id <Team ID>

• -st, --search-team name <Team Name>

Example:

INFO [main] CommandLineParser.main(244) | Searching for team with the id 30. INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":{"id":30,"infoVulnCount":0,"lowVulnCount":0,"mediumVulnCount":0,"highVulnCount":0,"criticalVulnCount":0,"totalVulnCount":0,"name":"TeamName","applications":[{"id":30,"name":"Application","url":"http://test.com","applicationCriticality":{"id":1,"name":"Low"}}]}} ```

Application

These methods allow application lookup by id, name, or uniqueId.

• -sa, --search-app id <Application ID>

• -sa, --search-app name <Application Name> <Team Name>

• -sa, --search-app uniqueId <UniqueId> <Team Name>

Example:

INFO [main] CommandLineParser.main(285) | Searching for application with the name Application of team TeamName {"message":"","success":true,"responseCode":-1,"object":{"id":30,"name":"Application","url":"http://test.com","uniqueId":null,"applicationCriticality":{"id":1,"name":"Low"},"scans":[],"infoVulnCount":0,"lowVulnCount":0,"mediumVulnCount":0,"highVulnCount":0,"criticalVulnCount":0,"totalVulnCount":0,"tags":[],"waf":null,"organization":{"name":"TeamName","id":30}}} ```

Tag

The following allows users to lookup all tags in a system or lookup by id/name.

• -tg, --tags

• -stg, --search-tag id <Tag ID>

• -stg, --search-tag name <Tag Name>

Example:

INFO [main] CommandLineParser.processTagRequest(410) | Searching for tag with the id 6. INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":{"id":6,"name":"AppTag","type":"APPLICATION"}} ```

Upload

Single Scan File

This method allows the upload of a scan file to an application:

-u, --upload <Application ID> <File Path>

OR

-us, --upload-single <Application ID> <File Path>

Example:

INFO [main] CommandLineParser.main(279) | Uploading scan(s) to Application 30.
INFO [main] CommandLineParser.printOutput(1038) | Operation successful, printing JSON output.
{"message":"","success":true,"responseCode":-1,"object":"Scan upload process started.","links":[{"method":"GET","rel":"related","href":"http://localhost:8080/threadfix/rest/applications/30/pendingScan/99/status"}]}

Multiple Scan Files

This method allows the upload of multiple scan files to an application:

-um, --upload-multi <Application ID> <File Paths>

Example:

INFO [main] CommandLineParser.main(255) | Uploading scan(s) to Application with ID 30.
INFO [main] CommandLineParser.printOutput(1038) | Operation successful, printing JSON output.
{"message":"","success":true,"responseCode":-1,"object":"Scan upload process started.","links":[{"method":"GET","rel":"related","href":"http://localhost:8080/threadfix/rest/applications/30/pendingScan/97/status"}]}

Update Application

Queue Scan

This method allows users to queue a scan for the given applicationId with the given scanner type:

• -q, --queueScan <ApplicationId> <Scanner Name>

• Scanner Name is the name of a scanner supported by a Scan Agent. It can be one of the following: Acunetix WVS, Security AppScan Standard, Burp Suite, OWASP Zed Attack Proxy, or WebInspect.

Example:

INFO [main] CommandLineParser.main(197) | Queueing a scan. {"message":"","success":true,"responseCode":-1,"object":{"id":2,"active":true,"scanStatuses":[{"id":2,"active":true,"message":"Scan queued at: 13-10-15:12:40:827 -0500"}],"scanner":"Acunetix WVS","version":null,"createTime":1444758023827,"startTime":null,"endTime":null,"timeoutTime":1444801223827,"status":1,"scanAgentInfo":null,"secureKey":null,"scanAgentInstanceSecureKey":null,"scanConfig":null,"targetUrl":"http://test.com","scannerShortName":"acunetix","statusString":"QUEUED","taskStatus":"STATUS_QUEUED"}}

```

Add Url

This method allows users to add a URL for the given ApplicationId.

-au, --addAppUrl <ApplicationId> <Application Url>

Example:

INFO [main] CommandLineParser.main(212) | Adding url to applicationId 30 {"message":"","success":true,"responseCode":-1,"object":{"id":30,"name":"Application","url":"http://testfire.net/","uniqueId":null,"applicationCriticality":{"id":1,"name":"Low"},"scans":[{"id":14,"importTime":1309962639000,"numberClosedVulnerabilities":0,"numberNewVulnerabilities":2,"numberOldVulnerabilities":0,"numberResurfacedVulnerabilities":0,"numberTotalVulnerabilities":2,"numberRepeatResults":0,"numberRepeatFindings":0,"numberInfoVulnerabilities":0,"numberLowVulnerabilities":0,"numberMediumVulnerabilities":1,"numberHighVulnerabilities":1,"numberCriticalVulnerabilities":0,"fileName":null,"originalFileNames":["w3af-demo-site-2.xml"],"savedFileNames":[],"scannerName":"w3af"}],"infoVulnCount":0,"lowVulnCount":0,"mediumVulnCount":1,"highVulnCount":1,"criticalVulnCount":0,"totalVulnCount":2,"tags":[{"id":6,"name":"AppTag","type":"APPLICATION"}],"waf":{"name":"mod_sec1","id":30},"organization":{"name":"TeamName","id":30}}} ```

Set Task Config File

This method allows users to save the scan configuration for the given applicationId with the given scanner type:

• -stc, --setTaskConfig <ApplicationId> <Scanner Name> <file>

• Scanner Name can be short or full name of a scanner supported by Scan Agent

• file File path to scanner config file

Example:

Set Parameters

This method allows users to set scan parameters. Available parameters can be found with --printScanOptions.

• -sp, --setParameters <ApplicationId> <Framework Type> <[Repository Url]>

• Repository Url is optional.

Example:

INFO [main] CommandLineParser.main(174) | Setting parameters for application 30 to Framework Type: STRUTS INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":{"id":30,"name":"Application","url":"http://testfire.net/","uniqueId":null,"applicationCriticality":{"id":1,"name":"Low"},"scans":[{"id":14,"importTime":1309962639000,"numberClosedVulnerabilities":0,"numberNewVulnerabilities":2,"numberOldVulnerabilities":0,"numberResurfacedVulnerabilities":0,"numberTotalVulnerabilities":2,"numberRepeatResults":0,"numberRepeatFindings":0,"numberInfoVulnerabilities":0,"numberLowVulnerabilities":0,"numberMediumVulnerabilities":1,"numberHighVulnerabilities":1,"numberCriticalVulnerabilities":0,"fileName":null,"originalFileNames":["w3af-demo-site-2.xml"],"savedFileNames":[],"scannerName":"w3af"}],"infoVulnCount":0,"lowVulnCount":0,"mediumVulnCount":1,"highVulnCount":1,"criticalVulnCount":0,"totalVulnCount":2,"tags":[{"id":6,"name":"AppTag","type":"APPLICATION"}],"waf":{"name":"mod_sec1","id":30},"organization":{"name":"TeamName","id":30}}} ```

Add Tag

This method allows users to add Tag for the given applicationId.

-aat, --addAppTag <Application ID> <Tag ID>

Example:

INFO [main] CommandLineParser.processTagRequest(428) | Adding TagId 6 to ApplicationId 30. INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":{"id":30,"name":"Application","url":"http://test.com","uniqueId":null,"applicationCriticality":{"id":1,"name":"Low"},"tags":[{"id":6,"name":"AppTag","type":"APPLICATION"}],"team":{"name":"TeamName","id":30}}} ```

Remove Tag

This method allows users to remove Tag for the given applicationId.

-rat, --removeAppTag <Application ID> <Tag ID>

Example:

INFO [main] CommandLineParser.processTagRequest(439) | Removing TagId 6 from ApplicationId 30. INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":"Tag successfully removed from application"} ```

Others

Update Tag

This method allows users to update a new name to a tag for the given tagId.

-utg, --update-tag <tagId> <new name>

Example:

INFO [main] CommandLineParser.processTagRequest(449) | Updating name of TagId 6 to newTagName. INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":{"id":6,"name":"newTagName","type":"APPLICATION"}}

```

Remove Tag

This method allows users to remove a tag for the given tagId.

-rtg, --remove-tag <tagId>

Example:

INFO [main] CommandLineParser.printOutput(428) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":"Tag deleted successfully"}

```

Notes

All commands except for “Set”, as well all object names, can be reduced to their first letter. Application Channel is reduced to ac to prevent collision with a from Application. The following commands are both valid.

• java -jar tfcli.jar -ct TestTeam

• java -jar tfcli.jar -u 3 results.xml

To create a team that has the name "Big Team", or any team comprised of multiple words make sure to enclose the team name in single quotes:

• java -jar tfcli.jar -ct New Team, this will create a team called "New"

• java -jar tfcli.jar -ct 'New Team', this will create a team called "New Team"

For the help menu, and the full list of commands, use:

• java -jar tfcli.jar --help

Scripting

A common task may be to automate a scan at a specific time each day and then upload the results to ThreadFix. This can be accomplished by finding the ID of the correct Application and using it with the upload method. To find the ID of the Application, either look at the JSON as the object is being created from the command line or search by type name using the search application method.

Another tool to address automation and scripting needs is the ThreadFix API.

Vulnerability Search

The Vulnerability Search feature exposes a lot of filtering functionality through the REST interface. The following section describes the arguments the command line client accepts. Search is invoked from the command line using:

java -jar tfcli.jar --search <arg1> <arg2> ...

The arguments can be combined, so genericVulnerabilityIds=23,67 numberResults=100 scannerNames=Arachni,w3af will return up to 100 Arachni or w3af vulnerabilities with CWE 23 or 67.

Vulnerability Type

genericVulnerabilityIds

Default: All types

This parameter allows filtering on the CWE type attached to the Vulnerability. CWE IDs can be found on the CWE website here: http://cwe.mitre.org.

Example:

Team

teamIds

Default: All Teams

This parameter allows filtering on Teams. Single or multiple Team IDs are accepted. Team IDs can be obtained using the search team method.

Application

applicationIds

Default: All Applications

This parameter allows filtering on Applications. Single or multiple Application IDs are accepted. Application IDs can be obtained using the search application method.

Scanner Type

scannerNames

Default: All Scanner Types

This parameter allows filtering on Scanner Types. Single or multiple scanner names are accepted. This parameter accepts spaces, so tfcli.jar -search scannerNames=Fortify 360, Security AppScan Standard applicationIds=1,3 will parse correctly. The scanner name that ThreadFix accepts can be found using the ThreadFix web UI.

Severity

genericSeverityValues

Default: All Severities

This parameter allows filtering based on the generic severity assigned to the Vulnerability. Single or multiple severity integer values are accepted. Integer values for the severities are as follows:

• 1 = Info

• 2 = Low

• 3 = Medium

• 4 = High

• 5 = Critical

Number of Results

numberVulnerabilities

This parameter controls the number of results returned by the search.

Parameter

parameter

Default: any parameter

This parameter will filter on parameters. Submitting parameter=name will match vulnerabilities with the parameter username or the parameter firstName.

Path

path

Default: any path

This parameter will filter on path. Submitting path=login.jsp will match vulnerabilities with the path /login.jsp or the parameter /demosite/login.jsp.

Start Date

startDate

Default: any date

This parameter limits results to those whose first appearance was after the specified date. The value currently must match the pattern given above.

End Date

endDate

Default: any date

This parameter limits results to those whose first appearance was before the specified date. The value currently must match the pattern given above.

Vulnerability status

• showOpen

• showClosed=true

• showFalsePositive=true

• showHidden=true

Default: showOpen is true, the others are false.

All four states can be toggled on and off. Specifying showClosed=true showHidden=true will show you only hidden and closed vulnerabilities.

Number Merged

numberMerged

Default: No restriction on number merged

This method limits the results to only merged vulnerabilities. These are vulnerabilities with multiple scan findings. The number is a lower bound, so numberMerged=4 shows only vulnerabilities with four or more merged results.

Returned Vulnerability Format

Table of Contents