Alerts - List

Reference

Service:: Advanced Security

API Version:: 7.2-preview.1

Get alerts for a repository

GET https://advsec.dev.azure.com/{organization}/{project}/_apis/alert/repositories/{repository}/alerts?api-version=7.2-preview.1

With optional parameters:

GET https://advsec.dev.azure.com/{organization}/{project}/_apis/alert/repositories/{repository}/alerts?top={top}&orderBy={orderBy}&criteria.alertIds={criteria.alertIds}&criteria.alertType={criteria.alertType}&criteria.confidenceLevels={criteria.confidenceLevels}&criteria.dependencyName={criteria.dependencyName}&criteria.fromDate={criteria.fromDate}&criteria.keywords={criteria.keywords}&criteria.licenseName={criteria.licenseName}&criteria.modifiedSince={criteria.modifiedSince}&criteria.onlyDefaultBranch={criteria.onlyDefaultBranch}&criteria.phaseId={criteria.phaseId}&criteria.phaseName={criteria.phaseName}&criteria.pipelineName={criteria.pipelineName}&criteria.ref={criteria.ref}&criteria.ruleId={criteria.ruleId}&criteria.ruleName={criteria.ruleName}&criteria.severities={criteria.severities}&criteria.states={criteria.states}&criteria.toDate={criteria.toDate}&criteria.toolName={criteria.toolName}&expand={expand}&continuationToken={continuationToken}&api-version=7.2-preview.1

URI Parameters

Name	In	Required	Type	Description
organization	path	True	string	The name of the Azure DevOps organization.
project	path	True	string	Project ID or project name
repository	path	True	string	The name or ID of the repository
api-version	query	True	string	Version of the API to use. This should be set to '7.2-preview.1' to use this version of the api.
continuationToken	query		string	If there are more alerts than can be returned, a continuation token is placed in the "x-ms-continuationtoken" header. Use that token here to get the next page of alerts
criteria.alertIds	query		integer[]	If provided, only return alerts with the ids specified. Otherwise, return any alert.
criteria.alertType	query		AlertType	If provided, only return alerts of this type. Otherwise, return alerts of all types.
criteria.confidenceLevels	query		string[]	If provided, only return alerts at these confidence levels. Both High and Other need to be specified to fetch alerts of all confidence levels. Otherwise, return alerts with high confidence level. Only applicable for secret alerts.
criteria.dependencyName	query		string	If provided, only alerts for this dependency are returned. Otherwise, return alerts for all dependencies. In a sarif submission, a dependency (or a component) is specified in result.RelatedLocations[].logicalLocation. Not applicable for secret alerts.
criteria.fromDate	query		string date-time	If provided, only return alerts last seen after this date. Otherwise return all alerts.
criteria.keywords	query		string	If provided, only return alerts whose titles match this pattern.
criteria.licenseName	query		string	If provided, only alerts created for dependency with this license are returned. Otherwise, return alerts for all licenses. In a sarif submission, license for a dependency (or a component) is specified in result.RelatedLocations[].logicalLocation.properties.license. Not applicable for secret alerts.
criteria.modifiedSince	query		string date-time	If provided, only return alerts that were modified since this date. Otherwise return all alerts.
criteria.onlyDefaultBranch	query		boolean	If true or not set, only return alerts found on the default branch of the repository. If there have been no runs completed on the default branch, the last run is used instead regardless of the branch used for that run. If false, return alerts from all branches. This option is ignored if ref is provided. Not applicable for secret alerts.
criteria.phaseId	query		string uuid	If provided with pipelineName, only return alerts detected in this pipeline phase Otherwise, return alerts detected in all phases. Not applicable for secret alerts.
criteria.phaseName	query		string	If provided with pipelineName, only return alerts detected in this pipeline phase Otherwise, return alerts detected in all phases. Not applicable for secret alerts.
criteria.pipelineName	query		string	If provided, only return alerts detected in this pipeline. Otherwise, return alerts detected in all pipelines. Not applicable for secret alerts.
criteria.ref	query		string	If provided, only include alerts for this ref. If not provided and OnlyDefaultBranch is true, only include alerts found on the default branch or last run branch if there is no analysis configuration for the default branch. Otherwise, include alerts from all branches. Not applicable for secret alerts.
criteria.ruleId	query		string	If provided, only return alerts for this rule. Otherwise, return alerts of all rules.
criteria.ruleName	query		string	If provided, only return alerts for this rule. Otherwise, return alerts for all rules.
criteria.severities	query		string[]	If provided, only return alerts at these severities. Otherwise, return alerts at any severity.
criteria.states	query		string[]	If provided, only return alerts in these states. Otherwise, return alerts in any state.
criteria.toDate	query		string date-time	If provided, only return alerts last seen before this date. Otherwise return all alerts.
criteria.toolName	query		string	If provided with toolName, only return alerts detected by this tool. Otherwise, return alerts detected by all tools.
expand	query		AlertListExpandOption
orderBy	query		string	Must be "id" "firstSeen" "lastSeen" "fixedOn" or "severity" Defaults to "id"
top	query		integer int32	The maximum number of alerts to return

Responses

Name	Type	Description
200 OK	Alert[]	successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name	Description
vso.advsec	Grants the ability to read alerts, result instances, analysis result instances

Definitions

Name	Description
Alert
AlertListExpandOption
AlertType	Type of the alert. E.g. secret, code, etc.
AlertValidityInfo	Validity data for an alert that will be part of Alerts APIs and UI.
AlertValidityStatus
Confidence	Confidence level of the alert.
DependencyKind	Dependency kind of this logical location.
Dismissal	Information about an alert dismissal
DismissalType	Reason for the dismissal
IdentityRef
License	License information for dependencies
LicenseState	License state
LogicalLocation
PhysicalLocation	Location in the source control system where the issue was found
ReferenceLinks	The class to represent a collection of REST reference links.
Region
RelationMetadata	The metadata to be associated with the alert.
Rule	The analysis rule that caused the alert.
Severity	Severity of the alert.
State	This value is computed and returned by the service. It is a value based on the results from all analysis configurations.
Tool	An Analysis tool that can generate security alerts
ValidationFingerprint
VersionControlDetails	Information for locating files in a source control system

Alert

Name	Type	Description
additionalProperties	object	Additional properties of this alert.
alertId	integer	Identifier for the alert. It is unique within Azure DevOps organization.
alertType	AlertType	Type of the alert. E.g. secret, code, etc.
confidence	Confidence	Confidence level of the alert.
dismissal	Dismissal	Contains information for the dismissal of the alert if the alert has been dismissed.
firstSeenDate	string	This value is computed and returned by the service. This value represents the first time the service has seen this issue reported in an analysis instance.
fixedDate	string	This value is computed and returned by the service. If the issue is fixed, this value represents the time the service has seen this issue fixed in an analysis instance.
gitRef	string	Reference to a git object, e.g. branch ref.
introducedDate	string	This value is computed and returned by the service. This value represents the first time the vulnerability was introduced.
lastSeenDate	string	This value is computed and returned by the service. This value represents the last time the service has seen this issue reported in an analysis instance.
logicalLocations	LogicalLocation[]	Logical locations for the alert. This value is computed and returned by the service. It is a value based on the results from all analysis configurations. An example of a logical location is a component.
physicalLocations	PhysicalLocation[]	This value is computed and returned by the service. It is a value based on the results from all analysis configurations. An example of a physical location is a file location.
relations	RelationMetadata[]	Relations between alerts and other artifacts.
repositoryUrl	string	Repository URL where the alert was detected.
severity	Severity	Severity of the alert.
state	State	This value is computed and returned by the service. It is a value based on the results from all analysis configurations.
title	string	Title will only be rendered as text and does not support markdown formatting. There is a maximum character limit of 256.
tools	Tool[]	Tools that have detected this issue.
truncatedSecret	string	A truncated/obfuscated version of the secret pertaining to the alert (if applicable).
validationFingerprints	ValidationFingerprint[]	ValidationFingerprints for the secret liveness check. Only returned on demand in Get API with Expand parameter set to be ValidationFingerprint (not returned in List API)
validityDetails	AlertValidityInfo	Validity details of an alert. Currently, this is only applicable to secret alerts. In case of secret alerts, the validity status and time is computed by looking at the liveness results for validation fingerprints associated to an alert.

AlertListExpandOption

Name	Type	Description
minimal	string	Return a minimal representation of an alert.
none	string	No Expands.

AlertType

Type of the alert. E.g. secret, code, etc.

Name	Type	Description
code	string	The code contains a weakness determined by static analysis.
dependency	string	The code uses a dependency with a known vulnerability.
secret	string	The code contains a secret that has now been compromised and must be revoked.
unknown	string	The code has an unspecified vulnerability type

AlertValidityInfo

Validity data for an alert that will be part of Alerts APIs and UI.

Name	Type	Description
validityLastCheckedDate	string
validityStatus	AlertValidityStatus

AlertValidityStatus

Name	Type	Description
active	string
inactive	string
unknown	string

Confidence

Confidence level of the alert.

Name	Type	Description
high	string	High confidence level for alert
other	string	Other confidence level for alert

DependencyKind

Dependency kind of this logical location.

Name	Type	Description
component	string	The component being alerted.
rootDependency	string	The root dependency introduced the component being alerted.
unknown	string
vulnerableDependency	string	Vulnerable Dependency. Deprecating this value. Use Component instead.

Dismissal

Information about an alert dismissal

Name	Type	Description
dismissalId	integer	Unique ID for this dismissal
dismissalType	DismissalType	Reason for the dismissal
message	string	Informational message attached to the dismissal
stateChangedBy	string	Identity that dismissed the alert
stateChangedByIdentity	IdentityRef	Identity that dismissed the alert

DismissalType

Reason for the dismissal

Name	Type	Description
acceptedRisk	string	Dismissal indicating user is accepting a risk for the alert
agreedToGuidance	string	Dismissal indicating user is agreeing to follow license guidance.
falsePositive	string	Dismissal indicating alert is a false positive and will likely not be fixed.
fixed	string	Dismissal indicating alert has been fixed
unknown	string	Dismissal type unknown

IdentityRef

Name	Type	Description
_links	ReferenceLinks	This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.
descriptor	string	The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations.
directoryAlias	string	Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary
displayName	string	This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.
id	string
imageUrl	string	Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary
inactive	boolean	Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary
isAadIdentity	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType)
isContainer	boolean	Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType)
isDeletedInOrigin	boolean
profileUrl	string	Deprecated - not in use in most preexisting implementations of ToIdentityRef
uniqueName	string	Deprecated - use Domain+PrincipalName instead
url	string	This url is the full route to the source resource of this graph subject.

License

License information for dependencies

Name	Type	Description
name	string	License name
state	LicenseState	License state
url	string	Url for license information

LicenseState

License state

Name	Type	Description
harvested	string	Information of the license has been harvested by ClearlyDefined
notHarvested	string	Information of the license has not been harvested by ClearlyDefined
unknown	string	Information of the license has not been harvested by ClearlyDefined

LogicalLocation

Name	Type	Description
fullyQualifiedName	string
kind	DependencyKind	Dependency kind of this logical location.
license	License	License information for Dependency Only applicable when Kind is "Component" and the alertType of the alert with this location is License

PhysicalLocation

Location in the source control system where the issue was found

Name	Type	Description
filePath	string	Path of the file where the issue was found
region	Region	Details about the location where the issue was found including a snippet
versionControl	VersionControlDetails	Source control system-specific information about the location

ReferenceLinks

The class to represent a collection of REST reference links.

Name	Type	Description
links	object	The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

Region

Name	Type	Description
columnEnd	integer	The column where the code snippet ends
columnStart	integer	The column where the code snippet starts
lineEnd	integer	The line number where the code snippet ends
lineStart	integer	The line number where the code snippet starts

RelationMetadata

The metadata to be associated with the alert.

Name	Type	Description
attributes	object	Any additional attributes of the metadata.
rel	string	The type of the metadata.
url	string	The URL of the metadata.

Rule

The analysis rule that caused the alert.

Name	Type	Description
additionalProperties	object	Additional properties of this rule dependent on the rule type. For example, dependency rules may include the CVE ID if it is available.
description	string	Description of what this rule detects
friendlyName	string	Plain-text rule identifier
helpMessage	string	Additional information about this rule
opaqueId	string	Tool-specific rule identifier
resources	string	Markdown-formatted list of resources to learn more about the Rule. In some cases, RuleInfo.AdditionalProperties.advisoryUrls is used instead.
tags	string[]	Classification tags for this rule

Severity

Severity of the alert.

Name	Type	Description
critical	string
error	string
high	string
low	string
medium	string
note	string
undefined	string
warning	string

State

This value is computed and returned by the service. It is a value based on the results from all analysis configurations.

Name	Type	Description
active	string	Alert has been detected in the code
autoDismissed	string	The tool has determined that the issue is no longer a risk
dismissed	string	Alert was dismissed by a user
fixed	string	The issue is no longer detected in the code
unknown	string	Alert is in an indeterminate state

Tool

An Analysis tool that can generate security alerts

Name	Type	Description
name	string	Name of the tool
rules	Rule[]	The rules that the tool defines

ValidationFingerprint

Name	Type	Description
validationFingerprintHash	string
validationFingerprintJson	string
validityLastUpdatedDate	string
validityResult	string

VersionControlDetails

Information for locating files in a source control system

Name	Type	Description
commitHash	string
itemUrl	string

Share via