How Findings Work
Hold Up!
Make sure to read this section to understand how findings are structured in Nucleus before uploading data to your project. If you do not, you could pollute your project with incorrect or duplicated data.
Findings in Nucleus are represented by a parent/child relationship, where the parent is the "unique" finding and the child is the "instance" finding.
A unique finding describes all of the information that is generic for a finding, and is common across every asset that the finding is on. This includes properties like the finding's name, severity, generic description and recommendation steps (amongst others).
To set uniqueness
The most important field for determining uniqueness of a finding is the finding_number. This field will group together numerous instances of a single finding. A common use case is to use a CVE_number as a finding_number so that all instances of that CVE are grouped into a single unique finding.
An instance of a finding is a specific occurrence of that finding on an asset, and contains information that is only related to that occurrence. This includes properties like the port that a network vulnerability was found on, the code snippet for a SAST finding, or a HTTP request/response pair recorded during a DAST scan.
A unique finding is as the name suggests - unique, with potentially many instances of that finding across multiple assets. There is a one-to-many relationship between unique findings and finding instances, where a unique finding can be related to many instances, but an instance can be related to only one unique finding:

Nucleus automatically normalizes findings from all scanners into the above parent/child data model, and the FlexConnect Framework is no different.
As it would be overly complex to represent this relationship in JSON, XML and CSV files, the above data model is flattened in the FlexConnect Framework with each finding on an asset containing both unique and instance fields. On import, the Nucleus Scan Ingestion Engine automatically unflattens these findings into the above parent/child data model. The next section provides examples of this flattened schema.
Structure
Similar to assets, findings are structured differently depending on the file type.
In JSON files, individual assets contain a key called findings, which is a list of findings on that asset:
JSON
{
"nucleus_import_version": "1",
"scan_tool": "SuperGrep",
"scan_type": "Application",
"assets": [
{
"host_name": "my_code_repo",
"findings": [
{
"finding_number": "FINDING-1",
"finding_name": "Cross Site Scripting on...",
"finding_severity": "Critical",
"finding_type": "Vuln",
"finding_description": "The module is vulnerable to...",
"finding_recommendation": "To remediate this vulnerability, ...",
"finding_code_snippet": "My Line Of Code",
"finding_line_number": "9",
"finding_path": "path/to/vulnerable/file.java"
},
{
"finding_number": "FINDING-1",
"finding_name": "Cross Site Scripting on...",
"finding_severity": "Critical",
"finding_type": "Vuln",
"finding_description": "The module is vulnerable to...",
"finding_recommendation": "To remediate this vulnerability, ...",
"finding_code_snippet": "Another Line Of Code",
"finding_line_number": "9001",
"finding_path": "local/path/bad.java"
}
]
},
{
"host_name": "SuperRepo",
"findings": [
{
"finding_number": "FINDING-1",
"finding_name": "Cross Site Scripting on...",
"finding_severity": "Critical",
"finding_type": "Vuln",
"finding_description": "The module is vulnerable to...",
"finding_recommendation": "To remediate this vulnerability, ...",
"finding_code_snippet": "eval('...')",
"finding_line_number": "134",
"finding_path": "intentionally/vulnerable/file.java"
},
{
"finding_number": "FINDING-2",
"finding_name": "SQL Injection on...",
"finding_severity": "High",
"finding_type": "Vuln",
"finding_description": "The module is vulnerable to...",
"finding_recommendation": "To remediate this vulnerability, ...",
"finding_code_snippet": "$db->execute();",
"finding_line_number": "096",
"finding_path": "sql/injection/is/hard.java"
}
]
}
]
}In XML files, individual asset objects contain an object called findings, where each sub-object is a finding on that asset:
Markup
<nucleusCustomScan>
<nucleus_import_version>1</nucleus_import_version>
<scan_tool>SuperGrep</scan_tool>
<scan_type>Application</scan_type>
<assets>
<asset>
<host_name>my_code_repo</host_name>
<findings>
<finding>
<finding_number>FINDING-1</finding_number>
<finding_name>Cross Site Scripting on...</finding_name>
<finding_severity>Critical</finding_severity>
<finding_type>Vuln</finding_type>
<finding_description>The module is vulnerable to...</finding_description>
<finding_recommendation>To remediate this vulnerability, ...</finding_recommendation>
<finding_code_snippet>My Line Of Code</finding_code_snippet>
<finding_line_number>9</finding_line_number>
<finding_path>path/to/vulnerable/file.java</finding_path>
</finding>
<finding>
<finding_number>FINDING-1</finding_number>
<finding_name>Cross Site Scripting on...</finding_name>
<finding_severity>Critical</finding_severity>
<finding_type>Vuln</finding_type>
<finding_description>The module is vulnerable to...</finding_description>
<finding_recommendation>To remediate this vulnerability, ...</finding_recommendation>
<finding_code_snippet>Another Line Of Code</finding_code_snippet>
<finding_line_number>9001</finding_line_number>
<finding_path>local/path/bad.java</finding_path>
</finding>
</findings>
</asset>
<asset>
<host_name>SuperRepo</host_name>
<findings>
<finding>
<finding_number>FINDING-1</finding_number>
<finding_name>Cross Site Scripting on...</finding_name>
<finding_severity>Critical</finding_severity>
<finding_type>Vuln</finding_type>
<finding_description>The module is vulnerable to...</finding_description>
<finding_recommendation>To remediate this vulnerability, ...</finding_recommendation>
<finding_code_snippet>eval('...')</finding_code_snippet>
<finding_line_number>134</finding_line_number>
<finding_path>intentionally/vulnerable/file.java</finding_path>
</finding>
<finding>
<finding_number>FINDING-2</finding_number>
<finding_name>SQL Injection on...</finding_name>
<finding_severity>High</finding_severity>
<finding_type>Vuln</finding_type>
<finding_description>The module is vulnerable to...</finding_description>
<finding_recommendation>To remediate this vulnerability, ...</finding_recommendation>
<finding_code_snippet>$db->execute();</finding_code_snippet>
<finding_line_number>096</finding_line_number>
<finding_path>sql/injection/is/hard.java</finding_path>
</finding>
</findings>
</asset>
</assets>
</nucleusCustomScan>In CSV files, findings are flattened where each finding field is a column of the CSV file:
Markup
nucleus_import_version,scan_tool,scan_type,scan_date,host_name,finding_number,finding_name,finding_severity,finding_type,finding_description,finding_recommendation,finding_code_snippet,finding_line_number,finding_path
1,SuperGrep,Application,2021-10-10 12:12:12,my_code_repo,FINDING-1,Cross Site Scripting on...,Critical,Vuln,The module is vulnerable to...,"To remediate this vulnerability, ...",My Line Of Code,9,path/to/vulnerable/file.java
1,SuperGrep,Application,2021-10-10 12:12:12,my_code_repo,FINDING-1,Cross Site Scripting on...,Critical,Vuln,The module is vulnerable to...,"To remediate this vulnerability, ...",Another Line Of Code,9001,local/bad/path.java
1,SuperGrep,Application,2021-10-10 12:12:12,SuperRepo,FINDING-1,Cross Site Scripting on...,Critical,Vuln,The module is vulnerable to...,"To remediate this vulnerability, ...",eval('...'),134,intentionally/vulnerable/file.java
1,SuperGrep,Application,2021-10-10 12:12:12,SuperRepo,FINDING-2,SQL Injection on...,High,Vuln,The module is vulnerable to...,"To remediate this vulnerability, ...",$db->execute();,96,sql/injection/is/hard.javaFinding Fields
This section provides a definition of all finding fields. These fields can be flexibly used to represent both vulnerabilities and compliance findings, and include optional fields for use with findings from a variety of different source tools such as network scanners, software composition analysis, static analysis, dynamic analysis, manual methods, etc.
Unique vs Instance Fields
Fields that are marked Unique indicate that the field belongs to the unique finding (i.e. the parent finding). These fields must always be consistent for the corresponding finding_number field across scans and assets. If the field's value changes, that value will be reflected in the unique finding and will apply for all finding instances.
Fields that are marked Instance can change from finding to finding as the field is specific to the instance of that finding on the asset.
| Name | Description | Accepted Values or Format |
|---|---|---|
| finding_type | Optional. Unique. The type of this finding. If not provided, defaults to Vuln. Note: For JSON & XML files only findings of one type can be included per asset. To include both types of findings on a single asset, create the asset twice. | Allowed values are Vuln and Compliance. |
| finding_number | Required. Unique. A number used to identify the unique finding amongst all findings from the same scanner/source. | Maximum of 250 characters long. Only ASCII characters are allowed. |
| finding_name | Required. Unique. The name of the unique finding. | Maximum of 128 characters long. Only ASCII characters are allowed. |
| finding_severity | Required. Unique. The severity of this finding. | Allowed values are Critical, High, Medium, Low and Informational. |
| finding_description | Optional. Unique. A long description of the unique finding. This description should be generic across all instances of the finding, and should not contain any information that is specific to an instance of this finding. | N/A |
| finding_recommendation | Optional. Unique. A recommendation for remediating or mitigating the finding. This should be generic across all instances of the finding, and should not contain any information that is specific to an instance of this finding. | N/A |
| finding_exploitable | Optional. Unique. A boolean that indicates whether or not the finding is exploitable. Defaults to false. | Allowed values are true and false. |
| finding_references | Optional. Instance. An extensible field used to specify additional key/value pair metadata on a finding. For Compliance type findings, this field is also used in JSON files to specify compliance frameworks and controls related to the finding. This is not supported in XML or CSV files. See the Compliance Findings example below for the correct format. | N/A |
| finding_cve | Optional. Unique. A list of CVEs and/or CWE's that relate to this finding. | Maximum of 512 characters long. A comma separated list. |
| finding_iava | Optional. Unique. A list of IAVAs that relate to this finding. | Maximum of 512 characters long. A comma separated list. |
| finding_sub_type | Optional. Unique. This is used to determine the columns that show up in the Finding Overview -> Instances tab. Available options include:
| See description for available options. |
| finding_discovered | Optional. Instance. The date that the finding instance was discovered. | Date in the format "Y-m-d H:i:s". E.g. 2018-10-10 11:12:13 |
| finding_result | Optional. Instance. The result of the compliance or configuration check. Defaults to Failed. | Allowed values are Passed or Failed. |
| finding_output | Optional. Instance. A generic field used for specifying a scanner's output for this finding on a specific asset. This field can flexibly be used to capture finding information specific to this asset, such as a description, recommendation, or test output. | N/A |
| finding_package | Optional. Instance. The installed package that this finding affects. | Maximum of 256 characters long. Only ASCII characters are allowed. |
| finding_package_version | Optional. Instance. The version of the package that is affected by this finding. | Maximum of 128 characters long. Only ASCII characters are allowed. |
| finding_package_fix_version | Optional. Instance. The version of this package that this finding is remediated in. JSON files supports one version or a list of fixed versions. XML and CSV files only support a single version. | N/A |
| finding_port | Optional. Instance. The port that this finding was found on, if applicable. E.g. 443. A protocol can be optionally also be specified, eg.g. 443/tcp or 10000/udp. Commonly used for results from network and/or infrastructure scanners. | N/A |
| finding_service | Optional. Instance. The service running on the port specified in finding_port. E.g. https. Commonly used for results from network and/or infrastructure scanners. | Maximum of 32 characters long. Only ASCII characters are allowed. |
| finding_path | Optional. Instance. The path to this finding such as a URL endpoint, file path or package dependency path. Commonly used for results from SAST, DAST and SCA scanners. | Maximum of 4096 characters long. Only ASCII characters are allowed. |
| finding_line_number | Optional. Instance. The line of code that this finding relates to. Commonly used for results from SAST and DAST scanners in combination with finding_path and/or finding_code_snippet (for SAST). | Only digits are allowed. |
| finding_code_snippet | Optional. Instance. The code that is affected by this finding. Commonly used for results from SAST scanners in combination with finding_path and finding_line_number. | N/A |
| finding_http_request | Optional. Instance. The raw HTTP request that was sent to the asset when probed or tested. Commonly used for results from DAST, network and/or infrastructure scanners. | N/A |
| finding_http_response | Optional. Instance. The raw HTTP response that was returned from the asset when probed or tested. Commonly used for results from DAST, network and/or infrastructure scanners. | N/A |
Finding Examples
Network & Infrastructure Vulnerabilities
Example JSON
JSON
{
"nucleus_import_version": "1",
"scan_tool": "NetworkScannerTool",
"scan_type": "Host",
"scan_date": "2021-01-01 00:00:00",
"assets": [
{
"host_name": "secretserver",
"findings": [
{
"finding_type": "Vuln",
"finding_number": "NETWORK-1",
"finding_name": "Operating System EOL",
"finding_severity": "Critical",
"finding_description": "According to the version number, the operating system on the remote host is no longer supported.",
"finding_recommendation": "Upgrade to a version of the operating system that is currently supported.",
"finding_exploitable": "false",
"finding_references": {
"CVSS Base Score": "10.0",
"Test ID": "12345"
},
"finding_output": "Support for Example Operating System ended on 1970-01-01. Upgrade to the latest version.",
"finding_port": "0/tcp",
"finding_service": "general"
}
]
}
]
}Example XML
Markup
<nucleusCustomScan>
<nucleus_import_version>1</nucleus_import_version>
<scan_tool>NetworkScannerTool</scan_tool>
<scan_type>Host</scan_type>
<scan_date>2021-01-01 00:00:00</scan_date>
<assets>
<asset>
<host_name>secretserver</host_name>
<findings>
<finding>
<finding_type>Vuln</finding_type>
<finding_number>NETWORK-1</finding_number>
<finding_name>Operating System EOL</finding_name>
<finding_severity>Critical</finding_severity>
<finding_description>According to the version number, the operating system on the remote host is no longer supported.</finding_description>
<finding_recommendation>Upgrade to a version of the operating system that is currently supported.</finding_recommendation>
<finding_exploitable>false</finding_exploitable>
<finding_references>
<finding_reference>
<key>CVSS Base Score</key>
<value>10.0</value>
</finding_reference>
<finding_reference>
<key>Test ID</key>
<value>12345</value>
</finding_reference>
</finding_references>
<finding_output>Support for Example Operating System ended on 1970-01-01. Upgrade to the latest version.</finding_output>
<finding_port>0/tcp</finding_port>
<finding_service>general</finding_service>
</finding>
</findings>
</asset>
</assets>
</nucleusCustomScan>Example CSV
MarkupJSON
nucleus_import_version,scan_tool,scan_type,scan_date,host_name,finding_type,finding_number,finding_name,finding_severity,finding_description,finding_recommendation,finding_exploitable,finding_references,finding_output,finding_port,finding_service
"1","NetworkScannerTool","Host","2021-01-01 00:00:00","secretserver","Vuln","NETWORK-1","Operating System EOL","Critical","According to the version number, the operating system on the remote host is no longer supported.","Upgrade to a version of the operating system that is currently supported.","false","CVSS Base Score:10.0,Test ID:12345","Support for Example Operating System ended on 1970-01-01. Upgrade to the latest version.","0/tcp","general"Code Analysis (SAST) Vulnerabilities
Example JSON
MarkupJSON
{
"nucleus_import_version": "1",
"scan_tool": "CodeScannerTool",
"scan_type": "Application",
"assets": [
{
"host_name": "my_secret_code_repo",
"findings": [
{
"finding_type": "Vuln",
"finding_number": "FINDING-1",
"finding_name": "Cross Site Scripting on...",
"finding_severity": "Critical",
"finding_description": "The module is vulnerable to...",
"finding_recommendation": "To remediate this vulnerability, ...",
"finding_code_snippet": "My Line Of Code",
"finding_line_number": "9",
"finding_path": "path/to/vulnerable/file.java"
}
]
}
]
}Example XML
Markup
<nucleusCustomScan>
<nucleus_import_version>1</nucleus_import_version>
<scan_tool>CodeScannerTool</scan_tool>
<scan_type>Application</scan_type>
<assets>
<asset>
<host_name>my_secret_code_repo</host_name>
<findings>
<finding>
<finding_type>Vuln</finding_type>
<finding_number>FINDING-1</finding_number>
<finding_name>Cross Site Scripting on...</finding_name>
<finding_severity>Critical</finding_severity>
<finding_description>The module is vulnerable to...</finding_description>
<finding_recommendation>To remediate this vulnerability, ...</finding_recommendation>
<finding_code_snippet>My Line Of Code</finding_code_snippet>
<finding_line_number>9</finding_line_number>
<finding_path>path/to/vulnerable/file.java</finding_path>
</finding>
</findings>
</asset>
</assets>
</nucleusCustomScan>Example CSV
Markup
nucleus_import_version,scan_tool,scan_type,scan_date,host_name,finding_type,finding_number,finding_name,finding_severity,finding_description,finding_recommendation,finding_code_snippet,finding_line_number,finding_path
1,CodeScannerTool,Application,2021-10-10 12:12:12,my_secret_code_repo,Vuln,FINDING-1,Cross Site Scripting on...,Critical,The module is vulnerable to...,"To remediate this vulnerability, ...",My Line Of Code,9,path/to/vulnerable/file.javaWeb Application (DAST) Vulnerabilities
Example JSON
MarkupJSON
{
"nucleus_import_version": "1",
"scan_tool": "WebAppScannerTool",
"scan_type": "Application",
"scan_date": "2021-01-01 00:00:00",
"assets": [
{
"host_name": "my.secret.webapp.com",
"findings": [
{
"finding_type": "Vuln",
"finding_number": "WEBAPP-SQL-1",
"finding_name": "Blind SQL Injection",
"finding_severity": "High",
"finding_description": "The web application is vulnerable to Blind SQL Injection.",
"finding_recommendation": "Ensure that all SQL queries are parameterised.",
"finding_exploitable": "true",
"finding_references": {
"Explainer URL": "https://www.owasp.org/index.php/Blind_SQL_Injection"
},
"finding_cve": "CWE-74,CWE-89",
"finding_output": "The endpoint was queried with the blind SQL injection payload 1' ORDER BY 1--+ and found to be vulnerable.",
"finding_path": "https://my.secret.webapp.com/login",
"finding_http_request": "EXAMPLE HTTP REQUEST HERE",
"finding_http_response": "EXAMPLE HTTP RESPONSE HERE"
}
]
}
]
}Example XML
Markup
<nucleusCustomScan>
<nucleus_import_version>1</nucleus_import_version>
<scan_tool>WebAppScannerTool</scan_tool>
<scan_type>Application</scan_type>
<scan_date>2021-01-01 00:00:00</scan_date>
<assets>
<asset>
<host_name>my.secret.webapp.com</host_name>
<findings>
<finding>
<finding_type>Vuln</finding_type>
<finding_number>WEBAPP-SQL-1</finding_number>
<finding_name>Blind SQL Injection</finding_name>
<finding_severity>High</finding_severity>
<finding_description>The web application is vulnerable to Blind SQL Injection.</finding_description>
<finding_recommendation>Ensure that all SQL queries are parameterised.</finding_recommendation>
<finding_exploitable>true</finding_exploitable>
<finding_references>
<finding_reference>
<key>Explainer URL</key>
<value>https://www.owasp.org/index.php/Blind_SQL_Injection</value>
</finding_reference>
</finding_references>
<finding_cve>CWE-74,CWE-89</finding_cve>
<finding_output>The endpoint was queried with the blind SQL injection payload 1' ORDER BY 1--+ and found to be vulnerable.</finding_output>
<finding_path>https://my.secret.webapp.com/login</finding_path>
<finding_http_request>EXAMPLE HTTP REQUEST HERE</finding_http_request>
<finding_http_response>EXAMPLE HTTP RESPONSE HERE</finding_http_response>
</finding>
</findings>
</asset>
</assets>
<nucleusCustomScan>Example CSV
Markup
nucleus_import_version,scan_tool,scan_type,scan_date,host_name,finding_type,finding_number,finding_name,finding_severity,finding_description,finding_recommendation,finding_exploitable,finding_references,finding_cve,finding_output,finding_path,finding_http_request,finding_http_response
"1","WebAppScannerTool","Application","2021-01-01 00:00:00","my.secret.webapp.com","Vuln","WEBAPP-SQL-1","Blind SQL Injection","High","The web application is vulnerable to Blind Sql Injection.","Ensure that all SQL queries are parameterised.","true","key:value","CWE-74,CWE-89","The endpoint was queried with the blind SQL injection payload 1' ORDER BY 1--+ and found to be vulnerable.","https://my.secret.webapp.com/login","EXAMPLE HTTP REQUEST HERE","EXAMPLE HTTP RESPONSE HERE"Dependency, Software Package & Container Image (SCA) Vulnerabilities
Example JSON
JSON
{
"nucleus_import_version": "1",
"scan_tool": "PackageScannerTool",
"scan_type": "Container Image",
"assets": [
{
"image_repo": "ninja/secretcontainerimage",
"image_manifest_digest": "sha256:dbbacecc49b088458781c16f3775f2a2ec7521079034a7ba499c8b0bb7f86875",
"findings": [
{
"finding_type": "Vuln",
"finding_number": "RHSA-2021:2147",
"finding_name": "Package glib2 (2.56.1-5.el7) requires update - RHSA-2021:2147",
"finding_severity": "High",
"finding_description": "GLib provides the core application building blocks for libraries and applications written in C. It provides the core object system used in GNOME, the main loop implementation, and a large set of utility functions for strings and common data structures. Security Fix(es): * glib: integer overflow in g_bytes_new function on 64-bit platforms due to an implicit cast from 64 bits to 32 bits (CVE-2021-27219) For more details about the security issue(s), including the impact, a CVSS score, acknowledgments, and other related information, refer to the CVE page(s) listed in the References section.",
"finding_recommendation": "Update glib2 package",
"finding_references": {
"Vulnerable Version": "2.56.1-5.el7",
"Package": "glib2"
},
"finding_cve": "CVE-2021-27219",
"finding_path": "glib2",
"finding_output": "This was fixed in version xxxxx."
}
]
}
]
}Example XML
Markup
<nucleusCustomScan>
<nucleus_import_version>1</nucleus_import_version>
<scan_tool>PackageScannerTool</scan_tool>
<scan_type>Container Image</scan_type>
<assets>
<asset>
<image_repo>ninja/secretcontainerimage</image_repo>
<image_manifest_digest>sha256:dbbacecc49b088458781c16f3775f2a2ec7521079034a7ba499c8b0bb7f86875</image_manifest_digest>
<findings>
<finding>
<finding_type>Vuln</finding_type>
<finding_number>RHSA-2021:2147</finding_number>
<finding_name>Package glib2 (2.56.1-5.el7) requires update - RHSA-2021:2147</finding_name>
<finding_severity>High</finding_severity>
<finding_description>GLib provides the core application building blocks for libraries and applications written in C. It provides the core object system used in GNOME, the main loop implementation, and a large set of utility functions for strings and common data structures. Security Fix(es): * glib: integer overflow in g_bytes_new function on 64-bit platforms due to an implicit cast from 64 bits to 32 bits (CVE-2021-27219) For more details about the security issue(s), including the impact, a CVSS score, acknowledgments, and other related information, refer to the CVE page(s) listed in the References section.</finding_description>
<finding_recommendation>Update glib2 package</finding_recommendation>
<finding_references>
<finding_reference>
<key>Vulnerable Version</key>
<value>2.56.1-5.el7</value>
</finding_reference>
<finding_reference>
<key>Package</key>
<value>glib2</value>
</finding_reference>
</finding_references>
<finding_cve>CVE-2021-27219</finding_cve>
<finding_path>glib2</finding_path>
<finding_output>This was fixed in version xxxxx.</finding_output>
</finding>
</findings>
</asset>
</assets>
</nucleusCustomScan>Example CSV
MarkupJSON
nucleus_import_version,scan_tool,scan_type,scan_date,image_repo,image_manifest_digest,finding_type,finding_number,finding_name,finding_severity,finding_description,finding_recommendation,finding_references,finding_cve,finding_path,finding_output
1,PackageScannerTool,Container Image,2021-01-01 00:00:00,ninja/secretcontainerimage,sha256:dbbacecc49b088458781c16f3775f2a2ec7521079034a7ba499c8b0bb7f86875,Vuln,RHSA-2021:2147,Package glib2 (2.56.1-5.el7) requires update - RHSA-2021:2147,High,"GLib provides the core application building blocks for libraries and applications written in C. It provides the core object system used in GNOME, the main loop implementation, and a large set of utility functions for strings and common data structures. Security Fix(es): * glib: integer overflow in g_bytes_new function on 64-bit platforms due to an implicit cast from 64 bits to 32 bits (CVE-2021-27219) For more details about the security issue(s), including the impact, a CVSS score, acknowledgments, and other related information, refer to the CVE page(s) listed in the References section.",Update glib2 package,"Vulnerable Version:2.56.1-5.el7,Package:glib2",CVE-2021-27219,glib2,This was fixed in version xxxxx.