Every engineering team running SonarQube in their CI/CD pipeline knows the pain: you push code, the SAST stage runs, and the quality gate fails. Sometimes it's a real vulnerability. But often, it's a false positive — a hardcoded IP in a test file, a "weak random" in a non-security context, or a hotspot that's already been reviewed.
The result? Developers spend hours manually reviewing SonarQube dashboards, marking false positives, triaging hotspots, and re-running pipelines. Multiply that by hundreds of repositories and thousands of merge requests, and it becomes a serious drag on engineering velocity.
In a typical enterprise setup, the security CI pipeline processes every merge request across the organization through one or more SonarQube instances. The SAST quality gate is non-negotiable — every repo must pass. The challenge is automating the triage without compromising security standards.
The Solution: An LLM-Powered Remediation Agent
sonar-agent is an AI-powered agent that sits inside the SAST pipeline stage and automatically remediates SonarQube quality gate failures. When the quality gate fails, the agent:
1. Fetches all open issues and security hotspots from SonarQube via API
2. Applies organization-defined safety rules (plain-English rules file) to determine what can be marked safe
3. Uses an LLM to reason about each issue in context — reading the actual source code, understanding the severity, and making a judgment call
4. Takes action — marks false positives, resolves won't-fix items, and marks safe hotspots
5. Re-runs the scanner — if the gate still fails, it loops and tries again (up to a configurable maximum)
The entire process is transparent: every action is logged with reasoning, and the agent never touches BLOCKER/CRITICAL issues or known dangerous patterns (injection, XSS, deserialization) unless explicitly overridden by a safety rule.
Architecture
How the Agent Reasons
When the agent encounters a SonarQube issue, it doesn't blindly follow rules. It makes a contextual decision using the LLM:
Example: Hardcoded IP Address (S1313)
```python
# SonarQube flags this as a security issue
INTERNAL_API = "http://192.168.1.100:8080/api"
```
The agent's reasoning:
> This is a private RFC 1918 IP address (192.168.x.x) used for an internal API endpoint.
> Private IPs are not externally routable and pose no security risk as hardcoded values.
> Action: Mark as SAFE — private network address, not a credential.
Example: SQL Injection (S2077)
```python
cursor.execute("SELECT * FROM users WHERE id = " + user_id)
```
The agent's reasoning:
> This is a genuine SQL injection vulnerability — user input is concatenated directly
> into a SQL query without parameterization. Safety rules prohibit marking injection
> issues as safe.
> Action: SKIP — real vulnerability, requires developer fix.**
Integration Example
The integration works with any CI/CD system. Here's a generic example using GitLab CI:
```yaml
sast:
image: your-registry/sonar-agent:latest
variables:
SONAR_HOST_URL: "http://your-sonarqube-server/"
SONAR_MAX_REMEDIATIONS: "5"
script:
- sonar-scanner # run the initial scan
- |
if sonar-quality-gate — status pass; then
echo "Quality gate PASSED."
exit 0
fi
if [ -z "${LLM_API_KEY}" ]; then
echo "No LLM key configured — failing as usual."
exit 1
fi
echo "Quality gate failed — starting auto-remediation…"
for i in $(seq 1 ${SONAR_MAX_REMEDIATIONS}); do
echo "=== Remediation attempt ${i} ==="
python3 sonar-agent/agent.py \
— sonar-project-key "${SONAR_PROJECT_KEY}" \
— branch "${CI_BRANCH_NAME}" \
— rules-file "rules.txt"
sonar-scanner # re-scan
if sonar-quality-gate — status pass; then
echo "Quality gate PASSED on attempt ${i}!"
exit 0
fi
done
echo "Still failing after ${SONAR_MAX_REMEDIATIONS} attempts."
exit 1
```
The same pattern applies to GitHub Actions, Jenkins, Azure DevOps, or any CI system — the core logic is:
1. Run scanner
2. Check gate
3. If failed and LLM key exists, run agent
4. Re-scan and repeat
Conclusion
The sonar-agent turns a manual, time-consuming triage process into an automated, auditable, and safety-bounded workflow. It respects security boundaries (never auto-resolving real vulnerabilities), integrates transparently into existing pipelines, and saves developers hours of SonarQube dashboard clicking.
The key insight: **AI agents are most useful not when they replace human judgment, but when they handle the 80% of decisions that are routine, so humans can focus on the 20% that actually matter.**