diff --git a/package-lock.json b/package-lock.json index d6ceac1..b3d7c64 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "azure-devops-extension-api", - "version": "4.228.0", + "version": "4.229.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "azure-devops-extension-api", - "version": "4.228.0", + "version": "4.229.0", "license": "MIT", "dependencies": { "whatwg-fetch": "~3.0.0" diff --git a/package.json b/package.json index 815bc4c..8f263b9 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "azure-devops-extension-api", - "version": "4.228.0", + "version": "4.229.0", "description": "REST client libraries and contracts for Azure DevOps web extension developers.", "repository": { "type": "git", diff --git a/src/Alert/Alert.ts b/src/Alert/Alert.ts index 57d5ee7..3549060 100644 --- a/src/Alert/Alert.ts +++ b/src/Alert/Alert.ts @@ -106,9 +106,21 @@ export interface AlertStateUpdate { } export enum AlertType { + /** + * The code has an unspecified vulnerability type + */ Unknown = 0, + /** + * The code uses a dependency with a known vulnerability. + */ Dependency = 1, + /** + * The code contains a secret that has now been compromised and must be revoked. + */ Secret = 2, + /** + * The code contains a weakness determined by static analysis. + */ Code = 3 } @@ -287,27 +299,78 @@ export enum ComponentType { Vcpkg = 16 } +/** + * Information about a vulnerable dependency + */ export interface Dependency { + /** + * Dependency name + */ componentName: string; + /** + * Source of the dependency + */ componentType: ComponentType; + /** + * Version information + */ componentVersion: string; + /** + * Unique ID for the dependency + */ dependencyId: number; } +/** + * An instance of a vulnerable dependency that was detected + */ export interface DependencyResult { + /** + * Information about the vulnerable dependency that was found + */ dependency: Dependency; + /** + * Unique ID for this dependency + */ dependencyResultId: number; + /** + * ID for the Result that this instance belongs to + */ resultId: number; + /** + * Heirarchal information when multiple instances are found + */ rootDependencyId: number; + /** + * Information about where the dependency was found + */ versionControlFilePath: VersionControlFilePath; } +/** + * Information about an alert dismissal + */ export interface Dismissal { + /** + * Unique ID for this dismissal + */ dismissalId: number; + /** + * Reason for the dismissal + */ dismissalType: DismissalType; + /** + * Informational message attached to the dismissal + */ message: string; requestedOn: Date; + /** + * Identity that dismissed the alert + */ stateChangedBy: string; + /** + * Identity that dismissed the alert + */ stateChangedByIdentity: WebApi.IdentityRef; } @@ -338,9 +401,21 @@ export interface LogicalLocation { kind: string; } +/** + * Location in the source control system where the issue was found + */ export interface PhysicalLocation { + /** + * Path of the file where the issue was found + */ filePath: string; + /** + * Details about the location where the issue was found including a snippet + */ region: Region; + /** + * Source control system-specific information about the location + */ versionControl: VersionControlDetails; } @@ -352,28 +427,76 @@ export interface Pipeline { } export interface Region { + /** + * The column where the code snippet ends + */ columnEnd: number; + /** + * The column where the code snippet starts + */ columnStart: number; + /** + * A subset of the code snippet highlighting the issue + */ highlightSnippet: string; + /** + * The line number where the code snippet ends + */ lineEnd: number; + /** + * The line number where the code snippet starts + */ lineStart: number; + /** + * The full code snippet + */ snippet: string; } export interface Result { + /** + * Additional information about the alert. Valid when ResultType is Dependency + */ dependencyResult: DependencyResult; + /** + * Full fingerprint of the Result. This is used to detect duplicate instances of the same alert + */ fingerprint: string; + /** + * Unique ID of the fingerprint of the Result + */ fingerprintId: number; + /** + * Unique ID of the Result + */ resultId: number; /** * This is the index into the SARIF Results array. If we have to do any tool specific insertions, we'll use this key to index back into the SARIF Results array. */ resultIndex: number; + /** + * Detailed description of the rule that triggered the alert + */ resultMessage: string; + /** + * The type of rule that triggered the alert + */ resultType: ResultType; + /** + * ID of the rule that the triggered the alert + */ ruleId: number; + /** + * Short description of the rule that triggered the alert + */ ruleShortDescription: string; + /** + * The severity of the alert + */ severity: Severity; + /** + * Additional information about the alert. Valid when ResultType is VersionControl + */ versionControlResult: VersionControlResult; } @@ -381,8 +504,17 @@ export interface Result { * This enum defines the different result types. */ export enum ResultType { + /** + * The result was found from an unspecified analysis type + */ Unknown = 0, + /** + * The result was found from dependency analysis + */ Dependency = 1, + /** + * The result was found from static code analysis + */ VersionControl = 2 } @@ -390,14 +522,33 @@ export enum ResultType { * The analysis rule that caused the alert. */ export interface Rule { + /** + * Additional properties of this rule + */ + additionalProperties: { [key: string] : any; }; + /** + * Description of what this rule detects + */ description: string; + /** + * Plain-text rule identifier + */ friendlyName: string; + /** + * Additional information about this rule + */ helpMessage: string; + /** + * Tool-specific rule identifier + */ opaqueId: string; /** * Markdown-formatted list of resources to learn more about the Rule. In some cases, RuleInfo.AdditionalProperties.advisoryUrls is used instead. */ resources: string; + /** + * Classification tags for this rule + */ tags: string[]; } @@ -419,7 +570,7 @@ export interface SearchCriteria { */ keywords: string; /** - * If true, 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. \
This option is ignored if branchName or ref are provided. + * If true, 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. \
This option is ignored if ref is provided. */ onlyDefaultBranchAlerts: boolean; /** @@ -468,54 +619,138 @@ export enum Severity { } export enum State { + /** + * Alert is in an indeterminate state + */ Unknown = 0, + /** + * Alert has been detected in the code + */ Active = 1, + /** + * Alert was dismissed by a user + */ Dismissed = 2, + /** + * The issue is no longer detected in the code + */ Fixed = 4, + /** + * The tool has determined that the issue is no longer a risk + */ AutoDismissed = 8 } +/** + * An Analysis tool that can generate security alerts + */ export interface Tool { + /** + * Name of the tool + */ name: string; + /** + * The rules that the tool defines + */ rules: Rule[]; } export interface UxFilters { + /** + * Branches to display alerts for. If empty, show alerts from all branches + */ branches: Branch[]; packages: Dependency[]; + /** + * Pipelines to show alerts for. If empty, show alerts for all pipelines + */ pipelines: Pipeline[]; progressPercentage: number; rules: Rule[]; secretTypes: string[]; + /** + * Alert severities to show. If empty show all alert servities + */ severities: Severity[]; + /** + * Alert states to show. If empty show all alert states + */ states: State[]; } +/** + * Information for locating files in a source control system + */ export interface VersionControlDetails { commitHash: string; itemUrl: string; } export interface VersionControlFilePath { + /** + * Path of the file in the version control system + */ filePath: string; + /** + * Hash of the file in the version control system + */ filePathHash: number[]; + /** + * Unique ID for the file in the version control system + */ versionControlFilePathId: number; } export interface VersionControlResult { + /** + * The ID to associate this structure with the cooresponding Result + */ resultId: number; + /** + * Information about the snippet where the Result was found + */ versionControlSnippet: VersionControlSnippet; } export interface VersionControlSnippet { + /** + * column in the code file where the snippet ends + */ endColumn: number; + /** + * line in the code file where the snippet ends + */ endLine: number; + /** + * subset of the code snippet highlighting the alert issue + */ highlightSnippet: string; + /** + * larger code snippet + */ snippet: string; + /** + * column in the code file where the snippet starts + */ startColumn: number; + /** + * line in the code file where the snippet starts + */ startLine: number; + /** + * Version control system where the code was found + */ versionControl: string; + /** + * path of the code file in the version control system + */ versionControlFilePath: VersionControlFilePath; + /** + * Unique Id number for the file path + */ versionControlFilePathId: number; + /** + * Unique Id number for this snippet + */ versionControlSnippetId: number; } diff --git a/src/Alert/AlertClient.ts b/src/Alert/AlertClient.ts index fb39110..074e88f 100644 --- a/src/Alert/AlertClient.ts +++ b/src/Alert/AlertClient.ts @@ -17,9 +17,11 @@ export class AlertRestClient extends RestClientBase { } /** + * Get an alert. + * * @param project - Project ID or project name - * @param alertId - - * @param repository - + * @param alertId - ID of alert to retrieve + * @param repository - Name or id of a repository that alert is part of * @param ref - */ public async getAlert( @@ -88,9 +90,11 @@ export class AlertRestClient extends RestClientBase { } /** + * Get an alert. + * * @param project - Project ID or project name - * @param alertId - - * @param repository - + * @param alertId - ID of alert to retrieve + * @param repository - Name or id of a repository that alert is part of * @param ref - */ public async getAlertSarif( diff --git a/src/Git/Git.ts b/src/Git/Git.ts index e29fccc..00b738b 100644 --- a/src/Git/Git.ts +++ b/src/Git/Git.ts @@ -166,6 +166,14 @@ export interface BillableCommitterDetail extends BillableCommitter { * Time reported by the commit. */ commitTime: Date; + /** + * DisplayName of the Pusher. + */ + displayName: string; + /** + * MailNickName of the Pusher. + */ + mailNickName: string; /** * Project Id commit was pushed to. */ @@ -178,6 +186,10 @@ export interface BillableCommitterDetail extends BillableCommitter { * Time of the push that contained the commit. */ pushedTime: Date; + /** + * Pusher Id for the push. + */ + pusherId: string; /** * Push Id that contained the commit. */ @@ -186,6 +198,10 @@ export interface BillableCommitterDetail extends BillableCommitter { * Repository name commit was pushed to. */ repoName: string; + /** + * SamAccountName of the Pusher. + */ + samAccountName: string; } /** diff --git a/src/Git/GitClient.ts b/src/Git/GitClient.ts index b7725fc..c8c7be6 100644 --- a/src/Git/GitClient.ts +++ b/src/Git/GitClient.ts @@ -227,7 +227,7 @@ export class GitRestClient extends RestClientBase { * * @param projectName - * @param repositoryId - Repository user is trying to access - * @param permission - Permission being requestd, must be "viewAlert" "dismissAlert" or "manage" + * @param permission - Permission being requestd, must be "viewAlert" "dismissAlert" "manage" "viewEnablement" or "repoRead" */ public async getPermission( projectName?: string, @@ -334,22 +334,16 @@ export class GitRestClient extends RestClientBase { * @param project - Project ID or project name * @param includeDetails - Return all the details on the billable committers. * @param billingDate - UTC expected. If not specified defaults to the previous billing day. - * @param skip - Skip X rows of resultset to simulate paging. - * @param take - Return Y rows of resultset to simulate paging. */ public async getBillableCommittersDetail( project: string, includeDetails: string, - billingDate?: Date, - skip?: number, - take?: number + billingDate?: Date ): Promise { const queryValues: any = { '$includeDetails': includeDetails, - '$billingDate': billingDate, - '$skip': skip, - '$take': take + '$billingDate': billingDate }; return this.beginRequest({ @@ -3876,6 +3870,29 @@ export class GitRestClient extends RestClientBase { }); } + /** + * @param project - Project ID or project name + * @param identityId - + */ + public async getRefFavoritesForProject( + project: string, + identityId?: string + ): Promise { + + const queryValues: any = { + identityId: identityId + }; + + return this.beginRequest({ + apiVersion: "7.2-preview.1", + routeTemplate: "{project}/_apis/git/favorites/refsForProject", + routeValues: { + project: project + }, + queryParams: queryValues + }); + } + /** * Create a git repository in a team project. * diff --git a/src/Management/Management.ts b/src/Management/Management.ts index 1de1045..a665f76 100644 --- a/src/Management/Management.ts +++ b/src/Management/Management.ts @@ -55,6 +55,7 @@ export interface BillingInfo { azureSubscriptionId: string; billingMode: BillingMode; organizationId: string; + tenantId: string; } export enum BillingMode { @@ -72,12 +73,37 @@ export enum BillingMode { MultiOrg = 2 } +/** + * Information related to billing for Advanced Security services + */ export interface MeterUsage { + /** + * The Azure DevOps account + */ accountId: string; azureSubscriptionId: string; + /** + * A list of identifiers for the commiters to the repositories that have Advanced Security features enabled + */ billedCommitters: string[]; + /** + * The date this billing information pertains to + */ billingDate: Date; + /** + * True when a bill is generated for Advanced Security feature usage in this organziation + */ isAdvSecBillable: boolean; + /** + * True when Advanced Security features are enabled in this organization + */ isAdvSecEnabled: boolean; + /** + * The Azure subscription + */ + tenantId: string; + /** + * The number of commiters to repositories that have Advanced Security features enabled + */ uniqueCommitterCount: number; }