You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/instructions/arm-api-review.instructions.md
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -909,6 +909,7 @@ When reviewing resources that support availability zones, verify: `zones` is a t
909
909
910
910
- The `name` property in the `checkNameAvailability` request **MUST** have `pattern` and `maxLength` constraints matching the target resource type's name validation rules.
911
911
- At minimum, the `name` field **SHOULD** be constrained to valid ARM resource name characters (alphanumeric, hyphens, underscores, periods). Example: `"pattern": "^[a-zA-Z0-9][a-zA-Z0-9-_.]{0,259}$"`, `"maxLength": 260`.
912
+
- The `pattern` constraint **MUST** use allowlist (positive character class) syntax. Denylist (negated character class `[^...]`) syntax **MUST NOT** be used as the primary character-matching construct (`OAPI-PATTERN-ALLOWLIST`). A denylist such as `^[^<>%&:\\?/]+$` permits emoji, control characters, and non-Latin scripts that the service almost certainly rejects. Severity: **Blocking** for new properties/parameters; **Warning** for existing ones. See [`.github/skills/azure-api-review/references/pattern-validation.md`](../skills/azure-api-review/references/pattern-validation.md) for detection guidance, the severity matrix, and fix examples.
912
913
- If a spec defines a custom `checkNameAvailability` request model with a bare `string``name` field (no `pattern`, no `maxLength`), flag it as a **security concern** and instruct the author to add constraints.
913
914
-**Why:** Unconstrained string inputs to backend queries are a SQL/NoSQL injection risk. Input validation in the spec provides client-side SDK validation and signals to implementers that the field requires server-side sanitization.
914
915
@@ -1151,6 +1152,8 @@ When reviewing ARM resource-manager swagger files, verify:
- ✅ `name` field has `pattern` and `maxLength` constraints — not a bare unconstrained string (CNA-004)
1155
+
- ✅ `name` field `pattern` uses allowlist syntax (positive character class) — not denylist (`[^...]`) (OAPI-PATTERN-ALLOWLIST, CNA-004)
1156
+
- ✅ All `pattern` constraints across path parameters, query parameters, and body properties use allowlist syntax — no denylist (`[^...]`) as the primary construct (`OAPI-PATTERN-ALLOWLIST`): Blocking for new, Warning for existing
-`pattern` constraints **MUST** use allowlist (positive character class) syntax. Denylist (negated character class `[^...]`) syntax **MUST NOT** be used as the primary character-matching construct (`OAPI-PATTERN-ALLOWLIST`). A negative lookahead (`(?!...)`) used alongside a positive class is acceptable (e.g., `^(?![.-])[A-Za-z0-9_.-]{1,128}$`). Severity: **Blocking** for new properties/parameters; **Warning** for existing ones carried forward from a prior API version. See [`.github/skills/azure-api-review/references/pattern-validation.md`](../skills/azure-api-review/references/pattern-validation.md) for detection guidance, the severity matrix, fix examples, and regression-risk notes.
160
161
- For action operations on a resource, the URL pattern **SHOULD** be: `/<resource-collection>/<resource-id>:<action>`.
161
162
- For action operations on a collection: `/<resource-collection>:<action>`.
162
163
-**DO NOT** use action URLs for standard CRUD operations that map naturally to GET/PUT/PATCH/DELETE.
@@ -644,6 +645,7 @@ When reviewing, systematically check:
644
645
- ✅ No unused/orphaned definitions in `definitions` section (SCHEMA-UNUSED-DEF)
645
646
- ✅ Example files use string placeholders for secrets, SSH keys, and credentials — no realistic-looking sensitive values (EX-SECRET-PLACEHOLDER)
646
647
- ✅ Resource name path parameters include `pattern` constraints with length limits and character restrictions
648
+
- ✅ All `pattern` constraints use allowlist (positive character class) syntax — no denylist (`[^...]`) as the primary construct (`OAPI-PATTERN-ALLOWLIST`): Blocking for new properties/parameters, Warning for existing ones
647
649
- ✅ PUT operation descriptions use idempotent language ("Creates or updates..." not "Creates a new...")
for detection guidance, severity matrix, fix examples, and
143
+
regression-risk notes.
133
144
- Properties representing UTC timestamps **SHOULD** include a `Utc`
134
145
suffix in the name (e.g., `lastModifiedTimeUtc`).
135
146
- Properties named `<something>Id`**MUST** be specific about what kind
@@ -444,3 +455,4 @@ When reviewing TypeSpec files, verify:
444
455
- ✅ No bearer/OAuth tokens passed in ARM request bodies -- use managed identity or Key Vault
445
456
- ✅ Generated OpenAPI files match `tsp compile .` output
446
457
- ✅ Example files present for all operations, with realistic descriptive values (EX-DESCRIPTIVE-VALUES)
458
+
- ✅ All `@pattern` and `NamePattern` constraints use allowlist (positive character class) syntax — no denylist (`[^...]`) as the primary construct (`OAPI-PATTERN-ALLOWLIST`): Blocking for new properties/parameters, Warning for existing ones
|_(none)_| DenylistPatternDetection | ❌ No automated rule | File a follow-up issue to add `OAPI-PATTERN-ALLOWLIST` to `@azure-tools/typespec-azure-core` and `@microsoft.azure/openapi-validator`. Agent-level coverage: `openapi-review.instructions.md §4`, `typespec-review.instructions.md §2.2`, `arm-api-review.instructions.md §21.4`, and [`pattern-validation.md`](pattern-validation.md). |
0 commit comments