Configuration

Installation

Prerequisites

Before installing ORT, ensure the following are available in your environment:

Java: JDK 21 or later
Git: Required for cloning the ORT repository
SCANOSS API key: Obtainable from the SCANOSS platform
Shell environment:
- Windows: PowerShell, Command Prompt, or Git Bash
- macOS/Linux: Terminal (Bash or Zsh)
Text editor: VS Code, Notepad++, nano, vim, or any editor of your choice

Windows Installation

Open PowerShell and run the following commands:

# Clone ORT repository
git clone https://github.com/oss-review-toolkit/ort.git
cd ort

# Build ORT using Gradle
.\gradlew.bat installDist

# Add ORT to PATH for the current session only
$env:PATH = "$PWD\cli\build\install\ort\bin;$env:PATH"

# To add ORT to PATH permanently, use one of the following approaches:
# Option 1: System Properties > Environment Variables (GUI)
# Option 2: Add the following line to your PowerShell profile:
#   notepad $PROFILE
#   $env:PATH = "C:\path\to\ort\cli\build\install\ort\bin;$env:PATH"

# Verify installation
ort --help

Configure Java Memory (Windows)

To set the Java heap size permanently, add the following via System Properties > Environment Variables:

Variable name: JAVA_OPTS
Variable value: -Xmx8g

To set it temporarily for the current PowerShell session:

$env:JAVA_OPTS = "-Xmx8g"

macOS/Linux Installation

Open a terminal and run the following commands. If you use Zsh (the default shell on macOS), replace ~/.bashrc with ~/.zshrc throughout.

# Clone ORT repository
git clone https://github.com/oss-review-toolkit/ort.git
cd ort

# Build ORT using Gradle
./gradlew installDist

# Configure Java memory (8 GB recommended)
echo 'export JAVA_OPTS="-Xmx8g"' >> ~/.bashrc
source ~/.bashrc

# Add ORT to PATH
echo "export PATH=\"$(pwd)/cli/build/install/ort/bin:\$PATH\"" >> ~/.bashrc
source ~/.bashrc

# Verify installation
ort --help

SCANOSS Configuration

Create the Configuration Directory

ORT stores scanner settings, policy rules, and other configuration files in a dedicated configuration directory. Windows:

# Create the configuration directory
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.ort\config"

# Open the configuration file in Notepad
notepad "$env:USERPROFILE\.ort\config\config.yml"

# Alternatively, open in VS Code if installed:
# code "$env:USERPROFILE\.ort\config\config.yml"

macOS/Linux:

# Create the configuration directory
mkdir -p ~/.ort/config

# Open the configuration file in nano
nano ~/.ort/config/config.yml

# Alternatively, create the file directly using cat:
cat > ~/.ort/config/config.yml << 'EOF'
# Configuration content will be added in the next step
EOF

Configure the SCANOSS Scanner

Add the following content to config.yml:

ort:
  scanner:
    scanners:
      SCANOSS:
        options:
          apiUrl: "https://api.scanoss.com"
        secrets:
          apiKey: "your-scanoss-api-key-here"

Replace your-scanoss-api-key-here with your actual SCANOSS API key.

Configuration Options

API URL

The apiUrl option specifies the SCANOSS API endpoint:

https://api.scanoss.com — SCANOSS cloud service
Custom URL — For self-hosted SCANOSS instances

API Key

The apiKey is required for authenticated access to the SCANOSS knowledge base. To obtain an API key:

Visit SCANOSS Platform
Sign up or log in
Navigate to the API Keys section
Generate a new API key

Additional Options

The following additional scanner options are available:

ort:
  scanner:
    scanners:
      SCANOSS:
        options:
          apiUrl: "https://api.scanoss.com"
          timeout: 300
          retries: 3
        secrets:
          apiKey: "your-scanoss-api-key-here"

timeout: Maximum time in seconds to wait for a scan response
retries: Number of retry attempts on transient failures

Policy Configuration

Create the Policy Rules File

ORT uses Kotlin Script (.kts) files to define policy rules using the Kotlin DSL. Create a rules.kts file in your configuration directory. Windows:

# Open the policy rules file in Notepad
notepad "$env:USERPROFILE\.ort\config\rules.kts"

# Alternatively, open in VS Code if installed:
# code "$env:USERPROFILE\.ort\config\rules.kts"

macOS/Linux:

# Open the policy rules file in nano
nano ~/.ort/config/rules.kts

# Alternatively, create the file directly using cat:
cat > ~/.ort/config/rules.kts << 'EOF'
# Policy rules will be added in the next step
EOF

Basic Policy Rules

Add the following content to rules.kts:

/**
 * Basic ORT Policy Rules
 */

import org.ossreviewtoolkit.model.*

ruleSet(ortResult, licenseInfoResolver) {
    // Rule: Warn about packages without declared licences
    packageRule("DECLARED_LICENSE_CHECK") {
        require {
            pkg.metadata.declaredLicenses.isNotEmpty()
        }

        warning(
            message = "Package ${pkg.metadata.id.toCoordinates()} has no declared licence",
            howToFix = "Add licence information to the package"
        )
    }
}

Advanced Policy Rules

Block Copyleft Licences

packageRule("COPYLEFT_LICENSE_CHECK") {
    require {
        val copyleftLicenses = setOf("GPL-2.0", "GPL-3.0", "AGPL-3.0")
        val packageLicenses = licenseInfoResolver.resolveLicenseInfo(pkg.metadata.id)
            .licenses.map { it.license.toString() }

        packageLicenses.none { it in copyleftLicenses }
    }

    error(
        message = "Package ${pkg.metadata.id.toCoordinates()} uses a copyleft licence",
        howToFix = "Replace with a permissively licenced alternative or obtain a commercial licence"
    )
}

Flag High-Severity Vulnerabilities

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

    require {
        criticalVulns.isEmpty()
    }

    error(
        message = "Package ${pkg.metadata.id.toCoordinates()} has ${criticalVulns.size} critical/high vulnerabilities",
        howToFix = "Update to a patched version or apply the relevant security patches"
    )
}

Enforce Component Age Policies

packageRule("COMPONENT_AGE_CHECK") {
    val maxAgeInDays = 730 // 2 years
    val publishDate = pkg.metadata.publishedAt

    require {
        publishDate != null &&
        publishDate.isAfter(Instant.now().minus(maxAgeInDays, ChronoUnit.DAYS))
    }

    warning(
        message = "Package ${pkg.metadata.id.toCoordinates()} is older than $maxAgeInDays days",
        howToFix = "Consider updating to a more recent version"
    )
}

Configuration File Structure

Complete Configuration Example

The following is a comprehensive config.yml example covering scanner, analyser, and reporter settings:

ort:
  # Scanner configuration
  scanner:
    scanners:
      SCANOSS:
        options:
          apiUrl: "https://api.scanoss.com"
          timeout: 300
          retries: 3
        secrets:
          apiKey: "your-scanoss-api-key-here"

  # Analyser configuration
  analyzer:
    allowDynamicVersions: false
    enabledPackageManagers:
      - NPM
      - Maven
      - Gradle
      - Pip
      - Bundler

  # Reporter configuration
  reporter:
    formats:
      - StaticHtml
      - SpdxDocument
      - CycloneDx

Environment Variables

ORT can also be configured using environment variables. These take effect at runtime and do not require changes to config.yml:

# SCANOSS API key
export ORT_SCANOSS_API_KEY="your-api-key"

# SCANOSS API URL
export ORT_SCANOSS_API_URL="https://api.scanoss.com"

# Java memory settings
export JAVA_OPTS="-Xmx8g"

Note: If both environment variables and config.yml are present, confirm which takes precedence in your version of ORT, as override behaviour may vary.

Verification

Verify the Installation

Confirm that ORT is correctly installed and accessible on your PATH:

# Display ORT version
ort --version

# Display general help
ort --help

# Display help for individual commands
ort analyze --help
ort scan --help
ort evaluate --help
ort report --help

Verify the SCANOSS Configuration

Confirm that your configuration file is present and readable:

# macOS/Linux
cat ~/.ort/config/config.yml

# Windows
type %USERPROFILE%\.ort\config\config.yml

To verify that the SCANOSS scanner is invoked correctly, run a scan against a known target and check the output for SCANOSS-specific log entries:

ort scan --help

Troubleshooting

Common Issues

Java Memory Errors

If ORT throws an OutOfMemoryError, increase the Java heap size:

# macOS/Linux
export JAVA_OPTS="-Xmx16g"

# Windows PowerShell
$env:JAVA_OPTS = "-Xmx16g"

API Connection Errors

If ORT cannot connect to the SCANOSS API:

Verify that the API key in config.yml is correct and has not expired
Confirm network connectivity to api.scanoss.com
Verify that the apiUrl value in config.yml is correct
Check that firewall or proxy rules are not blocking outbound HTTPS traffic

Configuration File Not Found

If ORT cannot locate the configuration file:

# macOS/Linux: verify the configuration directory exists and contains config.yml
ls ~/.ort/config

# Windows: verify the configuration directory exists and contains config.yml
dir %USERPROFILE%\.ort\config

# macOS/Linux: ensure the file has correct read permissions
chmod 644 ~/.ort/config/config.yml

Debug Mode

To enable verbose debug logging, pass the --debug flag:

ort --debug scan --ort-file analyzer-result.yml --scanners SCANOSS

Next Steps

Once ORT is configured with SCANOSS, proceed with the following:

Run your first scan — See the Usage Examples section
Define custom policies — Extend rules.kts with rules specific to your organisation
Integrate with CI/CD — Automate scanning as part of your development pipeline
Generate reports — Produce compliance artefacts for your projects

Documentation

Links

Installation

Prerequisites

Windows Installation

Configure Java Memory (Windows)

macOS/Linux Installation

SCANOSS Configuration

Create the Configuration Directory

Configure the SCANOSS Scanner

Configuration Options

API URL

API Key

Additional Options

Policy Configuration

Create the Policy Rules File

Basic Policy Rules

Advanced Policy Rules

Block Copyleft Licences

Flag High-Severity Vulnerabilities

Enforce Component Age Policies

Configuration File Structure

Complete Configuration Example

Environment Variables

Verification

Verify the Installation

Verify the SCANOSS Configuration

Troubleshooting

Common Issues

Java Memory Errors

API Connection Errors

Configuration File Not Found

Debug Mode

Next Steps

Documentation

Links

​Installation

​Prerequisites

​Windows Installation

​Configure Java Memory (Windows)

​macOS/Linux Installation

​SCANOSS Configuration

​Create the Configuration Directory

​Configure the SCANOSS Scanner

​Configuration Options

​API URL

​API Key

​Additional Options

​Policy Configuration

​Create the Policy Rules File

​Basic Policy Rules

​Advanced Policy Rules

​Block Copyleft Licences

​Flag High-Severity Vulnerabilities

​Enforce Component Age Policies

​Configuration File Structure

​Complete Configuration Example

​Environment Variables

​Verification

​Verify the Installation

​Verify the SCANOSS Configuration

​Troubleshooting

​Common Issues

​Java Memory Errors

​API Connection Errors

​Configuration File Not Found

​Debug Mode

​Next Steps

Installation

Prerequisites

Windows Installation

Configure Java Memory (Windows)

macOS/Linux Installation

SCANOSS Configuration

Create the Configuration Directory

Configure the SCANOSS Scanner

Configuration Options

API URL

API Key

Additional Options

Policy Configuration

Create the Policy Rules File

Basic Policy Rules

Advanced Policy Rules

Block Copyleft Licences

Flag High-Severity Vulnerabilities

Enforce Component Age Policies

Configuration File Structure

Complete Configuration Example

Environment Variables

Verification

Verify the Installation

Verify the SCANOSS Configuration

Troubleshooting

Common Issues

Java Memory Errors

API Connection Errors

Configuration File Not Found

Debug Mode

Next Steps