Share via

Alerts - Get

Service:
Advanced Security
API Version:
7.2-preview.1

Get an alert.

GET https://advsec.dev.azure.com/{organization}/{project}/_apis/alert/repositories/{repository}/alerts/{alertId}?api-version=7.2-preview.1
With optional parameters: 
GET https://advsec.dev.azure.com/{organization}/{project}/_apis/alert/repositories/{repository}/alerts/{alertId}?ref={ref}&expand={expand}&api-version=7.2-preview.1

URI Parameters

Name In Required Type Description
alertId
 path True

integer (int64)

ID of alert to retrieve
organization
 path True

string

The name of the Azure DevOps organization.
project
 path True

string

Project ID or project name
repository
 path True

string

Name or id of a repository that alert is part of
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.
expand
 query

ExpandOption

Expand attributes of a secret alert. Possible values are None and ValidationFingerprint. Defaults to None. Be aware that if expand is set to ValidationFingerprint, the response may contain the secret in its unencrypted form. Please exercise caution when using this data.
ref
 query

string

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
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
ExpandOption

Expand attributes of a secret alert. Possible values are None and ValidationFingerprint. Defaults to None. Be aware that if expand is set to ValidationFingerprint, the response may contain the secret in its unencrypted form. Please exercise caution when using this data.
IdentityRef
License

License information for dependencies
LicenseState

License state
LicenseType

License type
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
ValidationResult

The result of the validation.
VersionControlDetails

Information for locating files in a source control system

Alert

Object
Name Type Description
additionalProperties

object

Additional properties of this alert.
alertId

integer (int64)

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 (date-time)

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 (date-time)

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 (date-time)

This value is computed and returned by the service. This value represents the first time the vulnerability was introduced.
lastSeenDate

string (date-time)

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.
projectId

string (uuid)

Identifier of the project where the alert was detected.
relations

RelationMetadata[]

Relations between alerts and other artifacts.
repositoryId

string

Identifier of the repository where the alert was detected.
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.

AlertType

Enumeration

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

Value Description
unknown

The code has an unspecified vulnerability type
dependency

The code uses a dependency with a known vulnerability.
secret

The code contains a secret that has now been compromised and must be revoked.
code

The code contains a weakness determined by static analysis.

AlertValidityInfo

Object

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

Name Type Description
validityLastCheckedDate

string (date-time)

validityStatus

AlertValidityStatus

AlertValidityStatus

Enumeration
Value Description
none

When there are no validation fingerprints attached to the alert.
unknown

When the validations for validation fingerprints associated to the alert have not been conclusive.
active

When at least one validation fingerprint associated to the alert is exploitable.
inactive

When all validation fingerprints associated to the alert are not exploitable.

Confidence

Enumeration

Confidence level of the alert.

Value Description
high

High confidence level for alert
other

Other confidence level for alert

DependencyKind

Enumeration

Dependency kind of this logical location.

Value Description
unknown
rootDependency

The root dependency introduced the component being alerted.
component

The component being alerted.
vulnerableDependency

Vulnerable Dependency. Deprecating this value. Use Component instead.

Dismissal

Object

Information about an alert dismissal

Name Type Description
dismissalId

integer (int64)

Unique ID for this dismissal
dismissalType

DismissalType

Reason for the dismissal
message

string

Informational message attached to the dismissal
stateChangedBy

string (uuid)

Identity that dismissed the alert
stateChangedByIdentity

IdentityRef

Identity that dismissed the alert

DismissalType

Enumeration

Reason for the dismissal

Value Description
unknown

Dismissal type unknown
fixed

Dismissal indicating alert has been fixed
acceptedRisk

Dismissal indicating user is accepting a risk for the alert
falsePositive

Dismissal indicating alert is a false positive and will likely not be fixed.
agreedToGuidance

Dismissal indicating user is agreeing to follow license guidance.
toolUpgrade

Dismissal indicating backend detection tool was upgraded and the alert is not detected by the new version of tool.
notDistributed

Dismissal indicating the affected dependencency is not distributed to end users.

ExpandOption

Enumeration

Expand attributes of a secret alert. Possible values are None and ValidationFingerprint. Defaults to None. Be aware that if expand is set to ValidationFingerprint, the response may contain the secret in its unencrypted form. Please exercise caution when using this data.

Value Description
none

No Expands.
validationFingerprint

Return validationFingerprints in Alert.

IdentityRef

Object
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

Object

License information for dependencies

Name Type Description
name

string

License name
state

LicenseState

License state
type

LicenseType

License type
url

string

Url for license information

LicenseState

Enumeration

License state

Value Description
unknown

Information of the license has not been harvested by ClearlyDefined
notHarvested

Information of the license has not been harvested by ClearlyDefined
harvested

Information of the license has been harvested by ClearlyDefined

LicenseType

Enumeration

License type

Value Description
unknown

The license type is unknown or not specified.
permissive

A permissive license allows software to be freely used, modified, and distributed with minimal restrictions. Examples: MIT, Apache 2.0.
weakCopyleft

A weak copyleft license requires modifications to the software to be shared under the same license, but does not impose restrictions on larger works that include the software. Examples: LGPL.
strongCopyleft

A strong copyleft license requires that any derivative works or larger works that include the software must also be distributed under the same license. Examples: GPL.
networkCopyleft

A network copyleft license extends the copyleft requirement to software that is accessed over a network, requiring the source code to be made available. Examples: AGPL.
other

A license that does not fit into the standard categories or is custom-defined. In CG, it indicates a commercial license.
noAssertion

No assertion is made about the license type, leaving it unspecified.

LogicalLocation

Object
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

Object

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
Object

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

Object
Name Type Description
columnEnd

integer (int32)

The column where the code snippet ends
columnStart

integer (int32)

The column where the code snippet starts
lineEnd

integer (int32)

The line number where the code snippet ends
lineStart

integer (int32)

The line number where the code snippet starts

RelationMetadata

Object

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

Object

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

Enumeration

Severity of the alert.

Value Description
low
medium
high
critical
note
warning
error
undefined

State

Enumeration

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

Value Description
unknown

Alert is in an indeterminate state
active

Alert has been detected in the code
dismissed

Alert was dismissed by a user
fixed

The issue is no longer detected in the code
autoDismissed

The tool has determined that the issue is no longer a risk

Tool

Object

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

Object
Name Type Description
assetFingerprint

object

The key value representation of the asset fingerprint.
validationFingerprintHash

string

The hash associated to the secret.
validationFingerprintJson

string

The JSON representation of the secret. Be aware that this field may contain the secret in its unencrypted form. Please exercise caution when using this field.
validityLastUpdatedDate

string (date-time)

The date when the validity was last updated.
validityResult

ValidationResult

The result of the validation.

ValidationResult

Enumeration

The result of the validation.

Value Description
none

Default value, no information about the secret can be inferred from this.
exploitable

Represents a secret that can be used to connect to a resource.
notExploitable

Represents a secret that can't be used to connect to a resource.
inconclusive

Represents a secret where no determination can be made about its exploitability.
validationNotSupported

Represents a secret where we are unable to validate, e.g. dynamic validator missing.
transientError

Represents a secret where the validation process failed due to a transient error, e.g. network issue. This result indicates that the validation process should be retried.

VersionControlDetails

Object

Information for locating files in a source control system

Name Type Description
commitHash

string

itemUrl

string