Usage Examples

Getting Started

This guide demonstrates how to use ORT with SCANOSS to analyse your projects, scan for licence compliance issues, evaluate policies, and generate reports.

Basic Workflow

Step 1: Analyse Dependencies

The first step is to analyse your project’s dependency manifests to build a complete dependency tree.

# Run the analyser on your project
ort analyze -i . -o ort-results

This command accepts the following flags:

-i . — Analyses the current directory
-o ort-results — Writes results to the ort-results directory

The analyser will:

Detect supported package managers (npm, Maven, Gradle, etc.)
Parse dependency manifests
Build a complete dependency tree
Generate analyzer-result.yml

Note: The analyze subcommand name reflects ORT’s CLI spelling and is used verbatim throughout this guide.

Step 2: Scan with SCANOSS

Once dependency analysis is complete, scan the identified packages for licence and copyright information using SCANOSS.

# Scan packages for licences and copyright data
ort scan \
  --ort-file ort-results/analyzer-result.yml \
  --output-dir ort-results \
  --scanners SCANOSS

This command:

Reads the analyser results
Scans all identified packages using SCANOSS
Detects licences and copyrights
Generates scan-result.yml

Note: Vulnerability data may also be returned by SCANOSS where available, but vulnerability detection is not guaranteed for all packages.

Step 3: Generate an HTML Report

Generate an interactive HTML report to review your scan results.

# Generate an HTML report
ort report \
  --ort-file ort-results/scan-result.yml \
  --output-dir ort-results \
  --report-formats StaticHtml

Step 4: View Reports

Open the generated HTML report in your browser: Windows (PowerShell):

Start-Process ort-results\scan-report-web-app.html

Windows (Command Prompt):

start ort-results\scan-report-web-app.html

macOS:

open ort-results/scan-report-web-app.html

Linux:

xdg-open ort-results/scan-report-web-app.html

Advanced Workflows

Complete Workflow with Policy Evaluation

To include policy evaluation in your compliance workflow, add the evaluate step between the scan and report stages. macOS / Linux:

# Step 1: Analyse dependencies
ort analyze -i . -o ort-results

# Step 2: Scan with SCANOSS
ort scan \
  --ort-file ort-results/analyzer-result.yml \
  --output-dir ort-results \
  --scanners SCANOSS

# Step 3: Evaluate policies
ort evaluate \
  --ort-file ort-results/scan-result.yml \
  --output-dir ort-results \
  --rules-file ~/.ort/config/rules.kts

# Step 4: Generate report including evaluation results
ort report \
  --ort-file ort-results/evaluation-result.yml \
  --output-dir ort-results \
  --report-formats StaticHtml

Windows (PowerShell):

# Step 1: Analyse dependencies
ort analyze -i . -o ort-results

# Step 2: Scan with SCANOSS
ort scan `
  --ort-file ort-results/analyzer-result.yml `
  --output-dir ort-results `
  --scanners SCANOSS

# Step 3: Evaluate policies
ort evaluate `
  --ort-file ort-results/scan-result.yml `
  --output-dir ort-results `
  --rules-file "$env:USERPROFILE\.ort\config\rules.kts"

# Step 4: Generate report including evaluation results
ort report `
  --ort-file ort-results/evaluation-result.yml `
  --output-dir ort-results `
  --report-formats StaticHtml

Windows (Command Prompt):

rem Step 1: Analyse dependencies
ort analyze -i . -o ort-results

rem Step 2: Scan with SCANOSS
ort scan ^
  --ort-file ort-results/analyzer-result.yml ^
  --output-dir ort-results ^
  --scanners SCANOSS

rem Step 3: Evaluate policies
ort evaluate ^
  --ort-file ort-results/scan-result.yml ^
  --output-dir ort-results ^
  --rules-file "%USERPROFILE%\.ort\config\rules.kts"

rem Step 4: Generate report including evaluation results
ort report ^
  --ort-file ort-results/evaluation-result.yml ^
  --output-dir ort-results ^
  --report-formats StaticHtml

Report Formats

Generate Multiple Formats

ORT can generate reports in several formats simultaneously. Select the format(s) appropriate for your use case.

# SPDX SBOM (Software Bill of Materials)
ort report --ort-file ort-results/scan-result.yml \
  --output-dir ort-results --report-formats SpdxDocument

# CycloneDX SBOM
ort report --ort-file ort-results/scan-result.yml \
  --output-dir ort-results --report-formats CycloneDx

# Multiple formats in a single command
ort report --ort-file ort-results/scan-result.yml \
  --output-dir ort-results \
  --report-formats StaticHtml,SpdxDocument,CycloneDx

Format Use Cases

Static HTML Report

Recommended for:

Human-readable licence compliance reviews
Sharing results with stakeholders
Interactive exploration of scan results

ort report --ort-file ort-results/evaluation-result.yml \
  --output-dir ort-results \
  --report-formats StaticHtml

SPDX Document

An industry-standard Software Bill of Materials (SBOM) format. Recommended for:

Legal compliance requirements
Tool interoperability
Sharing with third parties that require a standardised SBOM

ort report --ort-file ort-results/evaluation-result.yml \
  --output-dir ort-results \
  --report-formats SpdxDocument

CycloneDX

A modern SBOM format with strong tooling support. Recommended for:

Vulnerability tracking workflows
Security analysis pipelines
Integration with CycloneDX-compatible tools

ort report --ort-file ort-results/evaluation-result.yml \
  --output-dir ort-results \
  --report-formats CycloneDx

Specific Use Cases

Scanning a JavaScript / Node.js Project

# Navigate to your Node.js project
cd /path/to/nodejs-project

# Analyse npm dependencies
ort analyze -i . -o ort-results

# Scan with SCANOSS
ort scan \
  --ort-file ort-results/analyzer-result.yml \
  --output-dir ort-results \
  --scanners SCANOSS

# Generate report
ort report \
  --ort-file ort-results/scan-result.yml \
  --output-dir ort-results \
  --report-formats StaticHtml,SpdxDocument

Scanning a Java / Maven Project

# Navigate to your Maven project
cd /path/to/maven-project

# Analyse Maven dependencies
ort analyze -i . -o ort-results

# Scan with SCANOSS
ort scan \
  --ort-file ort-results/analyzer-result.yml \
  --output-dir ort-results \
  --scanners SCANOSS

# Generate report
ort report \
  --ort-file ort-results/scan-result.yml \
  --output-dir ort-results \
  --report-formats StaticHtml,CycloneDx

Scanning a Python Project

# Navigate to your Python project
cd /path/to/python-project

# Analyse pip dependencies
ort analyze -i . -o ort-results

# Scan with SCANOSS
ort scan \
  --ort-file ort-results/analyzer-result.yml \
  --output-dir ort-results \
  --scanners SCANOSS

# Generate report
ort report \
  --ort-file ort-results/scan-result.yml \
  --output-dir ort-results \
  --report-formats StaticHtml,SpdxDocument

CI/CD Integration

GitHub Actions Workflow

Create .github/workflows/ort-scan.yml:

name: ORT Compliance Scan

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ort-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          java-version: "21"
          distribution: "temurin"

      - name: Install ORT
        run: |
          git clone https://github.com/oss-review-toolkit/ort.git
          cd ort
          ./gradlew installDist
          echo "$PWD/cli/build/install/ort/bin" >> $GITHUB_PATH

      - name: Configure ORT
        run: |
          mkdir -p ~/.ort/config
          cat > ~/.ort/config/config.yml << EOF
          ort:
            scanner:
              scanners:
                SCANOSS:
                  options:
                    apiUrl: "https://api.scanoss.com"
                  secrets:
                    apiKey: "${{ secrets.SCANOSS_API_KEY }}"
          EOF

      - name: Run ORT analysis
        run: ort analyze -i . -o ort-results

      - name: Run ORT scan
        run: |
          ort scan \
            --ort-file ort-results/analyzer-result.yml \
            --output-dir ort-results \
            --scanners SCANOSS

      - name: Generate reports
        run: |
          ort report \
            --ort-file ort-results/scan-result.yml \
            --output-dir ort-results \
            --report-formats StaticHtml,SpdxDocument,CycloneDx

      - name: Upload reports
        uses: actions/upload-artifact@v4
        with:
          name: ort-reports
          path: ort-results/

GitLab CI/CD Pipeline

Create .gitlab-ci.yml:

ort-scan:
  image: eclipse-temurin:21-jdk
  stage: test
  before_script:
    - apt-get update && apt-get install -y git
    - git clone https://github.com/oss-review-toolkit/ort.git
    - cd ort && ./gradlew installDist && cd ..
    - export PATH="$PWD/ort/cli/build/install/ort/bin:$PATH"
    - mkdir -p ~/.ort/config
    - |
      cat > ~/.ort/config/config.yml << EOF
      ort:
        scanner:
          scanners:
            SCANOSS:
              options:
                apiUrl: "https://api.scanoss.com"
              secrets:
                apiKey: "$SCANOSS_API_KEY"
      EOF
  script:
    - ort analyze -i . -o ort-results
    - ort scan --ort-file ort-results/analyzer-result.yml --output-dir ort-results --scanners SCANOSS
    - ort report --ort-file ort-results/scan-result.yml --output-dir ort-results --report-formats StaticHtml,SpdxDocument
  artifacts:
    paths:
      - ort-results/
    expire_in: 1 week

Policy Enforcement Examples

Example 1: Block GPL Licences

packageRule("NO_GPL_LICENSES") {
    val gplLicenses = setOf("GPL-2.0", "GPL-3.0", "LGPL-2.1", "LGPL-3.0")
    val packageLicenses = licenseInfoResolver.resolveLicenseInfo(pkg.metadata.id)
        .licenses.map { it.license.toString() }

    require {
        packageLicenses.none { it in gplLicenses }
    }

    error(
        message = "Package ${pkg.metadata.id.toCoordinates()} uses a GPL licence: ${packageLicenses.filter { it in gplLicenses }}",
        howToFix = "Replace with a permissively licensed alternative, or obtain a commercial licence."
    )
}

Example 2: Require a Licence for All Packages

packageRule("REQUIRE_LICENSE") {
    require {
        val licenses = licenseInfoResolver.resolveLicenseInfo(pkg.metadata.id).licenses
        licenses.isNotEmpty()
    }

    error(
        message = "Package ${pkg.metadata.id.toCoordinates()} has no detected licence.",
        howToFix = "Verify the package licence or contact the package maintainer."
    )
}

Example 3: Block Packages with Critical Vulnerabilities

packageRule("NO_CRITICAL_VULNERABILITIES") {
    val vulnerabilities = ortResult.getVulnerabilities(pkg.metadata.id)
    val criticalVulns = vulnerabilities.filter { it.severity == "CRITICAL" }

    require {
        criticalVulns.isEmpty()
    }

    error(
        message = "Package ${pkg.metadata.id.toCoordinates()} has ${criticalVulns.size} critical vulnerabilities: ${criticalVulns.map { it.id }.joinToString()}",
        howToFix = "Update to a version of ${pkg.metadata.id.name} that resolves these vulnerabilities, then re-run the scan."
    )
}

Note: The howToFix message above has been corrected. The original referenced ${pkg.metadata.id.version}, which is the current (affected) version — not a remediated one. Update the message to reference the specific fixed version where known.

Troubleshooting Common Issues

Issue: Analysis Fails for a Specific Package Manager

Solution:

# Restrict analysis to specific package managers
ort analyze -i . -o ort-results --package-managers NPM,Maven

# Exclude directories or package managers marked as excluded in .ort/excludes.yml
ort analyze -i . -o ort-results --skip-excluded

Issue: Scan Takes Too Long

Solution:

# Increase the scan timeout (value in seconds)
ort scan \
  --ort-file ort-results/analyzer-result.yml \
  --output-dir ort-results \
  --scanners SCANOSS \
  --scanner-options SCANOSS:timeout=600

Issue: Out-of-Memory Errors

Solution:

# Increase the Java heap size before running ORT
export JAVA_OPTS="-Xmx16g"
ort scan \
  --ort-file ort-results/analyzer-result.yml \
  --output-dir ort-results \
  --scanners SCANOSS

Best Practices

1. Version-Control Your Configuration

Store your ORT configuration alongside your project source:

# Copy global ORT configuration into the project repository
mkdir .ort
cp ~/.ort/config/config.yml .ort/
cp ~/.ort/config/rules.kts .ort/

# Reference the project-local configuration at runtime
ort scan \
  --config .ort/config.yml \
  --ort-file ort-results/analyzer-result.yml \
  --output-dir ort-results \
  --scanners SCANOSS

2. Use Exclusions for Large Projects

For large projects, use ORT’s exclusion mechanism to skip directories or packages that are out of scope, rather than scanning everything unconditionally:

# Skip packages and paths marked as excluded in .ort/excludes.yml
ort scan \
  --ort-file ort-results/analyzer-result.yml \
  --output-dir ort-results \
  --scanners SCANOSS \
  --skip-excluded

Note: The --skip-excluded flag skips packages or paths marked as excluded in your ORT configuration. It does not perform incremental or diff-based scanning.

3. Schedule Regular Compliance Scans

Run scans on a schedule to detect newly disclosed vulnerabilities or licence changes. The following example uses a cron job (Linux/macOS) to run a weekly scan:

# Add to crontab with: crontab -e
# Runs every Sunday at midnight
0 0 * * 0 cd /path/to/project && \
  ort analyze -i . -o ort-results && \
  ort scan \
    --ort-file ort-results/analyzer-result.yml \
    --output-dir ort-results \
    --scanners SCANOSS

4. Document Policy Decisions

Add comments to policy rules to record the rationale and approval process:

/**
 * Blocks all copyleft licences in accordance with company policy (effective 2024-01-01).
 * Exceptions must be approved by the legal team and documented in .ort/exceptions.yml.
 */
packageRule("NO_COPYLEFT") {
    // Rule implementation
}

Next Steps

Customise policies — Adapt policy rules to your organisation’s licence and security requirements.
Automate — Integrate ORT into your CI/CD pipelines using the examples above.
Monitor — Schedule regular scans to track compliance over time.
Report — Generate compliance reports in the format required by your stakeholders.

For further information, refer to the ORT documentation.

Documentation

Links

Getting Started

Basic Workflow

Step 1: Analyse Dependencies

Step 2: Scan with SCANOSS

Step 3: Generate an HTML Report

Step 4: View Reports

Advanced Workflows

Complete Workflow with Policy Evaluation

Report Formats

Generate Multiple Formats

Format Use Cases

Static HTML Report

SPDX Document

CycloneDX

Specific Use Cases

Scanning a JavaScript / Node.js Project

Scanning a Java / Maven Project

Scanning a Python Project

CI/CD Integration

GitHub Actions Workflow

GitLab CI/CD Pipeline

Policy Enforcement Examples

Example 1: Block GPL Licences

Example 2: Require a Licence for All Packages

Example 3: Block Packages with Critical Vulnerabilities

Troubleshooting Common Issues

Issue: Analysis Fails for a Specific Package Manager

Issue: Scan Takes Too Long

Issue: Out-of-Memory Errors

Best Practices

1. Version-Control Your Configuration

2. Use Exclusions for Large Projects

3. Schedule Regular Compliance Scans

4. Document Policy Decisions

Next Steps

Documentation

Links

​Getting Started

​Basic Workflow

​Step 1: Analyse Dependencies

​Step 2: Scan with SCANOSS

​Step 3: Generate an HTML Report

​Step 4: View Reports

​Advanced Workflows

​Complete Workflow with Policy Evaluation

​Report Formats

​Generate Multiple Formats

​Format Use Cases

​Static HTML Report

​SPDX Document

​CycloneDX

​Specific Use Cases

​Scanning a JavaScript / Node.js Project

​Scanning a Java / Maven Project

​Scanning a Python Project

​CI/CD Integration

​GitHub Actions Workflow

​GitLab CI/CD Pipeline

​Policy Enforcement Examples

​Example 1: Block GPL Licences

​Example 2: Require a Licence for All Packages

​Example 3: Block Packages with Critical Vulnerabilities

​Troubleshooting Common Issues

​Issue: Analysis Fails for a Specific Package Manager

​Issue: Scan Takes Too Long

​Issue: Out-of-Memory Errors

​Best Practices

​1. Version-Control Your Configuration

​2. Use Exclusions for Large Projects

​3. Schedule Regular Compliance Scans

​4. Document Policy Decisions

​Next Steps

Getting Started

Basic Workflow

Step 1: Analyse Dependencies

Step 2: Scan with SCANOSS

Step 3: Generate an HTML Report

Step 4: View Reports

Advanced Workflows

Complete Workflow with Policy Evaluation

Report Formats

Generate Multiple Formats

Format Use Cases

Static HTML Report

SPDX Document

CycloneDX

Specific Use Cases

Scanning a JavaScript / Node.js Project

Scanning a Java / Maven Project

Scanning a Python Project

CI/CD Integration

GitHub Actions Workflow

GitLab CI/CD Pipeline

Policy Enforcement Examples

Example 1: Block GPL Licences

Example 2: Require a Licence for All Packages

Example 3: Block Packages with Critical Vulnerabilities

Troubleshooting Common Issues

Issue: Analysis Fails for a Specific Package Manager

Issue: Scan Takes Too Long

Issue: Out-of-Memory Errors

Best Practices

1. Version-Control Your Configuration

2. Use Exclusions for Large Projects

3. Schedule Regular Compliance Scans

4. Document Policy Decisions

Next Steps