Overview


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 *

Vulcan Field

Field value type

Assets - Projects *

string

Assets - Last Report

date format

Assets - Tags

string - only one tag at the time

Assets - Details

string

Component - File name*

string

Component - Line number*

string

Vulnerabilities - ID

string

Vulnerabilities - Name*

string

Vulnerabilities - CVE

string separated with comma in CVE format. Example: CVE-2020-3178,CVE-2020-3174

Vulnerabilities - Technical Severity

float

Vulnerabilities - Description

string

Vulnerabilities - Discovery Time

date format

Vulnerabilities - Details

string

Vulnerabilities - CWE

string separates with comma (same as CVE format)

Vulnerabilities - Unique instance ID

string

Solutions - Description

string

Solutions - Reference

string

Solutions - Reference Link

URL

Solutions - OS

string

Solutions - OS Version

string

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 *

Vulcan Field

Field value type

Assets - Projects *

string

Assets - Last Report

date format

Assets - Tags

string - only one tag at the time

Assets - Details

string

Libraries - Name

string

Librairie - Version

string

Vulnerabilities - ID

string

Vulnerabilities - Name*

string

Vulnerabilities - CVE

string separated with comma in CVE format. Example: CVE-2020-3178,CVE-2020-3174

Vulnerabilities - Technical Severity

float

Vulnerabilities - Description

string

Vulnerabilities - Discovery Time

date format

Vulnerabilities - Details

string

Vulnerabilities - CWE

string separate with comma (same as CVE format)

Vulnerabilities - Unique instance ID

string

Solutions - Description

string

Solutions - Reference

string

Solutions - Reference Link

URL

Solutions - OS

string

Solutions - OS Version

string

Mapping Hosts (Asset Inventory)

Mandatory fields are marked with *

Vulcan Field

Field value type

Assets - Name

string

Assets - Last Seen

date format

Assets - Tags

string

Assets - Details

string

Assets IP

string in IP format

Assets - OS

string

Assets FQDN

string

Mapping Hosts (Vulnerability Assessment)

Mandatory fields are marked with *

Vulcan Field

Field value type

Assets - Name*

string

Assets - Last Seen

date format

Assets - Tags

string

Assets - Details

string

Assets IP

string in IP format

Assets - OS

string

Assets FQDN

string

Vulnerabilities - Name*

string

Vulnerabilities - CVE

string separated with comma in CVE format. Example: CVE-2020-3178,CVE-2020-3174

Vulnerabilities - Technical Severity

float/integers

Vulnerabilities - Description

string

Vulnerabilities - Discovery Time

date format

Vulnerabilities - Details

string

Vulnerabilities - CWE

string separate with comma (same as CVE format)

Vulnerabilities - Unique instance ID

string

Solutions - Description

string

Solutions - Reference

string

Solutions - Reference Link

URL

Solutions - OS

string

Solutions - OS Version

string

Mapping Images

Mandatory fields are marked with *

Vulcan Field

Field value type

Assets - ID*

string

Assets - Last Scan

date format

Assets - Name*

string

Assets - Tags

string

Assets - Details

string

Assets ?????

string

Components - Name

string

Components - Type

string

Components - ID

string

Vulnerabilities - ID

string

Vulnerabilities - Name*

string

Vulnerabilities - CVE

string separated with comma in CVE format. Example: CVE-2020-3178,CVE-2020-3174

Vulnerabilities - Technical Severity

float/integers

Vulnerabilities - Description

string

Vulnerabilities - Discovery Time

date format

Vulnerabilities - Details

string

Vulnerabilities - CWE

string separated with comma (same as CVE format)

Vulnerabilities - Unique instance ID

string

Solutions - Description

string

Solutions - Reference

string

Solutions - Reference Link

URL

Solutions - OS

string

Solutions - OS Version

string

Mapping Websites (DAST)

Mandatory fields are marked with *

Vulcan Field

Field value type

Assets - Name*

string

Assets - Last Seen

date format

Assets - Tags

string

Assets - Details

string

Assets - URL

string

Pages - URL

string

Vulnerabilities - ID

string

Vulnerabilities - Name*

string

Vulnerabilities - CVE

string separated with comma in CVE format. Example: CVE-2020-3178,CVE-2020-3174

Vulnerabilities - Technical Severity

float/integers

Vulnerabilities - Description

string

Vulnerabilities - Discovery Time

date format

Vulnerabilities - Details

string

Vulnerabilities - CWE

string separate with comma (same as CVE format)

Vulnerabilities - Unique instance ID

string

Solutions - Description

string

Solutions - Reference

string

Solutions - Reference Link

URL

Solutions - OS

string

Solutions - OS Version

string

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 *

Vulcan Field

Field value type

Assets - Name*

string

Assets - ID

string

Assets - Cloud Provider

string

Assets - Resource Name

string

Assets - Last Scan

date format

Assets - Tags

string

Assets - Details

string

Vulnerabilities - ID

string

Vulnerabilities - Name*

string

Vulnerabilities - CVE

string separated with comma in CVE format. Example: CVE-2020-3178,CVE-2020-3174

Vulnerabilities - Technical Severity

float/integers

Vulnerabilities - Description

string

Vulnerabilities - Discovery Time

date format

Vulnerabilities - Details

string

Vulnerabilities - CWE

string separate with comma (same as CVE format)

Vulnerabilities - Unique instance ID

string

Solutions - Description

string

Solutions - Reference

string

Solutions - Reference Link

URL

Solutions - OS

string

Solutions - OS Version

string

Unique Identifiers

Unique Identifier

Field

Asset unique identifier

Asset uniqueness is determined by the field:
"Assets - Name"

Vulnerabilities unique identifier

By default, the vulnerability uniqueness is determined by the field:
Vulnerabilities - ID

Fallback field: Vulnerabilities - Name

Solution unique identifier

The solution title is generated in the following format and based on the following fields:

{server_name} Recommendations for {vuln_title}

  • Solution fields aren't mandatory. If you wish to add solution info into the solution fields, then the Solutions - Description field becomes mandatory.

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

API Call

Description

api/asset_manager/vulcanreport/api_v1/list_connectors/

GET a list of all the VulcanReportConnector that exists in the system

api/asset_manager/vulcanreport/api_v1/connector/{ID}/upload_report/ response: {"report_id": 1}

POST a CSV file to a specific VulcanReportConnector ID

api/asset_manager/vulcanreport/api_v1/connector/{ID}/report_status/ response: [{"report_id": 1, "status": "parsed", "record_count": 30}, {"report_id": 2, "status": "parsing"}]

GET all the names of the uploaded reports to a specific VulcanReportConnector ID with parsing status. If status=parsed - return the number of recored that were found in the report. If not, indicate that status=parsing.

api/asset_manager/vulcanreport/api_v1/connector/{ID}/report_status/{REPORT_ID}/ response: {"report_id": 1, "status": "parsed", "record_count": 30}

GET information for a specific report in a VulcanReportConnector ID with parsing status. If status=Parsed - return the number of recored that were found in the report. If not, indicate that status=Parsing.

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.

Did this answer your question?