About Vulcan Report Connector

The Vulcan ConnectX/Report Connector enables you to upload CSV, ZIP, XLS, files from SAST/DAST and Vulnerability assessment tools that might not be supported yet by the existing Vulcan Connectors. On top of that, you can use the Vulcan Report Connector to upload Penetration Test files for asset data type Host or Website, depending on PT application type or infrastructure. Once you upload your data file and select the appropriate data type, the relevant mapping table appears on the connector screen. Then, you need to map the Headers in your file to the right Header/Field in the Vulcan Platform.

Connector Details

Supported file formats: CSV, ZIP, and XLS
Max file size: 200 Mb
File structure: The first row must contain headers.

Mandatory fields: Each Data Type file has its own mandatory fields marked with *.

File data types and examples

There are 5 types of CSV files you can upload; each represents a different Vulcan data type. Click on data type to download an example file.

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 representing 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.
Cloud Resources -Files representing scan results from cloud scanning tools.

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.
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
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.
- Make sure the Severity field is numeric ("Critical" = 100, "High" = 90, "Medium" = 50, "Low" = 30).
- 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.
- Date fields must be in the date format: DD/MM/YYYY. For example, 20/03/2023.
Click Create
That's it! your records are now in the Vulcan Platform.

Fields mapping and value type

Mapping Code Project - SAST

Mandatory fields are marked with *

Vulcan Field	Value type	More info
Assets - Projects *	string	The primary name of the web application
Assets - Last Report	date format	The last time the asset was scanned
Assets - Tags	string - only one tag at the time	This field lets you ingest existing tags from the vendor's platform and map those tags into Vulcan Asset Tags and Business Groups. You can map as many CSV headers to this field as you want. Each tag requires its independent column, and each column can be mapped to tags as well as to other categories. Read here about the importance of Business Groups and Tags.
Assets - Details	string	The relevant data you want to view in the asset itself. You can map as many CSV headers to this field as you want.
Component - File name*	string	The scanned file under the asset
Component - Line number*	string	The line number on which the vulnerability was reported
Vulnerabilities - ID	string	Unique Vulnerability identifier
Vulnerabilities - Name*	string	The name of the vulnerability as reported from the CSV
Vulnerabilities - CVE	string separated with comma in CVE format. Example: `CVE-2020-3178,CVE-2020-3174`	If CVE is available, it allows the Vulcan Platform to map and point to solutions and threat intelligence.
Vulnerabilities - Technical Severity	float	Numeric risk score as given from the CSV. This is typically the CVSS v3, but other severity fields can be mapped here instead. Using this value, Vulcan can provide the risk calculation basis for the Vulcan risk score. Note that the value range must be between 0 and 10.
Vulnerabilities - Description	string	The description of the vulnerability as given in the CSV
Vulnerabilities - Discovery Time	date format	The date on which the vulnerability was first found. If this value is not mapped, the default value will be set to the time Vulcan first ingested the vulnerability into the platform.
Vulnerabilities - Details	string	It is highly recommended to map the "Recommended Solution" header to the Vulnerabilities - Details field. Without a CVE, there will be no correlation to Vulcan Remediation Library. Therefore, it is critical to map the tool's recommended solution in case of no CVE. Any vulnerability details that do not fit into other categories/headers should be mapped to the `Vulnerabilities - Details` header.
Vulnerabilities - CWE	string separates with comma (Example: CWE-12345)	If CWE is available, it allows the Vulcan Platform to map to OWASP Top 10 categories for prioritization. This is an important field for DAST results.
Vulnerabilities - Unique instance ID	string	Vulnerability identifier for an asset-vulnerability connection.
Solutions - Description	string	Solution fields aren't mandatory. If you wish to add solution info into the solution fields, then you should at least provide `Solutions - Description`.
Solutions - Reference	string
Solutions - Reference Link	URL
Solutions - OS	string
Solutions - OS Version	string

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 (Example: CWE-12345)
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	Value type	More Info
Assets - Name*	string	Primary machine name of asset (typically a hostname, but can be FQDN or NetBIOS depending on the source of the asset).
Assets - Last Seen	date format	The last time the asset was scanned
Assets - Tags	string	This field lets you ingest existing tags from the vendor's platform and map those tags into Vulcan Asset Tags and Business Groups. You can map as many CSV headers to this field as you want. Each tag requires its independent column, and each column can be mapped to tags as well as to other categories. Read here about the importance of Business Groups and Tags.
Assets - Details	string	The relevant data you want to view in the asset itself. You can map as many CSV headers to this field as you want.
Assets IP	string in IP format	The IP address of the Asset.
Assets - OS	string	The asset's operating system. For example, if the asset is Windows Server 2016, the cell should say "Windows Server 2016."
Assets FQDN	string
Vulnerabilities - Name*	string	The name of the vulnerability as reported from the CSV
Vulnerabilities - CVE	string separated with comma in CVE format. Example: `CVE-2020-3178,CVE-2020-3174`	If CVE is available, it allows the Vulcan Platform to map and point to solutions and threat intelligence.
Vulnerabilities - Technical Severity	float	Numeric risk score as given from the CSV. This is typically the CVSS v3, but other severity fields can be mapped here instead. Using this value, Vulcan can provide the risk calculation basis for the Vulcan risk score. Note that the value range must be between 0 and 10.
Vulnerabilities - Description	string	The description of the vulnerability as given in the CSV
Vulnerabilities - Discovery Time	date format	The date on which the vulnerability was first found. If this value is not mapped, the default value will be set to the time Vulcan first ingested the vulnerability into the platform.
Vulnerabilities - Details	string	It is highly recommended to map the "Recommended Solution" header to the Vulnerabilities - Details field. Without a CVE, there will be no correlation to Vulcan Remediation Library. Therefore, it is critical to map the tool's recommended solution in case of no CVE. Any vulnerability details that do not fit into other categories/headers should be mapped to the `Vulnerabilities - Details` header.
Vulnerabilities - CWE	string separate with comma (example: CWE-12345)	If CWE is available, it allows the Vulcan Platform to map to OWASP Top 10 categories for prioritization. This is an important field for DAST results.
Vulnerabilities - Unique instance ID	string	Vulnerability identifier for an asset-vulnerability connection.
Solutions - Description	string	Solution fields aren't mandatory. If you wish to add solution info into the solution fields, then you should at least provide `Solutions - Description`.
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	More Info
Assets - ID*	string	Unique Asset identifier
Assets - Last Scan	date format	The last time the asset was scanned
Assets - Name*	string	Primary machine name of asset (typically a hostname, but can be FQDN or NetBIOS depending on the source of the asset).
Assets - Tags	string	This field lets you ingest existing tags from the vendor's platform and map those tags into Vulcan Asset Tags and Business Groups. You can map as many CSV headers to this field as you want. Each tag requires its independent column, and each column can be mapped to tags as well as to other categories. Read here about the importance of Business Groups and Tags.
Assets - Details	string	The relevant data you want to view in the asset itself. You can map as many CSV headers to this field as you want.
Assets - sha256	string	a string represent image hash format
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	Value range must be between 0 and 10
Vulnerabilities - Description	string
Vulnerabilities - Discovery Time	date format
Vulnerabilities - Details	string
Vulnerabilities - CWE	string separated with comma (Example: CWE-12345)
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	Value type	More Info
Assets - Name*	string	Primary name of the web application
Assets - Last Seen	date format	Last time the asset was seen
Assets - Tags	string	This field lets you ingest existing tags from the vendor's platform and map those tags into Vulcan Asset Tags and Business Groups. You can map as many CSV headers to this field as you want. Each tag requires its independent column, and each column can be mapped to tags as well as to other categories. Read here about the importance of Business Groups and Tags.
Assets - Details	string	The relevant data you want to view in the asset itself. You can map as many CSV headers to this field as you want.
Assets - URL	string	The parent URL of the application
Pages - URL	string	The specific URL location of the vulnerability within the application. This is an important field for DAST results.
Vulnerabilities - ID	string	Unique Vulnerability identifier
Vulnerabilities - Name*	string	The name of the vulnerability as reported from the CSV
Vulnerabilities - CVE	string separated with comma in CVE format. Example: `CVE-2020-3178,CVE-2020-3174`	If CVE is available, it allows the Vulcan Platform to map and point to solutions and threat intelligence.
Vulnerabilities - Technical Severity	float	Numeric risk score as given from the CSV. This is typically the CVSS v3, but other severity fields can be mapped here instead. Using this value, Vulcan can provide the risk calculation basis for the Vulcan risk score. Note that the value range must be between 0 and 10.
Vulnerabilities - Description	string	The description of the vulnerability as given in the CSV
Vulnerabilities - Discovery Time	date format	The date on which the vulnerability was first found. If this value is not mapped, the default value will be set to the time Vulcan first ingested the vulnerability into the platform.
Vulnerabilities - Details	string	It is highly recommended to map the "Recommended Solution" header to the Vulnerabilities - Details field. Without a CVE, there will be no correlation to Vulcan Remediation Library. Therefore, it is critical to map the tool's recommended solution in case of no CVE. Any vulnerability details that do not fit into other categories/headers should be mapped to the `Vulnerabilities - Details` header.
Vulnerabilities - CWE	string separated with comma (Example: CWE-12345)	If CWE is available, it allows the Vulcan Platform to map to OWASP Top 10 categories for prioritization. This is an important field for DAST results.
Vulnerabilities - Unique instance ID	string	Vulnerability identifier for an asset-vulnerability connection.
Solutions - Description	string	Solution fields aren't mandatory. If you wish to add solution info into the solution fields, then you should at least provide `Solutions - Description`.
Solutions - Reference	string
Solutions - Reference Link	URL
Solutions - OS	string
Solutions - OS Version	string

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	value range must be between 0 and 10
Vulnerabilities - Description	string
Vulnerabilities - Discovery Time	date format
Vulnerabilities - Details	string
Vulnerabilities - CWE	string separate with comma (Example: CWE-12345)
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.

Managing 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.

Updating Assets' tags at scale

You can use the Vulcan Report connector to upload data files and update assets data at scale. For example, you can use the Hosts (Asset Inventories) Data Type to update Dynamic tags (such as ownership properties) at scale.

All you need to do is:

Create your excel/csv file or work with an exported one and have the following mandatory headers:
Asset Name
Tag (or more than one tag)

For example:
In this example, we created 2 different dynamic ownership tags for each asset and added a regular tag. In the "Tag1" column we've put the personal email address of the owner, and in the "Tag2" column we've put the distribution list email address of the region the asset belongs to.
Upload the file to the Vulcan Report connector and select the Hosts (Asset Inventories) Data Type.
Note: You can upload as many files as you want by creating a Vulcan Connector instance per each file. Each Vulcan Connector instance can host one file. Maximum file size is 200 MB.
Map out the Asset Name to the Assets - Name filed and the tags to Assets - Tag. For example:
Click Create.
It usually takes several minutes for a file to complete the sync. Larger files take longer. The notification bar and the Log tab indicate the sync progress:
Once the sync is complete, the subjected assets will have the Dynamic Ownership tags and regular tags attached to them.
To enable the Dynamic Mechanism, you need to enable the Dynamic property for the tags first.

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.

Uploading a Penetration Test

To use the Vulcan Report connector for uploading a penetration test, follow the instructions at: https://help.vulcancyber.com/en/articles/8017187-uploading-a-penetration-test-pt-report

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.

How many reports can I create?

Each Vulcan Report/ConnectX connector represents a file from a specific product. Therefore, you can create as many report connectors as you need.
For example, one report connector can represent your data from CMDBs (e.g., ServiceNow), which contains relevant data of your hosts (Name, IP address, OS, etc.). The second report connector 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.).

How is the data correlated across the different reports I upload?

Correlation between different reports can be done only by asset name. For example:
A CMDB report can contain the asset name, and the Vulnerability Scanner report can contain the related asset name for each vulnerability. If the assets' names match, then the data correlates in Vulcan.

Wiz Connector

Lacework Connector

Purplemet Connector

CrowdStrike Connector

Checkmarx One Connector