Sonarqube

---
name: sonarqube
description: "Expert agent for SonarQube and SonarCloud. Covers quality gates, quality profiles, Clean Code taxonomy, SonarScanner setup, branch analysis, PR decoration, Security Hotspots, taint analysis, and OWASP/CWE mappings. WHEN: \"SonarQube\", \"SonarCloud\", \"SonarLint\", \"quality gate\", \"quality profile\", \"sonar-project.properties\", \"SonarScanner\", \"Security Hotspot\", \"new code period\", \"clean code\"."
license: MIT
---

# SonarQube / SonarCloud

This skill covers SonarQube (self-managed) and SonarCloud (SaaS). It covers SonarQube Community through Enterprise editions, current releases (2026.x), and the LTA (Long-Term Active) release model. You also cover SonarLint for IDE integration.

## How to Approach Tasks

1. **Identify deployment type** -- SonarQube (self-managed) or SonarCloud (SaaS)? Edition matters for features (Community → Developer → Enterprise → Data Center).
2. **Identify the task type:**
   - **Setup/Scanner** -- Scanner configuration, CI/CD integration, sonar-project.properties
   - **Quality Gates** -- Gate definition, pass/fail conditions, new code period
   - **Quality Profiles** -- Rule activation, custom rules, language-specific settings
   - **Security** -- Vulnerability vs. Hotspot classification, taint rules, OWASP mappings
   - **Architecture** -- Load `references/architecture.md` for internals
3. **Apply version context** -- Some features (AI fix suggestions, taint across files) require specific editions or versions.

## Core Concepts

### Clean Code Taxonomy

SonarQube's quality classification framework (introduced to replace the older technical debt model):

**Four attributes of Clean Code:**
- **Consistency:** Code follows language and project conventions; predictable patterns
- **Intentionality:** Code is clear, well-named; intent is obvious without comments
- **Adaptability:** Code is modular, low coupling; easy to change without risk
- **Responsibility:** Code handles errors properly, protects data, respects security boundaries

**Issue categories under Clean Code:**
- **Reliability:** Bugs that will or likely will cause incorrect behavior
- **Security:** Vulnerabilities that can be exploited; Hotspots that require human review
- **Maintainability:** Code smells affecting adaptability and consistency
- **Coverage:** Test coverage gaps
- **Duplication:** Code duplication metrics

**Issue severity levels (post-2023 taxonomy):**
- **Blocker** → Likely to impact reliability/security in production
- **Critical** → May impact reliability/security
- **Major** → Low impact quality issue with significant developer effort to fix
- **Minor** → Low impact quality issue
- **Info** → Non-impactful quality observation

### Security Vulnerabilities vs. Security Hotspots

This distinction is critical for correct workflow:

**Security Vulnerability:**
- SonarQube is confident this is a real security issue
- Requires fixing (failing quality gate if active rule)
- Examples: SQL injection, XSS, path traversal confirmed by taint analysis
- Action: Fix the code

**Security Hotspot:**
- Code that is security-sensitive and requires human review
- Not necessarily a vulnerability — may be a legitimate use
- Examples: `Math.random()` use, `//NOSONAR`, hardcoded IP addresses
- Action: Review, then mark as "Safe" or "To Review" or convert to Vulnerability

**Why the distinction matters:** Hotspots have a separate workflow. They never block quality gates by themselves — only Vulnerabilities do. Teams should review Hotspots during code review, not treat them as build failures.

### Quality Gates

A quality gate is a set of conditions that must pass before code is considered release-ready. It answers: "Is this code good enough to ship?"

**Default Sonar Way gate conditions (New Code focus):**
- Security Rating = A (no new Vulnerabilities)
- Reliability Rating = A (no new Bugs)
- Maintainability Rating = A (no new Code Smells)
- Coverage ≥ 80% (on new code)
- Duplicated Lines (%) ≤ 3%

**Configuring quality gates:**

In SonarQube UI: Administration → Quality Gates → Create / Edit

Key decisions:
- **New Code vs. Overall Code:** Best practice is to gate on new code only. This allows teams to address legacy debt gradually while preventing new issues.
- **Rating vs. Count:** Rating (A-E) is relative; Count (number of issues) is absolute. Rating is generally more appropriate.
- **Conditions to add:** Consider adding specific OWASP/CWE rules that are business-critical.

```
# Example quality gate policy:
New Code:
  Security Vulnerabilities: 0
  Bugs: 0
  Code Smells: Rating A (≤5% of new lines)
  Test Coverage: ≥ 70%
  Security Hotspots Reviewed: 100%
```

**Failure handling in CI:**
When a quality gate fails, the CI pipeline should fail. This requires `sonar.qualitygate.wait=true` in scanner properties.

### New Code Period

The "new code period" defines what SonarQube considers "new" for quality gate evaluation:

- **Previous version** (default): Code changed since the last project version was set. Set version via `sonar.projectVersion` in scanner.
- **Number of days:** Rolling window (e.g., last 30 days of changes).
- **Specific date:** Fixed baseline date.
- **Reference branch** (Developer Edition+): Compare against a branch (e.g., main).

**Best practice:** Use "Reference branch" for feature branch analysis (compare to main). Use "Previous version" for release pipeline gates.

### Quality Profiles

A quality profile is the set of rules activated for a specific language. Every project uses one quality profile per language.

**Built-in profiles:**
- **Sonar way:** The recommended profile. Conservative, well-tuned defaults.
- **Sonar way for Security:** More security rules activated (available in some editions).

**Custom profiles:**
1. Inherit from "Sonar way" (recommended) — you get future rule updates
2. Activate additional rules as needed
3. Change rule severity for organizational context
4. Deactivate rules that generate persistent false positives for your codebase

**Rule parameters:** Many rules have configurable parameters. Example: `java:S5131` (XSS) has configurable sanitizer methods — add your custom sanitizer.

```
Administration → Quality Profiles → [Language] → [Profile] → Activate Rules
```

### SonarScanner Setup

#### Project Configuration (sonar-project.properties)

```properties
# Required
sonar.projectKey=my-org_my-project
sonar.projectName=My Project
sonar.sources=src

# Optional but recommended
sonar.projectVersion=1.0.0
sonar.sourceEncoding=UTF-8
sonar.java.binaries=target/classes
sonar.tests=src/test
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml
sonar.exclusions=**/generated/**,**/vendor/**,**/*.min.js

# Quality gate
sonar.qualitygate.wait=true
```

#### CI Integration Examples

**GitHub Actions:**
```yaml
- name: SonarQube Scan
  uses: SonarSource/sonarqube-scan-action@master
  env:
    SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
    SONAR_HOST_URL: ${{ vars.SONAR_HOST_URL }}
  with:
    args: >
      -Dsonar.projectKey=${{ env.PROJECT_KEY }}
      -Dsonar.qualitygate.wait=true
      -Dsonar.pullrequest.key=${{ github.event.pull_request.number }}
      -Dsonar.pullrequest.branch=${{ github.head_ref }}
      -Dsonar.pullrequest.base=${{ github.base_ref }}
```

**Maven:**
```xml
<!-- pom.xml plugin -->
<plugin>
  <groupId>org.sonarsource.scanner.maven</groupId>
  <artifactId>sonar-maven-plugin</artifactId>
  <version>4.0.0.4121</version>
</plugin>
```
```bash
mvn verify sonar:sonar \
  -Dsonar.projectKey=my-project \
  -Dsonar.host.url=https://sonarqube.example.com \
  -Dsonar.token=$SONAR_TOKEN
```

**Gradle:**
```groovy
// build.gradle
plugins {
  id "org.sonarqube" version "5.1.0.4882"
}
sonar {
  properties {
    property "sonar.projectKey", "my-project"
    property "sonar.host.url", "https://sonarqube.example.com"
  }
}
```
```bash
./gradlew sonar -Dsonar.token=$SONAR_TOKEN
```

**.NET:**
```bash
dotnet sonarscanner begin \
  /k:"my-project" \
  /d:sonar.host.url="https://sonarqube.example.com" \
  /d:sonar.token="$SONAR_TOKEN"
dotnet build
dotnet sonarscanner end /d:sonar.token="$SONAR_TOKEN"
```

### Branch Analysis and PR Decoration

Branch analysis requires **Developer Edition or higher** (self-managed) or SonarCloud.

**Branch types:**
- **Main branch:** The primary tracked branch (defaults to `main` or `master`)
- **Long-lived branches:** Release branches, tracked independently (`release/v2.0`)
- **Short-lived branches:** Feature branches, compared against main, deleted after merge

**PR decoration:** SonarQube/SonarCloud posts analysis results as a PR comment and status check. Requires:
1. ALM (Application Lifecycle Management) integration configured in Administration → DevOps Platform Integrations
2. Token with PR read/write permissions
3. Scanner configured with PR parameters (`sonar.pullrequest.key`, `sonar.pullrequest.branch`, `sonar.pullrequest.base`)

### Taint Analysis

Available in SonarQube Enterprise Edition and SonarCloud.

Taint analysis tracks user-controlled data flows from sources to sinks, detecting injection vulnerabilities:

- **Sources:** HttpServletRequest, Flask request, Express req, Django request, etc.
- **Sinks:** JDBC execute, subprocess, eval, innerHTML assignment, etc.
- **Sanitizers:** Framework-specific validation and encoding functions

**OWASP/SANS/CWE rule mappings:**
SonarQube rules are tagged with security standards:
- `owasp-a3` → OWASP A03 Injection
- `cwe-89` → SQL Injection
- `sans-top25-risky` → SANS Top 25 Risky Resources

Filter rules by tag in Quality Profile to focus on specific standards.

### SonarCloud Specifics

SonarCloud is the SaaS version of SonarQube, hosted by Sonar.

**Key differences from self-managed:**
- No infrastructure management
- Automatic version updates
- Built-in GitHub/GitLab/Bitbucket/Azure DevOps integration (no ALM configuration needed)
- Free for public repositories; licensed per lines of code for private repositories
- Organization-based project organization (mirrors GitHub organizations)

**SonarCloud setup (GitHub):**
1. Install SonarCloud GitHub App
2. Create organization in SonarCloud (links to GitHub org)
3. Analyze projects — SonarCloud creates `sonar-project.properties` automatically
4. Add `SONAR_TOKEN` to GitHub secrets
5. Configure GitHub Actions workflow

### Suppressions and Exclusions

**Issue-level suppression (inline):**
```java
String query = "SELECT * FROM users WHERE id = " + userId; // NOSONAR
```
Use sparingly — NOSONAR suppresses ALL rules on that line.

**File/directory exclusions:**
```properties
sonar.exclusions=**/generated/**,**/test/**,**/*.min.js
sonar.coverage.exclusions=**/*Config*.java,**/*Application.java
```

**Issue-specific suppression in UI:**
Mark issues as "Won't Fix" or "False Positive" in the SonarQube interface. These persist across scans.

### Common Issues and Troubleshooting

**Quality gate always passes even with issues:**
- Check: Is `sonar.qualitygate.wait=true` set?
- Check: Is the project analyzing to the correct branch?
- Check: Are issues on "new code" or "overall code"? Gate may be configured for new code only.

**Missing coverage:**
- Ensure test framework generates XML report before scanner runs
- Verify `sonar.coverage.jacoco.xmlReportPaths` (Java) or equivalent points to correct path
- Coverage reports must exist before scanner reads them

**PR decoration not appearing:**
- Verify ALM integration configuration in Administration
- Check that scanner is passing the correct PR parameters
- Confirm token has PR comment/status write permissions

**Analysis takes too long:**
- Enable incremental analysis for PRs
- Exclude generated code and vendor directories
- For Java: ensure compiled classes are available (sonar.java.binaries)

## Edition Comparison

| Feature | Community | Developer | Enterprise | Data Center |
|---|---|---|---|---|
| Branch analysis | No (main only) | Yes | Yes | Yes |
| PR decoration | No | Yes | Yes | Yes |
| Taint analysis | Basic | Enhanced | Full | Full |
| Security reports | No | No | Yes (portfolio) | Yes |
| High availability | No | No | No | Yes |
| SonarCloud equivalent | Free tier | Team | Business | — |

## Reference Files

- `references/architecture.md` — SonarQube internals: analysis server, Compute Engine, database model, quality gate evaluation pipeline, SonarCloud architecture comparison