Skip to main content

​
Prerequisites

Before you begin, ensure you have the following:

​
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. Option B: Build from source If you prefer to build the plugin locally, run the following command from the repository root: 
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: 
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:
ParameterDescriptionRequiredDefault
Scan API URLSCANOSS API endpoint. Format: http(s)://host:portOptionalhttps://api.osskb.org
Scan API TokenSCANOSS API authentication tokenOptional—
Custom Certificate ChainPEM-encoded custom certificate chainOptional—
SCANOSS HPSMEnable High Precision Snippet Matching (requires a Premium subscription)Optionalfalse
SCANOSS SettingsEnable use of a SCANOSS settings file during scanning. See the SCANOSS settings documentationOptionaltrue
SCANOSS Settings File PathPath to the scanoss.json settings file used during scanningOptionalscanoss.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: 
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 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