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.
ThreadFix File Format
As the file format is still new, only some of the fields are currently supported through the importer, thus leaving some fields within ThreadFix null.
Three sample scan files (DAST, SAST, and DEPENDENCY) are available at the bottom of this page.
The file extension is .threadfix (all lowercase)
The file must use UTF-8 encoding.
Table of Contents
- 1 Table of Contents
- 1.1 File Format
- 1.1.1 FindingCollection
- 1.1.2 Finding
- 1.1.3 DynamicDetails
- 1.1.4 SurfaceLocation
- 1.1.5 StaticDetails
- 1.1.6 DataFlowElement
- 1.2 DependencyDetails (support added in 2.7.3)
- 1.3 Mapping
- 1.1 File Format
- 2 Example Scan Files
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
.
FindingCollection
Name | Required | Used | Type | Description |
---|---|---|---|---|
| yes | Export only | integer | The Scan's primary key, scanId. This column is ignored on imports. |
| yes | yes | timestamp ¥ | The date the scan was run |
| yes | yes | timestamp ¥ | The date the scan was last audited or otherwise edited |
| yes | Export only | timestamp ¥ | The date the .threadfix file was generated. This column is ignored on imports, but is planned for future use. |
| yes | yes | CollectionType (string) | The type of scanner used. Valid options: In the future support will be added for:
*As of ThreadFix version 2.7.6 |
| 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 your source. (This is no longer allowed as of TF version 2.7.8)
|
| no | no | string | Not used. Future support may be added for multiple sub-channels. |
| 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. |
| yes | yes | Findings | A collections of findings. See Finding below. |
| 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. |
| 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 |
---|---|---|---|---|
| no | Export Only | integer | The Finding's primary key, findingId. This column is ignored on imports. |
| no | no | timestamp ¥ | Not used. Future support may be added for individual findings to have different discovery dates. |
| no | no | timestamp ¥ | Not used. Future support may be added for individual findings to have different updated dates. |
| yes | yes | string | A unique id for a finding from the scanner. This id must be unique or the other findings with the same nativeId will get de-duplicated. Character limit:
If the source scanner has the ability to track the same vulnerability across multiple scans, this filed should use an ID value that is common between multiple scan runs. |
| 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: Do NOT use an empty string as the value. |
| yes | yes | string | The original severity name from the scanner. Do NOT use an empty string as the value. Character limit: 25 |
| no | no | string | Not used. Future support will be added for CVSS Scores for Network and Dependency scanners. |
| 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. |
| no | yes* | string | Populates the finding description on the finding details page. 2047 character limit.
*As of ThreadFix version 2.7.2 |
| no | yes | string | Populates the scanner details on the finding details page. |
| no | yes | string | Populates the scanner recommendation on the finding details page. |
| 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. |
| no | no | map<string,string> | Allows key value pair metadata to be associated with a Finding. |
| 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. |
| no | yes | Mapping[] | An array of common classification IDs (Such as CWE, CVE) to categorized the finding. See Mapping below. Not required, but highly recommended. If no CWE is provided, no merging can take place with other scanning tools. |
| 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 you do not specify a rawFinding, ThreadFix will list the entire finding from your .threadfix file in the rawFinding section. Specifying this field could result in loss of data in ThreadFix. |
| no | yes* | string[] | An array of comments to add and associate to the finding in ThreadFix. Format: Note:
*As of ThreadFix version 2.7.3 |
| 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}
*As of ThreadFix version 2.7.7 |
DynamicDetails
Use this Details object to represent data from a DAST scanner.
Name | Required | Used | Type | Description |
---|---|---|---|---|
| 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 |
---|---|---|---|---|
| yes | yes | string | The url at which the DAST scanner identified the vulnerability. |
| yes | yes | string | The vulnerability parameter |
| no | yes | string | The successful attack string the DAST scanner used. |
| no | yes | string | The successful attack payload the DAST scanner used. |
| 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 |
---|---|---|---|---|
| yes | 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. |
| 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 |
---|---|---|---|---|
| yes | yes | string | The source code file name for this element of the vulnerable data flow. |
| yes | yes | integer | The line of code for the data flow element. |
| yes | yes | integer | The column where the vulnerable parameter starts. |
| yes | yes | string | The text of the vulnerable source code. |
| 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 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)
Use this Details object to represent data from a Dependency-based scanner.
Name | Required | Used | Type | Description |
---|---|---|---|---|
| yes | yes | string | The name of the library the dependency finding was identified for. |
| 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:
|
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 indentified, for example a link to the CVE page on www.mitre.org. |
filePathList | no | yes | string[] | INTRODUCED in ThreadFix version 2.7.6. A list of paths to the library in your 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 your 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. |
Mapping
Name | Required | Used | Type | Description |
---|---|---|---|---|
| yes | yes | MappingType (string) | Identifies the vulnerability classification mapping type. Valid options:
Options that are not yet valid, but to be supported in the future:
|
| yes | yes | string | The actual id to map to. CWE and CVE values must be valid. Note: For CWE, you can use a “-1” value to map a finding to “None” or you can omit the mappings element altogether, which will result in an “Unmapped” CWE value. |
| 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. |
| no* | yes | string | The name of the custom vulnerability categorization system. Required for Mappings of mappingType |
Example Scan Files
The following sample files show a typical .threadfix file from a DAST, SAST, and DEPENDENCY scanner.