advsec_get_alerts
Retrieve Azure DevOps Advanced Security alerts for a repository, filtering by type, state, severity, or rule. Manage code and dependency vulnerabilities effectively with specified criteria.
Instructions
Retrieve Advanced Security alerts for a repository.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| alertType | No | Filter alerts by type. If not specified, returns all alert types. | |
| confidenceLevels | Yes | Filter alerts by confidence levels. Only applicable for secret alerts. Defaults to both 'high' and 'other'. | |
| continuationToken | No | Continuation token for pagination. | |
| onlyDefaultBranch | No | If true, only return alerts found on the default branch. Defaults to true. | |
| orderBy | No | Order results by specified field. Defaults to 'severity'. | severity |
| project | Yes | The name or ID of the Azure DevOps project. | |
| ref | No | Filter alerts by git reference (branch). If not provided and onlyDefaultBranch is true, only includes alerts from default branch. | |
| repository | Yes | The name or ID of the repository to get alerts for. | |
| ruleId | No | Filter alerts by rule ID. | |
| ruleName | No | Filter alerts by rule name. | |
| severities | No | Filter alerts by severity level. If not specified, returns alerts at any severity. | |
| states | No | Filter alerts by state. If not specified, returns alerts in any state. | |
| toolName | No | Filter alerts by tool name. | |
| top | No | Maximum number of alerts to return. Defaults to 100. | |
| validity | No | Filter alerts by validity status. Only applicable for secret alerts. |
Implementation Reference
- src/tools/advsec.ts:53-98 (handler)The handler function that implements the core logic of the 'advsec_get_alerts' tool. It constructs filter criteria from input parameters, calls the Azure DevOps Alert API to retrieve alerts, and returns the results as JSON or an error message.async ({ project, repository, alertType, states, severities, ruleId, ruleName, toolName, ref, onlyDefaultBranch, confidenceLevels, validity, top, orderBy, continuationToken }) => { try { const connection = await connectionProvider(); const alertApi = await connection.getAlertApi(); const isSecretAlert = !alertType || alertType.toLowerCase() === "secret"; const criteria = { ...(alertType && { alertType: mapStringToEnum(alertType, AlertType) }), ...(states && { states: mapStringArrayToEnum(states, State) }), ...(severities && { severities: mapStringArrayToEnum(severities, Severity) }), ...(ruleId && { ruleId }), ...(ruleName && { ruleName }), ...(toolName && { toolName }), ...(ref && { ref }), ...(onlyDefaultBranch !== undefined && { onlyDefaultBranch }), ...(isSecretAlert && confidenceLevels && { confidenceLevels: mapStringArrayToEnum(confidenceLevels, Confidence) }), ...(isSecretAlert && validity && { validity: mapStringArrayToEnum(validity, AlertValidityStatus) }), }; const result = await alertApi.getAlerts( project, repository, top, orderBy, criteria, undefined, // expand parameter continuationToken ); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return { content: [ { type: "text", text: `Error fetching Advanced Security alerts: ${errorMessage}`, }, ], isError: true, }; } }
- src/tools/advsec.ts:20-52 (schema)The Zod input schema defining all parameters for the 'advsec_get_alerts' tool, including filters for alerts, pagination, and repository details.{ project: z.string().describe("The name or ID of the Azure DevOps project."), repository: z.string().describe("The name or ID of the repository to get alerts for."), alertType: z .enum(getEnumKeys(AlertType) as [string, ...string[]]) .optional() .describe("Filter alerts by type. If not specified, returns all alert types."), states: z .array(z.enum(getEnumKeys(State) as [string, ...string[]])) .optional() .describe("Filter alerts by state. If not specified, returns alerts in any state."), severities: z .array(z.enum(getEnumKeys(Severity) as [string, ...string[]])) .optional() .describe("Filter alerts by severity level. If not specified, returns alerts at any severity."), ruleId: z.string().optional().describe("Filter alerts by rule ID."), ruleName: z.string().optional().describe("Filter alerts by rule name."), toolName: z.string().optional().describe("Filter alerts by tool name."), ref: z.string().optional().describe("Filter alerts by git reference (branch). If not provided and onlyDefaultBranch is true, only includes alerts from default branch."), onlyDefaultBranch: z.boolean().optional().default(true).describe("If true, only return alerts found on the default branch. Defaults to true."), confidenceLevels: z .array(z.enum(getEnumKeys(Confidence) as [string, ...string[]])) .optional() .default(["high", "other"]) .describe("Filter alerts by confidence levels. Only applicable for secret alerts. Defaults to both 'high' and 'other'."), validity: z .array(z.enum(getEnumKeys(AlertValidityStatus) as [string, ...string[]])) .optional() .describe("Filter alerts by validity status. Only applicable for secret alerts."), top: z.number().optional().default(100).describe("Maximum number of alerts to return. Defaults to 100."), orderBy: z.enum(["id", "firstSeen", "lastSeen", "fixedOn", "severity"]).optional().default("severity").describe("Order results by specified field. Defaults to 'severity'."), continuationToken: z.string().optional().describe("Continuation token for pagination."), },
- src/tools/advsec.ts:18-99 (registration)Registers the 'advsec_get_alerts' tool on the MCP server using server.tool(), providing the tool name, description, input schema, and handler function.ADVSEC_TOOLS.get_alerts, "Retrieve Advanced Security alerts for a repository.", { project: z.string().describe("The name or ID of the Azure DevOps project."), repository: z.string().describe("The name or ID of the repository to get alerts for."), alertType: z .enum(getEnumKeys(AlertType) as [string, ...string[]]) .optional() .describe("Filter alerts by type. If not specified, returns all alert types."), states: z .array(z.enum(getEnumKeys(State) as [string, ...string[]])) .optional() .describe("Filter alerts by state. If not specified, returns alerts in any state."), severities: z .array(z.enum(getEnumKeys(Severity) as [string, ...string[]])) .optional() .describe("Filter alerts by severity level. If not specified, returns alerts at any severity."), ruleId: z.string().optional().describe("Filter alerts by rule ID."), ruleName: z.string().optional().describe("Filter alerts by rule name."), toolName: z.string().optional().describe("Filter alerts by tool name."), ref: z.string().optional().describe("Filter alerts by git reference (branch). If not provided and onlyDefaultBranch is true, only includes alerts from default branch."), onlyDefaultBranch: z.boolean().optional().default(true).describe("If true, only return alerts found on the default branch. Defaults to true."), confidenceLevels: z .array(z.enum(getEnumKeys(Confidence) as [string, ...string[]])) .optional() .default(["high", "other"]) .describe("Filter alerts by confidence levels. Only applicable for secret alerts. Defaults to both 'high' and 'other'."), validity: z .array(z.enum(getEnumKeys(AlertValidityStatus) as [string, ...string[]])) .optional() .describe("Filter alerts by validity status. Only applicable for secret alerts."), top: z.number().optional().default(100).describe("Maximum number of alerts to return. Defaults to 100."), orderBy: z.enum(["id", "firstSeen", "lastSeen", "fixedOn", "severity"]).optional().default("severity").describe("Order results by specified field. Defaults to 'severity'."), continuationToken: z.string().optional().describe("Continuation token for pagination."), }, async ({ project, repository, alertType, states, severities, ruleId, ruleName, toolName, ref, onlyDefaultBranch, confidenceLevels, validity, top, orderBy, continuationToken }) => { try { const connection = await connectionProvider(); const alertApi = await connection.getAlertApi(); const isSecretAlert = !alertType || alertType.toLowerCase() === "secret"; const criteria = { ...(alertType && { alertType: mapStringToEnum(alertType, AlertType) }), ...(states && { states: mapStringArrayToEnum(states, State) }), ...(severities && { severities: mapStringArrayToEnum(severities, Severity) }), ...(ruleId && { ruleId }), ...(ruleName && { ruleName }), ...(toolName && { toolName }), ...(ref && { ref }), ...(onlyDefaultBranch !== undefined && { onlyDefaultBranch }), ...(isSecretAlert && confidenceLevels && { confidenceLevels: mapStringArrayToEnum(confidenceLevels, Confidence) }), ...(isSecretAlert && validity && { validity: mapStringArrayToEnum(validity, AlertValidityStatus) }), }; const result = await alertApi.getAlerts( project, repository, top, orderBy, criteria, undefined, // expand parameter continuationToken ); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; return { content: [ { type: "text", text: `Error fetching Advanced Security alerts: ${errorMessage}`, }, ], isError: true, }; } } );
- src/tools.ts:29-29 (registration)Top-level call to configure and register Advanced Security tools, including 'advsec_get_alerts', as part of configuring all tools.configureAdvSecTools(server, tokenProvider, connectionProvider);
- src/tools/advsec.ts:11-14 (helper)Constant object defining the string name for the 'advsec_get_alerts' tool used in registration.const ADVSEC_TOOLS = { get_alerts: "advsec_get_alerts", get_alert_details: "advsec_get_alert_details", };