Versions Compared

Old Version 3

changes.mady.by.user Daniel Colon

Saved on

compared with

New Version 4

changes.mady.by.user Daniel Colon

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Image RemovedImage 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.

Table of Contents

Table of Contents

FindingCollection

Name

Required

Used

Type

Description

id

no

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

no

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

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

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'HH:mm:ss'Z'** 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

no

timestamp ¥

Not used.

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

updated

no

no

timestamp ¥

Not used.

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

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

    yes

    string

    The original severity name from the scanner.

    Character limit: 25

    Note

    Do NOT use an empty string as the value.

    cvssScore

    no

    no

    string

    Not used.

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

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

    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.

    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.

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

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