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
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
Go to Connectors > Add a Connector
Click the Vulcan Report /ConnectX icon
Give your Vulcan Connector an indicative name. This way, you can identify what this report represents.
For example:
Browse or drag and drop the file you wish to upload (CSV, XLS, XLSX).
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.
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.
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: |
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: |
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: |
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: |
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: |
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: |
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: |
Vulnerabilities unique identifier | By default, the vulnerability uniqueness is determined by the field: Fallback field: |
Solution unique identifier | The solution title is generated in the following format and based on the following fields:
|
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
Click on the File Management tab on the connector set-up page to access the uploaded files.
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.