Image Removed NoteThe file extension is .threadfix (all lowercase). The file must use UTF-8 encoding. Only some of the fields are currently supported through the importer,

Image Added

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.

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

*As of ThreadFix version 2.7.6

source

yes

string

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

Warning
Do not use "Manual" as

your

the source. (This is no longer allowed as of TF version 2.7.8)

context

no

string

Still true? (same question for all below)

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-dd'T'HHddTHH:mm:ss'Z'** ssZ format. **For ThreadFix version 2.8.3 or newer, the 'Z' will reflect the time zone based on UTC. This is part of 3.0.8 now right?

Finding

Name

Required

Used

Type

Description

id

no

Export Only

integer

The Finding's primary key, findingId. This column is ignored on imports.

created

no

timestamp ¥

Not used.

Future support may be added for individual findings to have different discovery dates.

Still true?

updated

no

timestamp ¥

Not used.

Future support may be added for individual findings to have different updated dates.

Still true?

nativeId

yes

string

A unique ID for a finding from the scanner.

Note
This ID must be unique or the other findings with the same nativeId will get de-duplicated.

Character limit:

limit for 3x?

~~2.7.9 and older: 50~~

2.8.0 and newer:

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

Note
Do NOT use an empty string as the value.

nativeSeverity

yes

string

The original severity name from the scanner.

Character limit: 25

Note
Do NOT use an empty string as the value.

cvssScore

no

Not used.

Future support will be added for CVSS Scores for Network and Dependency scanners. Still true?

yes

string

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.*As of ThreadFix version 2.7.2 Is there as an equivalent version number to reference for 3x?

. 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[]

does this need the brackets? Same with a few others below.

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.

Note
Specifying this field could result in loss of data in ThreadFix.

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

)For Versions prior to 2.7.9: If you need to include a dash within a comment, use an "em dash" (—) instead; if you use an en dash, the text after it will be ignored (fixed in 2.7.9). is this comment necessary? Or half of it?

)
If the date is missing from the comment, the date of the upload will be used as the comment date.

*As of ThreadFix version 2.7.3 Is there as an equivalent version number to reference for 3x?

group

no

FindingGroup

Not used.

Future support may be added allowing with ManualAssessment data to allow for custom groupings of findings.

Still true?


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}

*

As of ThreadFix version 2.7.7 Is there as an equivalent version number to reference for 3x?

*All timestamps are to be in yyyy-MM-dd'T'HH:mm:ss'Z'** format.
**For ThreadFix version 2.8.3 or newer, the 'Z' will reflect the time zone based on UTC-ddTHH:mm:ssZ format.

DynamicDetails

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

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
`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	yes	DataFlowElement[]	An array of ordered DataFlow elements representing the source to sink

(sync?)

vulnerable flow of data identified by a SAST scanner. See DataFlowElement below.
`parameter`	yes

*

yes

string

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

*As of ThreadFix version 2.7.1

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

(should this be sync?)

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

you do

not, the order DataFlowElements are saved in the database may not reflect the vulnerability's actual data flow.

DependencyDetails

(support added in 2.7.3) is there an equivalent 3x version number or has it been from the beginning of 3X?

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
www.mitre.org. Is the correct link supposed to be
https://cve.mitre.org
/ or https:
/
/cwe
.
mitre.org ?
filePathList
no
yes
string[]
INTRODUCED in ThreadFix version 2.7.6.
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.
Ok to delete?
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

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:

(available yet?)

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

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.

This was edited into the 2x version of this doc, is this true for 3x today?


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

Versions Compared

Old Version 3

New Version Current

Key

File Format

Table of Contents

FindingCollection

Finding

DynamicDetails

SurfaceLocation

StaticDetails

DataFlowElement

DependencyDetails

Mapping

Example Scan Files

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`

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

Replacement for 'filePath'.
filePath	no	yes*	string	DEPRECATED as of ThreadFix version 2.7.6.

Page Comparison

Versions Compared

Old Version 3

New Version Current

Key

File Format

Table of Contents

FindingCollection

Finding

DynamicDetails

SurfaceLocation

StaticDetails

DataFlowElement

DependencyDetails

Mapping

Example Scan Files