Desktop Integration

This guide walks you through setting up SCANOSS on your local development machine. You’ll learn how to scan your code, review findings, declare components and establish automated pre-commit checks.

Prerequisites

Before you begin, ensure you have:

• Python 3.9 or later
• Git installed and configured
• Project directory to scan
• 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:

• SCANOSS-PY
• SCANOSS-CC

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 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:

1. Click Run a new scan
2. Make sure the Directory to scan points to your project’s root folder
3. Click Start Scan
4. When the scan finishes, you should see Scan completed successfully! in the Console Output.
5. 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:

1. Review Results: View side-by-side code comparisons showing your code matched against the detected open source component
2. 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
   • Restore: Undo a previous decision and return the finding to a pending state
3. 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 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 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:

1. Review the results: The detailed findings are in .scanoss/results.json

   See Understanding the Results to understand what each field means

2. Declare the components: Follow the Declare Components section to properly declare the detected components

3. Check in scanoss.json: After updating scanoss.json with your component declarations, stage the file:

   git add scanoss.json
   

4. 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