This script is provided under an OSS license (specified in the LICENSE file) to wrap the Black Duck scanning utility Synopsys Detect to remove the need for a download script, but also produce optional text, xml and html reports.
It does not represent any extension of licensed functionality of Synopsys software itself and is provided as-is, without warranty or liability.
Detect_wrapper is intended to replace the use of the detect.sh or detect.ps1 scripts to download and run the latest version of Synopsys Detect for scanning in Black Duck, as well as provide reports and outputs from the scan result.
It can be installed as a pip package.
It will download the latest detect.jar and run it using Java (which is still required).
It takes the same arguments as Detect, with some additional options to support reporting and other bevaviour.
The main benefits of using this script over the existing shell scripts are:
- Will use proxy parameters (system proxy on Windows or command line provided proxy settings) to download detect.jar
- Checks required prerequisites (Java and connectivity to download Detect)
- Supports managing global Detect default options within the server (see section CENTRAL DEFAULT DETECT OPTIONS below)
- Runs Detect
- Optionally generates Junit test output XML files for lists of components, policies or vulnerabilities
- Optionally generates an HTML or text report with information about the scan results including counts of components, top 10 components by policy or vulnerability risk and top 10 vulnerabilities.
- Optionally produces a report for the whole project or for the last scan only - listing newly added components with policy and vulnerability risks
- Python 3.0 or greater
- Pip 20.0 or greater
- Similar prerequisites to Synopsys Detect
- Permissions to create/read the values for the DETECT_DEFAULT_OPTIONS project for server-managed defaults
Install the package using the command:
pip3 install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple detect_wrapper
Run the command:
detect_wrapper [wrapper options] [Detect options]
Where [wrapper options] can be:
--wrapper.last_scan_only: Report (calculate policy violations) on the last scan only
--wrapper.auto_last_scan: For first scan, report on full scan otherwise report (calculate policy violations) on the last scan only
--wrapper.report_text: Output console text report
--wrapper.report_html=out.html: Output HTML file (out.html)
--wrapper.junit_xml: Output Junit XML (default policy violations for full scan)
--wrapper.junit_type=[comps|vulns|pols]: Output Junit XML data for components, vulnerabilities or policies
--wrapper.detect_jar=detect.jar: Specify existing Detect jar file (detect.jar)
--wrapper.no_defaults: Ignore scan options stored on server in DETECT_DEFAULT_OPTIONS project (notes fields within versions)
--wrapper.version: Print version
--wrapper.help: Print this help
Detect_wrapper will look for Detect options set as environment variables, in the application-project.yml file or as command line arguments (the same as Detect does). Central default options will also be added to the specified arguments (see the section CENTRAL DEFAULT DETECT OPTIONS below).
Offline/dry-run scans are not supported. RAPID scanning is also not (yet) supported.
By default, Detect_wrapper reports results and policy violations for the full project version, but the --wrapper.last_scan_only option will focus only on the changes identified in the most recent scan. The option --wrapper.auto_last_scan will produce a full report for the first scan, but will produce last scan only data for all subsequent scans in a project version.
When --wrapper.last_scan_only is specified (or when --wrapper.auto_last_scan runs a last scan only), policy violations are calculated only for the components added in the last scan. This changes the default behaviour of Detect which will report all policy violations across the whole project.
Detect_wrapper can create text or HTML reports when the options --wrapper.report_text or --wrapper.report_html are specified.
Full project reports include the component counts (full project and last scan) with highest policy violation as well as the number of directly identified components (not Transitive dependencies).
A section on the Top 10 Components with Issues is included by decreasing Policy and Vulnerability severity.
Vulnerabilities are listed by severity counts, as well as the top 10 vulnerabilities by severity.
Detect_wrapper supports the use of centralised (server-based) Detect options. The program will create a project in the Black Duck server called DETECT_DEFAULT_OPTIONS if it does not exist.
Versions in the DETECT_DEFAULT_OPTIONS project should be named based on a comma-delimited list of files or file extensions which will be searched for in the project folder. The Detect.detector.search.depth option defines the depth which will be searched (as for Detect).
For example, if the version name is pom.xml,.txt then the project folder(s) will be searched for either the file pom.xml or any file with .txt extension; if matched then the value of the Notes field from the project version pom.xml,.txt will be added to the Detect options determined from the command line, environment or YML file. Options must be separated by semicolons in the Notes field (e.g. --detect.tools=DETECTOR;--detect.maven.build.command=package).
The ALL version adds options to all runs of Detect_wrapper, and OTHER will be used where no other match is found.
Options which are matched from the DETECT_DEFAULT_OPTIONS will be replaced by any duplicate items specified on the command line, environment or YML file.
Use the Detect_wrapper option --wrapper.no_defaults to bypass the use of server defined default options.
Note that the DETECT_DEFAULT_OPTIONS project must be readable by all scanning users for default options to be supported.
Detect_wrapper can be used in Github Actions by installing the program as a prerequisite. The following YML snippet shows how to install Python and Detect_wrapper, run a scan, store an output HTML report as an artifact and publish unit test results for SCA data.
runs-on: ubuntu-latest
strategy:
matrix:
python-version: [3.6]
steps:
- uses: actions/checkout@v2
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v2
with:
python-version: ${{ matrix.python-version }}
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip3 install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple detect_wrapper
- name: Run Detect_Wrapper
run: |
detect_wrapper --blackduck.url=https://SERVER --blackduck.api.token=API_TOKEN --blackduck.trust.cert=true \
--wrapper.report_html=sca_report.html --wrapper.report_text --wrapper.junit_xml=sca_results.xml
- uses: actions/upload-artifact@v2
with:
name: my-artifact
path: sca_report.html
- name: Publish Test Report
uses: mikepenz/action-junit-report@v2
with:
report_paths: '**/sca_results.xml'
check_name: 'Black Duck SCA Scan Results'
github_token: ${{ secrets.GITHUB_TOKEN }}