The ZeroNorth platform provides a way to upload custom Issues that are not specific to any scanning tool on the market. For example, you may have Issues from scan tools that ZeroNorth does not yet have an integration with, or you may have Issues from a manual/custom pen test results. By uploading your custom Issues, you can benefit from ZeroNorth’s Issue refinement, Issue compression, Issue correlation, and various metrics. In effect, your custom Issues will look like and be treated like any other Issue picked up by the ZeroNorth platform from a scanning tools/service that ZeroNorth has native integration with.
Requirements
- You have a valid license and access to the ZeroNorth platform.
- You have connectivity to https://fabric.zeronorth.io and to https://api.zeronorth.io from where you want to upload the Issues.
- You have the custom issues prepared into a JSON document matching the format ZeroNorth specified below.
Flow
- Prepare the Issues data into the JSON document format that ZeroNorth can accept.
- Create a “Receiver Policy” in the ZeroNorth platform.
- Upload the prepared JSON document to the Receiver Policy.
The above steps are describe in more detail in the following sections.
Prepare the JSON Document of Issues
The ZeroNorth platform can accept custom issues data as a JSON document that looks like:
{ "meta": { "key": [ "issueName" ], "author": "Jane Doe" }, "issues": [ { "scanTool": "myScanTool", "issueName": "Cross Site Scripting", "IssueDescription": "Lorem ipsum...", "fileName": "my_source_file.java", "remediationSteps": "fix it", "risk": "high", "severity": 8, "status": "open", "referenceIdentifiers": [ { "type": "string", <--- MUST BE LOWER CASE!!! "id": "string" }, ... ] }, ... ]}
The basic schema is:
- A “meta” section, which should contain:
- “key” - the name of the attribute (from the issue objects) that should be used to construct a unique key. The key value is used by ZeroNorth for Issue compression. For example, two issue objects with the same key attribute value will be combined into one, but their unique instances (typically fileName, url, etc.) will be enumerated in the resulting compressed Issue.
Note that the attribute(s) to be named as the key(s) are ZeroNorth attributes not the attributes from the source of the issues. In the above example in which the key set to “issueName”, that’s the ZeroNorth attribute “issueName”.
- Optionally “author”.
- An array of “issues” where each Issue object can have the following attributes:
Required
| Attribute name | Format | Description |
|---|---|---|
| issueName | String | Name of vulnerability, license issue, compliance issue, etc. |
| issueDescription | String (long) | Description of vulnerability, license issue, compliance issue, etc. |
| scanTool | String | The name of the scanning tool (e.g. “SonarQube”) |
| severity | Float | CVSS 3.0 score (a number from 1.0-10.0) |
Recommended
| Attribute name | Format | Description |
|---|---|---|
| confidence | Float | Derived from the tool output. |
| cvss | String (long) | Derived from the tool output. |
| fileName | String | Recommended to assist in triaging errors (if present). |
| host | String | Recommended to assist in triaging errors (if present). |
| ip | String | Recommended to assist in triaging errors (if present). |
| issueType | String | Type of issue (e.g. vulnerability, license issue, compliance issue, etc.) |
| lineNumber | String | Recommended to assist in triaging errors (if present). |
| link | String | Recommended to assist in triaging errors (if present). |
| port | Integer | Recommended to assist in triaging errors (if present). |
| product | String | Logical metadata field that can be used for tracking of product(s) |
| project | String | Logical metadata field that can be used for tracking of project(s) |
| remedationSteps | String (long) | Remediation instructions, often provided by the scan tool. |
| scanSeverity | String | The severity as reported by the scan tool |
| scanStatus | String | Recommended for measuring scan duration and status |
| tags | String | Logical metadata tags, which can be leveraged to describe asset owners, teams, business units, etc. |
| url | String | Recommended to assist in triaging errors (if present). |
Optional
| Attribute name | Format | Description |
|---|---|---|
| author | String | Logical metadata field designed to track the owner of the scan result |
| effort | String (long) | Logical metadata field designed to gauge the required effort to remediate a vulnerability |
| exploitabilityScore | Float | Derived from the tool output |
| imageLayerId | String | Metadata field to track image layer ID from containers |
| imageNamespace | String | Logical metadata field |
| impactScore | String | Derived from the tool output |
| libraryName | String | Derived from the tool output |
| license | String | Derived from the tool output |
| linesOfCodeImpacted | String | Recommended to assist in triaging errors (if present) |
| referenceIdentifiers | Array | An array of Vulnerability identifiers, such as CVE, CWE, etc. For example: |
“referenceIdentifiers”: [
{
“type”: “cwe”,
“id”: “79”
},
…
]
Note: ZeroNorth will automatically hotlink “cwe” and “cve” type identifiers.|
|remediationTags|String|Logical metadata tags to track remediation status|
|rule|String|Logical metadata field for rule definition|
|scanId|String|Logical metadata field that describes the scan enumeration|
|scanType|String|DAST, SAST, SCA, etc.|
|status|String|Description of scan status|
|vulnerabilityDetails|String (long)|Logical metadata field to add more context about a vulnerability|
The following attribute names are reserved and cannot be used in your JSON file:
- alertRulesets
- customerId
- discoveryIssueId
- discoveryRunTime
- discoveryTimespan
- ignore
- ignoreRulesets
- jobId
- policyId
- policyName
- refinementVersion
- remediationRunTime
- remediationTimespan
- runTime
- scenarioId
- severityCode
- target
- targetId
Below is an example JSON document:
{ "meta": { "key": [ "issueName" ], "author": "Jane Doe" }, "issues": [ { "scanTool": "MySastTool", "issueName": "Cross Site Scripting", "issueDescription": "Lorem ipsum...", "fileName": "homepage-jobs.php", "remediationSteps": "Fix me fast.", "risk": "high", "severity": 8, "status": "open", "referenceIdentifiers": [ { "type": "cwe", <--- MUST BE LOWER CASE!!! "id": "79" } ] }, { "scanTool": "MySastTool", "issueName": "Cross Site Scripting", "issueDescription": "Lorem ipsum...", "fileName": "homepage-contact.php", "remediationSteps": "Fix me fast!", "risk": "high", "severity": 8, "status": "open", "referenceIdentifiers": [ { "type": "cwe", "id": "79" } ] } ]}
The full JSON document should then be in form a like:
[ "meta": { ... }, "issues": [ { issue #1 }, { issue #2 }, ... ]}
Prepare the Receiver Policy
Refer to the KB article Creating a ZeroNorth™ Scan for the general instructions, but the following details apply:
- Scenario - use the “JSON v2” (a.k.a. “external”) Scenario. Select the type appropriate for your Target.
- Integration - use the “Custom” type for uploading Issues from a DAST/Network scan or from a pen test. Use the “Repo/Artifact” type for uploading Issues from a SAST/SCA scan.
- Target - create a Target for the above Integration.
- Policy - combine the Target and the Scenario, making sure to set Initiate Scan From to “Manual Issue Upload”.
Upload the Issues
The prepared JSON document of custom issues can then be uploaded to the Receiver Policy in one of two ways:
- Via the UI - see the instructions in the related article Manual Upload of Scan Results .
- Via the API - use the BASH script you can download via the link below.
7 KB Download