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>
Comments
0 comments
Article is closed for comments.