Note
The file extension is .threadfix (all lowercase). The file must use UTF-8 encoding. Only some of the fields are currently supported through the importer, leaving some fields within ThreadFix null.

Three sample scan files (DAST, SAST, and DEPENDENCY) are available at the bottom of this page.

File Format

When creating a .threadfix file that represents a scan to be imported into ThreadFix database, the base object is a FindingCollection. A finding collection includes data about the scan, as well as a list of Findings.

Name	Required	Used	Type	Description
`url`	yes	yes	string	The URL at which the DAST scanner identified the vulnerability.
`parameter`	yes	yes	string	The vulnerability parameter
`attackString`	no	yes	string	The successful attack string the DAST scanner used.
`attackRequest`	no	yes	string	The successful attack payload the DAST scanner used.
`attackRespose`	no	yes	string	The response the application returned demonstrating a successful attack.

StaticDetails

Use this Details object to represent data from a SAST scanner.

Name

Required

Used

Type

Description

dataFlow

yes

DataFlowElement[]

An array of ordered DataFlow elements representing the source to sink vulnerable flow of data identified by a SAST scanner. See DataFlowElement below.

parameter

yes

string

A field identifying the vulnerability source parameter; the parameter expected from the method call.

file

yes*

yes

String

The source code file name for this vulnerability.

*Required field, but can be provided in the first DataFlowElement instead of here.

DataFlowElement

Name	Required	Used	Type	Description
`file`	yes	yes	string	The source code file name for this element of the vulnerable data flow.
`lineNumber`	yes	yes	integer	The line of code for the data flow element.
`columnNumber`	yes	yes	integer	The column where the vulnerable parameter starts.
`text`	yes	yes	string	The text of the vulnerable source code.
`sequence`	no	yes	integer	A sequential number used to order the steps of the data flow element, from source at 1 and increasing to the sink. Each sequence number must only be used once, and the sink sequence number should equal the number of DataFlowElements in the array. While not technically required, it is highly recommended to use this field to control order. If not, the order DataFlowElements are saved in the database may not reflect the vulnerability's actual data flow.

DependencyDetails

Use this Details object to represent data from a Dependency-based scanner.

Name	Required	Used	Type	Description
`library`	yes	yes	string	The name of the library the dependency finding was identified for.
`description`	yes	yes	string	A text description of the issue that was identified.
issueType	yes	yes	IssueType (string)	The type of dependency issue identified. Valid options: VULNERABILITY - an identified problem in the library related to the code LICENSE - an identified issue with the licensing involved with using the library UNKNOWN - any other type of issue, or an issue that is difficult to categorize
reference	yes*	yes	string	The CVE or scanner-specific identifier for the type of issue. If it is a CVE, be sure to include "CVE-" at the start of the string (for example: "CVE-2012-6708"). *Required field, but can be taken from a "CVE" type mapping provided in the Mappings section for the finding.
referenceLink	no	yes	string	A link to the details of the type of issue identified, for example a link to the CVE page on https://cve.mitre.org/.
filePathList	no	yes	string[]	A list of paths to the library in the user’s code, such as the jar file for offending libraries. Replacement for 'filePath'.
filePath	no	yes*	string	DEPRECATED as of ThreadFix version 2.7.6. The path to the library in the user’s code, such as the jar file for an offending library. Not used when 'filePathList' is present.
version	no	yes	string	The version for the library.
CVE	no	export only	string	If a dependency finding contains CVE data, any and all CVEs will be included here. For example this is useful when the `reference` field returns a BlackDuck specific reference type `BDSA` and not a `CVE`.

Mapping

Name	Required	Used	Type	Description
`mappingType`	yes	yes	MappingType (string)	Identifies the vulnerability classification mapping type. Valid options: `CWE` - MITRE Common Weakness Enumeration, strongly recommended but not technically required that all Findings have one primary CWE. CWE is required for merging. `CVE` - MITRE Common Vulnerabilities and Exposures `TOOL_VENDOR` - For custom vulnerability types from a scanner vendor. Mappings with this type requires the `vendorOtherTypeField` to be populated. Options that are not yet valid, but to be supported in the future: `PRODUCT_VENDOR` - For custom vulnerability types from a developer of a vulnerable piece of software. For example, Microsoft KB numbers. Mappings with this type are planned to require the `vendorOtherTypeField` to be populated. `OTHER` - For any other custom type. Mappings with this type are planned to require the `vendorOtherTypeField` to be populated.
`value`	yes	yes	string	The actual ID to map to. CWE and CVE values must be valid. Note: For CWE, users can use a “-1” value to map a finding to “None” or can omit the mappings element altogether, which will result in an “Unmapped” CWE value.
`primary`	no*	yes	boolean	If more than one Mapping of a given mappingType is included for one Finding, one and only one mapping must be labeled as primary. If only one Mapping of a given mappingType is included, it is assumed to be the primary.
`vendorOtherType`	no*	yes	string	The name of the custom vulnerability categorization system. Required for Mappings of mappingType `TOOL_VENDOR`, `PRODUCT_VENDOR` and `OTHER`.

Example Scan Files

The following sample files show a typical .threadfix file from a DAST, SAST, and DEPENENCY DEPENDENCY scanner.

Warning
A scanner with a matching name must be configured in ThreadFix to successfully import. See Create a New Scanner.

Expand

title	Dynamic_findings.threadfix

Code Block

{
  "id": 123,
  "created": "2018-02-01T00:00:00Z",
  "updated": "2018-02-02T13:00:00Z",
  "exported": "2018-02-03T11:00:00Z",
  "collectionType": "DAST",
  "source": "MyCustomScanner",
  "executiveSummary": "After an automated and manual review of SampleApp, it was found to be...",
  "metadata": {
    "version": "1.2",
	"reviewed by third party": "true"
  },
  "findings": [
    {
      "id": 234,
      "nativeId": "abcd-1234-ef12-5678-3456",
      "severity": "High",
      "nativeSeverity": "Severity2",
      "summary": "Double Reflected Cross-site Scripting(XSS)",
      "description": "The worst kind of XSS",
      "scannerDetail": "\t\tAbstract:\n\n\t\t<Content><Paragraph>On line <Replace key=\"PrimaryLocation.line\"",
	  "scannerRecommendation": "<fixRecommendations>\n            <fixRecommendation type=\"General\">\n              <text>If the...",
	  "statuses": { "False Positive": false, "Exploitable": true},
      "dynamicDetails": {
        "surfaceLocation": {
          "url": "http://localhost:8080/app/login",
          "parameter": "isAdmin",
          "attackString": "<script>alert('hi')</script>",
          "attackRequest": "\n\t\tPOST /bodgeit/login.jsp HTTP/1.1\n\t\tReferer: ",
		  "attackResponse": "HTTP/1.1 200 OK\nDate: Thu, 01 Feb 2018 01:53:47 GMT\nServer: Apache/2.2.19 (W..."
        }
      },
      "metadata": {
        "Org Unit": "East Asia",
        "Remediation Priority": "Medium",
        "Risk from External Attackers": "Low",
        "Risk from Internal Attackers": "High"
      },
      "tags": [
        "PCI",
        "External API"
      ],
      "mappings": [
        {
          "mappingType": "CWE",
          "value": "79",
          "primary": true
        },
        {
          "mappingType": "TOOL_VENDOR",
          "value": "IBM-454",
          "primary": true,
          "vendorOtherType": "AppScanID"
        },
        {
          "mappingType": "TOOL_VENDOR",
          "value": "IBM-1883",
          "vendorOtherType": "AppScanID"
        }
      ],
      "comments": [
        "12/1/17 - Cannot be reproduced by hand",
        "12/2/17 - Never mind, i figured it out."
      ]
    }
  ]
}

Expand

title	Static_findings.threadfix

Code Block

{
  "id": 123,
  "created": "2018-01-01T00:00:00Z",
  "updated": "2018-01-02T00:00:00Z",
  "exported": "2018-01-03T11:00:00Z",
  "collectionType": "SAST",
  "source": "MyCustomScanner",
  "executiveSummary": "After an automated and manual review of SampleApp, it was found to be...",
  "metadata": {
    "version": "1.2",
	"reviewed by third party": "true"
  },
  "findings": [
    {
      "id": 234,
      "nativeId": "abcd-1234-ef12-5678-3456",
      "severity": "High",
      "nativeSeverity": "Severity2",
      "summary": "Double Reflected Cross-site Scripting(XSS)",
      "description": "The worst kind of XSS",
      "scannerDetail": "Abstract:\n\n<Content><Paragraph>Without proper access control, the method <Replace key=\"EnclosingFunction.name\"/> in <Replace key=\"PrimaryLocation.file\"/> can execute a SQL statement on line <Replace key=\"PrimaryLocation.line\"/> that contains an attacker-controlled primary key, thereby allowing the attacker to access unauthorized records.<AltParagraph>Without proper access control, executing a SQL statement that contains a user-controlled primary key can allow an attacker to view unauthorized records.</AltParagraph></Paragraph></Content>\n",
      "scannerRecommendation": "Recommendations: Rather than relying on the presentation layer to restrict values submitted by the user, access control should be handled by the application and database layers. Under no circumstances should a user be allowed to retrieve or modify a row in the database without the appropriate,,,",
	  "statuses": { "False Positive": false, "Exploitable": true},
      "staticDetails": {
        "parameter": "isAdmin",
		"file": "/src/Controllers/LoginController.cs",
		"dataFlow": [
          {
            "file": "/src/Controllers/LoginController.cs",
            "lineNumber": 26,
            "columnNumber": 4,
            "text": "return authService(request.Param[\"admin\"]);",
			"sequence": 1
          },
          {
            "file": "/src/Services/AuthenticationService.cs",
            "lineNumber": 46,
            "columnNumber": 12,
            "text": "return authDao(isAdmin);",
            "sequence": 2
          }
        ]
      },
      "metadata": {
        "Org Unit": "East Asia",
        "Remediation Priority": "Medium",
        "Risk from External Attackers": "Low",
        "Risk from Internal Attackers": "High"
      },
      "tags": [
        "PCI",
        "External API"
      ],
      "mappings": [
        {
          "mappingType": "CWE",
          "value": "79",
          "primary": true
        },
        {
          "mappingType": "TOOL_VENDOR",
          "value": "FORT-454",
          "primary": true,
          "vendorOtherType": "FortifyFindingDB"
        },
        {
          "mappingType": "TOOL_VENDOR",
          "value": "FORT-1883",
          "vendorOtherType": "FortifyFindingDB"
        }
      ],
      "comments": [
        "12/1/17 - Cannot be reproduced by hand",
        "12/2/17 - Never mind, i figured it out."
      ]
    }
  ]
}

Expand

title	Dependency_findings.threadfix

Code Block

{
  "id": 123,
  "created": "2019-01-14T00:00:00Z",
  "updated": "2018-01-14T13:00:00Z",
  "exported": "2018-01-15T11:00:00Z",
  "collectionType": "DEPENDENCY",
  "source": "MyCustomScanner",
  "executiveSummary": "After an automated and manual review of SampleApp, it was found to be...",
  "metadata": {
    "version": "1.2",
    "reviewed by third party": "true"
  },
  "findings": [
    {
      "id": 234,
      "nativeId": "abcd-1234-ef12-5678-3456",
      "severity": "Medium",
      "nativeSeverity": "6",
      "summary": "jQuery vulnerable to Flash Cross Site Scripting",
      "description": "jQuery is vulnerable to cross site scripting in File...",
      "scannerDetail": "jQuery is vulnerable to cross site scripting in File...",
      "scannerRecommendation": "Fix Available - Fixed in 2.0.15",
	  "statuses": { "False Positive": false, "Exploitable": true},
      "dependencyDetails": {
        "library": "jQuery",
		"description": "jQuery is vulnerable to cross site scripting in File...",
		"reference": "BDSA-2015-0110",
		"referenceLink": "https://yourinstaceof.blackducksoftware.com/api/vulnerabilities/BDSA-2015-0110",
		"filePathList": [
			"./samplePath1.jar",
			"./src/samplePath2.jar",
			"./root/bin/samplePath3.jar"
		],
		"version": "1.4.1",
		"issueType": "VULNERABILITY"
      },
      "metadata": {
        "Org Unit": "East Asia",
        "Remediation Priority": "Medium",
        "Risk from External Attackers": "Low",
        "Risk from Internal Attackers": "High"
      },
      "tags": [
        "PCI",
        "External API"
      ],
      "mappings": [
        {
          "mappingType": "CWE",
          "value": "79",
          "primary": true
        }
      ],
      "comments": [
        "1/14/19 - Cannot be reproduced by hand",
        "1/15/19 - Never mind, i figured it out."
      ]
    },
	{
      "id": 235,
      "nativeId": "1234-5678-90ab-cdef-1234",
      "severity": "High",
      "nativeSeverity": "8",
      "summary": "jQuery vulnerable to Flash Cross Site Scripting",
      "description": "jQuery is vulnerable to cross site scripting in File...",
      "scannerDetail": "jQuery is vulnerable to cross site scripting in File...",
      "scannerRecommendation": "Fix Available - Fixed in 2.0.15",
      "dependencyDetails": {
        "library": "jQuery",
		"description": "jQuery is vulnerable to cross site scripting in File...",
		"reference": "BDSA-2015-0110",
		"referenceLink": "https://yourinstaceof.blackducksoftware.com/api/vulnerabilities/BDSA-2015-0110",
		"filePath": "./src/test/resources/jquery-1.4.2.jar",
		"version": "1.4.2",
		"issueType": "VULNERABILITY"
      },
      "metadata": {
        "Org Unit": "East Asia",
        "Remediation Priority": "Medium",
        "Risk from External Attackers": "Low",
        "Risk from Internal Attackers": "High"
      },
      "tags": [
        "PCI",
        "External API"
      ],
      "mappings": [
        {
          "mappingType": "CWE",
          "value": "79",
          "primary": true
        },
		{
		  "mappingType": "CVE",
		  "value": "CVE-2012-6708",
		  "primary": false
		}
      ],
      "comments": [
        "1/15/19 - Same steps to reproduce as jQuery 1.4.1"
      ]
    }
  ]
}

yes	Export only	integer	The Scan's primary key, scanId. This column is ignored on imports.
`created`	yes	yes	timestamp ¥	The date the scan was run.
`updated`

Versions Compared

Old Version 5

New Version Current

Key

File Format

Table of Contents

FindingCollection

Finding

DynamicDetails

SurfaceLocation

StaticDetails

DataFlowElement

DependencyDetails

Mapping

Example Scan Files

Page Comparison

Versions Compared

Old Version 5

New Version Current

Key

File Format

Table of Contents

FindingCollection

Finding

DynamicDetails

SurfaceLocation

StaticDetails

DataFlowElement

DependencyDetails

Mapping

Example Scan Files