Warning

The SSVL Converter has been deprecated. For any questions or assistance please contact ThreadFix Support.

Goal

Denim Group created the SSVL Converter tool to allow organizations with existing scanner data in non-ThreadFix-supported formats to import that data to ThreadFix. If your team uses Excel or other spreadsheets to store data, the SSVL Converter tool can help ease the ThreadFix adoption process.

Strategy

SSVL Converter allows the user to get data from CSV or Excel files into ThreadFix by using the SSVL format. There are a few steps on either side of actually using the tool.

Before

First of all, you must have data in the CSV or Excel formats.

CSV format is recommended. When using Excel format, the CWE ID will be missing from the vulnerability created by ThreadFix.

Second, the file must contain a unique ID for each vulnerability. This can just be the line number, but the SSVL format requires a NativeID. This can be your external tool's ID or your internal tracking ID. As long as the ID maintains consistency between runs, ThreadFix will be able to track the vulnerabilities just like normal scanner exports.

Third, the SSVL Converter tool requires that vulnerability types be in the numeric CWE format. If you have text names for vulnerabilities, you will need to convert them to numbers in order to get that information into ThreadFix.

For a finding without a CWE associated with it, you can use -1 for the CWE, which corresponds with "None."
The SSVL Converter expects, by default, the date format 'dd/MM/yyyy.' If you plan on converting using a different date format, a configuration file defining this format must be provided.

After

The SSVL Converter tool produces an SSVL file, which you can upload into ThreadFix.

How to Run

We have packaged the SSVL Converter tool as a command-line JAR file. You can download it from the Tools Download page within ThreadFix (cog → Download Tools). An interactive prompt walks the user through configuration, if run with no arguments. At the end of the interactive session, the user can export the configuration to a file to be reused later. SSVL Converter will also print the command to reuse configuration.

Interactive mode

The basic command to run SSVL Converter will be:

java -jar ssvl-converter.jar

The steps for interactive configuration are:

1. Optionally load configuration

SSVL Converter will allow the user to load an existing configuration file if one is present. If a configuration file is entered, then SSVL Converter will check the configuration file and only prompt for steps 2 and 3, if necessary.

2. Get header information (column names)

SSVL Converter needs to know about the header names in the file. If the headers are the first line in the file, SSVL Converter will prompt for the file path. Then it will read headers from the first line in the supplied file and confirm its results with the user.

If the first line of the file contains vulnerability data, then SSVL Converter will prompt the user to input the header names and confirm.

3. Confirm header mappings

SSVL Converter has a list of default column names. If your file uses other names for its column headers, then SSVL Converter needs to be configured to recognize your header names properly. For instance, SSVL Converter needs the CWE ID for each line. If your file has the CWE ID in the "Vulnerability Type" column instead of the "CWE" column, then SSVL Converter will fail to parse the data.

After header names are entered, SSVL Converter checks its header configuration and prints its results to the user.

Before configuration

Failure: configured header 'Severity' for field 'Severity' was not found in headers.
Failure: configured header 'CWE' for field 'CWE' was not found in headers.
Failure: configured header 'Source' for field 'Source' was not found in headers.
Failure: configured header 'url' for field 'url' was not found in headers.
Failure: configured header 'parameter' for field 'parameter' was not found in headers.
Failure: configured header 'NativeID' for field 'NativeID' was not found in headers.
You must configure a value for native ID.
Failure: configured header 'ShortDescription' for field 'ShortDescription' was not found in headers.
Failure: configured header 'LongDescription' for field 'LongDescription' was not found in headers.

If there are failures where there shouldn't be, answering 'y' to the next question will prompt you with each of these questions:

Please input the name of the header for Severity (One of 'Information', 'Low', 'Medium', 'High', 'Critical' or a number from 1 to 5) or 'skip' to keep default value (Severity)
Please input the name of the header for CWE (number, ex. 79) or 'skip' to keep default value (CWE)
Please input the name of the header for Source (Origin of finding ex. Manual Testing or 'skip' to keep default value (Source)
Please input the name of the header for Path (String, ex. /login.jsp) or 'skip' to keep default value (url)
Please input the name of the header for Parameter (String, ex. username) or 'skip' to keep default value (parameter)
Please input the name of the header for ID (identifying String, ex. 72457) or 'skip' to keep default value (NativeID)
Please input the name of the header for Short Description or 'skip' to keep default value (ShortDescription)
Please input the name of the header for Long Description or 'skip' to keep default value (LongDescription)

After answering with the correct column names for each piece of information, the configuration check will run again. If done correctly, it should look something like this:

Success: configured header 'severity' for field 'Severity' was not found in headers.
Success: configured header 'VulnType' for field 'CWE' was found in headers.
Success: configured header 'Scanner' for field 'Source' was found in headers.
Success: configured header 'Location' for field 'url' was found in headers.
Success: configured header 'Injection Point' for field 'parameter' was found in headers.
Success: configured header 'ID' for field 'NativeID' was found in headers.
Success: configured header 'Text' for field 'ShortDescription' was found in headers.
Failure: configured header 'LongDescription' for field 'LongDescription' was not found in headers.

It is not necessary for every header to match, but headers that do not match will not be present in ThreadFix.

4. Enter input and output files

If the path to the file was not entered in step 1, SSVL Converter will prompt the user to enter the path to the input file. The user must also enter the output file path. Alternatively, submitting 'stdout' for the output file name will print to standard output.

5. Optionally save configuration

SSVL Converter will ask the user whether and where to save configuration for future runs. SSVL Converter skips this step if the user loaded configuration earlier in the process.

Non-interactive mode

The arguments for the non-interactive SSVL Converter mode are:

java -jar ssvl-converter.jar -configFile={path to config file} -file={path to file}

SSVL Converter will prompt the user for any configuration missing from the file.

SSVL Fields

Severity
CWE
Source
url
parameter
NativeID
ShortDescription
LongDescription
IssueID (Use only to link a vulnerability to an existing defect in the Threadfix application's associated defect tracker.)
Date ('IdentifiedTimestamp' date format in the SSVL file: "yyyy-MM-dd HH:mm:ss aaa XXX", e.g., "2017-02-28 00:00:00 AM -06:00")
SourceFileName
LineNumber
ColumnNumber
LineText

ThreadFix Documentation

SSVL Converter - Deprecated