RecoveryServicesBackup: add 2026-08-01 stable version with fetchInstantItemRecoveryOperationResult action (MSRC-114273)

[Himanshu Agarwal (hiaga)]

Summary

Adds a new stable API version 2026-08-01 to Microsoft.RecoveryServices/RecoveryServicesBackup and introduces a dedicated, RBAC-gated action to retrieve Instant Item Recovery (ILR) mount scripts:

• New operation ItemLevelRecoveryConnections_ListMountScripts
POST .../recoveryPoints/{recoveryPointId}/listMountScripts → returns InstantItemRecoveryTarget (the ILR clientScripts).
• Purpose: the ILR mount scripts contain iSCSI CHAP connection details. They were previously returned inline on the long-running operationsStatus (ILR provision) response, which is a broad operation-status read. This new action moves script retrieval to a dedicated, permission-scoped endpoint.

Change classification

• Additive / non-breaking. A new API version and a new action are added.
• InstantItemRecoveryTarget.clientScripts remains an optional property in the schema. The service will simply stop populating it on the operationsStatus response in the new version; the field is not removed (removal would be breaking). This keeps the change non-breaking while still meeting the security requirement.
• No prior GA'd version swagger is modified.

TypeSpec

recoveryservicesbackup is TypeSpec-authored; bms.json is generated. Source edits:

• main.tsp — added v2026_08_01 to the Versions enum.
• RecoveryPointResource.tsp — added the listMountScripts action gated with @added(Versions.v2026_08_01).

Generated stable/2026-08-01/bms.json + examples via tsp compile.

ARM modeling notes

• Modeled as a synchronous ARM POST action (ArmResourceActionSync) returning the resource payload in the 200 body — consistent with how the sibling provision/revoke ILR actions are modeled on the same RecoveryPointResource, and with ARM guidance for POST actions that return data.
• Reuses the existing InstantItemRecoveryTarget model as the response, matching the shape already returned via the ILR provision operationsStatus extended info, so no new response contract is introduced.

Draft PR — opened to begin swagger review in parallel with the service-side change. Not for merge until the service change is validated in canary.

[github-actions]

Next Steps to Merge

✅ All automated merging requirements have been met! To get your PR merged, see aka.ms/azsdk/specreview/merge.

Comment generated by summarize-checks workflow run.

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
Swagger	Microsoft.RecoveryServices-RecoveryServicesBackup
TypeSpec	Microsoft.RecoveryServices
Go	sdk/resourcemanager/recoveryservices/armrecoveryservicesbackup
JavaScript	@azure/arm-recoveryservicesbackup
Python	azure-mgmt-recoveryservicesbackup
Java	com.azure.resourcemanager:azure-resourcemanager-recoveryservicesbackup
C#	Azure.ResourceManager.RecoveryServicesBackup

---

Comment generated by After APIView workflow run.

[github-actions]

TypeSpec suppressions requiring review (testing, non-blocking)

Status: ❌ Approval required (currently under testing, review NOT enforced) — 5 suppressions

⚠️ This check is currently in testing mode and is non-blocking — it will not prevent this PR from merging. This PR adds or updates the TypeSpec suppressions listed below. Suppressions are strongly discouraged — they bypass linter rules that protect API quality and consistency. Authors should avoid adding new suppressions and prefer fixing the underlying issue; reviewers should approve only when there is a clear, compelling justification and no reasonable alternative. Review each linked rule and source location, then apply Approved-TypeSpecSuppression only if every justification is acceptable. The Status column shows ✅ once the label is applied and ❌ while approval is pending.

Changed suppressions (5)

Status	Rule	Source	Previous justification	New justification
❌	@azure-tools/typespec-azure-core/documentation-required Require documentation over enums, models, and operations.	RecoveryPointResource.tsp#L107	FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details	x-ms-authorization-auxiliary is a standard ARM cross-tenant auxiliary-token header defined by ARM; it carries no service-specific semantics to document.
❌	@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes Ensure post operations have the appropriate status codes.	RecoveryPointResource.tsp#L123	FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details	This action is accepted-only (returns 202 with no synchronous 200 body); the standard POST 200+default response-code set does not apply to this legacy asynchronous action.
❌	@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes Ensure post operations have the appropriate status codes.	RecoveryPointResource.tsp#L136	FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details	This action is accepted-only (returns 202 with no synchronous 200 body); the standard POST 200+default response-code set does not apply to this legacy asynchronous action.
❌	@azure-tools/typespec-azure-resource-manager/lro-location-header A 202 response should include a Location response header.	RecoveryPointResource.tsp#L122	FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details	provisionInstantItemRecovery returns 202 Accepted without a Location/Azure-AsyncOperation header; provisioning status is polled via GetProtectedItemOperationResult, so the LRO location-header requirement does not apply to this legacy action.
❌	@azure-tools/typespec-azure-resource-manager/lro-location-header A 202 response should include a Location response header.	RecoveryPointResource.tsp#L135	FIXME: Update justification, follow aka.ms/tsp/conversion-fix for details	revokeInstantItemRecovery returns 202 Accepted without a Location/Azure-AsyncOperation header; revoke status is polled via GetProtectedItemOperationResult, so the LRO location-header requirement does not apply to this legacy action.

For an overview of TypeSpec linting rules click here.
For a mapping from ARM lintdiff rules to corresponding TypeSpec linting rules click here.

💬 Have feedback on the TypeSpec suppression flow? Let us know.

[Himanshu Agarwal (hiaga)]

The two failing Swagger Avocado checks (MULTIPLE_DEFAULT_TAGS and MISSING_APIS_IN_DEFAULT_TAG) are pre-existing characteristics of the RecoveryServicesBackup readme, not regressions introduced by this PR:

• MULTIPLE_DEFAULT_TAGS: the readme's $(package-passivestamp) / $(package-activestamp) blocks sit under the Basic Information heading, so Avocado counts each as a default tag. This condition already exists on main and only surfaces here because advancing the default tag changes Avocado's error hash (its baseline-diff then treats it as net-new).
• MISSING_APIS_IN_DEFAULT_TAG: the 10 flagged paths are legacy APIs last defined in 2016-06-01 / 2023-01-15 and already absent from the current default (2026-05-01). They are absent from the new 2026-08-01 version too, so no API is dropped by this PR. The new 2026-08-01 stable is a clean superset of 2026-05-01 (only the new fetchInstantItemRecoveryOperationResult action is added).

Advancing the default tag to 2026-08-01 is required so SDK/codegen picks up the new version. Could a reviewer please apply Approved-Avocado + ARMSignedOff to clear these, consistent with prior RecoveryServicesBackup precedent (e.g. #41997, #42428)? Thanks!

[Ravi Eda (ravimeda)]

ARM API Review

Posting findings from the ARM API Reviewer agent (critic-verified, 3 iterations, converged) against commit f7995d5. See inline comments for findings 1, 4, 5, 6, 9, 10 and 11. Findings 2, 3, 7 and 8 concern lines that are unchanged in this PR diff, or live in stable/2026-08-01/bms.json whose diff GitHub omits due to file size, and are posted as top-level PR comments rather than inline.

[Ravi Eda (ravimeda)]

[EXISTING] 🔴 Blocking [§6.8 / §7.1 / §10.3] specification/recoveryservicesbackup/resource-manager/Microsoft.RecoveryServices/RecoveryServicesBackup/stable/2026-08-01/bms.json - line 11783 (JSON path $.definitions.OperationStatusProvisionILRExtendedInfo.properties.recoveryTarget); TypeSpec source models.tsp - line 8668.

Posted as a top-level comment because GitHub omits the diff patch for bms.json (file too large), so an inline anchor is not available.

Issue: The security objective of this PR is not represented in the contract. OperationStatusProvisionILRExtendedInfo.recoveryTarget still $refs InstantItemRecoveryTarget (carrying clientScripts then scriptContent) in the new 2026-08-01 document. Reachability is literal: OperationStatus.properties (line 11703) is the polymorphic OperationStatusExtendedInfo base (line 11722), whose OperationStatusProvisionILRExtendedInfo subtype (line 11778) carries the scripts. §6.8 therefore applies word-for-word: "Operation status properties MUST NOT contain sensitive information — operation status resources may be accessible through polling endpoints with different RBAC restrictions than the original operation." §7.1 adds: secrets "MUST NOT be exposed in the response of GET, PUT, or PATCH operations."

Blast radius: #/definitions/OperationStatus is $refd by seven operations in this version (lines 1865, 3053, 3450, 4227, 4527, 4949, 5353), so the credential-bearing subtype is declared on all of them.

The PR body says the service will simply stop populating the field. There is a signal about that in the new operation description (line 2039), but none on the recoveryTarget property itself - its description at line 11784 is unchanged - so no client, reviewer or CI check can tell from the property that it is no longer populated.

Classification reasoning: This issue also exists in the previous version - stable/2026-05-01/bms.json line 11657, same JSON path, at base SHA 6a330c8e. It is called out here because closing it is the stated purpose of this PR.

Suggested fix (preferred - deprecate in place). §10.3 (ARG003) states "DO NOT remove properties from a resource between API versions until the property usage has been fully deprecated... Instead, keep the property in the response and mark it as deprecated in the swagger description and documentation," and "All types and properties from previous API versions MUST be carried forward to new API versions." Excerpt - leave the #suppress on models.tsp line 8662 and the objectType discriminator member (line 8673) intact:

/**
 * Target details for file / folder restore. Deprecated: not populated from API version
 * 2026-08-01 onward. Use the recovery point mount-scripts action to retrieve the scripts.
 */
recoveryTarget?: InstantItemRecoveryTarget;

Suggested fix (stronger - only with sign-off). If the security team requires the property gone from the contract entirely, add @removed(Versions.v2026_08_01). That is both an SDK-breaking change and an ARG003 exception, so it needs breaking-change board and ARG-compatibility sign-off recorded on this PR. Do not apply it unilaterally.

Either way, a silent behavior change with no signal on the property is not acceptable.

[Ravi Eda (ravimeda)]

[EXISTING] 🔴 Blocking [SEC-SECRET-DETECT / §7.2] specification/recoveryservicesbackup/resource-manager/Microsoft.RecoveryServices/RecoveryServicesBackup/models.tsp - line 8355 (emitted: stable/2026-08-01/bms.json line 8635, JSON path $.definitions.ClientScriptForConnect.properties.scriptContent).

Posted as a top-level comment because this line is unchanged in the PR diff and cannot take an inline anchor.

Issue: ClientScriptForConnect.scriptContent carries the iSCSI mount script whose content includes CHAP connection credentials - the exact data MSRC-114273 concerns, and the new operation own doc comment says "The mount scripts contain the iSCSI connection details required to browse and recover files and folders." The property has no @secret decorator and no x-ms-secret: true in the emitted swagger. §7.2: "Any property that contains a secret in any operation (PUT, PATCH, GET, or POST) MUST be annotated with x-ms-secret: true in the swagger definition." Without it, ARM Template What-If treats the value as ordinary data (WHATIF-003) and secret-scanning tooling cannot identify the property.

Note the interlock: once scriptContent is annotated, the finding about OperationStatusProvisionILRExtendedInfo.recoveryTarget becomes machine-detectable - §7.1 then applies mechanically to all seven GETs returning OperationStatus.

Classification reasoning: This issue also exists in the previous version - stable/2026-05-01/bms.json line 8552, same JSON path, also without x-ms-secret, at base SHA 6a330c8e. The base file contains zero x-ms-secret occurrences. It is called out here because this PR newly returns the property from a dedicated action.

Suggested fix:

model ClientScriptForConnect {
  /**
   * File content of the client script for file / folder restore.
   */
  @secret
  scriptContent?: string;
  // ...
}

Trade-off to settle before applying: ClientScriptForConnect is not version-gated, so an unconditional @secret emits x-ms-secret: true into every previously published bms.json, changing already-released API version documents. Options: (a) apply it and get the regeneration of prior version files acknowledged as a metadata-only security correction; (b) if that is not acceptable, raise it with the ARM API review board and record the decision on this PR. Leaving the property unannotated is not an option.

[Sandip Shahane (sandipsh)]

Himanshu Agarwal (@hiaga) please address doc preview error https://dev.azure.com/apidrop/Content%20CI/_build/results?buildId=624347

[Himanshu Agarwal (hiaga)]

Himanshu Agarwal (Himanshu Agarwal (@hiaga)) please address doc preview error https://dev.azure.com/apidrop/Content%20CI/_build/results?buildId=624347

Sandip Shahane (@sandipsh) resolved the API doc preview issue by spliting the other folder verison bump into a separate PR - #45921

[github-actions]

Verdict: FAIL (protocol unavailable — cannot verify)

I cannot produce a substantive verdict on the SKIP-COVERED / empty-posting-set proposal because the binding instructions I'm required to load do not exist in this repository checkout:

• .github/agents/arm-api-review-critic.agent.md — missing
• .github/agents/protocols/arm-api-review-critic.protocol.md — missing
• .github/agents/protocols/arm-api-review-critic-inputs.template.md — missing

Only .github/agents/arm-api-review-critic-runtime.agent.md is present, and it explicitly delegates all verdict-format and evaluation logic to those three missing files, instructing that I "return an explicit failure verdict" if any required instruction file is unavailable.

Per my own instructions, I must not claim this review was Critic-verified. I have not independently validated:

• (a) whether SKIP-COVERED is the correct disposition for the recoveryTarget finding (comment 5428618231),
• (b) whether an empty new-posting-set is correct.

Action needed: restore the missing agent/protocol files (or point me at their correct location) so a real independent verification can be performed. Until then, treat the proposed SKIP-COVERED / empty-posting-set decision as unverified by the Critic, not approved.

🔍 ARM API review by ARM API Review: Automated Workflow

[github-actions]

ARM API Review Summary

Reviewed PR #44639 at head SHA 98f9dff196f176acbab8868e7fa7876371a7de7b | Triggered by: pull_request_target

Approval labels observed: BreakingChange-Approved-Security.

Category	Count
🔴 Blocking	0
🟠 Warning	0
🔵 Suggestion	0

This PR (RecoveryServicesBackup 2026-08-01: new listInstantItemRecoveryOperationResult action) has already undergone extensive human review (7 inline threads from @ravimeda, all resolved) and multiple prior automated ARM API review runs across 25 commits. Re-checking the current pinned SHA against the full diff and prior discussion inventory (review threads, top-level comments, reviews) found no new violations: the new action is a synchronous ArmResourceActionSync with a flat, non-enveloped request body and correct 200+default responses, the secret-bearing scriptContent is annotated @secret/x-ms-secret: true, the new API version is TypeSpec-authored (satisfies TSP-REQUIRED-V1), and readme.md/service.yaml are correctly wired for package-2026-08-01. One previously-posted [EXISTING] Blocking finding remains open and unchanged since it was last reported: OperationStatusProvisionILRExtendedInfo.recoveryTarget in models.tsp still lacks a deprecation note documenting that the legacy operationsStatus path continues to inline-return the secret-bearing clientScripts[].scriptContent alongside the new dedicated action (see #44639 (comment)); no new evidence or fix was found for it in this run, so it was not re-posted (SKIP-COVERED). The ARM API Review Critic sub-agent could not be dispatched after 3 attempts (its protocol files were unavailable in this checkout), so this run's self-check is unverified rather than Critic-verified; no Blocking findings were queued for publication in this run regardless.

posted-by: arm-api-reviewer-agent | rule: summary | severity: suggestion | classification: existing | critic: unknown | head-sha: 98f9dff

🔍 ARM API review by ARM API Review: Automated Workflow

[azure-sdk-automation]

✅ Release Plan Created

Field	Value
Release Plan	View Release Plan
API Version	2026-08-01
TypeSpec Project	specification/recoveryservicesbackup/resource-manager/Microsoft.RecoveryServices/RecoveryServicesBackup

Note: The SDK will be generated based on API version 2026-08-01. This is the final API version detected from the changes in this pull request.