Uncover complex vulnerabilities with AI
How to enable the SonarQube Hunter Agent for your organization and projects so it runs an AI-powered analysis that uncovers complex broken access control, business logic, and authentication flaws.
This guide walks you through enabling the SonarQube Hunter Agent so it runs an AI-powered analysis that uncovers complex, logic-level security vulnerabilities that pattern-based analysis misses.
SonarQube Hunter Agent is available as a beta feature in the Enterprise plan. For more information on release stages, see Product release lifecycle.
Prerequisites
A SonarQube Cloud organization on the Enterprise plan
Your organization bound to a supported DevOps platform (GitHub, GitLab, or Azure DevOps)
The project you want to scan bound to its DevOps platform
The Administer Organization permission (to enable the agent) and the Administer Project permission (to turn it on)
Enable Hunter Agent for your organization
You need to be an organization administrator.
In SonarQube Cloud, go to your organization > Administration > AI capabilities.
Enroll your organization in the SonarQube Hunter Agent beta.
If your organization is not yet bound to a DevOps platform, follow the prompt to bind it. The agent cannot be enabled until the organization is bound.
Activate the Allow project admins to enable scheduled scans option.
Once enabled, the Hunter Agent section lists the projects that have the agent turned on, so you can see which projects are covered.
Running analyses with Hunter Agent
If you're running the first Hunter Agent analysis for your project, see First analysis recommendations to avoid failing your quality gate on the main branch.
As a project administrator, you can run Hunter Agent analyses manually or set up scheduled analyses.
Open the project you want to scan.
Go to Administration > AI capabilities and open the Hunter Agent tab.
If you see a message that the agent isn't enabled for the organization, ask an organization administrator to enable it first, using the link in the message.
If the project isn't bound to its DevOps platform, bind it first, following the prompt.
Run a Hunter Agent analysis manually or schedule analyses:
Manually: on the Hunter Agent page, select Run now, choose the branch to scan, and start an analysis immediately.
On a schedule: the agent scans the project automatically each day. The project's Hunter Agent page shows the last scan and the next scheduled scan.
First analysis recommendations
SonarQube Hunter Agent raises its findings as regular issues. Running your first analysis directly on the main branch can cause a passing quality gate to fail and block your team before you've had a chance to work through the findings.
To roll out the agent without disrupting your main branch:
Start on a dedicated branch. For your first analysis, select Run now and choose a dedicated branch instead of your main branch. The findings surface as issues on that branch, so they don't affect your main branch's quality gate.
Work through the backlog. Triage, assign, and resolve the findings the agent raises, the same way you handle any other issue.
Schedule analyses on the main branch. After your fixes are merged into the main branch and the number of open findings is under control, set up scheduled analyses so the agent keeps covering it.
This approach keeps the first wave of findings off your main branch. It gives your team time to clear the backlog and brings the agent into your main-branch quality gate only once the results are manageable.
Viewing agent activity
Track SonarQube Hunter Agent runs on the Activity tab of the project's Hunter Agent page. The table lists each run with the time it started, the branch it ran on, and its outcome. It shows SonarQube Hunter Agent runs only.
Viewing findings
Each project with the agent enabled has a Hunter Agent page in its navigation. This page gives you a results overview: the total number of findings, a breakdown by vulnerability category (broken access control, business logic, and authentication and session management), and the count at each severity within a category.
Select the issues in one of the findings tiles on the Hunter Agent page to open the project's Issues page filtered to SonarQube Hunter Agent findings. Each category count links to the issues for that category. On the Issues page, you can also filter by the hunter-agent tag to see all agent findings, or by a per-category tag such as hunter-broken-access-control to focus on one category.
Each finding is raised as a vulnerability with a security software quality and an estimated severity, and includes an explanation with Why is this an issue? and How to fix it? sections. You review, assign, comment on, and resolve these findings like any other issue. See Managing code issues to learn how to review issues in SonarQube Cloud.
Related pages
Last updated
Was this helpful?