Versions Compared

Old Version 10

changes.mady.by.user Daniel Colon

Saved on

compared with

New Version 11

changes.mady.by.user Daniel Colon

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: updated to remove single quotations within the time stamp formatting example
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.

Table of Contents

Table of Contents

FindingCollection

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

Warning

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

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

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. 

Note

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

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

Note

Do NOT use an empty string as the value.

nativeSeverity

yes

yes

string

The original severity name from the scanner.

Character limit: 25

Note

Do NOT use an empty string as the value.

cvssScore

nono

yes

string

Not used.

Future support will be added for CVSS Scores for Network and Dependency scannersdecimal

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. 

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

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

*All timestamps are to be in yyyy-MM-dd'T'HHddTHH:mm:ss'Z'** format.
**For ThreadFix version 2.8.3 or newer, the 'Z' will reflect the time zone based on UTCssZ 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 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.

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

Warning

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

Expand
titleDynamic_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
titleStatic_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
titleDependency_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"
      ]
    }
  ]
}