blackduck-metrics

License Apache-2.0

Overview Black Duck Metrics connects to your Black Duck instance and extracts data from the system using REST API to CSV files of raw data, and an XLSX (Excel) file containing graphs. This data can be useful to help report on your usage and spot anomalies.

The utility extracts information from the entire system (provided the correct permission is granted) and extracts users, scans, policies, projects and versions including metadata such as the quantity of each level of vulnerability, e.g. the number of critical vulns in each version. It does NOT extract the actual components that are included in projects or the vulnerabilities associated. When you run the tool you can specify if you would like project, version and user names to be anonymised in the output, however this does make it harder to identify projects.

This utility is designed to help review Black Duck usage but should be used only periodically. This solution is not designed to optimally extract data from Black Duck to synchronize with other systems or for daily monitoring. This solution is designed for quarterly reviews of Black Duck usage.

For further reporting needs there are plenty of options:

1. The Black Duck reporting database : https://sig-product-docs.synopsys.com/bundle/bd-hub/page/ReportingDatabase/UsingDatabase.html
2. Microsoft PowerBI template : https://community.synopsys.com/s/article/Blackduck-Dashboards-using-Microsoft-Power-BI
3. Services - contact your Synopsys representative to discuss services to assist with your reporting requirements.

Pre-requisites:

• Java v8 or later
• Connectivity to the Black Duck instance
• A Read Only API token generated by a user with Super User or System Administrator role Read only required - requires this level of access to be able to get data on all scans, projects and versions across the system.

Online Execution:

Use the following commands to pull the latest version of Black Duck Metrics script and jar file from Github and run it locally.

Linux/Mac:

• Open a terminal and paste the following command:

  bash <(curl -s -L https://raw.githubusercontent.com/blackducksoftware/blackduck-metrics/main/blackduck-metrics.sh)

Windows:

• Open a 'Windows PowerShell' window and paste the following command:

  powershell "[Net.ServicePointManager]::SecurityProtocol = 'tls12'; irm https://raw.githubusercontent.com/blackducksoftware/blackduck-metrics/main/blackduck-metrics.ps1?$(Get-Random) | iex; metrics"

By default Black Duck Metrics will prompt for connection details to Black Duck and configuration options in the console window. It is possible to provide command line arguments to automate this and skip the interactive input.

Air-gapped Execution:

1. Download the latest version of the jar file from https://github.com/blackducksoftware/blackduck-metrics/tree/main/versions

2. In terminal/command prompt change directory to the jar file download folder.

3. Run the following command:

   java -jar blackduck-metrics-2023.12.1-jar-with-dependencies.jar

Output

The output of the tool is a zip file containing the raw CSV files and XLSX file. The console output will specify the file path to the zip once execution completes.

Security Considerations

The tool will extract data from Black Duck and place it in CSV and XLSX files within the output zip file. Please review the contents of these files and ensure you are comfortable with sending this data before sending these files to anyone.

Command Line Arguments

If you would prefer to automate running the tool you can specify the following command line parameters to skip the interactive parameter input.

Parameter detail:

• -mode - the mode to run, please specify a value of 1 (extract CSV and generate XLSX).
• -name - the name of the extraction e.g. customer-name.
• -url, -apikey - for connecting to the Black Duck instance
• -proxyhost -proxyport - if you need to connect via a proxy.
• -hideNames - will remove the project/project version/scan and user names from the results and instead use the ids for identification. Ideally we would have the project names to aide in communication with the customer but if a customer does not want to share this information it can be removed and discuss context via project/version Ids.
• -outputDir – the output directory to write the data to. This must either not exist or be an empty directory, relative paths are allowed.
• -threadCount - the number of threads to execute with. More threads are faster but will put more load on the server. If the server is heavily used at the time (scanning) then set to between 1 and 3. Default is 10.
• -pageSize - the page size to use when calling the API. Default is 50.
• -includeHeatMap - whether to include the heat map in the output.