> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

```mermaid theme={null}
graph TD
    ToolChoice{Choose Your Tool}

    ToolChoice -->|Command Line| InstallPY[Install SCANOSS-PY]
    ToolChoice -->|Desktop GUI| InstallCC[Install SCANOSS-CC]

    InstallPY --> ScanPY[Scan with SCANOSS-PY]
    InstallCC --> ScanCC[Scan with SCANOSS-CC]

    ScanPY --> Results[Understanding the Results]
    ScanCC --> Results

    Results --> DeclareChoice{Declare Components}

    DeclareChoice -->|GUI Workflow| DeclareCC[SCANOSS-CC]
    DeclareChoice -->|Manual Workflow| DeclarePY[SCANOSS-PY]

    DeclareCC --> Validate[Validate All Components Declared]
    DeclarePY --> Validate

    Validate --> PreCommit[Setup Pre-Commit Hooks]

    PreCommit --> GitCommit{Git Commit}

    GitCommit -->|Undeclared Found| Blocked[Review & Declare Missing Components]
    GitCommit -->|All Declared| Success[Code Ready to Push]

    Blocked --> DeclareChoice

    style ToolChoice fill:#42A5F5,stroke:#1976D2,stroke-width:3px,color:#fff
    style InstallPY fill:#26A69A,stroke:#00897B,stroke-width:2px,color:#fff
    style InstallCC fill:#26A69A,stroke:#00897B,stroke-width:2px,color:#fff
    style ScanPY fill:#AB47BC,stroke:#8E24AA,stroke-width:2px,color:#fff
    style ScanCC fill:#AB47BC,stroke:#8E24AA,stroke-width:2px,color:#fff
    style Results fill:#FF9800,stroke:#F57C00,stroke-width:3px,color:#fff
    style DeclareChoice fill:#42A5F5,stroke:#1976D2,stroke-width:2px,color:#fff
    style DeclareCC fill:#EC407A,stroke:#C2185B,stroke-width:2px,color:#fff
    style DeclarePY fill:#EC407A,stroke:#C2185B,stroke-width:2px,color:#fff
    style Validate fill:#FFA726,stroke:#F57C00,stroke-width:2px,color:#fff
    style PreCommit fill:#7E57C2,stroke:#5E35B1,stroke-width:3px,color:#fff
    style GitCommit fill:#42A5F5,stroke:#1976D2,stroke-width:2px,color:#fff
    style Blocked fill:#EF5350,stroke:#E53935,stroke-width:3px,color:#fff
    style Success fill:#66BB6A,stroke:#43A047,stroke-width:3px,color:#fff

    click ToolChoice "#install-scanoss-py-and-scanoss-cc" "Jump to Installation"
    click InstallPY "#install-scanoss-py" "Jump to SCANOSS-PY Installation"
    click InstallCC "#install-scanoss-cc" "Jump to SCANOSS-CC Installation"
    click ScanPY "#using-scanoss-py-command-line" "Jump to SCANOSS-PY Scan"
    click ScanCC "#using-scanoss-cc-desktop-gui" "Jump to SCANOSS-CC Scan"
    click Results "#understanding-the-results" "Jump to Results Section"
    click DeclareChoice "#declare-components" "Jump to Declare Components"
    click DeclareCC "#scanoss-cc" "Jump to SCANOSS-CC Declare"
    click DeclarePY "#scanoss-py" "Jump to SCANOSS-PY Declare"
    click Validate "/en/latest/poc/local-testing#declare-components" "Jump to Declare Components"
    click PreCommit "#setup-pre-commit-hooks" "Jump to Pre-Commit Hooks"
    click GitCommit "/en/latest/poc/local-testing#commit-changes" "Jump to Commit Changes"
```

## Prerequisites

Before you begin, ensure you have:

* [Python 3.9](https://www.python.org/) or later
* [Git](https://git-scm.com/) 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:
>
> ```bash theme={null}
> python3 --version
> git --version
> ```

## Install SCANOSS-PY and SCANOSS-CC

SCANOSS provides the following tools for local testing:

* [SCANOSS-PY](https://github.com/scanoss/scanoss.py)
* [SCANOSS-CC](https://github.com/scanoss/scanoss.cc)

### Install SCANOSS-PY

Open your terminal or command prompt, then run:

**Standard Installation:**

```bash theme={null}
pip3 install scanoss
```

**Verify Installation:**

```bash theme={null}
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:**

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/scanoss/scanoss.cc/main/scripts/install.sh | bash
```

**Windows (PowerShell as Administrator):**

```powershell theme={null}
irm https://raw.githubusercontent.com/scanoss/scanoss.cc/main/scripts/install-windows.ps1 | iex
```

**Verify Installation:**

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
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:
>
> ```bash theme={null}
> # 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:**

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
scanoss-cc configure --apiUrl https://api.scanoss.com --key $SCANOSS_API_KEY
```

**Launch SCANOSS-CC:**

```bash theme={null}
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:

```bash theme={null}
<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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
scanoss-py inspect undeclared -i results.json
```

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
scanoss-py scan --key $SCANOSS_API_KEY --settings scanoss.json -o results.json .
```

**Step 4: Validate Compliance**

Verify all components are properly declared:

```bash theme={null}
scanoss-py inspect undeclared -i results.json
```

Success output:

```bash theme={null}
0 undeclared component(s) were found.
```

Learn more about the [SCANOSS Settings file format](license-dataset/scanoss-settings) and [SCANOSS-PY](license-dataset/snippet-detection/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:

```bash theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
pre-commit validate-config
```

This confirms your configuration file is valid.

### Install the Hook

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

```bash theme={null}
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:

```bash theme={null}
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:

```gitignore theme={null}
# 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:

```bash theme={null}
# .env
SCANOSS_API_KEY=your_api_key_here
SCANOSS_DEBUG=true
```

**Important:** Also add `.env` to your `.gitignore` to avoid committing sensitive API keys:

```gitignore theme={null}
# 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:**

```bash theme={null}
git add .
```

**Attempt a commit:**

```bash theme={null}
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:

```bash theme={null}
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](local-testing#understanding-the-results) to understand what each field means

2. **Declare the components**: Follow the [Declare Components](local-testing#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:

   ```bash theme={null}
   git add scanoss.json
   ```

4. **Retry your commit**: Now retry the commit with your updated declarations:
   ```bash theme={null}
   git commit -m "Add new features"
   ```

### Declared Components

If all components are declared the commit proceeds normally:

```bash theme={null}
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](?assistant=open)