To import your data from Black Duck to the Kenna.AppSec module, you will need to leverage the BlackDuck Connector under the Open Source tools. There are two different BlackDuck Connectors: the API Connector and the JSON Connector. To learn about the differences between API and File-based connectors, please see the help page here.
We recommend the Black Duck Hub API Connector for ease of use. The connector is a full-run connector, and does not currently support incremental runs. The two connectors function similarly, however the JSON connector is just a file based connector, meaning it will not auto-pull information from BlackDuck.
User Prerequisites/Connector Setup:
-
Given that Black Duck deployments are On-Premise you will need one of the following:
-
Kenna Virtual Tunnel (VT)
-
Kenna Agent
-
-
Must have access to the BlackDuck API for the API Connector. See ‘Determine Appropriate Access’ below
Determine Appropriate Access
Create an access User with the appropriate level of access to Project(s) which you want imported into Cisco Vulnerability Management.
As an Administrator, go to the “hamburger menu” in the top-left corner and selection Administration → User Management → Create User then create a new User and edit their Roles.
-
If you want the Cisco Vulnerability Management to have access to ALL of your projects' vulnerabilities, simply grant this BlackDuck User the Global Project Viewer role.
-
Otherwise, if you would like Cisco Vulnerability Management to have access to the vulnerabilities of only certain projects, then:
-
Click the Add Project button
-
In the Project field, begin to type the name of each project that you would like this User to have visibility to. Auto complete suggestions will be provided matching available projects. You can enter multiple project names in this field.
-
Configuring your Connector in Cisco Vulnerability Management
To set up the API Connector, navigate to the Connectors tab in your Cisco Vulnerability Management deployment (you must be a Cisco Vulnerability Management Administrator to do so). On the Connectors page, select BlackDuck Hub under the "Open Source" category.
Once you select BlackDuck, the following screen will appear:
-
Enter a name for the connector, or leave it as “Black Duck Hub” if you wish.
-
Enter the Username and Password for the account you wish to leverage
- Enter the Host information
-
If your host is static, you must enter an IP address and the port.
-
If your host is dynamic, please enter the DNS and port information
-
-
Schedule the Connector. Select the frequency at which you’d like your Connector to run. (we recommend mirroring the cadence of your Black Duck Scans).
-
If your deployment is on-premise, you will need to check either the “Use Kenna Virtual Tunnel” or “Use Kenna Agent” checkbox depending on which of those you have deployed in your environment.
-
Click Save and Verify
*Note: If you’d like to set a connector level asset inactivity limit, you can do that at this time, or later. (We recommend 2-3x the scan cadence of your Black Duck Scans).
*Note: When extracting data from BlackDuck to import into Cisco Vulnerability Management, you'll have 3 Report options: Vulnerability Status, Vulnerability Remediation, and Vulnerability Update. The file format required for your connector is Vulnerability Status.
When Using the JSON Connector (File Based) customers will need to export a report by following the below steps:
-
Log into your BlackDuck as the User you created above with the appropriate level of Report access.
-
Go to the “hamburger menu” in the top-left corner of the UI and select Reports
-
Select Create New Report
-
Choose Report Type: Vulnerability Status Report
-
Choose Report Format: HTML
-
-
Wait for the Report to be processed.
-
Once available, click on the report to view it in your browser
-
From your browser’s File menu, choose Save As…. Alternatively, you may press CTRL + s on your keyboard (Command + s on Mac).
-
In order to successfully export JSON using the UI, you must adjust the name of the report being saved. Instead of Black Duck.htm, change the file extension to end in .json.htm as seen below:
-
The resulting file will contain the JSON results of the Vulnerability Status Report
-
Log into Cisco Vulnerability Management and go to Connectors
-
If you do not already have a BlackDuck JSON Connector, create one.
-
Upload the file from Step 7 by dragging it to your BlackDuck JSON Connector in Cisco Vulnerability Management.
What BlackDuck Items does Cisco Vulnerability Management Import?
|
BlackDuck Field |
Cisco Vulnerability Management Field |
Notes |
|---|---|---|
|
versionSummary > projectName |
Application Identifier |
Search for application_identifer in Cisco Vulnerability Management by using the custom query box and typing application:"" |
|
versionSummary > project.identifier |
Asset External_id |
|
|
Any of the following: 'Patched' OR 'Duplicate' OR 'Ignored' OR 'Mitigated' OR ‘Remediation_Complete’ |
vulnerability Status = Closed |
We do not map false positives or triage states. If an item has any of the statuses in column A, Cisco Vulnerability Management will mark the vulnerability Closed. |
|
absence of status= ('Patched' OR 'Duplicate' OR 'Ignored' OR 'Mitigated' OR ‘Remediation_Complete’) |
vulnerability Status = Open |
|
|
doc.score |
scanner_score |
Range: 1-10 Informational - 0 Low - 3 Medium - 6 High - 9 |
|
Vulnerability Title / Name |
|
|
|
Black Duck Security Advisory |
BDSA-##### |
Any Black Duck security advisories that are not correlated with CVEs, CWEs, or WASC-IDs will be imported as unique BDSAs. |
|
cwe_id |
CWE |
|
|
wasc_id |
WASC-ID |
|
|
cve_id |
CVE Raw Data |
|
|
report.generated_at |
Found On |
Black Duck does not pass timestamps in the report, thus Cisco Vulnerability Management generates a “report Generated at” timestamp for every connector run. Any data that is seen for the first time is Found On the earliest date-time referenced. |
|
report.generated_at |
last_seen_time & |
Black Duck does not pass timestamps in the report, thus Cisco Vulnerability Management generates a “report Generated at” timestamp for every connector run. Any data that is seen in our most recent report will be updated with their last_seen information. |
|
doc.description |
Description |
|
After we pull the Black Duck reports, Cisco Vulnerability Management generates a master document. Any item that is mapped from doc. refers to that master document. This doesn’t necessarily represent the field name in Black Duck.
Optional Settings
The following settings can be enabled on the backend for BlackDuck Hub Connectors. To have these settings enabled, or for more information, please contact Support, or your Customer Success Engineer.
-
Exclude Informationals
-
When this option is enabled, Cisco Vulnerability Management will not import vulnerabilities that do not include a CVE, CWE, or WASC ID.
-
-
Ignore Scanner Last Seen Time
-
If you do not want the asset last seen time in Cisco Vulnerability Management to be the scanner reported last seen time.
-
-
Custom Ordered Locators
-
Locators (IP, Netbios, FQDN, etc) can be reordered to better deduplicate vulnerabilities on the Connector level or the entire Platform level. For more information see the help article here.
-
Common Reasons for BlackDuck Hub Connector Run Failures
- Bad Credentials
- If you enter the incorrect connector credentials during the connector setup, we will not have access to the environment to make the API calls.
- If no reports are found we will abort the Connector run, rather than fail it outright
- If an API call fails (no data available, or other reasons)
-
Unexpected data returned
-
If Cisco Vulnerability Management receives data that is not in the expected format and we are unable to process it, the connector will fail.
-
-
If more than 1% of connector payloads fail to import cleanly, Cisco Vulnerability Management will auto-fail the Connector Run
Additional Assistance
Please contact Support should you require any additional assistance with the BlackDuck Hub Connector.
Comments
Please sign in to leave a comment.