As of December 31st, 2023 ThreadFix 2.X has reached End of Life and is no longer supported. For any further information please contact the Success and Implementation team.

Command Line Interface API Client

Owned by Hector Ruiz (Unlicensed)
Last updated: Jul 02, 2021
11 min read

Download

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


Details

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.


Create

Team

  • -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}} ```

Application

  • -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}}} ```

WAF

  • -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":[]}} ```

Tag

  • -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"}} ```


Team

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"}}]}} ```

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:

    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}}} ```

WAF

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":[]}} ```

Tag

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"}} ```


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:

    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"}]}

Multiple Scan Files

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 Paths> (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"}]}


Rules

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"} ```


Update Application

Queue Scan

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"}}

```

Add Url

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}}} ```

Set Task Config File

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"}

Set Parameters

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}}} ```

Add Tag

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}}} ```

Remove Tag

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"} ```


Others

Update Tag

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"}}

```

Remove Tag

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"}

```

Notes

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

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


Vulnerability Search

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.

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:

    denimgroup$ java -jar tfcli.jar --search genericVulnerabilityIds=79,89

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.

    denimgroup$ java -jar tfcli.jar --search teamIds=1,2,3,4,5

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.

    denimgroup$ java -jar tfcli.jar --search applicationIds=1,2,3,4,5

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.

    denimgroup$ java -jar tfcli.jar --search scannerNames=Arachni, Security AppScan Standard

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
    denimgroup$ java -jar tfcli.jar --search genericSeverityValues=2,4,5

Number of Results

  • numberVulnerabilities

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

    denimgroup$ java -jar tfcli.jar --search numberVulnerabilities=245

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.

    denimgroup$ java -jar tfcli.jar --search parameter=username

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.

    denimgroup$ java -jar tfcli.jar --search path=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.

    denimgroup$ java -jar tfcli.jar --search startDate=13-May-2009

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.

    denimgroup$ java -jar tfcli.jar --search endDate=13-May-2009

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.

    denimgroup$ java -jar tfcli.jar --search showClosed=true showHidden=true

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.

    denimgroup$ java -jar tfcli.jar --search numberMerged=3

Returned Vulnerability Format

{
  "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"
    }
  ]
}

www.threadfix.it | www.coalfire.com
Copyright © 2024 Coalfire. All rights reserved.

This Information Security Policy is CoalFire - Public: Distribution of this material is not limited.