sonarqube-api-interaction

SonarQube Web API Interaction

Overview

The SonarQube Web API enables programmatic access to projects, issues, quality gates, and rules. All requests require Bearer token authentication.

Authentication

All requests must include the Authorization header:

-H "Authorization: Bearer $SONARQUBE_TOKEN"

Error responses for authentication failures:

• 401 Unauthorized: Token is invalid, expired, or missing
• 403 Forbidden: Token lacks necessary permissions for the resource
• 404 Not Found: Project key, issue, or resource does not exist

Search Issues

Endpoint: GET /api/issues/search

Query Parameters:

• componentKeys — Comma-separated project keys (required)
• statuses — OPEN, CONFIRMED, RESOLVED, WONTFIX, FALSE_POSITIVE (default: OPEN)
• types — VULNERABILITY, SECURITY_HOTSPOT, BUG, CODE_SMELL
• severities — BLOCKER, CRITICAL, MAJOR, MINOR, INFO
• ps — Page size, default 100, max 500
• p — Page number (1-indexed)

Example Request:

curl -H "Authorization: Bearer $SONARQUBE_TOKEN" \
  "https://sonar.example.com/api/issues/search?componentKeys=my-project&statuses=OPEN,CONFIRMED&types=VULNERABILITY,SECURITY_HOTSPOT&severities=BLOCKER,CRITICAL,MAJOR&ps=100&p=1"

Response:

{
  "total": 42,
  "p": 1,
  "ps": 100,
  "issues": [
    {
      "key": "AVz7jNJ6ow7sdfP",
      "component": "my-project:src/main/java/App.java",
      "line": 42,
      "rule": "java:S2077",
      "severity": "BLOCKER",
      "type": "VULNERABILITY",
      "status": "OPEN",
      "message": "SQL injection vulnerability detected",
      "debt": "30min"
    }
  ],
  "paging": {
    "pageIndex": 1,
    "pageSize": 100,
    "total": 42
  }
}

Pagination: Use p parameter to iterate through pages if total > ps.

Quality Gate Project Status

Endpoint: GET /api/qualitygates/project_status

Query Parameters:

• projectKey — Project key (required)

Example Request:

curl -H "Authorization: Bearer $SONARQUBE_TOKEN" \
  "https://sonar.example.com/api/qualitygates/project_status?projectKey=my-project"

Response:

{
  "projectStatus": {
    "status": "ERROR",
    "caycStatus": "yellow",
    "qualityGateDetails": {
      "name": "Default Quality Gate",
      "conditions": [
        {
          "status": "ERROR",
          "metricKey": "security_rating",
          "operator": "GREATER_THAN",
          "errorThreshold": "1",
          "actualValue": "3",
          "conditionName": "Security Rating"
        },
        {
          "status": "OK",
          "metricKey": "coverage",
          "operator": "LESS_THAN",
          "errorThreshold": "80",
          "actualValue": "85"
        }
      ]
    }
  }
}

Status Values:

• OK — Quality gate passed
• ERROR — One or more conditions failed
• NONE — No quality gate assigned to project

Get Rule Details

Endpoint: GET /api/rules/show

Query Parameters:

• key — Rule key, e.g., "java:S2077" (required)

Example Request:

curl -H "Authorization: Bearer $SONARQUBE_TOKEN" \
  "https://sonar.example.com/api/rules/show?key=java:S2077"

Response:

{
  "rule": {
    "key": "java:S2077",
    "repo": "java",
    "name": "SQL injection vulnerability",
    "severity": "BLOCKER",
    "type": "VULNERABILITY",
    "status": "READY",
    "htmlDesc": "<p>SQL injection is a code injection technique...</p><h2>Noncompliant Code:</h2><pre>...</pre><h2>Compliant Code:</h2><pre>...</pre>",
    "tags": ["cwe", "security", "owasp-top10"],
    "system": false,
    "langName": "Java",
    "lang": "java",
    "mdDesc": "..."
  }
}

Fields:

• htmlDesc — HTML description with remediation guidance and code examples
• tags — Array including CWE references (e.g., "cwe/cwe-89")
• severity — BLOCKER, CRITICAL, MAJOR, MINOR, INFO
• type — VULNERABILITY, SECURITY_HOTSPOT, BUG, CODE_SMELL

Transition Issues

Endpoint: POST /api/issues/do_transition

Parameters (form-encoded):

• issue — Issue key, e.g., "AVz7jNJ6ow7sdfP" (required)
• transition — confirm, resolve, falsepositive, wontfix (required)

Example Request:

curl -X POST -H "Authorization: Bearer $SONARQUBE_TOKEN" \
  "https://sonar.example.com/api/issues/do_transition" \
  -d "issue=AVz7jNJ6ow7sdfP&transition=resolve"

Transition Meanings:

• confirm — Confirms the issue is a real vulnerability (from OPEN)
• resolve — Marks as fixed/resolved (from OPEN or CONFIRMED)
• falsepositive — Marks as not a real issue (from OPEN or CONFIRMED)
• wontfix — Accepted risk, won't be fixed (from OPEN or CONFIRMED)

Response:

{
  "issue": {
    "key": "AVz7jNJ6ow7sdfP",
    "status": "RESOLVED"
  }
}

List Projects

Endpoint: GET /api/projects/search

Query Parameters:

• q — Search query (optional)
• p — Page number (default: 1)
• ps — Page size (default: 100)

Example Request:

curl -H "Authorization: Bearer $SONARQUBE_TOKEN" \
  "https://sonar.example.com/api/projects/search?q=my"

Response:

{
  "paging": {
    "pageIndex": 1,
    "pageSize": 100,
    "total": 2
  },
  "projects": [
    {
      "key": "my-project",
      "name": "My Project",
      "qualifier": "TRK",
      "visibility": "public",
      "lastAnalysisDate": "2024-01-15T10:30:00+0000"
    }
  ]
}

Error Handling

HTTP Status	Error	Resolution
200	Success	Proceed normally
400	Bad Request	Check query parameters
401	Unauthorized	Verify $SONARQUBE_TOKEN is valid and not expired
403	Forbidden	User/token lacks required permissions
404	Not Found	Project key, issue, or rule doesn't exist
429	Too Many Requests	Rate limited; implement exponential backoff
500	Internal Server Error	SonarQube server error; retry after delay

Common Workflows

Check and Remediate Vulnerabilities

1. Search for OPEN vulnerabilities:

   curl ... /api/issues/search?componentKeys=my-project&types=VULNERABILITY&statuses=OPEN
   

2. For each issue, fetch rule details:

   curl ... /api/rules/show?key=<ruleKey>
   

3. Apply fix using remediation skill, then transition:

   curl -X POST ... /api/issues/do_transition?issue=<issueKey>&transition=resolve
   

Monitor Quality Gate

1. Check gate status:

   curl ... /api/qualitygates/project_status?projectKey=my-project
   

2. If ERROR, identify failing condition and remediate

3. Re-check until status is OK

Bulk Operations

For multiple issues, paginate through results:

for p in 1 2 3; do
  curl ... "/api/issues/search?componentKeys=my-project&p=$p&ps=100"
done