SonarQube

SonarQube is a self-hosted (or SaaS, as SonarQube Cloud) platform that runs static analysis and code-quality measurement under one roof, and enforces both through a single pass/fail mechanism called a Quality Gate. It didn't start as a security tool — it started in 2008 as "Sonar," a Java code-quality dashboard — and that ancestry is still visible in how it organizes findings: Bugs, Code Smells, and test coverage sit next to Vulnerabilities and Security Hotspots in the same project view, scored by the same gate. That's the whole pitch, and also the whole tradeoff this page works through: one governance layer for two different concerns, at the cost of a dataflow engine that's shallower than a security-only tool like CodeQL.

What SonarQube is, and the problem it solves

☺ Like you're 10: It's one dashboard that grades your code on two report cards at once — is it safe, and is it well-built — and refuses to let a bad enough grade on either one slip through.

SonarQube is developed by Sonar (formerly SonarSource), and it ships in two forms: a self-hosted server product — historically called SonarQube, recently reorganized under the name SonarQube Server — and a SaaS product, SonarQube Cloud (the renamed successor to SonarCloud). Both run the same underlying analysis engines and the same Quality Gate model; the difference is who operates the server and the database behind it. This page focuses on the self-hosted product, because that's the deployment shape most DevSecOps pipelines actually own and configure.

The problem it solves is consolidation. Without it, a team assembling equivalent coverage needs a linter for code smells, a coverage tool, a duplication checker, and a separate SAST engine — four tools, four dashboards, four different ideas of what "pass" means. SonarQube's Quality Gate collapses all of that into one evaluated set of conditions against one analysis, so "can this merge" is answered by one system instead of reconciling four. The cost of that consolidation is depth: because SonarQube's rule engine has to stay broad enough to cover dozens of languages and code-quality dimensions at once, its interprocedural taint tracking doesn't go nearly as deep as an engine built to do only one job, like CodeQL's whole-program relational database. SAST, DAST & SCA already named SonarQube alongside Semgrep, CodeQL, and Checkmarx as a SAST engine in the abstract; this page is what that abstraction looks like running in production.

Architecture: Scanner, Web Server, Compute Engine, and the database

☺ Like you're 10: One small program runs where your code lives and reads it; a separate, always-on server does the actual thinking afterward and remembers every past result.

Unlike Semgrep's stateless, no-server CLI (see Semgrep), SonarQube is a persistent, three-tier server product, and understanding its four moving parts explains most of its operational behavior — including some of its sharpest gotchas below.

• Scanner — a small client that runs where your code already is: a CI job, or a developer's machine. It doesn't analyze security rules deeply itself; it walks the source tree, computes raw metrics and syntax-level facts, and packages everything into a binary analysis report, which it uploads to the server and then exits. There are several scanner flavors for different build systems: the plain SonarScanner CLI, SonarScanner for Maven, SonarScanner for Gradle, and SonarScanner for .NET (dotnet-sonarscanner, which wraps a real begin/build/end cycle around the actual C# compiler, because C#'s analysis needs real compiler output to work from).
• Web Server — the always-on process that serves the UI and the Web API, accepts uploaded analysis reports, and queues them for processing. This is also where a developer, a reviewer, or a CI job reads back results — including the Quality Gate status.
• Compute Engine — a background worker inside the server process that pulls a queued report and does the actual heavy lifting: running the language-specific rule engines against it, computing every metric, and evaluating the Quality Gate. This runs asynchronously, after the scanner has already uploaded its report and exited — which is the root cause of the single most common SonarQube CI surprise, covered in the gotchas section below.
• Database — persistent storage for everything: issues, measures, Quality Gate history, users, and Quality Profiles. Production deployments require an external database — PostgreSQL is Sonar's recommended choice, with Microsoft SQL Server and Oracle also supported; the bundled embedded H2 database is for evaluation only and is not a supported production target. Alongside it, SonarQube also runs a single-node, embedded Elasticsearch instance purely to index issues for fast search inside the UI — it isn't meant to be reachable from outside the server, and it's a common source of first-install failures on Linux, also covered below.

Notice the gap between the scanner exiting and the webhook firing: the CI job that ran the scanner has usually already moved on to its next step by the time the Compute Engine has actually finished. That gap is deliberate architecture, not a bug — but it's also exactly the shape of the gotcha covered in the Quality Gate section next.

Quality Profiles vs. Quality Gates — the ruleset and the pass/fail line

☺ Like you're 10: One list decides which rules even apply to your code; a completely separate, shorter list decides whether today's grade is good enough to pass.

These two nouns get conflated constantly, and they answer different questions. A Quality Profile is the set of active rules for one language — hundreds of individual checks, each of which can be enabled, disabled, or have its severity adjusted. Every project is assigned one Quality Profile per language it contains (the built-in default is called "Sonar way"). A profile answers "what counts as a finding at all." A Quality Gate is a much smaller set of pass/fail conditions evaluated against the metrics an analysis produced — not a list of rules, a list of thresholds. A gate answers "given everything the profile found, does this analysis clear the bar." You tune a profile to control noise; you tune a gate to control what actually blocks a merge, and they are configured, and thought about, completely separately.

SonarQube's default gate — "Sonar way" — deliberately scopes almost every condition to the New Code period rather than the whole repository, under the philosophy Sonar calls Clean as You Code: don't demand a legacy codebase retroactively fix years of pre-existing debt before a single PR can merge, but do refuse to let today's change add to it. "New Code" itself is a configurable definition — commonly "since the previous version," a fixed number of days, or a specific reference branch — and getting that definition wrong is one of the gotchas below.

Treat those exact numbers as illustrative — Sonar has adjusted default thresholds across releases, so confirm the current default against your installed version's own Quality Gate settings before you cite one on the exam or in a design review. What won't change is the shape: five of six conditions are computed automatically from the analysis, and the sixth — Security Hotspots Reviewed — is the one condition on the whole default gate that measures human attention rather than a code metric, which is the thread the next section pulls on.

# sonar-project.properties — lives at the repo root
sonar.projectKey=acme_checkout
sonar.projectName=Checkout Service
sonar.sources=src
sonar.tests=test
sonar.exclusions=**/vendor/**,**/generated/**,**/*.pb.go
sonar.coverage.exclusions=**/*_test.go,**/migrations/**
sonar.python.coverage.reportPaths=coverage.xml
sonar.host.url=${env.SONAR_HOST_URL}
sonar.token=${env.SONAR_TOKEN}
# make the SCANNER ITSELF fail (non-zero exit) if the gate fails —
# without this, the scanner step is green even on a failing gate
sonar.qualitygate.wait=true
sonar.qualitygate.timeout=300

The Security Hotspot workflow: human review, not an auto-fail

☺ Like you're 10: A Vulnerability is the engine saying "this is dangerous, full stop." A Security Hotspot is the engine saying "I found something security-sensitive here, but only a person can tell if it's actually a problem."

This is the distinction the brief for this page is really about, and it's a genuine, deliberate design choice — not a lesser or half-implemented category. SonarQube splits security findings into two kinds, and they behave completely differently:

The mechanism matters as much as the category label. A Vulnerability contributes to the Security Rating metric the moment analysis finishes — no human has to look at anything for a critical SQL injection finding to drag New Code's Security Rating from A to E and fail the gate outright. A Security Hotspot contributes to a completely different metric, Security Hotspots Reviewed (%), which only asks whether a person opened it and recorded a decision — reviewing a hotspot and marking it SAFE satisfies the gate exactly as well as fixing it does, because the gate's job was never to judge the hotspot itself, only to make sure it didn't get silently ignored.

# Flags as a Security Hotspot, NOT an auto-failing Vulnerability —
# a wide-open CORS policy is a real risk on some endpoints and
# a deliberate, correct choice on a genuinely public one.
@app.route("/api/public-status")
def public_status():
    resp = make_response(jsonify(status="ok"))
    resp.headers["Access-Control-Allow-Origin"] = "*"   # <- Security Hotspot
    return resp

A reviewer opens that hotspot, sees the endpoint returns nothing but a static status string with no auth context anywhere near it, and marks it Safe with a one-line comment — "public health-check endpoint, no sensitive data, intentional." That review is a permanent, auditable decision attached to that exact line, which is precisely the kind of evidence Compliance as Code at Scale covers turning into artifacts an auditor can actually read. Contrast that with the SQL-concatenation Vulnerability example this course has used repeatedly (see Static Analysis & Secrets Detection) — there is no "mark it safe" option for a Vulnerability with that shape, because the engine isn't asking for a judgment call, it's reporting one it already made.

# list open hotspots for a project via the Web API
$ curl -u "$SONAR_TOKEN:" \
    "$SONAR_HOST_URL/api/hotspots/search?projectKey=acme_checkout&status=TO_REVIEW"

# record a review decision — SAFE, with a required justification
$ curl -u "$SONAR_TOKEN:" -X POST \
    "$SONAR_HOST_URL/api/hotspots/change_status" \
    -d "hotspot=AYhk3md...&status=REVIEWED&resolution=SAFE" \
    -d "comment=Public health-check endpoint, no sensitive data, intentional."

Config, and wiring the gate into CI

☺ Like you're 10: Three files do the real work: one tells the scanner what to look at, one runs it in the pipeline, and one actually checks whether the gate passed before letting the merge through.

Beyond sonar-project.properties above, a Maven or Gradle project usually skips a standalone properties file and drives the same settings from the build tool instead, so the same values live next to everything else in the build:

<!-- pom.xml — excerpt -->
<properties>
  <sonar.projectKey>acme_checkout</sonar.projectKey>
  <sonar.coverage.jacoco.xmlReportPaths>
    target/site/jacoco/jacoco.xml
  </sonar.coverage.jacoco.xmlReportPaths>
</properties>
<!-- then: mvn verify sonar:sonar -->

A CI pipeline needs two separate steps, not one — run the scan, then separately confirm the gate, because (as the warning above covers) those two things finish at different times:

# .github/workflows/sonar.yml — illustrative; pin real action versions
# from the Marketplace rather than copying tags verbatim
jobs:
  sonar-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }   # SonarQube wants full git history, not a shallow clone
      - name: SonarQube Scan
        uses: sonarsource/sonarqube-scan-action@v2
        env:
          SONAR_HOST_URL: ${{ secrets.SONAR_HOST_URL }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
      - name: Quality Gate Check
        uses: sonarsource/sonarqube-quality-gate-action@master
        timeout-minutes: 5   # polls report-task.txt's ceTaskUrl until the gate resolves
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

That second step — not the scan step — is the one branch protection should list as a required status check. A team that only requires the scan step green is exactly reproducing the gotcha from the previous section, just with an extra layer of GitHub Actions between them and the mistake.

Day-to-day commands

☺ Like you're 10: Run the scanner locally to see what it'll find before you push, then use the same API your CI uses to check or override the result by hand.

# local, exploratory run — good before opening a PR
$ sonar-scanner \
    -Dsonar.host.url=https://sonarqube.acme.internal \
    -Dsonar.token=$SONAR_TOKEN

# check a project's current Quality Gate status directly
$ curl -u "$SONAR_TOKEN:" \
    "$SONAR_HOST_URL/api/qualitygates/project_status?projectKey=acme_checkout" | jq .

# pull the raw issues list (vulnerabilities, bugs, code smells) — useful for
# feeding a triage platform like DefectDojo, or a script of your own
$ curl -u "$SONAR_TOKEN:" \
    "$SONAR_HOST_URL/api/issues/search?componentKeys=acme_checkout&types=VULNERABILITY"

# export a Quality Profile as XML — review it in a PR like any other config
$ curl -u "$SONAR_TOKEN:" \
    "$SONAR_HOST_URL/api/qualityprofiles/backup?qualityProfile=Sonar%20way&language=py" \
    -o sonar-way-python-backup.xml

For feedback earlier than any of this, SonarQube for IDE (formerly SonarLint) is the free editor plugin that runs a subset of the same rule engine locally, as you type, connected to your team's actual Quality Profile — the same "feedback in the IDE as the developer types" idea named as a top-maturity DSOMM behavior in Secure SDLC Gates & the DevSecOps Maturity Model.

Community Edition vs. the commercial tiers

☺ Like you're 10: The free version does real security and quality checking, all on its own; paying unlocks more languages of that checking, deeper analysis, and reports built for someone whose job is auditing many teams at once.

SonarQube Server ships in editions that stack: Community, Developer, Enterprise, and Data Center, each a superset of the one before it, alongside the separate SaaS product, SonarQube Cloud. Sonar has renamed and repackaged this lineup more than once — including a 2024 relicensing of Community Edition away from LGPLv3 to the Sonar Source-Available License (SSAL), which is source-available rather than an OSI-approved open-source license — so treat the table below as the shape of the offering, and confirm current names, licensing terms, and exact feature boundaries on Sonar's own edition-comparison page before it factors into a procurement or compliance decision.

The practical decision most teams actually face isn't "which tier" in the abstract — it's whether Community Edition's single-branch, narrower-ruleset shape is enough for how the team actually works. A team that only ever gates pull requests against a stable default branch often never notices the branch-analysis ceiling; a team that wants long-lived feature branches independently tracked in the dashboard hits it immediately. And a team that needs secrets or IaC scanning inside the same governance layer as its code Quality Gate is shopping for Advanced Security specifically — not for SonarQube's SAST rules, which Community Edition already covers — which is worth knowing before assuming a paid upgrade is about "better security scanning" when it's really about scope of coverage.

Gotchas and failure modes

☺ Like you're 10: Most of the surprises come from SonarQube being a real server with real state, not a stateless script — timing, storage, and "did anyone actually look at it" all matter in ways a simple CLI tool never has to think about.

• "CE" means two different things in the same product. Compute Engine (the background analysis worker) and Community Edition (the free tier) share the same abbreviation constantly in Sonar's own docs and community forum — always read from context, and don't assume a forum post about "CE" is talking about licensing.
• The New Code period silently determines whether the gate means anything. If it's pinned to a reference branch that's gone stale, or set to a huge day-count window, "New Code" can end up meaning almost the entire codebase — or almost nothing — and a gate that seems to never catch anything, or fails constantly for reasons nobody can explain, is very often this setting, not the rules.
• Elasticsearch's bootstrap checks fail hard on a fresh Linux host. The bundled, embedded Elasticsearch node needs vm.max_map_count raised (commonly to at least 262144) and a real memory allocation; the classic first-install failure is a cryptic max virtual memory areas vm.max_map_count is too low error that has nothing to do with your project and everything to do with the host's kernel settings.
• Unreviewed hotspots don't announce themselves the way a Vulnerability does. Because a Security Hotspot carries no severity until someone reviews it, a growing backlog doesn't show up as a wall of Critical findings — it shows up as a slowly dropping "Security Hotspots Reviewed" percentage that's easy to stop noticing until it drags a Quality Gate down.
• Forgetting sonar.exclusions pollutes every metric at once. Vendored dependencies, generated protobuf/OpenAPI code, and build output all get analyzed by default. Unlike a SAST-only tool where that mostly means noisy findings, here it also inflates duplication and complexity metrics — a Quality Gate can fail for reasons that have nothing to do with any code your team actually wrote.
• A green scanner step is not a green Quality Gate — see the dedicated warning above. This is worth repeating here because it's consistently the first surprise a team hits after their first successful-looking pipeline run.

Alternatives and when to choose it

☺ Like you're 10: Other tools read code for danger too — the real choice is whether you want a fast single-purpose scanner, the deepest possible security analysis, or one dashboard that also grades how well the code is built.

Most mature pipelines don't pick exactly one. A common, defensible shape: Semgrep as the fastest first gate on every PR, SonarQube's Quality Gate as the merge-blocking check that also keeps maintainability and coverage from rotting, and CodeQL running on a schedule for the deep, cross-function taint tracking neither of the other two attempts. See Vulnerability Management & Triage and the DefectDojo tool page for how findings from more than one of these actually get deduplicated into a single backlog once a pipeline runs several scanners at once.