Pre-Commit Hooks

Automatically scan your code before commits with SCANOSS pre-commit hooks, ensuring transparency and compliance are built directly into your workflow.

The SCANOSS pre-commit hook runs just before your changes are committed, triggering automated checks to detect undeclared open-source components. This shift-left approach helps catch compliance issues early in the development process.

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:

1. Scans staged files for open-source components
2. Compares detected components against your scanoss.json declarations
3. Blocks the commit if undeclared components are found

Example Output

$ 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 Software:
┌──────────────┬─────────┬────────────┬─────────┬──────────────┬──────────────┐
│ 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.

The commit is blocked until you either:

1. Declare the components in scanoss.json
2. Run scanoss-cc in the terminal to review and declare the components
3. Remove the problematic 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']