REST API安全与契约审计
从实际路由与代码行为出发检查接口契约、权限、校验和幂等性,定位可复现问题并提出验证和修复方案。
完整提示词
I want you to perform an ultra-deep, systematic, evidence-first, and production-oriented analysis of the complete REST API.
Main goal:
> Determine whether the API has consistent and secure contracts, correct HTTP semantics, clear validation, reliable authentication/authorization, deterministic error models, idempotent behavior where needed, stable versioning behavior, and strong compatibility with real-world clients and production conditions.
This is not:
- a generic REST best practices checklist
- automatic insistence on "REST purity"
- an attempt to turn every route into a textbook resource model
- insistence that everything must be `GET/POST/PUT/PATCH/DELETE` in perfect academic form
- automatic prohibition of RPC-like endpoints
- a superficial check of HTTP status codes
- just an OpenAPI review
- just a security audit
Focus is on real API behavior.
Priority:
**correctness > authorization > data integrity > contract stability > idempotency > error semantics > compatibility > elegance**
It is better to find 6 real API problems than to write 100 generic REST recommendations.
---
# 1. DETERMINE THE API STACK
Before findings, establish:
- framework
- routing system
- middleware
- validation library
- auth
- serialization
- ORM/repository
- OpenAPI/Swagger
- API versioning
- rate limiting
- pagination
- caching
- reverse proxy/API gateway
- tests
---
# 2. CREATE ROUTE INVENTORY
Find all REST routes.
For each record:
```text
Method:
Path:
Auth:
Authorization:
Request schema:
Response schema:
Status codes:
Side effects:
Idempotent:
Pagination:
Rate limit:
```
---
# 3. FINAL ROUTE TABLE
Produce:
| Method | Route | Auth | Authorization | Validation | Success | Main errors |
|---|---|---|---|---|---|---|
Do not rely only on documentation.
Code is the source of truth.
---
# 4. PATH SEMANTICS
Verify that path clearly represents:
- resource
- collection
- subresource
- operation
Examples:
```text
/users
/users/:id
/users/:id/sessions
```
However, an RPC-like route is not automatically a bug.
Example:
```text
/orders/:id/cancel
```
can be completely legitimate if it represents a business command.
---
# 5. RESOURCE IDENTITY
For each resource determine:
- primary ID
- public ID
- slug
- owner/tenant
Ask:
> Does the route stably identify the exact same logical resource?
---
# 6. GET SEMANTICS
GET should not have a business side effect.
Look for:
```text
GET /delete-user
GET /mark-paid
GET /send-email
```
If GET mutates state:
serious semantics/caching/security problem.
---
# 7. SAFE METHOD
If GET/HEAD can mutate durable state, a browser, crawler, cache, or prefetch mechanism may unexpectedly trigger the action.
---
# 8. POST
POST is legitimate for:
- create
- command
- non-idempotent operation
Do not force PUT where business semantics do not fit.
---
# 9. PUT
If PUT is used, verify that semantics represent replacement or idempotent update according to the API contract.
---
# 10. PATCH
Verify:
- partial update semantics
- omitted field
- explicit null
- field deletion
---
# 11. MISSING VS NULL
Critical contract question:
```json
{}
```
is not the same as:
```json
{"name": null}
```
if the API allows nullable fields.
---
# 12. DELETE
Verify behavior for:
- existing resource
- already deleted
- missing resource
- soft delete
- dependent resources
---
# 13. DELETE IDEMPOTENCY
Repeated DELETE must have well-defined behavior.
It does not have to return the same status code every time, but the final resource state must be stable.
---
# 14. HTTP STATUS CODES
Map actual usage:
- 200
- 201
- 202
- 204
- 400
- 401
- 403
- 404
- 409
- 422
- 429
- 500
- 502/503/504
Do not insist on one "sacred" status code where multiple models are legitimate.
---
# 15. 200 FOR ERROR
If an endpoint returns:
```json
{
"success": false,
"error": "..."
}
```
with 200 for normal failure semantics, inspect client impact.
---
# 16. 201 CREATED
For a create endpoint, verify whether the response clearly identifies the created resource.
---
# 17. 202 ACCEPTED
If the API returns 202:
it must be clear that the work is not yet finished.
Check how the client discovers the final result.
---
# 18. 204
204 must not have a meaningful response body.
Check actual framework behavior.
---
# 19. 400 VS 422
Do not waste audit time on an academic debate if the API is consistent.
What matters is a stable distinction between:
- malformed request
- validation/business rejection
---
# 20. 401 VS 403
Verify:
- 401 for missing/invalid authentication
- 403 for authenticated principal without permissions
where that matches the auth model.
---
# 21. RESOURCE EXISTENCE LEAK
Sometimes an API intentionally uses 404 even for an unauthorized resource to avoid leaking existence.
Do not blindfoldedly change that to 403.
---
# 22. 404
Verify that the endpoint does not return 200 + null for a missing resource if the client expects a normal resource.
However, a documented nullable lookup may be valid.
---
# 23. 409 CONFLICT
Relevant for:
- duplicate
- version conflict
- invalid state transition
Verify consistency.
---
# 24. 429
If rate limiting exists, verify the response contract and any Retry-After header.
---
# 25. 5XX
A server bug or upstream failure must not be presented as a user validation error.
---
# 26. RESPONSE BODY
For each endpoint verify stability of:
- field names
- types
- nullability
- nested structures
---
# 27. RESPONSE ENVELOPE
If the API uses:
```json
{"data": ...}
```
verify consistency.
Do not force an envelope if the API lacks one and clients work well.
---
# 28. METADATA
Pagination and metadata must have a stable shape.
---
# 29. ERROR MODEL
Ideally, every client-visible error has a stable machine-readable code.
Example:
```json
{
"error": {
"code": "EMAIL_ALREADY_EXISTS",
"message": "..."
}
}
```
It does not have to be exactly this structure.
---
# 30. ERROR MESSAGE AS CONTRACT
If client logic relies on:
```text
if message == "User not found"
```
that is a fragile contract.
---
# 31. ERROR CODE
A machine-readable code must be more stable than a human-readable message.
---
# 32. LOCALIZATION
Backend error messages do not necessarily need to be localized if the client relies on error codes and translates UI.
Verify actual architecture.
---
# 33. STACK TRACE LEAK
Production responses must never expose:
- stack traces
- SQL
- filesystem paths
- internal service details
- secrets
---
# 34. VALIDATION
Map all inputs:
- path params
- query params
- headers
- body
- multipart
---
# 35. PATH PARAM VALIDATION
If an endpoint expects UUID/int:
verify that invalid format is deterministically rejected.
---
# 36. QUERY PARAM VALIDATION
Especially:
- sort
- filter
- page
- limit
- date range
- search
---
# 37. BODY VALIDATION
Verify:
- required
- optional
- nullable
- enum
- min/max
- length
- nested arrays
- unknown fields
---
# 38. UNKNOWN FIELDS
Determine whether the API:
- ignores
- rejects
unknown fields.
Both models can be valid.
Security and stability are what matter.
---
# 39. MASS ASSIGNMENT
Critical:
```text
request body
↓
ORM update
```
without whitelisting.
Look for fields like:
- role
- ownerId
- isAdmin
- status
- balance
---
# 40. BUSINESS VALIDATION
Schema validation does not solve:
```text
start < end
amount <= allowed
state transition allowed
```
---
# 41. DUPLICATE VALIDATION
If the same business rule exists across multiple endpoints:
check for drift.
---
# 42. AUTHENTICATION INVENTORY
For each route classify:
```text
PUBLIC
AUTHENTICATED
ADMIN
SERVICE-TO-SERVICE
WEBHOOK
```
---
# 43. MISSING AUTH
Look for critical routes that are accidentally public.
---
# 44. AUTH MIDDLEWARE COVERAGE
Do not assume global middleware covers all route groups.
---
# 45. AUTHORIZATION
For each resource endpoint ask:
> Does the authenticated user have rights over THIS SPECIFIC resource?
---
# 46. IDOR
Classic flow:
```text
GET /documents/123
```
User must have authorization for document 123.
Not just a valid session.
---
# 47. UPDATE IDOR
Especially:
```text
PATCH /users/:id
```
Can a user modify someone else's ID?
---
# 48. DELETE IDOR
Same for delete.
---
# 49. NESTED RESOURCE AUTH
Example:
```text
/projects/:projectId/tasks/:taskId
```
Verify that task actually belongs to project and user has rights to project/task.
---
# 50. PARENT/CHILD MISMATCH
An endpoint might load a task only by `taskId`, ignoring `projectId`.
The route looks scoped, but authorization is not.
---
# 51. TENANT BOUNDARY
If multi-tenancy exists:
every query/write/cache must use tenant context.
---
# 52. TENANT ID FROM REQUEST
Client-provided tenant ID is not an authority.
It must be bound to the authenticated principal.
---
# 53. ADMIN ROUTES
Verify that having:
```text
/auth/admin/*
```
in the path name is not sufficient by itself.
Real role/capability verification must exist.
---
# 54. ROLE VS PERMISSION
If the system has granularity:
- role
- permission
- ownership
verify that the endpoint uses the proper level.
---
# 55. FIELD-LEVEL AUTHORIZATION
A user may be allowed to edit a resource, but not all fields.
Example:
- name yes
- ownerId no
- billingStatus no
---
# 56. RESPONSE FIELD AUTHORIZATION
The same resource may contain sensitive fields not meant for every caller.
---
# 57. AUTHORIZED WRITE, UNAUTHORIZED READ
Inspect asymmetric edge cases.
---
# 58. API VERSIONING
Determine whether there is:
- path version
- header version
- media type
- implicit unversioned API
---
# 59. VERSIONING IS NOT MANDATORY BY DEFAULT
A small internal API can legitimately be unversioned.
Severity depends on external client compatibility requirements.
---
# 60. BREAKING CHANGE
Identify:
- field rename
- type change
- enum removal
- endpoint removal
- semantics change
---
# 61. ADDITIVE CHANGE
Adding an optional response field is often backward-compatible.
However, strict client parsers can alter that reality.
---
# 62. ENUM EVOLUTION
A new enum value can break a client expecting an exhaustive list.
---
# 63. REQUIRED REQUEST FIELD
Adding a new required field can break older clients.
---
# 64. OLD CLIENT
For mobile/public APIs ask:
> Does the backend still work with a client that is several months old?
---
# 65. DEPRECATION
If an endpoint is being sunset:
verify plan and usage.
---
# 66. PAGINATION
For collection endpoints determine:
- offset
- cursor
- keyset
- none
---
# 67. UNBOUNDED COLLECTION
If a dataset can grow, an endpoint without limits can become a production risk.
---
# 68. LIMIT BOUNDS
Client must not be allowed to request:
```text
limit=10000000
```
if that can exhaust backend resources.
---
# 69. NEGATIVE PAGE/LIMIT
Validation.
---
# 70. STABLE ORDERING
Pagination requires deterministic ordering.
---
# 71. OFFSET PAGINATION
If data changes between page requests:
there may arise:
- duplicates
- missing items
Evaluate the use case.
---
# 72. CURSOR
Cursor must be:
- validated
- stable
- opaque if internal details should not be exposed
---
# 73. CURSOR TAMPERING
If cursor contains user-controlled decoded parameters, verify validation.
---
# 74. SORTING
Whitelist sort fields.
Never insert raw `sort` directly into SQL.
---
# 75. SORT DIRECTION
Validate:
```text
asc
desc
```
---
# 76. FILTERS
Map supported filter semantics.
---
# 77. SEARCH
Verify:
- length bounds
- normalization
- DB cost
- user-visible semantics
---
# 78. DATE FILTER
Verify:
- inclusive/exclusive boundaries
- timezone
- invalid range
---
# 79. `from > to`
Business validation must reject or define behavior.
---
# 80. CACHING
REST endpoints can use:
- Cache-Control
- ETag
- Last-Modified
- CDN
Verify only where caching actually exists.
---
# 81. PRIVATE RESPONSE CACHE
Authenticated responses must not accidentally be shared-cached across users.
---
# 82. CACHE KEY
If response depends on:
- Authorization
- tenant
- locale
cache must respect that.
---
# 83. ETAG
If optimistic conditional updates exist:
verify `If-Match` semantics.
---
# 84. 304
For conditional GET verify response behavior.
---
# 85. IDEMPOTENCY
Classify endpoint:
```text
SAFE
IDEMPOTENT
NON-IDEMPOTENT
CONDITIONALLY IDEMPOTENT
```
---
# 86. POST RETRY
For critical POST:
```text
request commits
↓
response lost
↓
client retries
```
Analyze duplicate consequences.
---
# 87. PAYMENT / ORDER / BOOKING
These especially require idempotency analysis.
---
# 88. IDEMPOTENCY KEY STORAGE
If present:
verify:
- TTL
- user scope
- endpoint scope
- payload consistency
- persistence
---
# 89. SAME KEY DIFFERENT PAYLOAD
Must have defined response.
One key must never silently return the result of an entirely different operation.
---
# 90. IN-MEMORY IDEMPOTENCY
Not sufficient for multi-instance deployments or restarts if guarantees must be durable.
---
# 91. CONDITIONAL UPDATE
For concurrent edits verify:
- version
- ETag
- updatedAt
- DB atomicity
---
# 92. LOST UPDATE
Scenario:
```text
Client A reads version 1
Client B reads version 1
A updates
B updates
```
If B blindly overwrites A, verify whether that is acceptable.
---
# 93. PUT/PATCH RACE
HTTP method alone does not solve concurrency.
---
# 94. DELETE VS UPDATE RACE
Simulate:
```text
A delete
B update
```
Which final state is permitted?
---
# 95. CREATE DUPLICATE
Business unique constraints must prevent duplicates even if the client omits an idempotency key where domain requires uniqueness.
---
# 96. ERROR RETRYABILITY
For each error code ask:
```text
Should client retry?
```
---
# 97. VALIDATION ERROR
It makes no sense to automatically retry an identical payload.
---
# 98. RATE LIMIT
Retry can make sense after an appropriate cooldown period.
---
# 99. SERVER ERROR
Transient candidate, but not every 500 should be retried infinitely.
---
# 100. TIMEOUT
For write timeouts:
outcome can be unknown.
---
# 101. ASYNC API
If an endpoint starts long-running work:
verify pattern:
```text
POST /jobs
↓
202 + jobId
↓
GET /jobs/:id
```
or other documented pattern.
---
# 102. FAKE ASYNC
An endpoint returning 200 "success" immediately while work can subsequently fail permanently can mislead the client.
---
# 103. JOB STATUS
Verify:
- pending
- running
- success
- failed
---
# 104. POLLING
If client polls status:
verify rate and expiration.
---
# 105. CALLBACK / OUTBOUND WEBHOOK
If API subsequently notifies client via webhook:
verify reliability and idempotency.
---
# 106. LONG-RUNNING HTTP
If an endpoint keeps HTTP requests open for minutes:
verify proxy/server timeouts and resource costs.
---
# 107. FILE DOWNLOAD
Verify:
- authorization
- content type
- content disposition
- range requests where needed
- streaming
---
# 108. FILE NAME
User-controlled filename in Content-Disposition must be securely encoded and sanitized.
---
# 109. RANGE
For media or large downloads, Range support can be critical.
Do not require Range for small JSON/file endpoints without reason.
---
# 110. UPLOAD
For multipart:
verify:
- size limit
- file count
- field limits
- streaming
- cleanup
---
# 111. EMPTY FILE
Validation according to domain.
---
# 112. MULTIPLE FILES
Verify total size limit, not just per-file limit.
---
# 113. PARTIAL UPLOAD
If connection drops:
temporary file cleanup.
---
# 114. CONTENT TYPE
Client-provided header is not sufficient security proof.
---
# 115. URL INPUT
If API accepts URLs:
this can be an SSRF attack surface.
Full security audit later, but map trust boundary now.
---
# 116. CALLBACK URL
Same.
---
# 117. REDIRECT URL
Auth/payment redirect URLs must be whitelisted according to the business/security model.
---
# 118. HOST HEADER
If API builds absolute URLs from the Host header:
verify trusted proxy and host validation.
---
# 119. PROXY
Determine:
- forwarded proto
- forwarded host
- forwarded for
- trust proxy configuration
---
# 120. CLIENT IP
If rate limiting or auditing uses IP, verify that attacking clients cannot spoof trusted forwarding headers.
---
# 121. CORS
Map:
- allowed origins
- credentials
- methods
- headers
Remember:
CORS is not API authorization.
---
# 122. WILDCARD + CREDENTIALS
Check framework behavior.
---
# 123. PREFLIGHT
OPTIONS requests must not accidentally require the same auth as business requests if browser integration prevents it.
---
# 124. CSRF
If API uses cookies/sessions:
verify CSRF protection.
---
# 125. BEARER TOKEN
If credentials are not browser-ambient, CSRF threat model is different.
---
# 126. COOKIE ATTRIBUTES
If cookie auth exists:
- Secure
- HttpOnly
- SameSite
according to architecture.
---
# 127. CONTENT NEGOTIATION
If API claims to be JSON-only:
verify Content-Type handling.
---
# 128. INVALID JSON
Must yield controlled 4xx, not a generic crash or 500.
---
# 129. BODY SIZE
JSON body must have reasonable bounds per endpoint.
---
# 130. DECOMPRESSION
If server accepts compressed requests, check decompression bomb risk where relevant.
---
# 131. SERIALIZATION
Response serialization can fail due to:
- circular references
- unsupported types
- BigInt
- dates
depending on stack.
---
# 132. BIG INTEGER
JavaScript backends can suffer precision loss on large integer IDs from DB.
Verify actual stack.
---
# 133. DATE FORMAT
API must use a stable canonical representation.
Verify timezone and offset handling.
---
# 134. DECIMAL
Financial decimal values must not carelessly pass through binary floating point if precision has business significance.
---
# 135. NULL
Response schema must clearly distinguish:
- field absent
- field null
if clients depend on this difference.
---
# 136. BOOLEAN STRING
Look for inconsistencies:
```json
{"active": "true"}
```
vs:
```json
{"active": true}
```
---
# 137. OPENAPI
If OpenAPI exists:
compare spec against actual routes.
---
# 138. DOCUMENTED, NOT IMPLEMENTED
Endpoint or spec may promise fields or statuses that runtime code never returns.
---
# 139. IMPLEMENTED, NOT DOCUMENTED
Public API drift.
---
# 140. REQUIRED FIELD DRIFT
OpenAPI states required, code does not demand it or vice versa.
---
# 141. TYPE DRIFT
Spec integer, runtime string.
---
# 142. STATUS CODE DRIFT
Spec 404, runtime 200/null.
---
# 143. SECURITY SCHEME DRIFT
Spec claims auth required, route is public or vice versa.
---
# 144. CONTRACT TESTING
If API serves multiple clients:
contract testing can carry major value.
Do not demand enterprise tooling without need.
---
# 145. CLIENT GENERATION
If clients use generated SDKs from OpenAPI:
spec drift becomes significantly more severe.
---
# 146. BACKWARD COMPATIBILITY
For every change ask:
> Does the old client continue to function?
---
# 147. FIELD REMOVAL
Most common breaking response change.
---
# 148. TYPE CHANGE
Example:
```text
id: integer
```
becomes:
```text
id: string
```
can break clients.
---
# 149. ENUM
Unknown enum handling must be factored in.
---
# 150. ERROR CHANGE
Changing an error code can be breaking if clients implement specific UX flows around it.
---
# 151. PAGINATION CHANGE
Offset -> cursor may require versioning or a compatible transition phase.
---
# 152. DEFAULT SORT CHANGE
Can be user-visible breaking behavior even without schema alteration.
---
# 153. DEFAULT VALUE CHANGE
Same.
---
# 154. BOOLEAN DEFAULT
Omitted field can change semantics following a backend release.
---
# 155. FIELD SEMANTICS
The most dangerous breaking change preserves the data type but alters the meaning.
---
# 156. RATE LIMITING
Map:
- global
- user
- IP
- endpoint
- tenant
---
# 157. LIMIT RESPONSE
Verify status code and retry signaling.
---
# 158. LOGIN LIMIT
Authentication endpoints require abuse protection according to the threat model.
---
# 159. EXPENSIVE ENDPOINT
Search, export, and reports may require stricter capacity controls.
---
# 160. RATE LIMIT BYPASS
If rate limiting relies on spoofable headers:
problem.
---
# 161. DISTRIBUTED RATE LIMIT
In-memory limiting is not global across multiple instances.
It can still serve as useful local defense, but do not present it as a global guarantee.
---
# 162. CACHE + RATE LIMIT
Cache hits and misses can carry drastically different backend costs.
---
# 163. API TIMEOUTS
For each critical endpoint determine:
- server timeout
- reverse proxy timeout
- downstream timeout
---
# 164. CLIENT TIMEOUT SHORTER THAN SERVER
If client gives up after 10 s while backend continues 60 s expensive work, wasted processing accumulates.
---
# 165. SERVER TIMEOUT SHORTER THAN DOWNSTREAM
Illogical timeout budget.
---
# 166. CANCELLATION
If HTTP request disconnects:
does DB/network work continue?
Correct behavior depends on operation semantics.
---
# 167. MUTATION CANCELLATION
Do not cancel durable critical mutations blindly when a client disconnects.
---
# 168. READ CANCELLATION
Expensive reads can often be safely cancelled.
---
# 169. TRACEABILITY
For serious API errors it is valuable to have:
- request ID
- trace ID
If present, verify consistent logging and propagation.
---
# 170. REQUEST ID SPOOFING
If client supplies its own ID, server should validate or generate an internal ID so logs cannot be easily manipulated.
---
# 171. OBSERVABILITY
For each endpoint it should be possible to observe:
- latency
- errors
- status codes
- throughput
where production maturity warrants it.
---
# 172. HIGH CARDINALITY METRICS
Do not insert:
- user ID
- raw URL
- email
as metric labels without understanding cardinality and privacy impacts.
---
# 173. LOGGING
Do not log entire request/response bodies without sanitization.
---
# 174. AUTH HEADER
Never plain-text in logs.
---
# 175. COOKIE
Same.
---
# 176. PASSWORD
Same.
---
# 177. PAYMENT DATA
Same.
---
# 178. HEALTH ENDPOINT
If present:
verify it does not expose:
- secrets
- internal topology
- verbose stacks
---
# 179. DEBUG ENDPOINT
Look for:
```text
/debug
/test
/internal
/admin/dev
```
in production routes.
---
# 180. DOCUMENTATION ENDPOINT
Swagger UI in production is not automatically a vulnerability.
However, verify:
- sensitive internal APIs
- auth
- product policy
---
# 181. GraphQL / RPC ALONGSIDE REST
If backend provides multiple API paradigms:
verify that identical business rules are not implemented inconsistently.
---
# 182. LEGACY ENDPOINT
Older endpoints may carry weaker validation or auth logic.
---
# 183. DUPLICATE BUSINESS OPERATIONS
If there exists:
```text
POST /users/:id/activate
```
and:
```text
PATCH /users/:id { active: true }
```
verify that both enforce identical rules.
---
# 184. ADMIN BYPASS
Internal/admin APIs must not mutate DB directly if that bypasses critical invariants without clear intent.
---
# 185. BULK API
Bulk create/update/delete requires dedicated analysis.
---
# 186. BULK PARTIAL FAILURE
Define:
- all-or-nothing
- per-item result
- stop on first failure
---
# 187. BULK RESPONSE
Client must know which items succeeded.
---
# 188. BULK AUTHORIZATION
Each item must be authorized, not just the first one or parent collection.
---
# 189. BULK SIZE LIMIT
Do not permit unlimited item counts.
---
# 190. BULK TRANSACTION
Do not wrap massive batch operations in a single transaction without evaluating lock and time impacts.
---
# 191. EXPORT API
If generating large reports:
verify:
- sync vs async
- memory
- authorization
- expiration
---
# 192. IMPORT API
Verify:
- schema
- duplicate handling
- transaction
- partial failure
- idempotency
---
# 193. SOFT DELETE API
Verify how list and detail endpoints treat deleted resources.
---
# 194. RESTORE API
If a resource can be restored:
verify conflict resolution with newer resources occupying the same unique key.
---
# 195. ARCHIVE
Archive semantics should be distinguished from delete if product differentiates them.
---
# 196. STATE MACHINE ENDPOINTS
If resource has lifecycle:
```text
DRAFT
SUBMITTED
APPROVED
REJECTED
```
verify allowed transitions.
---
# 197. INVALID TRANSITION
Endpoint must not permit:
```text
REJECTED -> APPROVED
```
if domain disallows it.
---
# 198. CONCURRENT TRANSITION
Two requests can attempt divergent transitions from the same state.
Requires DB-level/atomic protection.
---
# 199. APPROVAL
Authorization may depend on current state.
---
# 200. STATE TRANSITION AUDIT LOG
High-value workflows may require audit trails.
---
# 201. IDEMPOTENT COMMAND
Repeated:
```text
POST /orders/:id/cancel
```
can legitimately return "already cancelled" without repeating side effects.
---
# 202. SIDE EFFECTS
Map whether API requests trigger:
- email
- notification
- event
- payment
- webhook
- file operations
---
# 203. RESPONSE BEFORE SIDE EFFECT
If API returns success prior to durable enqueueing of a critical side effect:
work can be lost.
---
# 204. RESPONSE AFTER NON-CRITICAL SIDE EFFECT
If request blocks waiting for email provider, it unnecessarily inflates latency and failure surface.
---
# 205. ATOMICITY
For each endpoint ask:
> What minimal part must be atomic for client success to remain truthful?
---
# 206. RETRY SAFETY
For each write endpoint ask:
> Can the exact same request safely arrive again?
---
# 207. PROXY RETRY
Not only clients.
Reverse proxies, gateways, or service meshes can sometimes retry requests.
Verify platform configuration before asserting.
---
# 208. MOBILE RETRY
Mobile clients may retry following a timeout even though the server operation actually succeeded.
---
# 209. DOUBLE CLICK
Frontend can dispatch two duplicate requests.
Backend must protect critical invariants without relying on disabled UI buttons.
---
# 210. CONTRACT MATRIX
For critical endpoints construct:
| Route | Input | Success | Errors | Idempotency | Compatibility risk |
|---|---|---|---|---|---|
---
# 211. AUTHORIZATION MATRIX
| Route | Principal | Resource ownership | Role/permission | Verified |
|---|---|---|---|---|
---
# 212. STATUS MATRIX
| Scenario | Expected HTTP | Actual | Consistent |
|---|---|---|---|
---
# 213. IDEMPOTENCY MATRIX
| Endpoint | Retry possible | Duplicate consequence | Protection | Risk |
|---|---|---|---|---|
---
# 214. PAGINATION MATRIX
| Endpoint | Method | Max size | Stable order | Cursor/offset | Risk |
|---|---|---|---|---|---|
---
# 215. VERSIONING MATRIX
| Contract | Old clients | New clients | Breaking risk | Status |
|---|---|---|---|---|
---
# 216. TESTS
Review:
- route tests
- integration tests
- auth tests
- validation tests
- OpenAPI tests
- concurrency tests
---
# 217. HAPPY PATH TEST IS NOT ENOUGH
Critical endpoints need failure coverage.
---
# 218. AUTH MATRIX TEST
For sensitive routes test:
```text
unauthenticated
wrong user
correct user
admin
```
where relevant.
---
# 219. VALIDATION TEST
Test boundaries:
- empty
- null
- max
- malformed
- unknown enum
---
# 220. IDEMPOTENCY TEST
Send the exact same request twice.
---
# 221. CONCURRENT TEST
Send conflicting requests in parallel.
---
# 222. PAGINATION TEST
Test duplicate sort values and data mutations across pages.
---
# 223. OPENAPI CONTRACT TEST
If spec exists, verify runtime responses conform to spec.
---
# 224. OLD CLIENT CONTRACT TEST
If fixtures or generated clients of older versions exist, utilize them.
---
# 225. FINDING FORMAT
Every serious finding must include:
```text
ID:
Severity:
Category:
Confidence:
Status:
Method:
Route:
Authentication:
Authorization:
Request schema:
Response schema:
File:
Handler:
Relevant code:
Problem:
Evidence:
HTTP Flow:
Request:
Server processing:
Response:
Reproduction:
Expected HTTP behavior:
Actual/Possible behavior:
Security impact:
Data impact:
Client compatibility impact:
Retry/idempotency impact:
Root cause:
Recommended remediation:
Regression/contract test:
Runtime verification:
Complexity:
XS / S / M / L / XL
```
---
# 226. SEVERITY
Use:
## P0 - CRITICAL
- cross-user/tenant private data access
- privilege escalation via API
- duplicate irreversible financial action
- exposed critical secret
## P1 - HIGH
- critical IDOR
- common retry creates duplicate business effect
- major contract flaw breaks primary client flow
- data corruption via concurrent API usage
- severe auth/authorization inconsistency
## P2 - MEDIUM
- significant API correctness problem
- inconsistent error/status behavior with real client impact
- pagination/versioning bug with serious consequences
## P3 - LOW
- limited contract edge case
- minor inconsistency
## P4 - IMPROVEMENT
- API design/maintainability/documentation improvement without confirmed functional failure
---
# 227. CONFIDENCE
Use:
```text
HIGH
MEDIUM
LOW
```
HIGH:
route + handler + data layer directly confirm scenario.
MEDIUM:
strong evidence, but production proxy/client behavior not verified.
LOW:
depends on external API gateway/client contract not accessible.
---
# 228. STATUS
Use:
```text
CONFIRMED
LIKELY
THEORETICAL
NOT VERIFIED
```
---
# 229. FALSE-POSITIVE PREVENTION
Before any P0/P1/P2 finding, verify:
1. route
2. middleware
3. request validator
4. auth
5. authorization
6. service
7. DB constraint
8. response serializer
9. API spec
10. tests
Do not conclude from route files alone simply because authorization is absent in the handler.
---
# 230. DO NOT ENFORCE "PURE REST"
An RPC-like command route can be superior to an unnatural PATCH model.
Example:
```text
POST /orders/:id/cancel
```
can be clearer than:
```text
PATCH /orders/:id
{"status":"cancelled"}
```
if cancellation has business rules and side effects.
---
# 231. DO NOT DEBATE ENDLESSLY ABOUT 400 VS 422
If the contract is consistent and clients operate properly:
this is secondary.
---
# 232. DO NOT INTRODUCE VERSIONING UNNECESSARILY
If API has only one tightly coupled client and no compatibility issues:
versioning can be P4.
---
# 233. DO NOT ADD RESPONSE ENVELOPE JUST FOR STYLE
```json
{"data": ...}
```
is not automatically better than direct resource representation.
---
# 234. DO NOT ADD HATEOAS AUTOMATICALLY
Do not require hyperlinks in every API response unless the product genuinely benefits.
---
# 235. DO NOT MODIFY CODE
During audit:
- do not change routes
- do not change status codes
- do not add versioning
- do not change schemas
- do not add idempotency keys
- do not change auth
Finish the audit first.
---
# 236. OUTPUT - REST_API_FORENSIC_AUDIT.md
Structure the final report:
## 1. Executive Summary
- API stack
- route count
- auth model
- contract quality
- highest risks
- production readiness
## 2. Route Inventory
## 3. HTTP Method / Resource Semantics
## 4. Request Validation Audit
## 5. Response Contract Audit
## 6. Error Contract Audit
## 7. Authentication Coverage
## 8. Authorization / IDOR Audit
## 9. Tenant Isolation Audit
## 10. Status Code Audit
## 11. Pagination Audit
## 12. Filter / Sort / Search Audit
## 13. Idempotency Audit
## 14. Concurrency / Lost Update Audit
## 15. Async Operations Audit
## 16. Upload / Download API Audit
## 17. Caching / Conditional Request Audit
## 18. CORS / CSRF / Proxy Context
## 19. API Versioning / Compatibility
## 20. OpenAPI / Documentation Drift
## 21. Observability
## 22. Testing Coverage
## 23. Findings Summary
| ID | Severity | Method/Route | Category | Problem | Confidence | Status |
|---|---|---|---|---|---|---|
## 24. P0 Findings
## 25. P1 Findings
## 26. P2 Findings
## 27. P3 Findings
## 28. P4 Improvements
## 29. Things Done Well
## 30. Unknown / Not Verified
## 31. Remediation Roadmap
---
# 237. SECOND PASS - UNAUTHENTICATED ATTACK
For each non-public route strip authentication.
Ask:
> Which middleware specifically rejects the request?
---
# 238. SECOND PASS - WRONG USER ATTACK
For each resource ID imagine:
```text
authenticated User B
↓
sends ID belonging to User A
```
Ask:
> Where is ownership checked?
---
# 239. SECOND PASS - FIELD TAMPERING
For each write request add unexpected fields:
```json
{
"role": "admin",
"ownerId": "other-user",
"status": "paid"
}
```
Ask what the backend does.
---
# 240. SECOND PASS - DUPLICATE REQUEST
For each critical POST/PATCH:
```text
request A
request A again
```
concurrently and following a lost response.
---
# 241. SECOND PASS - CONCURRENT REQUEST
Execute:
```text
Request A
Request B
```
against the same resource.
Ask whether an update is lost or an invariant violated.
---
# 242. SECOND PASS - INVALID INPUT
For each parameter test:
- null
- empty
- oversized
- malformed
- unsupported enum
- wrong type
---
# 243. SECOND PASS - PAGINATION MUTATION
Scenario:
```text
client fetches page 1
↓
new record inserted
↓
client fetches page 2
```
Ask whether offset pagination can:
- skip
- duplicate
items.
---
# 244. SECOND PASS - OLD CLIENT
Retain older request/response expectations.
Apply current backend.
Search for breaking changes.
---
# 245. SECOND PASS - TIMEOUT RETRY
Critical write:
```text
request sent
↓
server succeeds
↓
response delayed/lost
↓
client timeout
↓
retry
```
Ask what gets duplicated.
---
# 246. SECOND PASS - PROXY
If backend is deployed behind proxy/gateway:
verify:
- host
- proto
- client IP
- timeout
- body size
---
# 247. SECOND PASS - BULK
If bulk endpoints exist:
simulate one invalid item in the middle of a batch.
Ask what remains committed.
---
# 248. SECOND PASS - ASYNC
For 202/job endpoints:
simulate:
```text
accepted
↓
job permanently fails
```
Ask how the client discovers the failure.
---
# 249. SECOND PASS - API SPEC
Compare each critical route against OpenAPI spec if present.
Search for silent drift.
---
# 250. SECOND PASS - ERROR CONTRACT
For each failure type ask:
> Can the client reliably distinguish what action to take?
For example:
- fix input
- login
- ask permission
- retry
- stop retrying
- show conflict
---
# 251. FINAL QUALITY GATE
Before final response verify:
- all critical routes are inventoried
- GET side effects are verified
- auth and authorization are not conflated
- IDOR is checked against real resource ownership
- nested route parent-child relations are verified
- mass assignment is analyzed
- response fields do not accidentally expose internal/sensitive data
- status code findings have real client impact
- error codes are analyzed as machine contracts
- pagination has stable ordering
- unbounded list endpoints have real growth context
- critical POST/PATCH have retry/idempotency analysis
- concurrency is not inferred from HTTP method alone
- timeout write scenarios include unknown outcome
- bulk endpoints have partial failure semantics
- 202 has a mechanism to trace final outcomes
- OpenAPI is compared against runtime code where present
- old client compatibility is analyzed where critical
- proxy/CORS/CSRF are not confused with authorization
- pure REST aesthetics are not prioritized over correctness
- P4 design improvements are clearly segregated from real bugs
---
# FINAL RULE
I do not want a report like:
> Use proper HTTP methods, status codes, pagination, and OpenAPI.
That is not a REST API audit.
I am looking for problems like:
```text
PATCH /users/:id
↓
authentication verifies caller
↓
handler loads user by :id
↓
no ownership/role check
↓
ordinary user can modify another account
```
or:
```text
POST /payments
↓
payment succeeds
↓
response lost
↓
client retries same POST
↓
server has no idempotency protection
↓
payment is charged twice
```
or:
```text
GET /reports/export
↓
endpoint creates export record
↓
browser prefetch/crawler hits URL
↓
server creates report without explicit user action
```
or:
```text
PATCH /profile
{
"name": "Zoran",
"role": "admin"
}
↓
request body passed directly into ORM update
↓
role changes because field was not whitelisted
```
or:
```text
GET /projects/A/tasks/B
↓
caller may access project A
↓
task B actually belongs to project C
↓
handler loads B only by task ID
↓
parent project scope is never verified
```
or:
```text
GET /items?page=1
↓
new item inserted at top
↓
GET /items?page=2
↓
offset shifted
↓
client receives duplicate item and misses another
```
or:
```text
POST /jobs
↓
server returns 200 "success"
↓
job runs asynchronously
↓
job permanently fails
↓
client has no job ID or failure channel
↓
user believes operation completed
```
These are the REST API problems you need to find.
Think through:
- HTTP semantics
- resource identity
- trust boundary
- authorization
- validation
- stable contracts
- retry
- idempotency
- concurrency
- pagination
- old clients
- proxy/runtime behavior
For each serious finding you must be able to answer:
> Which exact HTTP request triggers the problem?
> Which principal sends it?
> Which resource is affected?
> Which status/body does the client receive?
> What happens if the exact same request arrives twice?
> What happens if two clients mutate the same resource concurrently?
> Does the old client still understand the response?
If not provable:
**NOT VERIFIED.**
If it is merely REST style without real impact:
**P4 - IMPROVEMENT.**
It is better to find 6 real contract/auth/idempotency problems than to write 100 academic REST recommendations.
The goal is to produce a forensically precise REST API audit from which each serious finding can be directly converted into:
- reproduction request
- integration test
- authorization fix
- schema/contract correction
- idempotency protection
- concurrency regression test
- compatibility safeguard
- production API hardening plan分类与标签
编程开发、REST接口审计、API安全、后端开发