Black Duck

---
name: black-duck
description: "Expert agent for Black Duck (Synopsys) SCA. Covers binary analysis, SOUP lists for medical device compliance, export control, BDBA (binary analysis), Detect CLI, SBOM generation, and enterprise license compliance. WHEN: \"Black Duck\", \"Synopsys Black Duck\", \"BDBA\", \"Black Duck binary analysis\", \"SOUP list\", \"Black Duck Detect\", \"Black Duck Hub\", \"Synopsys SCA\"."
license: MIT
---

# Black Duck (Synopsys)

This skill covers Black Duck, Synopsys's enterprise Software Composition Analysis platform. Black Duck is distinguished by its binary analysis capability — scanning compiled code when source is unavailable — and its use in regulated industries (medical devices, aerospace, automotive) where SOUP (Software of Unknown Provenance) documentation is required.

## How to Approach Tasks

1. **Identify the scan type:**
   - **Source/package scanning** -- Traditional SCA from manifests and source
   - **Binary analysis (BDBA)** -- Black Duck Binary Analysis for compiled artifacts
   - **Snippet analysis** -- Detecting copied open-source code fragments in custom code
2. **Identify the compliance context** -- Medical device (SOUP), export control, automotive (AUTOSAR), or general enterprise SCA.
3. **Identify the tool component** -- Black Duck Hub (server), Detect (CLI), BDBA (binary analysis), or SCA via Coverity+Black Duck integration.

## Black Duck Platform Overview

Black Duck is an enterprise SCA platform focused on:

- **Comprehensive open-source detection:** Source, binary, snippet-level
- **License compliance:** 2,500+ license types, policy engine
- **Security vulnerability management:** CVE, NVD, and proprietary Black Duck KnowledgeBase
- **Regulated industry compliance:** SOUP documentation, export control reports, CRA/FCC compliance
- **Binary analysis (BDBA):** Analyzes compiled binaries (ELF, PE, Mach-O, APK, JAR, containers) without source

---

## Black Duck Detect (CLI)

Detect is the primary CLI tool for Black Duck scanning. It integrates with package managers, build tools, and source control.

### Installation

```bash
# Download latest Detect
bash <(curl -s -L https://detect.synopsys.com/detect9.sh)

# Or download directly
curl -LO https://detect.synopsys.com/detect9.sh

# PowerShell (Windows)
powershell "[Net.ServicePointManager]::SecurityProtocol = 'tls12'; irm https://detect.synopsys.com/detect9.ps1?$(Get-Random) | iex; detect"
```

### Basic Scan

```bash
# Scan current directory
bash detect.sh \
  --blackduck.url=https://blackduck.example.com \
  --blackduck.api.token=$BLACK_DUCK_TOKEN \
  --detect.project.name="My Application" \
  --detect.project.version.name="1.0.0"

# Scan specific source directory
bash detect.sh \
  --blackduck.url=https://blackduck.example.com \
  --blackduck.api.token=$BLACK_DUCK_TOKEN \
  --detect.source.path=/path/to/source \
  --detect.project.name="My App" \
  --detect.project.version.name=$BUILD_NUMBER

# Fail on policy violations
bash detect.sh \
  --blackduck.url=https://blackduck.example.com \
  --blackduck.api.token=$BLACK_DUCK_TOKEN \
  --detect.project.name="My App" \
  --detect.policy.check.fail.on.severities=MAJOR,CRITICAL,BLOCKER
```

### Key Detect Options

```bash
# Specify which detectors to run
--detect.tools=DETECTOR,BINARY_SCAN,SIGNATURE_SCAN,IMPACT_ANALYSIS

# Exclude directories
--detect.excluded.directories=build,target,node_modules,.git

# Specify signature scan targets (large files)
--detect.blackduck.signature.scanner.paths=/path/to/scan

# Risk report output
--detect.risk.report.pdf=true

# Notices report (attribution/license text for distribution)
--detect.notices.report=true

# Snippet matching (find OSS code copied into your source)
--detect.blackduck.signature.scanner.snippet.matching=SNIPPET_MATCHING
```

---

## Binary Analysis (BDBA)

Black Duck Binary Analysis (BDBA) analyzes compiled binaries to identify open-source components — without requiring source code or package manager metadata.

### Supported Binary Formats

| Format | Description |
|---|---|
| ELF | Linux executables and shared libraries (.so) |
| PE | Windows executables (.exe, .dll) |
| Mach-O | macOS executables and frameworks |
| APK | Android application packages |
| IPA | iOS application archives |
| JAR/WAR/EAR | Java archives |
| ZIP/TAR/GZ | Archives (recursively analyzed) |
| Docker/OCI | Container images |
| RPM/DEB | Linux packages |
| MSI/NSIS | Windows installers |
| Firmware images | Embedded systems (YAFFS, SquashFS, JFFS2) |

### BDBA Analysis Techniques

**String analysis:** Extracts version strings, copyright notices, license text embedded in binary.

**Symbol matching:** Matches function/variable names against known open-source libraries.

**Byte-level matching:** Compares binary segments against a database of known library byte patterns.

**File hash matching:** Exact file matches against Black Duck KnowledgeBase.

**Recursive extraction:** Unpacks embedded archives, containers, and installers to analyze contents.

### BDBA via Black Duck Detect

```bash
# Enable binary scan in Detect
bash detect.sh \
  --blackduck.url=https://blackduck.example.com \
  --blackduck.api.token=$BLACK_DUCK_TOKEN \
  --detect.tools=BINARY_SCAN \
  --detect.binary.scan.file.path=/path/to/my-app.jar \
  --detect.project.name="My App"

# Scan a directory of binaries
bash detect.sh \
  --blackduck.url=https://blackduck.example.com \
  --blackduck.api.token=$BLACK_DUCK_TOKEN \
  --detect.tools=BINARY_SCAN \
  --detect.binary.scan.file.path=/path/to/binaries/
```

### BDBA Standalone

BDBA can run as an on-premise appliance or SaaS for binary analysis without the full Black Duck Hub:

```bash
# BDBA REST API
curl -X POST https://bdba.example.com/api/v1/groups/{group_id}/upload/ \
  -H "Authorization: Token $BDBA_TOKEN" \
  -F "file=@my-firmware.bin"

# Check analysis status
curl https://bdba.example.com/api/v1/products/{product_id}/ \
  -H "Authorization: Token $BDBA_TOKEN"
```

---

## SOUP Lists (Medical Device Compliance)

SOUP (Software of Unknown Provenance) documentation is required by:
- **IEC 62304:** Medical device software standard (FDA-regulated)
- **ISO 14971:** Risk management for medical devices
- **FDA guidance:** Cybersecurity in medical devices (2023)

### What SOUP Documentation Requires

For each third-party software component (including open-source):
1. **Component identification:** Name, version, vendor
2. **License:** License type, full text (attribution)
3. **Functionality:** What the component does in your product
4. **Anomaly list:** Known bugs and CVEs, your assessment of risk
5. **Configuration:** How it is configured in your system
6. **Testing:** Evidence of suitability testing

### Black Duck SOUP Report Generation

```bash
# Generate SOUP report
bash detect.sh \
  --blackduck.url=https://blackduck.example.com \
  --blackduck.api.token=$BLACK_DUCK_TOKEN \
  --detect.project.name="Medical Device Software" \
  --detect.project.version.name="1.0.0" \
  --detect.notices.report=true \          # Full license text (attribution)
  --detect.risk.report.pdf=true           # Risk report with CVEs
```

The combination of notices report + risk report provides:
- Complete component inventory (SOUP list)
- Full license texts (for attribution requirements)
- Known vulnerabilities per component (anomaly list foundation)

### FDA Cybersecurity Requirements (2023)

The FDA's 2023 guidance "Cybersecurity in Medical Devices" requires:
- SBOM in industry-standard format (CycloneDX or SPDX)
- Vulnerability monitoring process
- Coordinated vulnerability disclosure policy
- Post-market cybersecurity management

Black Duck generates CycloneDX and SPDX SBOMs directly from scan results.

---

## Export Control Compliance

Black Duck helps with export control classification:

**EAR (Export Administration Regulations) — cryptography:**
- Identifies components with cryptography (AES, RSA, TLS libraries)
- Flags potential EAR 5E002 classification triggers
- Report: "Encryption Report" — lists all components with cryptographic functionality

**ECCN (Export Control Classification Number) analysis:**
Used for determining whether software needs export license or is eligible for License Exception ENC.

```bash
# Generate encryption report
bash detect.sh \
  --blackduck.url=https://blackduck.example.com \
  --blackduck.api.token=$BLACK_DUCK_TOKEN \
  --detect.project.name="My App" \
  --blackduck.offline.mode=false

# Then via Black Duck API:
curl "https://blackduck.example.com/api/projects/{id}/versions/{versionId}/reports" \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"reportType":"VERSION","reportFormat":"CSV"}'
```

---

## License Compliance

### Black Duck KnowledgeBase

Black Duck maintains a proprietary KnowledgeBase with:
- 1,500+ open source forges indexed
- 3.5M+ open source projects
- Millisecond matching against billions of file fingerprints
- License detection from file content, not just metadata

### Policy Engine

Define approval/rejection policies per license type:

**In Black Duck Hub:**
Policy Management → Policy Rules → Add Rule

```
Rule: Reject GPL Components
  Component Usage: Uses/dynamically links to
  License: GPL-2.0, GPL-3.0, AGPL-3.0
  Action: BLOCK

Rule: Review LGPL Components
  License: LGPL-2.0, LGPL-2.1, LGPL-3.0
  Action: FORCE REVIEW
  
Rule: Block High CVEs
  Vulnerability Severity: HIGH, CRITICAL
  Vulnerability Status: NOT_REMEDIATED
  Action: BLOCK
```

### License Conflict Detection

Black Duck detects when multiple components have licenses that conflict with each other — e.g., GPL-licensed component statically linked with proprietary code.

---

## CI/CD Integration

### Jenkins Pipeline

```groovy
stage('Black Duck Scan') {
  steps {
    script {
      def detectScript = "bash detect.sh"
      def detectArgs = [
        "--blackduck.url=${env.BLACK_DUCK_URL}",
        "--blackduck.api.token=${env.BLACK_DUCK_TOKEN}",
        "--detect.project.name=${env.JOB_NAME}",
        "--detect.project.version.name=${env.BUILD_NUMBER}",
        "--detect.policy.check.fail.on.severities=MAJOR,CRITICAL",
        "--detect.notices.report=true"
      ]
      sh "${detectScript} ${detectArgs.join(' ')}"
    }
  }
}
```

### GitHub Actions

```yaml
- name: Black Duck Detect
  run: |
    bash <(curl -s -L https://detect.synopsys.com/detect9.sh) \
      --blackduck.url=${{ vars.BLACK_DUCK_URL }} \
      --blackduck.api.token=${{ secrets.BLACK_DUCK_TOKEN }} \
      --detect.project.name=${{ github.repository }} \
      --detect.project.version.name=${{ github.ref_name }} \
      --detect.policy.check.fail.on.severities=MAJOR,CRITICAL
```

### Synopsys Bridge (CI Plugin)

The Synopsys Bridge provides a unified plugin for multiple Synopsys products:

```yaml
# GitHub Actions with Synopsys Bridge
- name: Synopsys Bridge
  uses: synopsys-sig/synopsys-action@v1
  with:
    bridge_download_version: latest
    blackduck_url: ${{ vars.BLACKDUCK_URL }}
    blackduck_apiToken: ${{ secrets.BLACKDUCK_API_TOKEN }}
    blackduck_scan_full: true
    blackduck_automation_fixpr: true    # Auto-create fix PRs
    blackduck_failure_severities: CRITICAL,MAJOR
```

---

## Snippet Analysis

Snippet matching detects open-source code that has been copied/pasted directly into your proprietary code — even if you don't use it as a dependency.

**Use cases:**
- Developer copied utility function from Stack Overflow / GitHub
- Legacy code integrated by copy-paste rather than dependency
- Vendored (bundled) open-source code with modifications

**Enable in Detect:**
```bash
bash detect.sh \
  --blackduck.url=https://blackduck.example.com \
  --blackduck.api.token=$BLACK_DUCK_TOKEN \
  --detect.tools=SIGNATURE_SCAN \
  --detect.blackduck.signature.scanner.snippet.matching=SNIPPET_MATCHING \
  --detect.source.path=/path/to/source
```

**Note:** Snippet scanning is slower and generates more findings. Enable only when thorough license compliance is required (IPO, acquisition, regulated industries).

---

## Common Issues

**Detect not finding dependencies:**
- Check `--detect.excluded.directories` is not too broad
- For Java: ensure Maven/Gradle build was run before scan (needs resolved dependency tree)
- Check Detect logs: `--logging.level.detect=DEBUG`

**BDBA analysis incomplete:**
- Large binary files: check BDBA file size limits (default 2GB)
- Encrypted or obfuscated binaries: BDBA may have limited visibility
- Firmware images: ensure BDBA appliance has correct filesystem extractors installed

**Policy check not blocking build:**
- Verify `--detect.policy.check.fail.on.severities` includes the relevant levels
- Check that policies are defined in the Black Duck Hub project being scanned
- Verify the service account token has permission to read policies

**SOUP report missing components:**
- Run full signature scan alongside package manager detection
- Enable snippet matching for comprehensive detection
- Manually review "ignored" components in the Hub UI — policy may be filtering them