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

# SonarQube

> Integrate SCANOSS into your SonarQube analysis pipeline using the <a href="https://github.com/scanoss/scanoss-sonar-plugin" target="_blank">SCANOSS SonarQube Plugin</a>.

## Prerequisites

Before you begin, ensure you have the following:

* A running [SonarQube](https://www.sonarsource.com/products/sonarqube/) 10.x installation
* A valid SCANOSS API key (required only for premium features)
* The [SCANOSS SonarQube plugin](https://github.com/scanoss/scanoss-sonar-plugin): download the latest pre-built JAR from the [releases page](https://github.com/scanoss/scanoss-sonar-plugin/releases/latest)
* [Maven](https://maven.apache.org/) installed (required only if building the plugin from source)

## How It Works

The SCANOSS SonarQube plugin is a custom plugin built on the SCANOSS Java SDK. Once installed, it runs automatically as part of your SonarQube analysis. It is capable of:

* Scanning your source code for open-source components using **High Precision Snippet Matching (HPSM)**
* Ingesting SCANOSS settings from your `scanoss.json` file to control scan behaviour
* Reporting copyleft licence counts, copyright declarations, and vulnerability counts as SonarQube metrics
* Raising SonarQube issues for undeclared components not listed in your `scanoss.json` file

## Installation

### Step 1: Obtain the Plugin JAR

**Option A: Download the pre-built JAR (recommended)**

Download the latest release directly from the [GitHub releases page](https://github.com/scanoss/scanoss-sonar-plugin/releases/latest).

**Option B: Build from source**

If you prefer to build the plugin locally, run the following command from the repository root:

```bash theme={null}
mvn clean package
```

The compiled JAR will be output to `target/scanoss-sonar-plugin-VERSION.jar`.

### Step 2: Install the Plugin into SonarQube

Copy the JAR to your SonarQube `extensions/plugins/` directory:

```bash theme={null}
cp scanoss-sonar-plugin-VERSION.jar /path/to/sonarqube/extensions/plugins/
```

Replace `/path/to/sonarqube/` with the actual path to your SonarQube installation directory.

### Step 3: Restart SonarQube

Restart SonarQube to load the new plugin. Once the service has restarted, the SCANOSS plugin will be available for configuration.

## Configuration

### Plugin Parameters

In your SonarQube instance, navigate to the SCANOSS plugin settings and configure the following parameters:

| Parameter                    | Description                                                                                                                                                                  | Required | Default                 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------- |
| `Scan API URL`               | SCANOSS API endpoint. Format: `http(s)://host:port`                                                                                                                          | Optional | `https://api.osskb.org` |
| `Scan API Token`             | SCANOSS API authentication token                                                                                                                                             | Optional | —                       |
| `Custom Certificate Chain`   | PEM-encoded custom certificate chain                                                                                                                                         | Optional | —                       |
| `SCANOSS HPSM`               | Enable High Precision Snippet Matching (requires a Premium subscription)                                                                                                     | Optional | `false`                 |
| `SCANOSS Settings`           | Enable use of a SCANOSS settings file during scanning. See the [SCANOSS settings documentation](https://scanoss.readthedocs.io/projects/scanoss-py/en/latest/#settings-file) | Optional | `true`                  |
| `SCANOSS Settings File Path` | Path to the `scanoss.json` settings file used during scanning                                                                                                                | Optional | `scanoss.json`          |

> **Note:** The `Scan API URL` format description previously referenced `host:ip`. This has been corrected to `host:port`, as the second component of a URL authority is a port number, not an IP address.

## Running a Scan

### Using Docker

To run a SonarQube scan using the official SonarScanner CLI Docker image:

```bash theme={null}
export SONARQUBE_URL=host.docker.internal:9000
export PROJECT_KEY=[PROJECT_KEY]
export SONAR_TOKEN=[AUTH_TOKEN]

docker run \
    --rm \
    --add-host=host.docker.internal:host-gateway \
    -e SONAR_HOST_URL="http://${SONARQUBE_URL}" \
    -e SONAR_SCANNER_OPTS="-Dsonar.projectKey=${PROJECT_KEY}" \
    -e SONAR_TOKEN="${SONAR_TOKEN}" \
    -v "$(pwd):/usr/src" \
    sonarsource/sonar-scanner-cli -Dsonar.java.binaries=target
```

> **Note:** Replace `[PROJECT_KEY]` with your SonarQube project key and `[AUTH_TOKEN]` with a valid user-type authentication token.

## Policy Checks

The SCANOSS SonarQube plugin surfaces open-source compliance information through SonarQube metrics and issues.

### Reported Metrics

The following metrics are reported on every scan and are visible in the SonarQube project dashboard:

* **Copyleft Licence Count** — Number of components or snippets associated with copyleft licences
* **Copyright Declarations Count** — Number of copyright declarations detected in the codebase
* **Vulnerability Count** — Number of vulnerabilities detected in scanned components

### Reported Issues

* **Undeclared Components** — Components detected in the repository that are not declared in your `scanoss.json` file are raised as SonarQube issues

## Issue Detection Setup

To enable issue detection for undeclared components, you must configure a Quality Profile in SonarQube. Ensure your `scanoss.json` settings file is in place before proceeding.

### Step 1: Create a Quality Profile

1. Navigate to the **Quality Profiles** tab in SonarQube
2. In the desired language section, create a new profile named **SCANOSS Way**
3. Within the **SCANOSS Way** profile, add a new rule activation
4. Search for the **Undeclared Component** rule in the **SCANOSS Analyser** repository
5. Activate the **Undeclared Component** rule to add it to the profile

### Step 2: Assign the Quality Profile to Your Project

1. Navigate to your project in SonarQube
2. Go to **Project Settings → Quality Profiles**
3. Click **Add language**
4. Select the `text` language and assign the **SCANOSS Way** profile

## Extracting SCANOSS Data via the SonarQube Web API

SCANOSS metrics and issues can be queried programmatically using the SonarQube Web API. Authentication requires a user-type token — refer to the [SonarQube API documentation](https://next.sonarqube.com/sonarqube/web_api) for details on token generation.

### Authentication

Include the following header in all API requests:

```
Authorization: Bearer [TOKEN]
```

### Available Endpoints

**List all metrics** — Returns all available metrics. Use the `ps` parameter to increase page size when searching for SCANOSS-specific metrics:

```
GET https://{SONARQUBE_URL}/api/metrics/search?ps=500
```

**Retrieve SCANOSS metrics for a component** — Returns copyleft, copyright, and vulnerability counts for the specified project component:

```
GET https://{SONARQUBE_URL}/api/measures/component?component={PROJECT_KEY}&metricKeys=copyleft_license_count,copyright_count,vulnerability_count
```

**Search for undeclared component issues** — Returns all issues raised by the SCANOSS undeclared component rule:

```
GET https://{SONARQUBE_URL}/api/issues/search?rules=SCANOSS:UndeclaredComponent
```