Pre-Commit Hooks

The SCANOSS pre-commit hooks run just before your changes are committed, triggering automated scans to detect open-source components that have not been declared in your scanoss.json configuration. By catching undeclared components at commit time, issues are identified early in the development process rather than later in the pipeline.

Prerequisites

Before you begin, ensure the following are installed and configured:

Pre-Commit Framework: The framework that manages and runs the hooks.
SCANOSS Pre-Commit Plugin: The SCANOSS hook for detecting undeclared open-source components.
SCANOSS Code Compare (scanoss-cc): A CLI tool for reviewing and declaring detected components.
SCANOSS Settings (scanoss.json): The configuration file in which component declarations are managed. This file must exist at the root of your repository before the hook can validate against it.

Installation

pip install pre-commit

Getting Started

Configure the Hook

Create .pre-commit-config.yaml at the root of your repository:

repos:
  - repo: https://github.com/scanoss/pre-commit-hooks
    rev: v0.4.0 # Use the latest version from https://github.com/scanoss/pre-commit-hooks/releases
    hooks:
      - id: scanoss-check-undeclared-code

Verify Configuration

pre-commit validate-config

Install the Hook

pre-commit install

Test the Hook

# Stage files to test
git add .

# Run hook against all files
pre-commit run --all-files

Configuration

Environment Variables

The hook automatically loads variables from a .env file in your project root:

# .env
SCANOSS_API_KEY=your_api_key_here
SCANOSS_SCAN_URL=https://api.scanoss.com/scan/direct
HTTPS_PROXY=http://proxy.example.com:8080
SCANOSS_DEBUG=true

How It Works

Example Workflow

Given this project structure:

my-project/
├── src/
│   ├── scanner.py
│   └── utils.c
├── .env
└── .pre-commit-config.yaml

When you commit:

git add src/
git commit -m "Add new features"

The hook automatically:

Scans staged files for open-source components.
Compares detected components against the declarations in your scanoss.json file. A declaration is an explicit acknowledgement that a given open-source component is present and approved for use in your project.
Blocks the commit if any undeclared components are found.

Example Output

The following is an example of output produced when undeclared components are detected. File paths and package identifiers are truncated for brevity.

$ git commit -m "updating relevant files"
[WARNING] Unstaged files detected.
[INFO] Stashing unstaged files to ~/.cache/pre-commit/patch1763626421-7396.
SCANOSS Undeclared Check.................................................Failed
- hook id: scanoss-check-undeclared-code
- duration: 7.75s
- exit code: 1
- files were modified by this hook

SCANOSS detected 2 files containing potential open-source components:
┌──────────────┬─────────┬────────────┬─────────┬──────────────┬──────────────┐
│ File         │ Status  │ Match Type │ Matched │ Purl         │ License      │
├──────────────┼─────────┼────────────┼─────────┼──────────────┼──────────────┤
│ src/copyrig… │ pending │ snippet    │ 95%     │ pkg:github/… │ GPL-2.0-only │
├──────────────┼─────────┼────────────┼─────────┼──────────────┼──────────────┤
│ src/scanner… │ pending │ snippet    │ 96%     │ pkg:github/… │ MIT          │
└──────────────┴─────────┴────────────┴─────────┴──────────────┴──────────────┘
Run 'scanoss-cc' in the terminal to view the results in more detail.

[WARNING] Stashed changes conflicted with hook auto-fixes... Rolling back fixes...
[INFO] Restored changes from ~/.cache/pre-commit/patch1763626421-7396.

Note: The files were modified by this hook message indicates that the hook wrote scan result metadata to your working directory as part of its analysis. These modifications are rolled back if a conflict with unstaged changes is detected, as shown in the output above.

The commit is blocked until you take one of the following actions:

Declare the components in scanoss.json.
Run scanoss-cc in the terminal to review and declare the components interactively.
Remove the non-compliant or undeclared code.

Troubleshooting

Enable Debug Mode

Method 1: Environment Variable

export SCANOSS_DEBUG=true
git commit -m "test"

Method 2: .env File

# .env
SCANOSS_DEBUG=true

Method 3: Command-Line Argument

repos:
  - repo: https://github.com/scanoss/pre-commit-hooks
    rev: v0.4.0
    hooks:
      - id: scanoss-check-undeclared-code
        args: ["--debug"]

Documentation

Links

Prerequisites

Installation

Getting Started

Configure the Hook

Verify Configuration

Install the Hook

Test the Hook

Configuration

Environment Variables

How It Works

Example Workflow

Example Output

Troubleshooting

Enable Debug Mode

​Prerequisites

​Installation

​Getting Started

​Configure the Hook

​Verify Configuration

​Install the Hook

​Test the Hook

​Configuration

​Environment Variables

​How It Works

​Example Workflow

​Example Output

​Troubleshooting

​Enable Debug Mode

Prerequisites

Installation

Getting Started

Configure the Hook

Verify Configuration

Install the Hook

Test the Hook

Configuration

Environment Variables

How It Works

Example Workflow

Example Output

Troubleshooting

Enable Debug Mode