diff --git a/docs/rules.md b/docs/rules.md index 2213a7444..a5ce73411 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -942,12 +942,6 @@ For more detail, pls refer to https://github.com/microsoft/api-guidelines/blob/v Please refer to [path-resource-type-name-camel-case.md](./path-resource-type-name-camel-case.md) for details. -### Post201Response - -Using post for a create operation is discouraged. - -Please refer to [post201-response.md](./post201-response.md) for details. - ### PostOperationIdContainsUrlVerb A POST operation's operationId should contain the verb indicated at the end of the corresponding url. @@ -962,6 +956,12 @@ Long-running POST operations must have responses with 202 and default return cod Please refer to [post-response-codes.md](./post-response-codes.md) for details. +### Post201Response + +Using post for a create operation is discouraged. + +Please refer to [post201-response.md](./post201-response.md) for details. + ### PreviewVersionOverOneYear Per [Retirement-of-Previews](https://dev.azure.com/msazure/AzureWiki/_wiki/wikis/AzureWiki.wiki/37683/Retirement-of-Previews), service, feature, API, and SKU in preview for over one year need to move to GA or retire. @@ -1246,7 +1246,7 @@ Please refer to [tags-are-not-allowed-for-proxy-resources.md](./tags-are-not-all ### TenantLevelAPIsNotAllowed -Tenant level APIs are strongly discouraged and subscription or resource group level APIs are preferred instead. The reason for this guidance is that tenant level APIs have a really broad scope and blast radius. We permit APIs to be at this broad scope under rare conditions. Some ARM feature sets also do not cover tenant level APIs such as the use of AFEC. Additionally, if you intend to bypass the standard RBAC constructs and make the APIs unauthorized, you will need an approval from the PAS team before the open API spec can be merged. +This rule checks for the tenant level APIs. Please refer to [tenant-level-apis-not-allowed.md](./tenant-level-apis-not-allowed.md) for details. diff --git a/docs/tenant-level-apis-not-allowed.md b/docs/tenant-level-apis-not-allowed.md index 30eb133b6..2c6e2f66a 100644 --- a/docs/tenant-level-apis-not-allowed.md +++ b/docs/tenant-level-apis-not-allowed.md @@ -2,7 +2,7 @@ ## Category -ARM Error +ARM Warning ## Applies to @@ -14,22 +14,11 @@ ARM OpenAPI(swagger) specs ## Description -Tenant level APIs are strongly discouraged and subscription or resource group level APIs are preferred instead. The reason for this guidance is that tenant level APIs have a really broad scope and blast radius. We permit APIs to be at this broad scope under rare conditions. Some ARM feature sets also do not cover tenant level APIs such as the use of AFEC. Additionally, if you intend to bypass the standard RBAC constructs and make the APIs unauthorized, you will need an approval from the PAS team before the open API spec can be merged. +This rule checks for the tenant level APIs. ## How to fix the violation -The error can be fixed in one of the following two ways - -1. Do not define tenant level APIs -2. Address both the sub sections below - - 1. Provide a justification as to why you need the APIs to have the broad tenant scope to the ARM API reviewer. To do this, please attend the ARM API review office hours to have a conversation with the ARM API reviewer. To book a slot, please visit aka.ms\armofficehoursinfo. - - 2. In addition to modeling the API at the tenant scope, if you also intend to add the API to the "allowUnauthorizedActions" list in your ARM manifest, you must present your design and get an exception from the PAS team. Once you get an approval, please share the evidence of the approval by dropping a screenshot of the written approval as a comment on the PR. Please proceed by adding a suppression for the linter error indicating that the exception has been approved by the PAS team. If you do not intend to add the API to the "allowUnauthorizedActions" list in your ARM manifest, please add a suppression indicating the same. - -Please use the following guidance to add a suppression - https://github.com/Azure/autorest/blob/main/docs/generate/suppress-warnings.md#suppress-warnings - -To get an approval from PAS, please book their office hours slot at https://aka.ms/azurerbacofficehours . You will have to present the scenario and explain why the API needs to be unauthorized. If the service team would like to reach out over email, they can send an email to authzeng@microsoft.com +Tenant level APIs are strongly discouraged and subscription or resource group level APIs are preferred instead. Please note that these APIs require a review from the security RBAC team during manifest check-in. For details, refer to the Manifest security review process: https://eng.ms/docs/microsoft-security/identity/auth-authz/access-control-managed-identityacmi/policy-administration-service/pas-wiki/livesite/security/manifest ## Good Examples diff --git a/packages/rulesets/CHANGELOG.md b/packages/rulesets/CHANGELOG.md index 3192e9b66..f8df3bf8f 100644 --- a/packages/rulesets/CHANGELOG.md +++ b/packages/rulesets/CHANGELOG.md @@ -1,5 +1,17 @@ # Change Log - @microsoft.azure/openapi-validator-rulesets +## 2.1.8 + +### Patches + +- Modified the rule TenantLevelAPIsNotAllowed RPC-Uri-V1-11 from error to warning + +## 2.1.7 + +### Patches + +- Updated autorest package.json to 2.2.4 +- ## 2.1.6 ### Patches diff --git a/packages/rulesets/generated/spectral/az-arm.js b/packages/rulesets/generated/spectral/az-arm.js index d0a7ac15f..9b782781c 100644 --- a/packages/rulesets/generated/spectral/az-arm.js +++ b/packages/rulesets/generated/spectral/az-arm.js @@ -2978,7 +2978,7 @@ const tenantLevelAPIsNotAllowed = (pathItems, _opts, ctx) => { for (const apiPath of apiPaths) { if (pathItems[apiPath]["put"] && !apiPath.endsWith("/operations") && apiPath.startsWith("/providers")) { errors.push({ - message: `${apiPath} is a tenant level api. Tenant level APIs are strongly discouraged and subscription or resource group level APIs are preferred instead. If you cannot model your APIs at these levels, you will need to present your design and get an exception from PAS team.`, + message: `${apiPath} is a tenant level api. Tenant level APIs are strongly discouraged and subscription or resource group level APIs are preferred instead. Please note that these APIs require a review from the security RBAC team during manifest check-in. For details, refer to the Manifest security review process: https://eng.ms/docs/microsoft-security/identity/auth-authz/access-control-managed-identityacmi/policy-administration-service/pas-wiki/livesite/security/manifest`, path: [...path, apiPath], }); break; @@ -3976,9 +3976,9 @@ const ruleset = { }, TenantLevelAPIsNotAllowed: { rpcGuidelineCode: "RPC-Uri-V1-11", - description: "Tenant level APIs are strongly discouraged and subscription or resource group level APIs are preferred instead. Design presentation and getting an exception from the PAS team is needed if APIs cannot be modelled at subscription or resource group level.", + description: "Tenant level APIs require a review from the security RBAC team during manifest check-in. For details, refer to the Manifest security review process: https://eng.ms/docs/microsoft-security/identity/auth-authz/access-control-managed-identityacmi/policy-administration-service/pas-wiki/livesite/security/manifest", message: "{{error}}", - severity: "error", + severity: "warn", resolved: true, formats: [oas2], given: "$[paths,'x-ms-paths']", diff --git a/packages/rulesets/package.json b/packages/rulesets/package.json index 27d6c891e..34cc59e15 100644 --- a/packages/rulesets/package.json +++ b/packages/rulesets/package.json @@ -1,6 +1,6 @@ { "name": "@microsoft.azure/openapi-validator-rulesets", - "version": "2.1.7", + "version": "2.1.8", "description": "Azure OpenAPI Validator", "main": "dist/index.js", "scripts": { diff --git a/packages/rulesets/src/spectral/az-arm.ts b/packages/rulesets/src/spectral/az-arm.ts index 209503627..8ea47493e 100644 --- a/packages/rulesets/src/spectral/az-arm.ts +++ b/packages/rulesets/src/spectral/az-arm.ts @@ -950,9 +950,9 @@ const ruleset: any = { TenantLevelAPIsNotAllowed: { rpcGuidelineCode: "RPC-Uri-V1-11", description: - "Tenant level APIs are strongly discouraged and subscription or resource group level APIs are preferred instead. Design presentation and getting an exception from the PAS team is needed if APIs cannot be modelled at subscription or resource group level.", + "Tenant level APIs require a review from the security RBAC team during manifest check-in. For details, refer to the Manifest security review process: https://eng.ms/docs/microsoft-security/identity/auth-authz/access-control-managed-identityacmi/policy-administration-service/pas-wiki/livesite/security/manifest", message: "{{error}}", - severity: "error", + severity: "warn", resolved: true, formats: [oas2], given: "$[paths,'x-ms-paths']", diff --git a/packages/rulesets/src/spectral/functions/tenant-level-apis-not-allowed.ts b/packages/rulesets/src/spectral/functions/tenant-level-apis-not-allowed.ts index 02d3b0e5d..6655b7786 100644 --- a/packages/rulesets/src/spectral/functions/tenant-level-apis-not-allowed.ts +++ b/packages/rulesets/src/spectral/functions/tenant-level-apis-not-allowed.ts @@ -17,7 +17,7 @@ export const tenantLevelAPIsNotAllowed = (pathItems: any, _opts: any, ctx: any) for (const apiPath of apiPaths) { if (pathItems[apiPath]["put"] && !apiPath.endsWith("/operations") && apiPath.startsWith("/providers")) { errors.push({ - message: `${apiPath} is a tenant level api. Tenant level APIs are strongly discouraged and subscription or resource group level APIs are preferred instead. If you cannot model your APIs at these levels, you will need to present your design and get an exception from PAS team.`, + message: `${apiPath} is a tenant level api. Tenant level APIs are strongly discouraged and subscription or resource group level APIs are preferred instead. Please note that these APIs require a review from the security RBAC team during manifest check-in. For details, refer to the Manifest security review process: https://eng.ms/docs/microsoft-security/identity/auth-authz/access-control-managed-identityacmi/policy-administration-service/pas-wiki/livesite/security/manifest`, path: [...path, apiPath], }) break diff --git a/packages/rulesets/src/spectral/test/tenant-level-apis-not-allowed.test.ts b/packages/rulesets/src/spectral/test/tenant-level-apis-not-allowed.test.ts index 3b06703e8..1da969114 100644 --- a/packages/rulesets/src/spectral/test/tenant-level-apis-not-allowed.test.ts +++ b/packages/rulesets/src/spectral/test/tenant-level-apis-not-allowed.test.ts @@ -2,7 +2,7 @@ import { Spectral } from "@stoplight/spectral-core" import linterForRule from "./utils" const ERROR_MESSAGE = - "is a tenant level api. Tenant level APIs are strongly discouraged and subscription or resource group level APIs are preferred instead. If you cannot model your APIs at these levels, you will need to present your design and get an exception from PAS team." + "is a tenant level api. Tenant level APIs are strongly discouraged and subscription or resource group level APIs are preferred instead. Please note that these APIs require a review from the security RBAC team during manifest check-in. For details, refer to the Manifest security review process: https://eng.ms/docs/microsoft-security/identity/auth-authz/access-control-managed-identityacmi/policy-administration-service/pas-wiki/livesite/security/manifest" let linter: Spectral