security-alert-review

Security Alert Viewing

This Skill operates within the scope of aprojectandrepository; both are required to retrieve alerts.

Project Selection

If the user provides a project name (for example, "Contoso project"), use it directly without calling the project list API.
If not provided, ask the user to provide it once.

If still not provided, list projects for the user to choose from:

curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/_apis/projects?%24top=500&api-version=7.1"

Repository Selection

If the user provides a repository name, use it directly.
If not specified, ask for the repository name once.

If still not provided, list repositories in the project for the user to choose from:

curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/git/repositories?api-version=7.1"

Display value[].name。

Connection and Authentication

Always use curl to call the Azure DevOps REST API directly; each command carries its own authentication parameters.

Organization: read the environment variable AZURE_DEVOPS_ORG(organization name, for example contoso). If it is not set, ask the user once; if the user provides a URL, extract the organization name from https://dev.azure.com/{org} or https://{org}.visualstudio.com .
Host: other than dev.azure.com, the host for the Advanced Security alerts API is advsec.dev.azure.com。
Token: send the PAT with Basic authentication:-u ":$AZURE_DEVOPS_PAT"; if only AZURE_DEVOPS_EXT_PATis set (the variable used by the Azure CLI azure-devops extension), use it instead. When using a Microsoft Entra ID token instead, replace it with -H "Authorization: Bearer $AZURE_DEVOPS_TOKEN". If neither is set, ask the user to set AZURE_DEVOPS_PAT in their own terminal and retry, then stop. Read the token only from environment variables: do not ask the user to paste the token into the conversation, and do not print it or write it to a file.
PAT Permission Scope：Advanced Security (Read)、Code (Read)、Project and Team (Read)。
Encoding: URL-encode project and repository names in the path (write spaces as %20); in query strings, write $ as %24(for example, %24top) to avoid shell expansion.
Errors: HTTP 401, 403, 203, or a response that is an HTML login page means the token is invalid, expired, or lacks permission; report it and stop. HTTP 404 means the organization, project, or repository name is incorrect. If the response message contains VS2150009 , it means Advanced Security is not enabled for this repository; inform the user and stop.
Windows PowerShell: call curl.exe(not the curl alias), and write the environment variable as $env:AZURE_DEVOPS_PAT; PowerShell does not support <<'EOF', so first write the JSON body to a temporary file, then send it with --data-binary "@body.json" .

Query Parameters

The alerts list API filters with the criteria.* query parameter; separate multiple values with commas, and values are case-insensitive:

Parameter	Available Values	Example
`criteria.severities`	`critical`、`high`、`medium`、`low`、`note`、`warning`、`error`、`undefined`	"critical alerts" → `critical`
`criteria.states`	`active`、`dismissed`、`fixed`、`autoDismissed`	"active alerts" → `active`
`criteria.alertType`	`dependency`、`secret`、`code`(single value; there is also a newer `license`、`aiCode`）	"Dependabot alerts" → `dependency`
`criteria.confidenceLevels`	`high`、`other`	Defaults to `high,other`
`criteria.onlyDefaultBranch`	`true`、`false`	Defaults to `true`
`top`	Number of items per page	`top=100`
`continuationToken`	Previous page response header `x-ms-continuationtoken` value	Include when fetching the next page

Include criteria.confidenceLevels=high,otheron every call, unless the user explicitly requests another confidence filter. When this parameter is not included, secret scanning alerts only return high-confidence results.
If criteria.confidenceLevels=high,other is included but returns 0 results, remove this parameter and query again; if alerts are found as a result, note in the results that "only high-confidence secret scanning alerts are included".
When the user does not specify filter conditions, show all active alerts on the default branch:criteria.onlyDefaultBranch=true&criteria.states=active&criteria.confidenceLevels=high,other。

Rules

1. List repository alerts

When the user wants tolist alerts、show security alertsorview alerts, combine filter parameters according to the user's request:

curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://advsec.dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/alert/repositories/{repository}/alerts?criteria.onlyDefaultBranch=true&criteria.states=active&criteria.confidenceLevels=high,other&top=100&api-version=7.2-preview.1"

Present the results in a table.
When there are no alerts, clearly state that this repository has no alerts matching the criteria.

Examples: "Show security alerts for the Contoso project MyApp repository", "List critical dependency alerts for MyApp", "Show all active secret scanning alerts for MyApp"

2. Get details of a specific alert

When the user asks about aspecific alert(for example, "alert 42", "explain alert 42"):

curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://advsec.dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/alert/repositories/{repository}/alerts/{alertId}?api-version=7.2-preview.1"

When fetching details, include only api-version：expand=ValidationFingerprint would cause the response to include plaintext secrets, so this Skill does not use it.
Present all available detail fields, including affected files, line numbers, descriptions, remediation suggestions, and rule information.

Examples: "Show details of alert 42 in the Contoso project MyApp repository", "What is the problem with alert 42?"

3. Overview

When the user wants asummaryoroverviewof alerts, call the API from rule 1, without severity and type filters, including only criteria.states=active&criteria.confidenceLevels=high,other, and summarize as follows:
1. Count byalert type(Dependency, Secret, Code).
2. Within each type, count byseverity(Critical, High, Medium, Low, Other).
Present the summary in a concise table, with the total at the end.
Include -D - in the call to see the response headers. When the headers include x-ms-continuationtoken , it means there are more alerts: tell the user that this overview is based only on the first batch of alerts and that additional alerts exist.

Examples: "Give me a security overview of the MyApp repository", "Summarize the alerts for the Contoso project MyApp repository"

Present results

Date format is YYYY/MM/DD。

Present the alert list as a table:

Alert ID（alertId）
Title（title, or rule name)
Severity（severity), plus emoji: 🔴 Critical, 🟠 High, 🟡 Medium, 🟢 Low
Status（state：Active、Dismissed、Fixed、AutoDismissed）
Alert type（alertType：Dependency、Secret、Code）
Rule（tools[].rules[].friendlyName, if none, use opaqueId）
First discovered（firstSeenDate）

In addition to the list columns, the alert details also include:

Description（tools[].rules[].description): A complete description of what problem this alert represents.
File pathandline number(if any):physicalLocations[].filePath and physicalLocations[].region.lineStart。
Remediation advice（tools[].rules[].helpMessage and resources, if provided): How to fix it.
Confidence（confidence): High or Other (secret exposure alerts).
Validity（validityDetails.validityStatus): Active, Inactive, or Unknown (secret exposure alerts).
Tool name（tools[].name): The scanning tool that found this alert.

The overview is presented in the following table:

Alert type	🔴 Critical	🟠 High	🟡 Medium	🟢 Low	Other	Total
Dependency	Count	Count	Count	Count	Count	Count
Secret	Count	Count	Count	Count	Count	Count
Code	Count	Count	Count	Count	Count	Count
Total	Count	Count	Count	Count	Count	Count

Other column includes severities other than Critical, High, Medium, and Low (for example, Note, Warning, Error, Undefined). When alert types other than Dependency, Secret, and Code appear, add an extra row to the table.