Download the ThreadFix Command Line Interface (CLI) from ThreadFix by clicking Help (?) → Download Tools and clicking the corresponding "Jar File" link. File name: tfcli.jar
In order to use most of the methods, you must set your API key and potentially your URL too, if you aren't using http://localhost:8080/threadfix/.
In order to do that, issue these commands, substituting your ThreadFix API key and URL:
java -jar tfcli.jar --set key <apikey> java -jar tfcli.jar --set url <url>
Here's an example:
java -jar tfcli.jar --set key 7xo58j2lnogk24k7r2kb4 java -jar tfcli.jar --set url http://localhost:8080/threadfix/rest/latest
Be sure to include /rest at the end of the URL, or it will not work. Also, to use the latest ThreadFix API, you should add /latest per the example above...Reference: API Versioning |
All of the rest of the commands should be prefaced with java -jar tfcli.jar
.
-ct, --create-team <Team Name>
Use the name you want for your team.
Example:
denimgroup$ java -jar tfcli.jar --create-team TeamName
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}} ```
-ca, --create-app <Team ID> <Application Name> <Application Url>
Get the Team ID either by looking at the returned JSON from the create team method, your browser's URL after organization/
or by using the search-team method.
Example:
denimgroup$ java -jar tfcli.jar --create-app 30 Application http://test.com
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}}} ```
-cw, --create-waf <name> <type name>
type name
should be one of "mod_security", "Snort", "Imperva SecureSphere", "DenyAll rWeb", or "BIG-IP ASM"
Example:
INFO [main] CommandLineParser.main(120) | Creating a Waf with the name mod_sec1.
INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":{"id":30,"name":"mod_sec1","wafTypeName":"mod_security","applications":[]}} ```
-ctg, --create-tag <Tag Name> <[tagType]>
User the name you want for new tag. tagType
is optional , should be one of Application, Vulnerability, or Comment. By default ThreadFix will create Application tag.
Example:
denimgroup$ java -jar tfcli.jar --create-tag AppTag Application
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"}} ```
These methods allow team lookup by id or name.
-st, --search-team id <Team ID>
-st, --search-team name <Team Name>
Example:
denimgroup$ java -jar tfcli.jar --search-team id 30
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"}}]}} ```
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:
denimgroup$ java -jar tfcli.jar --search-app name Application TeamName
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}}} ```
These methods allow WAF lookup by id or name.
-sw, --search-waf id <WAF ID>
-sw, --search-waf name <WAF Name>
Example:
denimgroup$ java -jar tfcli.jar --search-waf id 30
INFO [main] CommandLineParser.main(259) | Searching for WAF with the id 30. INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":{"id":30,"name":"mod_sec1","wafTypeName":"mod_security","applications":[]}} ```
You can lookup for all tags in system or lookup by id/name.
-tg, --tags
-stg, --search-tag id <Tag ID>
-stg, --search-tag name <Tag Name>
Example:
denimgroup$ java -jar tfcli.jar --search-tag id 6
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"}} ```
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:
denimgroup$ java -jar tfcli.jar --upload 30 C:\example\path\w3af-demo-site-2.xml
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"}]}
This method allows the upload of multiple scan files to an application.
-u, --upload <Application ID> <File Paths> (this will upload multiple files from the same scanner type as a single scan)
OR
-um, --upload-multi
<Application ID> <File Path
s
>
(this will upload multiple files from any scanner type(s) as multiple scans)
Example:
denimgroup$ java -jar tfcli.jar --upload-multi 30 C:\example\path\w3af-demo-site-1.xml C:\example\path\w3af-demo-site-2.xml
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"}]}
This method allows the retrieval of rules corresponding to a WAF.
-r, --rules <WAF ID>
Example:
denimgroup$ java -jar tfcli.jar --rules 30
INFO [main] CommandLineParser.main(319) | Downloading all rules from WAF with ID 30. INFO [main] CommandLineParser.printOutput(496) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":"SecRule REQUEST_URI "^\/demo\/OSCommandInjection2\.php""phase:2,chain,deny,msg:'OS Command Injection attempt: /demo/OSCommandInjection2.php [fileName]',id:'100000',severity:'2'"\nSecRule ARGS:fileName "&|\||;|%7C|%26|%3B"\n\n"} ```
This method allows to queue a scan for the given applicationId with the given scanner type.
-q, --queueScan <ApplicationId> <Scanner Name>
Scanner Name
is name of a scanner supported by Scan Agent, can be one of the following: Acunetix WVS, Security AppScan Standard, Burp Suite, OWASP Zed Attack Proxy, or WebInspect.
Example:
denimgroup$ java -jar tfcli.jar --queueScan 30 acunetix
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"}}
```
This method allows to add URL for the given ApplicationId.
-au, --addAppUrl <ApplicationId> <Application Url>
Example:
denimgroup$ java -jar tfcli.jar --addAppUrl 30 http://testfire.net/
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}}} ```
This method allows 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:
denimgroup$ java -jar tfcli.jar --setTaskConfig 1 webinspect \path\to\webinpsect_setting.xml INFO [main] CommandLineParser.main(185) | Setting task config {"message":"","success":true,"responseCode":-1,"object":"Scan configuration for scanner: webinspect saved for appId: 1"}
This method allows to set scan parameters. Available parameters can be found with --printScanOptions.
-sp, --setParameters <ApplicationId> <Framework Type> <[Repository Url]>
Repository Url
is optional.
Example:
denimgroup$ java -jar tfcli.jar --setParameters 30 STRUTS
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}}} ```
This method allows to add Tag for the given applicationId.
-aat, --addAppTag <Application ID> <Tag ID>
Example:
denimgroup$ java -jar tfcli.jar --addAppTag 30 6
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}}} ```
This method allows to remove Tag for the given applicationId.
-rat, --removeAppTag <Application ID> <Tag ID>
Example:
denimgroup$ java -jar tfcli.jar --removeAppTag 30 6
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"} ```
This method allows to update new name to a tag for the given tagId.
-utg, --update-tag <tagId> <new name>
Example:
denimgroup$ java -jar tfcli.jar --update-tag 6 newTagName
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"}}
```
This method allows to remove a tag for the given tagId.
-rtg, --remove-tag <tagId>
Example:
denimgroup$ java -jar tfcli.jar --rtg 34
INFO [main] CommandLineParser.processTagRequest(391) | Removing TagId 34.
INFO [main] CommandLineParser.printOutput(428) | Operation successful, printing JSON output. {"message":"","success":true,"responseCode":-1,"object":"Tag deleted successfully"}
```
All commands except for set can be reduced to their first letter, and all object names can as well. 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
If you wish to create a team that has the name "Big Team", or any team that is comprised of multiple words make sure that you 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
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 your Application, either look at the JSON as you create the object 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
The Vulnerability Search feature exposes lots of filtering functionality through the REST interface.
The following section describes the arguments that 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.
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:
denimgroup$ java -jar tfcli.jar --search genericVulnerabilityIds=79,89
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.
denimgroup$ java -jar tfcli.jar --search teamIds=1,2,3,4,5
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.
denimgroup$ java -jar tfcli.jar --search applicationIds=1,2,3,4,5
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.
denimgroup$ java -jar tfcli.jar --search scannerNames=Arachni, Security AppScan Standard
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:
denimgroup$ java -jar tfcli.jar --search genericSeverityValues=2,4,5
numberVulnerabilities
This parameter controls the number of results returned by the search.
denimgroup$ java -jar tfcli.jar --search numberVulnerabilities=245
parameter
Default: any parameter
This parameter will filter on parameters. Submitting parameter=name
will match vulnerabilities with the parameter username
or the parameter firstName
.
denimgroup$ java -jar tfcli.jar --search parameter=username
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
.
denimgroup$ java -jar tfcli.jar --search path=login.jsp
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.
denimgroup$ java -jar tfcli.jar --search startDate=13-May-2009
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.
denimgroup$ java -jar tfcli.jar --search endDate=13-May-2009
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.
denimgroup$ java -jar tfcli.jar --search showClosed=true showHidden=true
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.
denimgroup$ java -jar tfcli.jar --search numberMerged=3
{ "message": "", "success": true, "responseCode": -1, "object": [ { "id": 471, "defect": { "id": 2, "nativeId": "EXAMPLE-438", "status": "Open", "defectURL": "https://yourjiraproject.net/browse/EXAMPLE-438", "statusUpdatedDate": null, "opened": true }, "genericVulnerability": { "id": 78, "name": "Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection')", "displayId": 78 }, "genericSeverity": { "id": 1, "name": "High", "intValue": 4, "displayName": "High" }, "originalGenericSeverity": { "id": 1, "name": "High", "intValue": 4, "displayName": "High" }, "surfaceLocation": { "id": 486, "parameter": "fileName", "path": "/demo/OSCommandInjection2.php", "httpMethod": null, "humanLocation": "http://example.url/demo/OSCommandInjection2.php" }, "calculatedUrlPath": "/OSCommandInjection2.php", "calculatedFilePath": "", "active": true, "isFalsePositive": false, "hidden": false, "openTime": 1309962639000, "closeTime": null, "findings": [ { "id": 486, "scannedDate": null, "longDescription": null, "attackString": null, "attackRequest": "", "attackResponse": "", "rawFinding": "<vulnerability id=\"[4094]\" method=\"POST\" name=\"OS commanding vulnerability\" plugin=\"osCommanding\" severity=\"High\" url=\"http://example.url/demo/OSCommandInjection2.php\" var=\"fileName\">\n OS Commanding was found at: \"http://example.url/demo/OSCommandInjection2.php\", using HTTP method POST. The sent post-data was: \"fileName=type+%25SYSTEMROOT%25%5Cwin.ini\". This vulnerability was found in the request with id 4094.\n </vulnerability>", "nativeId": "7defd04bac3089120e2187d1c28fccb3", "displayId": null, "surfaceLocation": { "id": 486, "parameter": "fileName", "path": "/demo/OSCommandInjection2.php", "httpMethod": null, "humanLocation": "http://example.url/demo/OSCommandInjection2.php" }, "staticPathInformation": null, "entryPointLineNumber": -1, "sourceFileLocation": null, "hasStatisticsCounter": true, "foundHAMEndpoint": false, "dataFlowElements": [], "calculatedUrlPath": "/OSCommandInjection2.php", "calculatedFilePath": "", "dependency": null, "hidden": null, "authenticationRequired": "UNKNOWN", "firstFindingForVuln": true, "markedFalsePositive": false, "scannerName": "w3af", "severity": "High", "vulnerabilityType": "OS commanding vulnerability" } ], "documents": [], "grcControl": null, "tags": [], "path": "/OSCommandInjection2.php", "staticFindings": [], "vulnerabilityComments": [], "parameter": "fileName", "fullUrl": "http://example.url/demo/OSCommandInjection2.php", "channelNames": ["w3af"], "uri": "/organizations/30/applications/30/vulnerabilities/471", "team": { "id": 30, "name": "TeamName" }, "app": { "id": 30, "name": "Application", "url": "http://testfire.net/", "applicationCriticality": { "id": 1, "name": "Low" }, "projectName": "yourjiraproject", "projectId": "EXAMPLE", "component": null, "useDefaultCredentials": true, "useDefaultProject": false, "svnRepositoryUrl": "null/trunk" }, "dependency": null, "vulnId": "471", "dynamicFindings": [], "authenticationRequired": "UNKNOWN" } ] }