Desktop Integration

Prerequisites

Before you begin, ensure you have:

Python 3.9 or later
Git installed and configured
Project directory to scan
(Optional) SCANOSS API key for enterprise features

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:

pip3 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 results.json .

The results are saved to the location you specify with the -o option when running the scan. 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 --settings scanoss.json -o 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 generates a results.json file containing all detected open source code in your project. Component Identification:

component: Name of the detected open source component
file: The file in your project where open source code was detected
file_hash: Unique identifier for the exact file content

Match Details:

id: Match type - how the code was detected:
- snippet - Part of a file matches known open source code
- file - An entire file matches a known component
matched: Similarity percentage
lines: Line range in your file where the match was found
oss_lines: Corresponding line range in the original open source component
status: Current state of the finding:
- pending - Newly detected, needs your review
- identified - Properly documented in your scanoss.json

Component Information:

vendor: Component maintainer or organisation
version: Detected version
latest: Most recent available version
url: Repository URL
purl: Package URL
release_date: When this version was released

License Information:

name: License identifier
copyleft: Whether derivative works must use the same license
patent_hints: Whether license contains patent clauses
source: Where license was detected:
- component_declared - From the component’s metadata
- file_spdx_tag - From SPDX tags in the file
- license_file - From a LICENSE file
- file_header - From file header comments
incompatible_with: Licenses that conflict with this one
url: Link to SPDX license definition
checklist_url: Link to OSADL compliance checklist

Additional Data:

copyrights: Copyright statements found in the code
cryptography: Cryptographic algorithms detected
dependencies: Dependencies declared in the component
health: Repository health metrics
quality: Code quality scores
vulnerabilities: Known CVEs affecting this component

What This Means for You: Any finding marked as "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
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 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 with your scanoss.json settings:

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

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

scanoss-py inspect undeclared -i 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 scan results - do not commit
.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 your .gitignore to avoid committing sensitive API keys:

# SCANOSS scan results - do not commit
.scanoss/

# 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! Need help? Contact our AI assistant

Overview

License Dataset

Cryptography Dataset

Security Dataset

Process & Integrations

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

Overview

License Dataset

Cryptography Dataset

Security Dataset

Process & Integrations

​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

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