Vulcan ConnectX (Vulcan Report) Connector

Overview

• Prerequisites

• File Examples

• How it works

• Configuring the Vulcan Report (ConnectX) connector

• Fields and value type

• Manage Files

  • Start and end cycles - an option to accumulate data

• Tracking the Remediation with Vulcan ConnectX

• API

• FAQ

Prerequisites

Supported formats: CSV, XLS, XLSX
Max file size: 200 Mb
Required fields: Asset name, CVSS V.3 (only in vulnerability reports), Vulnerability Name (only in vulnerability reports)
File structure: First row must contain headers

File Examples

Examples of recommended CSV templates:
Host Vulnerability

DAST (Website) Vulnerability

Host Inventory

How it works

Vulcan ConnectX lets you upload CSV/XLS/XSLX files to Vulcan.
You can upload any kind of CSV, while it requires mapping fields manually from your report to Vulcan ConnectX.

There are 5 types of CSV files you can upload; each represents a different Vulcan data type:

• Code Project (SAST) - Files that represent static analysis results.

• Website (DAST) - Files representing dynamic scan results of web applications, penetration tests, or crowd-sourced vulnerabilities.

• Code Project (SCA) - Files representing Software Composition Analysis (open source) results.

• Hosts (Asset Inventory) - Files that represent host inventory information. For example, CMDBs and Cloud providers.

• Hosts (Vulnerability Assessment) - Files that represent vulnerability information. For example, Vulnerability scanners.

• Images (Container Scanning) - Files representing scan results from image/container scanning tools.

Each ConnectX connector represents a file from a specific product. Therefore, you can create as many ConnectX connectors as you need.
For example, one Vulcan ConnectX connector can represent your data from CMDBs (e.g., ServiceNow), which contains relevant data of your hosts (Name, IP address, OS, etc.). The second ConnectX can represent your data from a Vulnerability Scanner (e.g., Rapid7 Nexpose) which contains relevant data of your last scan (Vulnerability name, CVSS, CVE, etc.). 

Each uploaded file contains one mandatory field: 'Asset - Name'.
Correlation between different reports can be done only by asset name. For example:
CMDB report contains the asset name, and the Vulnerability Scanner report contains the related asset name for each vulnerability. Only if the assets' names match the data correlated in Vulcan.

Configuring the Vulcan Report (ConnectX) connector

1. Go to Connectors > Add a Connector

2. Click the Vulcan Report /ConnectX icon

   

3. Give your Vulcan Connector an indicative name. This way, you can identify what this report represents.

   For example:

   

4. Browse or drag and drop the file you wish to upload (CSV, XLS, XLSX).

5. The Vulcan platform supports different asset types, each Data Type has unique attributes and mapping fields.

   

   Select the Data Type you are uploading:

   • Code Project SAST

   • Cope Project SCA

   • Host Asset Inventories

   • Host Vulnerability Assessment

   • Images

   • Website DAST

   • Cloud Resources

   For your reference, you can see the DAST/SAST and Vulnerability Assessment tools fields mapping available in the Vulcan ConnectX/Report Connector.

6. Once you select the Data Type, a dedicated Map Fields configuration is opened. Map out the headers fields in your file (left column) to the respective Vulcan fields (right column). You can also add custom values.

   For example:

   

   Notes:

   • All the Vulcan fields can be mapped to only one header, except 'Asset - Details' and 'Vulnerability - Details' (more details about those special Vulcan fields under the 'Supporting Custom Fields' section).

   • The Vulcan fields "Assets - Name" and "Vulnerabilities - Name" are mandatory.

   • When mapping a risk score to the Vulcan field "Vulnerabilities - Technical Severity", the mapped risk score represents the score of a Unique Vulnerability in the Vulcan Platform. The risk score of a vulnerability instance is calculated after the file is loaded. The score of a vulnerability instance is determined by all the risk-affecting factors configured in the Vulcan Platform, such as Asset tags and impact. Read here about vulnerability instance risk calculation and how it works.

7. Click Create

   That's it! your records are now in the Vulcan Platform.

Fields and Value type

Mapping Code Project (SAST)

Mandatory fields are marked with *

Read more about DAST/SAST and Vulnerability Assessment tools fields mapping available in the Vulcan ConnectX/Report Connector

Mapping Code Project (SCA)

Mandatory fields are marked with *

Mapping Hosts (Asset Inventory)

Mandatory fields are marked with *

Mapping Hosts (Vulnerability Assessment)

Mandatory fields are marked with *

Mapping Images

Mandatory fields are marked with *

Mapping Websites (DAST)

Mandatory fields are marked with *

Read more about DAST/SAST and Vulnerability Assessment tools fields mapping available in the Vulcan ConnectX/Report Connector

Mapping Cloud Resources

Mandatory fields are marked with *

Unique Identifiers

Supporting Custom Fields - Notes

• Each Vulcan field can be mapped once, except 'Asset - Details', 'Asset  - Tags' and 'Vulnerability - Details'. You can map these fields as many times as you want.

• Each header you map to 'Asset - Details' is displayed on the Asset card under the Details tab.

• Each header you map to 'Assets - Tags' is displayed as a tag on the relevant asset.

• Each header you map to 'Vulnerability - Details' is displayed on the Vulnerability card under the Vulnerability tab.

Manage Files

You can download, rename, or delete the files you uploaded. This can be useful in can you want to:

• Download the uploaded files

• Rename files

• Delete the data from older files

1. Click on the File Management tab on the connector set-up page to access the uploaded files.

2. Hover over the file to show the Download, Delete, and Edit options.

Note: Only the data retrieved from that file is deleted when deleting a file. The rest of the data coming from other related files will be maintained.

Start and end cycles - an option to accumulate data

You can choose when to start and end the cycles of your data. This means you can choose to upload more than one data file and ask the system to accumulate the data instead of overriding the existing data. For example, you can upload a file of vulnerabilities data every week until the cycle ends.

How does it work?

Once you upload a file, the system will ask you if it is you wish to accumulate the data you are uploading and add it to the existing data or if you wish to start a new cycle of data.

To enable this feature, contact your Customer Success Manager, or email us at support@vulcan.io.

Tracking and Remediation with Vulcan ConnectX/Report

Each Vulcan ConnectX/Report connector represents data from your organization's existing product or tool. Once a connector is created for the first time, you would probably like to upload more CSV representing newer results.

Vulcan ConnectX/Report lets users keep track of the data already ingested in Vulcan.

A scenario to consider

Suppose you have a vulnerability scanner CSV output from the January scan. After some time, you want to upload the output of the February scan to the same "Vulcan ConnectX/Report" connector. Here is the expected system behavior in this case:

• If a vulnerability exists on asset "X in January and exists on the same asset "X" in February, then the status of the vulnerability will remain as it was (Vulnerable/In Progress)

• Suppose a vulnerability from the January file is not found in the February file. In that case, the vulnerability status will be changed to Fixed as it indicates the vulnerability was fixed between January and February.

• Suppose a vulnerability exists on asset "X" in January, and the same is found on asset "Y" in February. In that case, the number of assets associated with this vulnerability will show "2" in Vulcan.

• A new vulnerability will be created if a vulnerability exists in the February file but not in the January file.

API

Vulcan API documentation is available at:
HTTPS://[Account Name].vulcancyber.com/#/app/api

URL prefix: https://{clientname}.vulcancyber.com/api/asset_manager/vulcanreport/api_v1/ 

More details can be found in the article API - User Guide.

Relevant API calls

You can use the attached python script to get started with the Vulcan Report connector API.
vulcan_report_api_test.py

FAQ

Can I edit my current mapping to something else?
Currently no. Once the connector is created, the mapping is permanent.

Can I override the existing Vulcan Report Connector?
Yes, but the file structure must be the same - meaning the order of the headers must stay the same. 

Does mapping stay the same after override?
If the CSV is with the same headers, then yes.

Can I create more than one ConnectX/Report Connector?
Yes. If you are uploading files from different tools, we recommend you create a dedicated ConnectX/Report Connector for each.

Can I set the risk score of a vulnerability instance?

No. When mapping a risk score to the Vulcan field "Vulnerabilities - Technical Severity", the mapped risk score represents the score of a Unique Vulnerability in the Vulcan Platform. The risk score of a vulnerability instance is calculated after the file is loaded. The score of a vulnerability instance is determined by all the risk-affecting factors configured in the Vulcan Platform, such as Asset tags and impact. Read here about vulnerability instance risk calculation and how it works.