codeguard-security-api

Interface Security Specification (Privilege Escalation · Data Permissions · File Upload · Signature)

Basis: PartMe.AI Development Specification "Interface Security Specification". Two major categories of common vulnerabilities:Privilege escalation bypass、File upload vulnerabilities。

I. Functional permission checks (prevent privilege escalation)

Login control

• Single-device login, login environment detection, login anomaly detection

Interface authentication annotations (choose according to framework; AI must include when writing interfaces)

Shiro：

@RequiresAuthentication                    // 已认证
@RequiresUser                              // 已登录（含 rememberMe）
@RequiresGuest                             // 游客
@RequiresPermissions("sys:user:view")      // 单权限
@RequiresPermissions({"a", "b"}, logical = Logical.OR)   // 多权限任一
@RequiresRoles("admin")                    // 角色

Spring Security：

@PreAuthorize("isAuthenticated()")
@PreAuthorize("hasAuthority('sys:user:view')")
@PreAuthorize("hasAnyAuthority('a','b')")
@PreAuthorize("hasRole('ADMIN')")
@PreAuthorize("hasAnyRole('ADMIN','OPS')")

AI behavior: when writing create/update/delete/query interfaces, if the project already uses the above frameworks,mustadd authentication annotations; prompt if missing.

II. Data permission checks (prevent unauthorized data access)

• Request parameter checks: create, delete, update, and query interfaces validate data ownership parameters, such as @RequiresDataPermissions(validate fields such as school code) + DataScopeProvider local validation
• Returned data filtering: set data access scope by role/user, dynamically append filter conditions during queries

AI behavior: when writing query interfaces, pay attention to filtering tenantId / shopId / data ownership fields; do not return unfiltered full-table data.

III. File upload checks (three-layer control)

Layer	Control item
Frontend	Pre-upload callback validation: format whitelist (xls/doc/pdf/zip, etc.) + size (e.g., ≤50MB)
Backend	JSR303 Bean Validation-based extended annotations (e.g., @FileNotEmpty): non-null, extension whitelist, maximum size (e.g., ≤100MB), MIME type detection
Operations	Nginx client_max_body_size limit request body (default about 2MB, adjust as needed and reload)

Risk: no restriction on type/size/path/filename → attackers upload backdoors to obtain WebShell. Stored filenames must be renamed (UUID); user-controllable path concatenation is prohibited.

IV. Interface signature mechanism (extension)

Externally exposed sensitive interfaces use apikey + timestamp + signature：

1. Client:signature = HMAC(secret, apikey + timestamp + body)
2. Server: verify apikey is valid → timestamp is within the window (anti-replay) → recompute signature and compare
3. Recommended window ±5 minutes + nonce cache for anti-replay

V. AI self-check list (go through item by item when writing interfaces)

• Has authentication annotations (or authentication is already unified at the gateway layer)
• Queries involving data ownership have data permission filtering
• File upload has: whitelist + size limit + renamed storage
• External interfaces have signature/anti-replay
• Sensitive returned fields are masked (see Data Security skill)

Out of scope (when not to use)

• The main issues are static code style, dependency CVEs, or database encryption, which should be handed to the corresponding dedicated skills.
• Do not require proof of "no privilege escalation" based only on controller annotations; also trace service, query, and cache paths.
• Requires testing with real credentials or production personal data.

Standard Workflow

Step 1: Establish assets and trust boundaries

List identity sources, gateways, services, databases, object ownership, external callers, and file storage.

Step 2: Trace the request path

Verify authentication, functional permissions, and object-level authorization layer by layer from route to controller/service/query/response.

Step 3: Check input and uploads

Confirm schema, size, content type, file headers, renaming, storage path, execution permissions, and antivirus/quarantine policies.

Step 4: Verify failure paths

Cover unauthenticated, low-privilege, cross-tenant, replay, oversized files, forged MIME, and non-owner resources.

Step 5: Output remediation and test evidence

For each finding, list the trust boundary, exploitable preconditions, minimal fix, negative tests, and residual risk.

Rules

1. Ownership information such as tenant/user/role must not be trusted directly from client parameters.
2. Passing authentication does not mean passing object-level authorization.
3. Signature comparison must be constant-time, and both timestamp and nonce must be verified.
4. File extensions are not trustworthy evidence of type.

Gotchas

1. In-memory filtering after querying can leak side channels: scope should be restricted at the data source layer as much as possible.
2. Batch endpoints easily miss per-object authorization: ownership must be verified for each ID.
3. Cache keys can cause cross-tenant leaks: they must include a trusted tenant dimension.
4. File content and MIME can be inconsistent: magic bytes and safe parsing need to be checked.
5. Reverse proxy restrictions cannot replace application-layer validation。
6. Relying only on timestamps cannot prevent replay within the window: a nonce/idempotency key is also needed.

Load resources on demand

• Read references/rules/decision-contract.md and references/operations/evidence-playbook.md。
• Open only the examples in examples/ that match the current asset.