Desktop Integration - SCANOSS documentation

This walkthrough runs SCANOSS entirely on your own machine: scan a local project, review and declare the components it finds, then wire up a pre-commit hook so future commits are checked automatically. It’s Step 1 of the step-by-step path, covering the same scanning and declaration ground as the End-to-End Workflow, in more depth and without the GitHub Actions/Dependency-Track pieces.

Prerequisites

Before you begin, ensure you have:

Python 3.9 or later
Git installed and configured
Project directory to scan
A SCANOSS API key (optional, but recommended, since the free tier without one has lower usage limits)

You can check if Python or Git is already installed by running these commands in your terminal or command prompt:
python3 --version
git --version

Install SCANOSS-PY and SCANOSS-CC

SCANOSS provides the following tools for local testing:

Install SCANOSS-PY

Open your terminal or command prompt, then run: Standard Installation:

pip install scanoss

Verify Installation:

scanoss-py --version

If the installation worked, you’ll see the tool’s version number.

Install SCANOSS-CC

Open your terminal (macOS/Linux) or PowerShell (Windows), and run the one that applies to your system. macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/scanoss/scanoss.cc/main/scripts/install.sh | bash

Windows (PowerShell as Administrator):

irm https://raw.githubusercontent.com/scanoss/scanoss.cc/main/scripts/install-windows.ps1 | iex

Verify Installation:

scanoss-cc --version

If successful, you’ll see the SCANOSS-CC version number printed in your terminal.

Configure API Access

While SCANOSS works without an API key, the free tier has usage limitations. To avoid hitting these limits, configure your API key before scanning.

Add Your API Key

Add your API key to your shell profile:

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export SCANOSS_API_KEY=your_api_key_here' >> ~/.bashrc
source ~/.bashrc

scanoss-py automatically detects the SCANOSS_API_KEY environment variable when set. You can also pass the API key directly with --key $SCANOSS_API_KEY when running either tool.

Navigate to Your Project Directory

In your terminal navigate to the project you want to scan:

cd /path/to/your/project

Ensure you’re in the root directory of your project where you’d typically find files like package.json, pom.xml, requirements.txt, or similar project configuration files.

You can confirm you’re in the right place by running:
# macOS / Linux
ls
# Windows
dir

Run Your First Scan

You can run scans using either SCANOSS-PY (command-line) or SCANOSS-CC (desktop GUI).

Using SCANOSS-PY (Command Line)

Basic Scan:

scanoss-py scan --key $SCANOSS_API_KEY -o .scanoss/results.json .

The results are saved to the location you specify with the -o option when running the scan. Writing to .scanoss/ keeps results out of your project root, matching what SCANOSS-CC does automatically and what the .gitignore entry you’ll add later expects. If you’d like to include declared dependencies from manifest files (e.g. package.json, requirements.txt etc.), install the scancode-toolkit dependency and use the -D flag:

pip install scancode-toolkit
scanoss-py scan --key $SCANOSS_API_KEY -D -o .scanoss/results.json .

Using SCANOSS-CC (Desktop GUI)

Before scanning, configure your API credentials:

scanoss-cc configure --apiUrl https://api.scanoss.com --key $SCANOSS_API_KEY

Launch SCANOSS-CC:

scanoss-cc

Follow the GUI Workflow:

Click Run a new scan
Make sure the Directory to scan points to your project’s root folder
Click Start Scan
When the scan finishes, you should see Scan completed successfully! in the Console Output.
Exit the application

The scan results are stored inside your project folder in a hidden directory named .scanoss. Look for the file:

<your-project>/.scanoss/results.json

Understanding the Results

After running a scan, SCANOSS writes a results.json file describing every detected open-source component: which file it matched, how confident the match is (matched, a similarity percentage), its licence, and its current status:

pending - newly detected, needs your review
identified - already declared in your scanoss.json

For the full field-by-field schema (vulnerabilities, cryptography, copyrights, dependencies, and more), see Understanding Scan Results.

What this means for you: any finding marked "status": "pending" requires a decision. Review the match and decide:

Include it in your scanoss.json to declare intentional use
Dismiss it if it’s a false positive or your own code
Replace it if the license is incompatible with your project

Declare Components

After reviewing scan results, you need to make decisions about detected components. Choose your workflow based on how you scanned:

SCANOSS-CC

Make sure you’re in your project directory where the scan results are located:

cd /path/to/your/project

SCANOSS-CC will automatically load results from .scanoss/results.json in the current directory. Launch SCANOSS-CC to review results and make decisions interactively:

scanoss-cc

In the SCANOSS-CC interface:

Review Results: View side-by-side code comparisons showing your code matched against the detected open source component
Make Decisions: Use the action icons at the top of the dashboard to:
- Include: Accept and declare the component as an intentional dependency
- Dismiss: Mark as false positive or your own code
- Replace: Flag for replacement with alternative code or different license
- Skip: Exclude a file, folder, or file extension from future scans entirely (takes effect on your next scan)
- Restore: Undo a previous decision and return the finding to a pending state
Save Changes: Your decisions are saved to scanoss.json at your project root. Future scans will remember these decisions.

Keyboard Shortcuts: View all shortcuts by selecting Help → Keyboard Shortcuts for faster decision-making.

SCANOSS-PY

You need to manually create a scanoss.json file at your project root. Step 1: Identify Undeclared Components Use the inspect command to find components that need to be declared:

scanoss-py inspect undeclared -i .scanoss/results.json

This will output suggested components to add to your scanoss.json:

{
  "bom": {
    "include": [
      {
        "purl": "pkg:github/scanoss/engine"
      },
      {
        "purl": "pkg:github/scanoss/scanoss.py"
      }
    ]
  }
}

Step 2: Create scanoss.json Take the suggested output from Step 1 and create a complete scanoss.json file in your project root directory (the same directory you scanned). Add the self section with your project information and expand the bom.include entries with comments:

{
  "self": {
    "name": "my-project",
    "license": "MIT",
    "description": "My project"
  },
  "bom": {
    "include": [
      {
        "purl": "pkg:github/scanoss/engine",
        "comment": "SCANOSS engine for code analysis"
      },
      {
        "purl": "pkg:github/scanoss/scanoss.py",
        "comment": "SCANOSS Python SDK for API integration"
      }
    ]
  }
}

Step 3: Rescan with Configuration Run the scan again. SCANOSS-PY automatically picks up scanoss.json from the scanned directory, so your declarations are applied without needing to reference it explicitly:

scanoss-py scan --key $SCANOSS_API_KEY -o .scanoss/results.json .

Step 4: Validate Compliance Verify all components are properly declared:

scanoss-py inspect undeclared -i .scanoss/results.json

Success output:

0 undeclared component(s) were found.

Learn more about the SCANOSS Settings file format and SCANOSS-PY.

Setup Pre-Commit Hooks

SCANOSS Pre-Commit Hooks ensures that before you push any code to your repository, SCANOSS automatically checks for undeclared open source components. This shift-left approach helps you catch compliance issues early in the development process, before code reaches your team or production.

Install Pre-Commit Framework

Open your terminal or command prompt and install the pre-commit framework:

pip install pre-commit

Configure the Hook

Navigate to your project root directory and create a new file named .pre-commit-config.yaml. Add the following configuration to the file:

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: In your terminal, navigate to your project directory and run:

pre-commit validate-config

This confirms your configuration file is valid.

Install the Hook

In your terminal, while still in your project directory, run:

pre-commit install

This installs the hook into your .git/hooks directory. Once installed, the hook runs automatically before every git commit. You should see output like:

pre-commit installed at .git/hooks/pre-commit

Configure .gitignore

Before committing, you need to configure your .gitignore file to exclude SCANOSS generated files from version control. Open your .gitignore file (or create one if it doesn’t exist) in your project root and add:

# SCANOSS temporary files and cache
*.wfp
.scanoss/

Save the .gitignore file in your project root directory.

Configure Environment Variables (Optional)

Open your IDE or text editor and create a new file named .env in your project root directory. Add your configuration:

# .env
SCANOSS_API_KEY=your_api_key_here
SCANOSS_DEBUG=true

Important: Also add .env to the .gitignore file you created earlier, to avoid committing sensitive API keys:

# Environment variables - do not commit
.env

Save the file in your project root directory. The hook will automatically load these variables during execution.

Commit Changes

Now test the hook to ensure it’s working correctly. Stage your files:

git add .

Attempt a commit:

git commit -m "Testing Pre-Commit Hooks"

The hook runs automatically and scans your staged files.

Undeclared Components

If undeclared components are found, the commit will be blocked and you’ll see a summary table in your terminal:

SCANOSS Undeclared Check.................................................Failed
- hook id: scanoss-check-undeclared-code
- duration: 7.75s
- exit code: 1

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.

What happened: The pre-commit hook generated a summary table in your terminal and created a detailed scan results file at .scanoss/results.json in your project directory. To resolve this: The commit is blocked until you review the findings and declare the components. Follow the same workflow mentioned earlier:

Review the results: The detailed findings are in .scanoss/results.json See Understanding the Results to understand what each field means
Declare the components: Follow the Declare Components section to properly declare the detected components
Check in scanoss.json: After updating scanoss.json with your component declarations, stage the file:
git add scanoss.json
Retry your commit: Now retry the commit with your updated declarations:
git commit -m "Add new features"

Declared Components

If all components are declared the commit proceeds normally:

SCANOSS Undeclared Check.................................................Passed
- hook id: scanoss-check-undeclared-code
- duration: 5.32s

[main 1a2b3c4] Add new features
 2 files changed, 45 insertions(+), 3 deletions(-)

Your code is now safe to push to the repository!

What’s Next

With local scanning, declaration, and pre-commit checks in place, the next step is enforcing the same checks automatically on every push and pull request: CI/CD Integration. Need help? Contact our AI assistant

​Prerequisites

​Install SCANOSS-PY and SCANOSS-CC

​Install SCANOSS-PY

​Install SCANOSS-CC

​Configure API Access

​Add Your API Key

​Navigate to Your Project Directory

​Run Your First Scan

​Using SCANOSS-PY (Command Line)

​Using SCANOSS-CC (Desktop GUI)

​Understanding the Results

​Declare Components

​SCANOSS-CC

​SCANOSS-PY

​Setup Pre-Commit Hooks

​Install Pre-Commit Framework

​Configure the Hook

​Install the Hook

​Configure .gitignore

​Configure Environment Variables (Optional)

​Commit Changes

​Undeclared Components

​Declared Components

​What’s Next

Prerequisites

Install SCANOSS-PY and SCANOSS-CC

Install SCANOSS-PY

Install SCANOSS-CC

Configure API Access

Add Your API Key

Navigate to Your Project Directory

Run Your First Scan

Using SCANOSS-PY (Command Line)

Using SCANOSS-CC (Desktop GUI)

Understanding the Results

Declare Components

SCANOSS-CC

SCANOSS-PY

Setup Pre-Commit Hooks

Install Pre-Commit Framework

Configure the Hook

Install the Hook

Configure .gitignore

Configure Environment Variables (Optional)

Commit Changes

Undeclared Components

Declared Components

What’s Next