> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/agent-centric-development-cycle/verify/how-to-guides/uncover-complex-vulnerabilities-with-ai.md).

# Uncover complex vulnerabilities with AI

This guide walks you through enabling the [SonarQube Hunter Agent](/agent-centric-development-cycle/verify/hunter-agent.md) 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](https://docs.sonarsource.com/sonarqube-cloud/appendices/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.

1. In SonarQube Cloud, go to *your organization* > **Administration** > **AI capabilities**.
2. Enroll your organization in the SonarQube Hunter Agent beta.
3. 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.
4. 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](#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.

1. Open the project you want to scan.
2. Go to **Administration** > **AI capabilities** and open the **Hunter Agent** tab.
3. 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.
4. If the project isn't bound to its DevOps platform, bind it first, following the prompt.
5. 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:

1. 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.
2. Work through the backlog. Triage, assign, and resolve the findings the agent raises, the same way you handle any other issue.
3. 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](https://docs.sonarsource.com/sonarqube-cloud/managing-your-projects/issues/) to learn how to review issues in SonarQube Cloud.

## Related pages

* [Hunter Agent](/agent-centric-development-cycle/verify/hunter-agent.md)
* [About the Agent Centric Development Cycle](/agent-centric-development-cycle/readme.md)
* [Reviewing issues](/sonarqube-cloud/managing-your-projects/issues/reviewing.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sonarsource.com/agent-centric-development-cycle/verify/how-to-guides/uncover-complex-vulnerabilities-with-ai.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.