Nucleus supports the ability to upload custom scan types through the manual file upload utility (Import Scans > From File), or via the API. Uploading or POSTing a scan allows you to import results from custom scans, or even a list of assets if all other fields are blank.

 

File Type Support

We support the following file types:

1. CSV (sample CSV file)

2. JSON (sample JSON file)

3. XML (sample XML file)

The format for these file types is defined later in this article.

 

Upload the Scan

To upload a custom scan, you need to follow these steps:

1. Navigate to Import Scans > From File.

2. Drag and Drop your custom file into the file import popup.

3. Click Import.

Your file will be uploaded and ingested as if it were a scan type from any tool.

 

Custom File Requirements

Important fields:

asset_name - This will determine the asset name in Nucleus. It can be an application name or a server or web site. You want this to be consistent across scans

finding_number - Determines the uniqueness of this finding. This should remain the same between scans so findings can be correlated. E.g. if you include 1 asset with 2 findings with the same finding_number, it will be counted as 1 unique finding and 2 total (given different finding_path or finding_port, see below). Note: This does not need to be an integer, a string also works.

finding_name - This should be a short name for the description. Each finding_number should have only 1 finding_name.

finding_severity - Severity of the finding, see below for allowed values, should be 1 to 1 with finding_number. If you have the same finding with different severities, append the finding_severity on the end to make it unique.

finding_path/finding_port - If a vulnerability was found in multiple places on a single asset, you use these fields so they count as different findings.

scan_type - This will determine how the finding details are displayed. Applications show paths and Hosts show ports.

 

Fields

nucleus_import_version

Description: The version of the import api to use.

Accepted Values: 1 (There is only 1 version of the api at this time)

Required: Yes

 

scan_date

Description: Date of scan.

Format: 2018-10-10 11:12:13

Required: If not included, date of upload will be used

 

 scan_tool

Description: Scan tool used when displaying the tool in the application. This should be consistent across scan imports.

Required: Yes

 

scan_type

Description: Scan type should explain the type of asset that is being scanned. Applications are things like web applications or SAST/DAST scans. Container images are Blackduck and Nessus container type scans.

Accepted Values: Application/Container Image/Database/Host

Required: Yes

 

Assets

asset_name

Description: Name of the host or base URL that was scanned.

Required: Either this or ip_address must be included for each host

 

ip_address

Description: IP address for the host or web service scanned.

Format: x.x.x.x

Required: Either this or asset_name must be included for each host

 

NOTE: The rest of the asset attributes below are only supported on initial asset creation.

asset_fqdn

Description: FQDN for scanned host.

Required: No

 

mac_address

Description: MAC address for scanned host.

Required: No

 

operating_system_name

Description: OS Name for scanned host.

Required: No

 

operating_system_version

Description: OS Version for scanned host.

Required: No

 

asset_notes

Description: Notes for scanned host.

Required: No

 

asset_criticality

Description: Critcality for scanned host.

Required: No

 

asset_location

Description: Asset location for scanned host.

Required: No

 

Findings

finding_number

Description: Unique identifier for this finding that is consistent across scans.

Character Limit: 250

Required: Yes

 

finding_name

Description: Name for this finding. There should only be 1 name per finding_number.

Character Limit: 128

Required: Yes

 

finding_severity

Description: Severity for this finding.

Accepted Values: Critical/High/Medium/Low/Informational

Required: Yes

 

finding_type

Description: Compliance or vulnerability finding.

Accepted Values: Compliance/Vuln

Default: Vuln

Required: No

 

finding_code_snippet

Description: For SAST/DAST type tools, if a code snippet can be provided, then add one here.

Required: No

 

finding_cve (This also works for CWEs)

Description: Comma separated list of CVEs (and/or CWE's) applicable to this finding

Character Limit: 512

Required: No

 

finding_description

Description: Longer description of the finding with as many details as you would like to add. finding_numbers should have the same description across all scans/hosts. Put anything host specific in the finding_output or similar fields

Required: No

 

finding_exploitable

Description: Is this finding exploitable

Accepted Values: true/false

Default: false

Required: No

 

finding_http_request

Description: Some tools provide the output of the http_request. Include that here and it will automatically be pulled into the finding_output field.

Required: No

 

finding_http_response

Description: Some tools provide the output of the http_response. Include that here and it will automatically be pulled into the finding_output field.

Required: No

 

finding_iava

Description: Comma separated list of IAVAs applicable to this finding

Character Limit: 170

Required: No

 

finding_line_number

Description: Some tools output a file's line number, include it here.

Required: No

 

finding_output

Description: Finding output specific to an asset. Note: If you include the finding_http_request and finding_http_response above, it will automatically pull that into this finding. Anything else you add here will show up above that information.

Required: No

 

finding_path

Description: Path to the finding, can be url path or file path, etc.

Character Limit: 4096

Required: No

 

finding_port

Description: Port where finding was found.

Required: No

 

finding_recommendation

Description: How to fix the finding. This will be included in any external tickets created, so be as helpful as possible here.

Required: No

 

finding_references

Description: Array of information that should be included in the finding reference tab of an issue. See below for examples for each file type. This can include compliance framework information to be included on compliance page.

Required: No

 

finding_result

Description: Did this finding pass or fail the check.

Accepted Values: Passed/Failed

Default: Failed

Required: No

 

finding_service

Description: A service that was tied to this finding.

Character Limit: 32

Required: No

 

finding_sub_type

Description: Extra grouping capability, mainly used for compliance grouping.

Character Limit: 128

Required: No

 

Sample File Types

Nucleus currently supports 3 file types: CSV, JSON and XML

Below are examples of these files.

Example CSV file (host scan)

nucleus_import_version,asset_name,ip_address,asset_fqdn,scan_date,scan_type,scan_tool,finding_number,finding_name,finding_severity,finding_type,finding_code_snippet,finding_cve,finding_description,finding_exploitable,finding_http_request,finding_http_response,finding_iava,finding_line_number,finding_output,finding_path,finding_port,finding_recommendation,finding_references,finding_result,finding_service,finding_sub_type
1,hostname1,192.168.1.1,,2018-10-10 11:12:13,Host,MyScanTool,100000,Finding found in dyg package,High,Vuln,,CVE-1000,A high severity finding was found in package dyg,false,,,,,Package dyg was found to be vulnerable since it used version 0.1.1,,,Update dyg package to 0.1.2,"package:dyg,vulnerable version:0.1.1,fixed version:0.1.2",Failed,,
1,hostname1,192.168.1.1,,2018-10-10 11:12:13,Host,MyScanTool,100001,Finding found in gyd package,Low,Vuln,,CVE-1001,A low severity finding was found in package gyd,true,,,,,Package gyd was found to be vulnerable since it used version 0.1.1,,,Update gyd package to 2.1.0,"package:gyd,vulnerable version:2.0.9,fixed version:2.1.0",Failed,,

Note: finding_references must be surrounded by quotation marks to be parsed correctly as a csv.

Example JSON file (host scan)

{
 "nucleus_import_version": "1",
 "scan_date": "2018-10-10 11:12:13",
 "scan_type": "Host",
 "scan_tool": "MyScanTool",
 "assets": [
  {
   "asset_name": "hostname1",
   "ip_address": "192.168.1.1",
   "asset_fqdn": "hostname1.domain.com",
   "findings": [
    {
      "finding_number": "100000",
      "finding_name": "Finding found in dyg package",
      "finding_severity": "High",
      "finding_type": "Vuln",
      "finding_code_snippet": "",
      "finding_cve": "CVE-1000",
      "finding_description": "A high severity finding was found in package dyg",
      "finding_exploitable": "",
      "finding_http_request": "",
      "finding_http_response": "",
      "finding_iava": "",
      "finding_line_number": "",
      "finding_output": "Package dyg was found to be vulnerable since it used version 0.1.1",
      "finding_path": "",
      "finding_port": "",
      "finding_recommendation": "Update dyg package to 0.1.2",
      "finding_references": {
       "package": "dyg",
       "vulnerable version": "0.1.1",
       "fixed version": "0.1.2"
      },
      "finding_result": "Failed",
      "finding_service": "",
      "finding_sub_type": ""
     },
     {
      "finding_number": "100001",
      "finding_name": "Finding found in gyd package",
      "finding_severity": "Low",
      "finding_type": "Vuln",
      "finding_code_snippet": "",
      "finding_cve": "CVE-1001",
      "finding_description": "A high severity finding was found in package gyd",
      "finding_exploitable": "",
      "finding_http_request": "",
      "finding_http_response": "",
      "finding_iava": "",
      "finding_line_number": "",
      "finding_output": "Package gyd was found to be vulnerable since it used version 2.0.9",
      "finding_path": "",
      "finding_port": "",
      "finding_recommendation": "Update dyg package to 2.1.0",
      "finding_references": {
       "package": "dyg",
       "vulnerable version": "2.0.9",
       "fixed version": "2.1.0"
      },
      "finding_result": "Failed",
      "finding_service": "",
      "finding_sub_type": ""
     }
    ]
   }
 ]
}

Example XML file (host scan)

<?xml version="1.0"?>
<nucleusCustomScan>
 <nucleus_import_version>1</nucleus_import_version>
 <scan_date>2018-10-10 11:12:13</scan_date>
 <scan_type>Host</scan_type>
 <scan_tool>MyScanTool</scan_tool>
 <assets>
  <asset>
   <asset_name>assetname1</asset_name>
   <ip_address>192.168.1.1</ip_address>
   <asset_fqdn>hostname1.domain.com</asset_fqdn>
   <findings>
    <finding>
     <finding_number>100000</finding_number>
     <finding_name>Finding found in dyg package</finding_name>
     <finding_severity>High</finding_severity>
     <finding_type>Vuln</finding_type>
     <finding_code_snippet/>
     <finding_cve>CVE-1000</finding_cve>
     <finding_description>A high severity finding was found in package dyg</finding_description>
     <finding_exploitable/>
     <finding_http_request/>
     <finding_http_response/>
     <finding_iava/>
     <finding_line_number/>
     <finding_output>Package dyg was found to be vulnerable since it used version 0.1.1</finding_output>
     <finding_path/>
     <finding_port/>
     <finding_recommendation>Update dyg package to 0.1.2</finding_recommendation>
     <finding_references>
      <finding_reference>
       <key>package</key>
       <value>dyg</value>
      </finding_reference>
      <finding_reference>
       <key>vulnerable version</key>
       <value>0.1.1</value>
      </finding_reference>
     <finding_reference>
     <key>fixed version</key>
     <value>0.1.2</value>
     </finding_reference>
     </finding_references>
     <finding_result>Failed</finding_result>
     <finding_service/>
     <finding_sub_type/>
    </finding>
    <finding>
     <finding_number>100001</finding_number>
     <finding_name>Finding found in gyd package</finding_name>
     <finding_severity>Low</finding_severity>
     <finding_type>Vuln</finding_type>
     <finding_code_snippet/>
     <finding_cve>CVE-1001</finding_cve>
     <finding_description>A high severity finding was found in package gyd</finding_description>
     <finding_exploitable/>
     <finding_http_request/>
     <finding_http_response/>
     <finding_iava/>
     <finding_line_number/>
     <finding_output>Package gyd was found to be vulnerable since it used version 2.0.9</finding_output>
     <finding_path/>
     <finding_port/>
     <finding_recommendation>Update gyd package to 2.1.0</finding_recommendation>
     <finding_references>
      <finding_reference>
       <key>package</key>
       <value>gyd</value>
      </finding_reference>
      <finding_reference>
       <key>vulnerable version</key>
       <value>2.0.9</value>
      </finding_reference>
     <finding_reference>
     <key>fixed version</key>
     <value>2.1.0</value>
     </finding_reference>
     </finding_references>
     <finding_result>Failed</finding_result>
     <finding_service/>
     <finding_sub_type/>
    </finding>
   </findings>
  </asset>
 </assets>
</nucleusCustomScan>