📙 You will learn

How to configure defect templates.

Prerequisites

Audience: IT Professional
Difficulty: Intermediate
Time needed: Approximately 20 minutes
Tools required: N/A

Velocity Templates

ThreadFix uses a Velocity template to generate defect descriptions. Velocity has also made available a comprehensive user guide.

Finding the Defect Description Template

Multiple defect templates can be defined at once. The original template is located at tomcat/webapps/threadfix/velocityTemplates/defect with the name Classic_Description.vm. User files can be placed in this directory with any desired changes or the existing template updated as necessary. When submitting a defect through the ThreadFix UI, choose between any template file in this directory and they will appear within ThreadFix by their filename.

Samples

Default Template

By default, ThreadFix submits defects with vulnerability information in the format as seen in the image displayed below of defects submitted to JIRA:

If the “Include Scanner Detail” field is checked when submitting a defect, the Scanner Detail field for the first vulnerability will be included in the beginning of the defect description, as shown in the image below:

If looking closely at the Classic_Description.vm file, the section which provides all of the default output is viewable:

The general information provided includes the Vulnerability Type for the submitted vulnerability. Users can create a defect for one vulnerability or one defect for multiple vulnerabilities. The general information also includes Scanner Detail information if the corresponding checkbox is selected when submitting defects. Following that, the defect description lists each vulnerability along with pertinent details. Dynamic findings, static findings, and DependencyCheck findings all provide different information sets to make the defect description more useful. The final section lists custom text for each vulnerability type, which can be configured in ThreadFix from the Customize ThreadFix Vulnerability Types page.

Additional information can be included for each vulnerability. At the top of Classic_Description.vm, change #set( $addFindingsDetails=false ) from “false” to “true”. This adds the following section to each vulnerability:

##This part will add most of the interesting details of the findings of a vulnerability
#macro( addFindingsDetails $vulnerability )
    #if( $vulnerability.findings && !$vulnerability.findings.isEmpty() )
        #foreach( $finding in $vulnerability.findings )
            #presentIfNotNull("Scanner Detail" $finding.scannerDetail false)
            #presentIfNotNull("Scanner Recommendation" $finding.scannerRecommendation false)
            #presentIfNotNull("Attack String" $finding.attackString true)
            #presentIfNotNull("Attack Request" $finding.attackRequest true)
            #presentIfNotNull("Attack Response" $finding.attackResponse true)
            #addDataFlow($finding)
        #end
    #end
#end

The presentIfNotNull method is a way of including vulnerability details only if they exist for that vulnerability, three variables are required for this.

1. First provide a string that will print before the information.
   

2. Specify which field to print (a full list of available fields are available at the bottom of this page).
   

3. If final variable is set to "true", JIRA defect trackers will treat the field as a code block and other defect trackers will separate the section with horizontal lines. Setting it to "false" will treat the field as plaintext. If the additional finding details are enabled, the same vulnerability defect shown above will now contain much more information by default:

Add Dependency Validation Information

There may be times when the default fields submitted with defects are not the desired ones. For example, more information may be desired to be provided for DependencyCheck findings. By customizing the Classic_Description.vm the preferred information for the defects can be retrieved. For this example, changes were made for the following:

##This part will add most of the interesting details of the findings of a vulnerability
#macro( addFindingsDetails $vulnerability )
    #if( $vulnerability.findings && !$vulnerability.findings.isEmpty() )
        #foreach( $finding in $vulnerability.findings )
            #presentIfNotNull("Scanner Detail" $finding.scannerDetail false)
            #presentIfNotNull("Scanner Recommendation" $finding.scannerRecommendation false)
            #presentIfNotNull("Attack String" $finding.attackString true)
            #presentIfNotNull("Attack Request" $finding.attackRequest true)
            #presentIfNotNull("Attack Response" $finding.attackResponse true)
            #addDataFlow($finding)
			#if( $finding.dependency )
				#presentIfNotNull("Component File Path" $finding.dependency.componentFilePath false)
				#presentIfNotNull("Description" $finding.dependency.description false)
				#presentIfNotNull("Source" $finding.dependency.source false)
			#end
        #end
    #end
#end

The defect ThreadFix submitted after making these changes contained more relevant information for a dependency validation finding:

Notice there is no “Source” section when it was included in the addFindingsDetails section. The vulnerability used for this defect did not have any data for that field, so due to the presentIfNotNull method it was excluded without issue.

Full Field List

A list of fields have been provided in this section for customizing defect submissions. Keep in mind that not every field is relevant to every vulnerability, use checks such as the presentIfNotNull method when including them. ThreadFix recommends making a backup of Classic_Description.vm before making any major changes.

Findings

The following fields should be used in the addFindingsDetails macro.

$finding.createdDate
$finding.modifiedDate
$finding.attackRequest
$finding.attackResponse
$finding.attackString
$finding.authenticationRequired
$finding.calculatedFilePath
$finding.calculatedUrlPath
$finding.longDescription
$finding.markedFalsePositive
$finding.nativeId
$finding.rawFinding
$finding.scannedDate
$finding.scannerDetail
$finding.scannerRecommendation
$finding.sourceFileLocation
$finding.urlReference
$finding.scanId
$finding.vulnerability.id
$finding.dependency.componentFilePath
$finding.dependency.componentName
$finding.dependency.cve
$finding.dependency.description
$finding.dependency.refLink
$finding.dependency.source
$finding.dependency.getRefId()
$finding.channelSeverity.name
$finding.channelVulnerability.name
$finding.getChannelNameOrNull()

Vulnerabilities

Most likely the following fields will be used in the first block of code, in the #foreach( $vulnerability in $vulnerabilities ) loop.

$vulnerability.closeTime
$vulnerability.foundByScanner
$vulnerability.isFalsePositive
$vulnerability.applicationId
$vulnerability.surfaceLocation.parameter
$vulnerability.surfaceLocation.path
$vulnerability.surfaceLocation.getUrl()
$vulnerability.genericSeverity.name
$vulnerability.genericSeverity.customName
$vulnerability.genericVulnerability.name
$vulnerability.genericVulnerability.customText
$vulnerability.genericVulnerability.cweId

Data Flow Elements

These fields can be used in the addDataFlow macro at the bottom of Classic_Description.vm.

$dataflowElement.sourceFileName
$dataflowElement.lineNumber
$dataflowElement.lineText
$dataflowElement.sequence
$dataflowElement.columnNumber

Extra

To get a link to the ThreadFix page for a vulnerability, use ${baseUrl}$vulnerability.getUri().

To get a link to the CWE entry for a vulnerability, use http://cwe.mitre.org/data/definitions/${vulnerability.genericVulnerability.id}.html

Optional Velocity Tools

ThreadFix has added the Velocity Tool manager which allows Velocity Tools to be added to the velocity-tools.xml file for Velocity Template editing. $display tools has been added and will allow access to the display tools. This addition does not change current functionality, it adds the ability to add to Velocity as needed by the client.

Velocity Tools Example Use - HTML Tags in Jira Defects

Occasionally users may find HTML tags in Jira defect descriptions from defects created in ThreadFix. The HTML tags are provided to ThreadFix by some of the remote providers and are used solely for formatting. When transferred to Jira these will display as originally exported by the remote provider. Users may now use velocity tools to have access to the $display.stripTags. By adding $display.stripTags($metadata.preamble) in place of metadata.preamblein Classic_Description.vm will remove HTML tags from being added into the Jira defect description.