feat: add vulnerabilities toolset for AI-assisted triage (#610)

Opt-in vulnerabilities toolset with GraphQL-backed list/get/dismiss/confirm tools, allowlist enforcement, and tests.

Co-authored-by: Simon Röthlisberger <simon.roethlisberger@swisscom.com>
Co-authored-by: sidi7 <sidi7@users.noreply.github.com>

Author: sidi7

README.md

@@ -753,7 +753,11 @@ Register the skill directory in your AI client to get optimal tool usage guidanc
 209. `update_dependency_proxy_settings` - Update dependency proxy settings for a group (enable/disable, credentials for authenticated Docker Hub pulls)
 210. `list_dependency_proxy_blobs` - List cached dependency proxy blobs for a group with cursor-based pagination
 211. `purge_dependency_proxy_cache` - Schedule purge of all cached dependency proxy blobs for a group
-212. `discover_tools` - Discover and activate additional tool categories for this session. Available categories: merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, users, workitems, webhooks, search, variables, dependency_proxy. Already-active categories are listed in the response.
+212. `list_project_vulnerabilities` - List vulnerabilities for a project with optional state, severity, and report type filters (GraphQL-backed, cursor pagination)
+213. `get_vulnerability` - Get full details of a specific vulnerability
+214. `dismiss_vulnerability` - Dismiss a vulnerability with a reason (acceptable_risk, false_positive, used_in_tests, mitigating_control, not_applicable) and optional comment
+215. `confirm_vulnerability` - Confirm a vulnerability as a real finding requiring remediation
+216. `discover_tools` - Discover and activate additional tool categories for this session. Available categories: merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, users, workitems, webhooks, search, variables, dependency_proxy, vulnerabilities. Already-active categories are listed in the response.
 
 <!-- TOOLS-END -->
 

docs/tools/index.md

@@ -17,7 +17,7 @@ directly from `TOOLSET_DEFINITIONS` in
 | Status | Groups |
 |---|---|
 | **Default** — always exposed | [Projects & Namespaces](projects.md), [Projects & Files](repositories.md), [Branches & Commits](branches.md), [Groups](groups.md), [Merge Requests](merge-requests.md), [Issues](issues.md), [Labels](labels.md), [CI Lint](ci.md), [Users & Events](users.md) |
-| **Opt-in** — must be enabled | [Work Items](workitems.md), [Pipelines, Jobs & Deployments](pipelines.md) (also `USE_PIPELINE=true`), [Milestones](milestones.md) (also `USE_MILESTONE=true`), [Wiki](wiki.md) (also `USE_GITLAB_WIKI=true`), [Releases](releases.md), [Tags](tags.md), [Variables](variables.md), [Webhooks](webhooks.md), [Search](search.md), [Dependency Proxy](dependency-proxy.md), [Meta & GraphQL](meta.md) |
+| **Opt-in** — must be enabled | [Work Items](workitems.md), [Pipelines, Jobs & Deployments](pipelines.md) (also `USE_PIPELINE=true`), [Milestones](milestones.md) (also `USE_MILESTONE=true`), [Wiki](wiki.md) (also `USE_GITLAB_WIKI=true`), [Releases](releases.md), [Tags](tags.md), [Variables](variables.md), [Webhooks](webhooks.md), [Search](search.md), [Dependency Proxy](dependency-proxy.md), [Vulnerabilities](vulnerabilities.md), [Meta & GraphQL](meta.md) |
 
 **How to enable opt-in groups** (any one is sufficient):
 
@@ -412,6 +412,19 @@ Inspect and manage the GitLab dependency proxy cache settings, blob storage, and
 | [`list_dependency_proxy_blobs`](dependency-proxy.md#list_dependency_proxy_blobs) | List cached dependency proxy blobs for a group | 📖 |
 | [`purge_dependency_proxy_cache`](dependency-proxy.md#purge_dependency_proxy_cache) | Schedule purge of all cached dependency proxy blobs for a group | ✏️ |
 
+### [Vulnerabilities](vulnerabilities.md)
+
+AI-assisted vulnerability triage — list findings, inspect details, dismiss with reason, or confirm for remediation. Backed by the GitLab GraphQL API; requires GitLab Ultimate. *(4 tools)*
+
+> Opt-in. Enable via `GITLAB_TOOLSETS=vulnerabilities` (or `GITLAB_TOOLSETS=all`), list individual tools in `GITLAB_TOOLS=`, or activate at runtime with the `discover_tools` MCP tool.
+
+| Tool | What it does | R/W |
+|---|---|:-:|
+| [`list_project_vulnerabilities`](vulnerabilities.md#list_project_vulnerabilities) | List vulnerabilities for a project with optional state, severity, and report type filters (GraphQL-backed, cursor pagination) | 📖 |
+| [`get_vulnerability`](vulnerabilities.md#get_vulnerability) | Get full details of a specific vulnerability | 📖 |
+| [`dismiss_vulnerability`](vulnerabilities.md#dismiss_vulnerability) | Dismiss a vulnerability with a reason (acceptable_risk, false_positive, used_in_tests, mitigating_control, not_applicable) and optional comment | ✏️ |
+| [`confirm_vulnerability`](vulnerabilities.md#confirm_vulnerability) | Confirm a vulnerability as a real finding requiring remediation | ✏️ |
+
 ### [Meta & GraphQL](meta.md)
 
 Server diagnostics, tool discovery, and the GraphQL escape hatch. *(2 tools)*
@@ -421,7 +434,7 @@ Server diagnostics, tool discovery, and the GraphQL escape hatch. *(2 tools)*
 | Tool | What it does | R/W |
 |---|---|:-:|
 | [`execute_graphql`](meta.md#execute_graphql) | Execute a GitLab GraphQL query | 📖 |
-| [`discover_tools`](meta.md#discover_tools) | Discover and activate additional tool categories for this session. Available categories: merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, users, workitems, webhooks, search, variables, dependency_proxy. Already-active categories are listed in the response. | 📖 |
+| [`discover_tools`](meta.md#discover_tools) | Discover and activate additional tool categories for this session. Available categories: merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, users, workitems, webhooks, search, variables, dependency_proxy, vulnerabilities. Already-active categories are listed in the response. | 📖 |
 
 ---
 

docs/tools/meta.md

@@ -29,7 +29,7 @@ Execute a GitLab GraphQL query
 
 *📖 Read-only*
 
-Discover and activate additional tool categories for this session. Available categories: merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, users, workitems, webhooks, search, variables, dependency_proxy. Already-active categories are listed in the response.
+Discover and activate additional tool categories for this session. Available categories: merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, users, workitems, webhooks, search, variables, dependency_proxy, vulnerabilities. Already-active categories are listed in the response.
 
 **Parameters**
 

docs/tools/vulnerabilities.md

@@ -0,0 +1,71 @@
+# Vulnerabilities
+
+AI-assisted vulnerability triage — list findings, inspect details, dismiss with reason, or confirm for remediation. Backed by the GitLab GraphQL API; requires GitLab Ultimate.
+
+!!! note "Feature toggle"
+    Opt-in. Enable via `GITLAB_TOOLSETS=vulnerabilities` (or `GITLAB_TOOLSETS=all`), list individual tools in `GITLAB_TOOLS=`, or activate at runtime with the `discover_tools` MCP tool.
+
+## Tools in this group
+
+- [`list_project_vulnerabilities`](#list_project_vulnerabilities) — 📖 Read-only
+- [`get_vulnerability`](#get_vulnerability) — 📖 Read-only
+- [`dismiss_vulnerability`](#dismiss_vulnerability) — ✏️ Writes
+- [`confirm_vulnerability`](#confirm_vulnerability) — ✏️ Writes
+
+---
+
+### `list_project_vulnerabilities`
+
+*📖 Read-only*
+
+List vulnerabilities for a project with optional state, severity, and report type filters (GraphQL-backed, cursor pagination)
+
+**Parameters**
+
+| Parameter | Type | Required | Description |
+|---|---|:-:|---|
+| `project_id` | string | ✓ | Project ID or URL-encoded path |
+| `state` | enum (`detected` \| `confirmed` \| `resolved` \| `dismissed`) |  | Filter by vulnerability state |
+| `severity` | enum (`critical` \| `high` \| `medium` \| `low` \| `info` \| `unknown`) |  | Filter by severity level |
+| `report_type` | enum (`sast` \| `dast` \| `dependency_scanning` \| `container_scanning` \| `secret_detection` \| `coverage_fuzzing` \| `api_fuzzing` \| `cluster_image_scanning` \| `generic`) |  | Filter by scan/report type (e.g. secret_detection, sast, dast) |
+| `first` | integer |  | Number of vulnerabilities to return (max: 100, default: 20) |
+| `after` | string |  | Cursor for pagination; use the endCursor from a previous response |
+
+### `get_vulnerability`
+
+*📖 Read-only*
+
+Get full details of a specific vulnerability
+
+**Parameters**
+
+| Parameter | Type | Required | Description |
+|---|---|:-:|---|
+| `vulnerability_id` | string | ✓ | The vulnerability ID (numeric or GraphQL global ID) |
+
+### `dismiss_vulnerability`
+
+*✏️ Writes*
+
+Dismiss a vulnerability with a reason (acceptable_risk, false_positive, used_in_tests, mitigating_control, not_applicable) and optional comment
+
+**Parameters**
+
+| Parameter | Type | Required | Description |
+|---|---|:-:|---|
+| `vulnerability_id` | string | ✓ | The ID of the vulnerability to dismiss (numeric or GraphQL global ID) |
+| `reason` | enum (`acceptable_risk` \| `false_positive` \| `used_in_tests` \| `mitigating_control` \| `not_applicable`) | ✓ | Reason for dismissal |
+| `comment` | string |  | Optional comment explaining the dismissal |
+
+### `confirm_vulnerability`
+
+*✏️ Writes*
+
+Confirm a vulnerability as a real finding requiring remediation
+
+**Parameters**
+
+| Parameter | Type | Required | Description |
+|---|---|:-:|---|
+| `vulnerability_id` | string | ✓ | The ID of the vulnerability to confirm (numeric or GraphQL global ID) |
+| `comment` | string |  | Optional comment explaining the confirmation |