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
`id`	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`	yes	yes	timestamp ¥	The date the scan was last audited or otherwise edited.
`exported`	yes	Export only	timestamp ¥	The date the .threadfix file was generated. This column is ignored on imports, but is planned for future use.
`collectionType`	yes	yes	CollectionType (string)	The type of scanner used. Valid options: `SAST`, `DAST, DEPENDENCY, MIXED` In the future support will be added for: `HYBRID`, `IAST`, `NETWORK`
`source`	yes	yes	string	Scanner name. A scanner with a matching name must be configured in ThreadFix to successfully import. See Create a New Scanner Do not use "Manual" as the source. (This is no longer allowed as of TF version 2.7.8)
`context`	no	no	string	Not used. Future support may be added for multiple sub-channels.
`executiveSummary`	no	no	string	Not used. Future support may be added to allow for a summary data entered by a scan auditor or for use with manual assessments.
`findings`	yes	yes	Findings	A collections of findings. See the Finding section below.
`metadata`	no	yes	map<string,string>	A list of key value pairs of additional metadata to be displayed on the Scan Details page. The Key name must be already configured in ThreadFix to be successfully imported.
`assessmentData`	no	no	AssessmentData	Not used. Future support for manual assessment data.

*All timestamps are to be in yyyy-MM-ddTHH:mm:ssZ format.

Finding

Name	Required	Used	Type	Description

Name	Required	Used	Type	Description
`id`	no	Export Only	integer	The Finding's primary key, findingId. This column is ignored on imports.
`created`	no	no	timestamp ¥	Not used. Future support may be added for individual findings to have different discovery dates.
`updated`	no	no	timestamp ¥	Not used. Future support may be added for individual findings to have different updated dates.
`nativeId`	yes	yes	string	A unique ID for a finding from the scanner. Character limit: 256 If the source scanner has the ability to track the same vulnerability across multiple scans, this file should use an ID value that is common between multiple scan runs.
`severity`	yes	yes*	Severity (string)	The ThreadFix severity to assign to this finding's "nativeSeverity", if it hasn't been mapped yet. *After a nativeSeverity has a mapping, all findings with that nativeSeverity will share the same severity mapping. Valid options: `Info`, `Low`, `Medium`, `High`, `Critical`
`nativeSeverity`	yes	yes	string	The original severity name from the scanner. Character limit: 25
`cvssScore`	no	yes	decimal	Populates the CVSS score field on the Finding Details page. Must be between 0 and 10, other decimal values will be ignored for this field.
`summary`	yes	yes*	string	Populates the finding summary on the finding details page. 150 character limit. *After a summary has a CWE mapping (from the "mappings" field), all findings with that summary will share the same CWE mapping.
`description`	no	yes	string	Populates the finding description on the finding details page. 2047 character limit.
`scannerDetail`	no	yes	string	Populates the scanner details on the finding details page.
`scannerRecommendation`	no	yes	string	Populates the scanner recommendation on the finding details page.
`findingDetails`	yes	yes	DynamicDetails, StaticDetails, or DependencyDetails	Provides additional finding details specific to the type or scanner used. A individual finding must have one, and only one type of details object, DynamicDetails, StaticDetails, or DependencyDetails. Future support will be added for the NetworkDetails type.
`metadata`	no	no	map<string,string>	Allows key value pair metadata to be associated with a Finding.
`tags`	no	yes	string[]	An array of ThreadFix tags to associate with the vulnerability. Note that a tag with a matching name must already be configured in ThreadFix to successfully associate with the record.
`mappings`	no	yes	Mapping[]	An array of common classification IDs (Such as CWE, CVE) to categorize the finding. See Mapping below. Not required, but highly recommended. If no CWE is provided, no merging can take place with other scanning tools.
`rawFinding`	no	yes	string	The data from the raw findings sections of the Scan Details page. This is used to override the information displayed on this page; if users do not specify a rawFinding, ThreadFix will list the entire finding from the .threadfix file in the rawFinding section.
`comments`	no	yes	string[]	An array of comments to add and associate to the finding in ThreadFix. Format: `"date (in MM/dd/yy) - text" (e.g., "12/1/17 - Cannot be reproduced by hand")` Note: The dash delimiter between the date and text is required, this is an "en dash" (-) If the date is missing from the comment, the date of the upload will be used as the comment date.
`group`	no	no	FindingGroup	Not used. Future support may be added allowing with ManualAssessment data to allow for custom groupings of findings.
statuses	no	yes	map<string, boolean>	An optional map of predefined statuses with their corresponding boolean value. Valid statuses are: Exploitable and/or False Positive Format: "statuses": { "False Positive": true, "Exploitable": false}

DynamicDetails

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

Name	Required	Used	Type	Description

Name	Required	Used	Type	Description
`surfaceLocation`	yes	yes	SurfaceLocation	The collection of data representing the location where the DAST scanner identified a vulnerability. See the SurfaceLocation section below.

SurfaceLocation

Name	Required	Used	Type	Description

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

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

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

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

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 DEPENDENCY scanner.

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

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

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

ThreadFix 3.X Documentation

ThreadFix File Format 3.X