BlackDuck Hub Connector

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

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 Kenna to have access to ALL of your projects' vulnerabilities, simply grant this BlackDuck User the Global Project Viewer role.

• Otherwise, if you would like Kenna 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 Kenna

To set up the API Connector, navigate to the Connectors tab in your Kenna deployment (you must be a Kenna 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 Kenna 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 Kenna, 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:

1. Log into your BlackDuck as the User you created above with the appropriate level of Report access.

2. Go to the “hamburger menu” in the top-left corner of the UI and select Reports

3. Select Create New Report

   1. Choose Report Type: Vulnerability Status Report

   2. Choose Report Format: HTML

4. Wait for the Report to be processed.

5. Once available, click on the report to view it in your browser

6. From your browser’s File menu, choose Save As…. Alternatively, you may press CTRL + s on your keyboard (Command + s on Mac).

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

   

    

8. The resulting file will contain the JSON results of the Vulnerability Status Report

9. Log into Kenna Security and go to Connectors

10. If you do not already have a BlackDuck JSON Connector, create one.

11. Upload the file from Step 7 by dragging it to your BlackDuck JSON Connector in Kenna.

What BlackDuck Items does Kenna Import?

After we pull the Black Duck reports, Kenna 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, Kenna 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 Kenna 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 Kenna 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, Kenna will auto-fail the Connector Run

Additional Assistance

Please contact Kenna Support should you require any additional assistance with the BlackDuck Hub Connector.