Minecraft-Console-Client/.skills/dotnet-security-review/references/architecture-checks.md

Architecture & Project-Specific Checks Reference

Phase 3 checks for common ASP.NET Core project patterns. Read the project's CLAUDE.md

or AGENTS.md for project-specific details (endpoint list, service names, DI registrations)

to inform these checks.

Check 1: Endpoint Auth Matrix Verification

Cross-reference the controller's actual [Authorize]/[AllowAnonymous] attributes against the project's documented auth requirements. Read CLAUDE.md or AGENTS.md for the expected auth matrix. Any mismatch is CRITICAL.

For projects with multiple auth schemes (e.g., Azure AD + custom JWT), verify each endpoint uses the correct scheme/policy.

Check 2: Anonymous Endpoint Abuse Potential

For each [AllowAnonymous] endpoint, verify:

• Rate limiting or throttling exists for sensitive operations (e.g., code generation, login attempts)
• Enumeration attacks are mitigated (IDs are GUIDs or non-sequential, not auto-increment)
• No state modification without prior authentication or verification (e.g., OTP first)

Check 3: OTP / MFA Security Review

If the project implements OTP or MFA, read the service implementation and verify:

• Code length is sufficient (6+ characters)
• Codes are generated with RandomNumberGenerator
• Hash is SHA-256 or stronger (not MD5/SHA1)
• Expiry is enforced (typically 5-10 minutes)
• Wrong attempt counter increments correctly and triggers lockout after a threshold
• No timing side-channel in hash comparison

Check 4: Exception Handling Coverage

Grep for throw new statements. Verify that all thrown exceptions are either:

• The project's structured error type (e.g., ApiException, DomainException, or the project's custom base exception), OR
• Known typed exceptions for external service failures

Any unstructured exception thrown from handler/service code may bypass error filters and leak internal details.

Check 5: Optimistic Concurrency on State Writes

If using a database with optimistic concurrency (ETags, row versions):

• Verify every write/update operation passes the concurrency token
• Verify the concurrency token store/tracking mechanism is consulted on every read/write cycle

Check 6: Expired State Handling

If the project uses application-level state expiry (not DB TTL):

• Verify expired records are deleted or excluded on read (not returned to callers)
• Verify callers cannot act on expired data

Check 7: Blob Storage SAS URL Security

If the project generates SAS URLs for blob storage:

• SAS token expiry is short-lived (minutes, not days)
• Permission is read-only (not write/delete)
• Scoped to the specific blob (not container-level)

Check 8: Message Queue Security

If the project uses message queues (Service Bus, RabbitMQ, etc.):

• Messages do not contain secrets or unnecessary PII
• Queue connections use managed identity or connection strings from secret stores

Check 9: JSON Serialization Settings

Check that TypeNameHandling is set to None (default) and not Auto/All anywhere. This applies to both Newtonsoft.Json and any custom serializer configuration.

Check 10: Background Task Queue Safety

If the project uses a background task queue:

• Bounded capacity prevents unbounded memory growth
• Backpressure is handled correctly (not silently dropping critical events like audit logs)
• Task failures are observed and logged/metered

Check 11: Custom Token / JWT Security

If the project issues its own JWTs (not just validating external tokens):

• Algorithm: HMAC-SHA256 or stronger (RSA for distributed validation)
• Signing key source: Key loaded from configuration/secret store, NOT hardcoded
• Signing key length: Minimum 256 bits (32 bytes) for HMAC-SHA256
• Token expiry: Appropriately capped (tokens should not outlive the session/resource they protect)
• Claims validation: Custom claims (e.g., resource IDs) are validated against route parameters by an authorization handler
• TokenValidationParameters: ValidateIssuer, ValidateAudience, ValidateLifetime, ValidateIssuerSigningKey all true
• ClockSkew: Tightened from default 5 minutes to 2 minutes or less

Check 12: Response Data Sanitization

If the project sanitizes response data (e.g., stripping internal paths or fields):

• Sanitization handles malformed input gracefully (does not throw/crash)
• Only known sensitive fields are stripped (no over-stripping that breaks functionality)
• Sanitization is applied on every code path returning the data (not just the happy path)

Check 13: Rate Limiting

Verify rate limiting posture:

• Grep for AddRateLimiter and UseRateLimiter -- if absent, note as finding
• Application-level throttling exists for sensitive operations (e.g., SMS/code generation resend limits)
• Brute force protection exists for verification endpoints (wrong attempt lockout)
• Recommendation: Add ASP.NET Core System.Threading.RateLimiting middleware for IP-based throttling on public endpoints

Check 14: Security Headers Completeness

Check Program.cs / middleware for these headers (report missing ones):

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• Referrer-Policy: strict-origin-when-cross-origin
• Permissions-Policy: camera=(), microphone=(), geolocation=()
• X-XSS-Protection: 0 (disable legacy XSS filter; CSP is the modern replacement)
• Content-Security-Policy (at minimum for APIs: default-src 'none')
• Server header removed
• X-Powered-By header removed

Check 15: Middleware Pipeline Ordering

Read Program.cs and verify correct middleware order:

1. UseExceptionHandler (outermost -- catches everything)
2. UseHsts (non-development only)
3. UseHttpsRedirection
4. Security headers middleware
5. UseRateLimiter (if present)
6. UseRouting (if explicit)
7. UseCors
8. UseAuthentication
9. UseAuthorization
10. MapControllers / endpoints

Authentication MUST come before Authorization. CORS MUST come before Authentication. ExceptionHandler MUST be first.

Check 16: NuGet Audit & Build Security

Check for build-level security configuration:

• Does Directory.Build.props exist? If so, verify NuGetAudit, NuGetAuditMode, NuGetAuditLevel settings.
• Are Roslyn security analyzer packages referenced? (SecurityCodeScan.VS2019, SonarAnalyzer.CSharp, Meziantou.Analyzer)
• Are AnalysisLevel / AnalysisMode set in .csproj or Directory.Build.props?
• Run Grep for floating versions: Version="[^"]*\*" in .csproj files
• Recommend dotnet list package --vulnerable --include-transitive as a CI step