feat(security): Enforce Content Size Limits for resources and prompts (fixes #538 US-1) (#3251)

* feat(security): enforce content size limits for resources and prompts

Implement configurable content size validation to prevent DoS attacks
via oversized content submissions. Resources are limited to 100KB and
prompt templates to 10KB by default (configurable via environment
variables CONTENT_MAX_RESOURCE_SIZE and CONTENT_MAX_PROMPT_SIZE).

Validation occurs at the service layer before database operations,
returning 413 Payload Too Large with structured error details.

Closes #538

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(security): review fixes for content size limits PR

- Fix ResourceCreate.validate_content to remove MAX_CONTENT_LENGTH
  schema-level check (now handled by service layer, consistent with
  ResourceUpdate)
- Fix broken test assertions checking raw bytes in formatted messages
  (TestErrorMessageClarity was asserting "200000" in human-readable
  "195.3 KB" strings)
- Fix broken test_update_prompt_validation_and_integrity_errors which
  had its body accidentally deleted by the original PR
- Restore accidentally deleted assertions in test_list_resources and
  test_create_resource_endpoint
- Add global exception handler for ContentSizeError (defense-in-depth,
  consistent with existing handlers for ValidationError/IntegrityError)
- Add reset_content_security_service() for test isolation
- Remove "Made with Bob" watermark from test file
- Remove duplicate pytest import in integration tests
- Fix broken README link to non-existent migration guide
- Fix double-commented lines in .env.example

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix: resolve flake8 lint issues in content size limits PR

- Move noqa:DUO138 to the line flake8 reports (validators.py)
- Add Args/Returns to content_size_exception_handler docstring (DAR101/DAR201)

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(tests): update security tests for service-layer size validation

Content size validation moved from Pydantic schema to service layer
(returns 413 instead of 422). Update test_resource_create_content_validation
and test_zip_bomb_prevention to reflect that ResourceCreate no longer
rejects oversized content at schema level.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(security): address codex review findings for content size limits

1. Remove MAX_TEMPLATE_LENGTH check from SecurityValidator.validate_template
   so the configurable CONTENT_MAX_PROMPT_SIZE is not silently capped at 64KB
   by the schema-level validator (finding #1)

2. Add db.rollback() to ContentSizeError handlers in resource_service to
   prevent partial metadata mutations from being committed when content
   size validation fails after ORM fields are already updated (finding #2)

3. Include actual_size and max_size in admin route 413 responses to match
   the structured error contract used by API routes (finding #3)

4. Update security and validator tests that expected schema-level length
   rejection — size enforcement now happens at service layer

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* chore: fix trailing whitespace in test files

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* docs: add content size limits to configuration docs, securing guide, and Helm values

- docs/docs/manage/configuration.md: add Content Security section with
  env var table, scope note, and error response example
- docs/docs/manage/securing.md: add section 9 (Content Size Limits)
  to production security checklist, renumber subsequent sections
- charts/mcp-stack/values.yaml: add CONTENT_MAX_RESOURCE_SIZE and
  CONTENT_MAX_PROMPT_SIZE to gateway env config

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

---------

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
Co-authored-by: Suresh Kumar Moharajan <suresh.kumar.m@ibm.com>
Co-authored-by: Mihai Criveti <crivetimihai@gmail.com>

Author: 3 people

.env.example

@@ -97,6 +97,19 @@ ALLOW_PUBLIC_VISIBILITY=true
 # SSRF_BLOCKED_NETWORKS=["169.254.169.254/32","169.254.169.123/32","fd00::1/128","169.254.0.0/16","fe80::/10","100.64.0.0/10"]
 # The 100.64.0.0/10 range is Carrier-Grade NAT (CGNAT) which some cloud providers use
 
+# -----------------------------------------------------------------------------
+# Content Security - Size Limits
+# -----------------------------------------------------------------------------
+# Maximum content sizes (in bytes) to prevent DoS attacks via large uploads
+
+# Maximum size for resource content (default: 102400 = 100KB)
+# Resources exceeding this limit will be rejected with 413 Payload Too Large
+# CONTENT_MAX_RESOURCE_SIZE=102400
+
+# Maximum size for prompt templates (default: 10240 = 10KB)
+# Prompts exceeding this limit will be rejected with 413 Payload Too Large
+# CONTENT_MAX_PROMPT_SIZE=10240
+
 # =============================================================================
 # Project defaults (batteries-included overrides)
 # =============================================================================

README.md

@@ -748,6 +748,17 @@ These settings are enabled by default for security—only disable for backward c
 | `REQUIRE_TOKEN_EXPIRATION` | Require exp claim in tokens | `true` |
 | `PUBLIC_REGISTRATION_ENABLED` | Allow public user self-registration | `false` |
 
+### 🛡️ Content Security
+
+Content size limits prevent DoS attacks and ensure system stability:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CONTENT_MAX_RESOURCE_SIZE` | Maximum resource content size (bytes) | `102400` (100KB) |
+| `CONTENT_MAX_PROMPT_SIZE` | Maximum prompt template size (bytes) | `10240` (10KB) |
+
+**Note:** Size limits apply only to new create/update operations. Existing content is not retroactively validated.
+
 ### ⚙️ Project Defaults (Dev Setup)
 
 These values differ from code defaults to provide a working local/dev setup:

charts/mcp-stack/values.yaml

@@ -410,6 +410,12 @@ mcpContextForge:
     # SSRF_ALLOW_PRIVATE_NETWORKS: "false"
     # SSRF_ALLOWED_NETWORKS: '["10.96.0.0/12"]' # example only, adjust to your cluster CIDR
 
+    # ─ Content Security - Size Limits ─
+    # Maximum content sizes (bytes) to prevent DoS via oversized uploads.
+    # Exceeding these returns HTTP 413 Payload Too Large.
+    CONTENT_MAX_RESOURCE_SIZE: "102400"        # 100KB default (min 1KB, max 10MB)
+    CONTENT_MAX_PROMPT_SIZE: "10240"           # 10KB default (min 512B, max 1MB)
+
     # ─ Logging ─
     LOG_LEVEL: INFO                  # DEBUG, INFO, WARNING, ERROR, CRITICAL
     LOG_FORMAT: json                 # json or text format

docs/docs/manage/configuration.md

@@ -669,6 +669,31 @@ mcpContextForge:
     (`SSRF_ALLOW_LOCALHOST=true`, `SSRF_ALLOW_PRIVATE_NETWORKS=true`, `SSRF_DNS_FAIL_CLOSED=false`) so bundled test services can register without extra setup.
     Keep production deployments on strict SSRF values unless you explicitly need internal destination access.
 
+### Content Security - Size Limits
+
+Content size limits prevent DoS attacks and resource exhaustion from oversized content submissions. Validation occurs at the service layer before database writes and returns **HTTP 413 Payload Too Large** with structured error details.
+
+| Setting                      | Description                                      | Default   | Range           |
+| ---------------------------- | ------------------------------------------------ | --------- | --------------- |
+| `CONTENT_MAX_RESOURCE_SIZE`  | Maximum resource content size (bytes)            | `102400` (100KB) | 1KB – 10MB |
+| `CONTENT_MAX_PROMPT_SIZE`    | Maximum prompt template size (bytes)             | `10240` (10KB)   | 512B – 1MB |
+
+!!! note "Scope"
+    Size limits apply only to new create and update operations. Existing content is not retroactively validated.
+
+!!! example "Error Response"
+    Oversized content returns a structured 413 response:
+    ```json
+    {
+      "detail": {
+        "error": "Resource content size limit exceeded",
+        "message": "Resource content size (195.3 KB) exceeds maximum allowed size (100.0 KB)",
+        "actual_size": 200000,
+        "max_size": 102400
+      }
+    }
+    ```
+
 ### Ed25519 Certificate Signing
 
 ContextForge supports **Ed25519 digital signatures** for certificate validation and integrity verification.

docs/docs/manage/securing.md

@@ -425,7 +425,20 @@ The CI pipeline automatically verifies SRI hashes on every build to detect unexp
 - [x] Hashes use SHA-384 algorithm (W3C recommended)
 - [ ] Review SRI hashes after any CDN library updates
 
-### 9. Container Security
+### 9. Content Size Limits
+
+Configure content size limits to prevent DoS via oversized resource or prompt submissions:
+
+```bash
+# Defaults shown — adjust to your workload requirements
+CONTENT_MAX_RESOURCE_SIZE=102400  # 100KB for resources (range: 1KB–10MB)
+CONTENT_MAX_PROMPT_SIZE=10240     # 10KB for prompt templates (range: 512B–1MB)
+```
+
+- [ ] Review default size limits for your use case
+- [ ] Monitor 413 responses in logs for legitimate content being blocked
+
+### 10. Container Security
 
 ```bash
 # Run containers with security constraints
@@ -443,15 +456,15 @@ docker run \
 - [ ] Set resource limits (CPU, memory)
 - [ ] Scan images for vulnerabilities
 
-### 10. Secrets Management
+### 11. Secrets Management
 
 - [ ] **Never store secrets in environment variables directly**
 - [ ] Use a secrets management system (Vault, AWS Secrets Manager, etc.)
 - [ ] Rotate credentials regularly
 - [ ] Restrict container access to secrets
 - [ ] Never commit `.env` files to version control
 
-### 11. MCP Server Validation
+### 12. MCP Server Validation
 
 Before connecting any MCP server:
 
@@ -461,23 +474,23 @@ Before connecting any MCP server:
 - [ ] Monitor server behavior for anomalies
 - [ ] Implement rate limiting for untrusted servers
 
-### 12. Database Security
+### 13. Database Security
 
 - [ ] Use TLS for database connections
 - [ ] Configure strong passwords
 - [ ] Restrict database access by IP/network
 - [ ] Enable audit logging
 - [ ] Regular backups with encryption
 
-### 13. Monitoring & Logging
+### 14. Monitoring & Logging
 
 - [ ] Set up structured logging without sensitive data
 - [ ] Configure log rotation and secure storage
 - [ ] Implement monitoring and alerting
 - [ ] Set up anomaly detection
 - [ ] Create incident response procedures
 
-### 14. Integration Security
+### 15. Integration Security
 
 ContextForge should be integrated with:
 
@@ -487,7 +500,7 @@ ContextForge should be integrated with:
 - [ ] SIEM for security monitoring
 - [ ] Load balancer with TLS termination
 
-### 15. Well-Known URI Security
+### 16. Well-Known URI Security
 
 Configure well-known URIs appropriately for your deployment:
 
@@ -511,7 +524,7 @@ Security considerations:
 - [ ] Update security.txt Expires field before expiration
 - [ ] Consider custom well-known files only if necessary
 
-### 16. Downstream Application Security
+### 17. Downstream Application Security
 
 Applications consuming ContextForge data must:
 

mcpgateway/admin.py

@@ -125,6 +125,7 @@
 from mcpgateway.services.argon2_service import Argon2PasswordService
 from mcpgateway.services.audit_trail_service import get_audit_trail_service
 from mcpgateway.services.catalog_service import catalog_service
+from mcpgateway.services.content_security import ContentSizeError
 from mcpgateway.services.email_auth_service import AuthenticationError, EmailAuthService, PasswordValidationError
 from mcpgateway.services.encryption_service import get_encryption_service
 from mcpgateway.services.export_service import ExportError, ExportService
@@ -12100,6 +12101,9 @@ async def admin_add_resource(request: Request, db: Session = Depends(get_db), us
         if isinstance(ex, ResourceURIConflictError):
             LOGGER.error(f"ResourceURIConflictError in admin_add_resource: {ex}")
             return ORJSONResponse(content={"message": str(ex), "success": False}, status_code=409)
+        if isinstance(ex, ContentSizeError):
+            LOGGER.error(f"ContentSizeError in admin_add_resource: {ex}")
+            return ORJSONResponse(content={"message": str(ex), "success": False, "actual_size": ex.actual_size, "max_size": ex.max_size}, status_code=413)
         LOGGER.error(f"Error in admin_add_resource: {ex}")
         return ORJSONResponse(content={"message": str(ex), "success": False}, status_code=500)
 
@@ -12189,6 +12193,9 @@ async def admin_edit_resource(
         if isinstance(ex, ResourceURIConflictError):
             LOGGER.error(f"ResourceURIConflictError in admin_edit_resource: {ex}")
             return ORJSONResponse(status_code=409, content={"message": str(ex), "success": False})
+        if isinstance(ex, ContentSizeError):
+            LOGGER.error(f"ContentSizeError in admin_edit_resource: {ex}")
+            return ORJSONResponse(status_code=413, content={"message": str(ex), "success": False, "actual_size": ex.actual_size, "max_size": ex.max_size})
         LOGGER.error(f"Error in admin_edit_resource: {ex}")
         return ORJSONResponse(content={"message": str(ex), "success": False}, status_code=500)
 
@@ -12423,6 +12430,9 @@ async def admin_add_prompt(request: Request, db: Session = Depends(get_db), user
         if isinstance(ex, PromptArgumentsJSONError):
             LOGGER.error(f"PromptArgumentsJSONError in admin_add_prompt: {ex}")
             return ORJSONResponse(status_code=422, content={"message": str(ex), "success": False, "field": ex.field_name})
+        if isinstance(ex, ContentSizeError):
+            LOGGER.error(f"ContentSizeError in admin_add_prompt: {ex}")
+            return ORJSONResponse(status_code=413, content={"message": str(ex), "success": False, "actual_size": ex.actual_size, "max_size": ex.max_size})
         LOGGER.error(f"Error in admin_add_prompt: {ex}")
         return ORJSONResponse(content={"message": str(ex), "success": False}, status_code=500)
 
@@ -12524,6 +12534,9 @@ async def admin_edit_prompt(
         if isinstance(ex, PromptArgumentsJSONError):
             LOGGER.error(f"PromptArgumentsJSONError in admin_edit_prompt: {ex}")
             return ORJSONResponse(status_code=422, content={"message": str(ex), "success": False, "field": ex.field_name})
+        if isinstance(ex, ContentSizeError):
+            LOGGER.error(f"ContentSizeError in admin_edit_prompt: {ex}")
+            return ORJSONResponse(status_code=413, content={"message": str(ex), "success": False, "actual_size": ex.actual_size, "max_size": ex.max_size})
         LOGGER.error(f"Error in admin_edit_prompt: {ex}")
         return ORJSONResponse(content={"message": str(ex), "success": False}, status_code=500)
 

mcpgateway/common/validators.py

@@ -76,7 +76,9 @@
 _HTML_SPECIAL_CHARS_RE: Pattern[str] = re.compile(r'[<>"\']')  # / removed per SEP-986
 _DANGEROUS_TEMPLATE_TAGS_RE: Pattern[str] = re.compile(r"<(script|iframe|object|embed|link|meta|base|form)\b", re.IGNORECASE)
 _EVENT_HANDLER_RE: Pattern[str] = re.compile(r"on\w+\s*=", re.IGNORECASE)
-_MIME_TYPE_RE: Pattern[str] = re.compile(r'^[a-zA-Z0-9][a-zA-Z0-9!#$&\-\^_+\.]*\/[a-zA-Z0-9][a-zA-Z0-9!#$&\-\^_+\.]*(?:\s*;\s*[a-zA-Z0-9!#$&\-\^_+\.]+=(?:[a-zA-Z0-9!#$&\-\^_+\.]+|"[^"\r\n]*"))*$')  # noqa: DUO138 - no ReDoS: inner groups require literal ; and = delimiters preventing backtrack ambiguity
+_MIME_TYPE_RE: Pattern[str] = re.compile(  # noqa: DUO138 - no ReDoS: inner groups require literal ; and = delimiters preventing backtrack ambiguity
+    r'^[a-zA-Z0-9][a-zA-Z0-9!#$&\-\^_+\.]*\/[a-zA-Z0-9][a-zA-Z0-9!#$&\-\^_+\.]*(?:\s*;\s*[a-zA-Z0-9!#$&\-\^_+\.]+=(?:[a-zA-Z0-9!#$&\-\^_+\.]+|"[^"\r\n]*"))*$'
+)
 _URI_SCHEME_RE: Pattern[str] = re.compile(r"^[a-zA-Z][a-zA-Z0-9+\-.]*://")
 _SHELL_DANGEROUS_CHARS_RE: Pattern[str] = re.compile(r"[;&|`$(){}\[\]<>]")
 _ANSI_ESCAPE_RE: Pattern[str] = re.compile(r"\x1B\[[0-9;]*[A-Za-z]")
@@ -833,20 +835,13 @@ def validate_template(cls, value: str) -> str:
                 ...
             ValueError: Template contains potentially dangerous expressions
 
-            Length limit testing:
-
-            >>> long_template = 'a' * 65537
-            >>> SecurityValidator.validate_template(long_template)
-            Traceback (most recent call last):
-                ...
-            ValueError: Template exceeds maximum length of 65536
+            Length limit note: size validation is performed at the service layer
+            using configurable limits (ContentSecurityService). This validator
+            only checks encoding, dangerous patterns, and SSTI prevention.
         """
         if not value:
             return value
 
-        if len(value) > cls.MAX_TEMPLATE_LENGTH:
-            raise ValueError(f"Template exceeds maximum length of {cls.MAX_TEMPLATE_LENGTH}")
-
         # Block dangerous tags but allow Jinja2 syntax {{ }} and {% %} (uses precompiled regex)
         if _DANGEROUS_TEMPLATE_TAGS_RE.search(value):
             raise ValueError("Template contains HTML tags that may interfere with proper display")

mcpgateway/config.py

@@ -1557,6 +1557,10 @@ def parse_issuers(cls, v: Any) -> list[str]:
     tool_rate_limit: int = 100  # requests per minute
     tool_concurrent_limit: int = 10
 
+    # Content Security - Size Limits
+    content_max_resource_size: int = Field(default=102400, ge=1024, le=10485760, description="Maximum size in bytes for resource content (default: 100KB)")  # 100KB  # Minimum 1KB  # Maximum 10MB
+    content_max_prompt_size: int = Field(default=10240, ge=512, le=1048576, description="Maximum size in bytes for prompt templates (default: 10KB)")  # 10KB  # Minimum 512 bytes  # Maximum 1MB
+
     # MCP Session Pool - reduces per-request latency from ~20ms to ~1-2ms
     # Disabled by default for safety. Enable explicitly in production after testing.
     mcp_session_pool_enabled: bool = False

mcpgateway/main.py

@@ -134,6 +134,7 @@
 from mcpgateway.services.a2a_service import A2AAgentError, A2AAgentNameConflictError, A2AAgentNotFoundError, A2AAgentService
 from mcpgateway.services.cancellation_service import cancellation_service
 from mcpgateway.services.completion_service import CompletionService
+from mcpgateway.services.content_security import ContentSizeError
 from mcpgateway.services.email_auth_service import EmailAuthService
 from mcpgateway.services.export_service import ExportError, ExportService
 from mcpgateway.services.gateway_service import GatewayConnectionError, GatewayDuplicateConflictError, GatewayError, GatewayNameConflictError, GatewayNotFoundError
@@ -2151,6 +2152,20 @@ async def database_exception_handler(_request: Request, exc: IntegrityError):
     return ORJSONResponse(status_code=409, content=ErrorFormatter.format_database_error(exc))
 
 
+@app.exception_handler(ContentSizeError)
+async def content_size_exception_handler(_request: Request, exc: ContentSizeError):
+    """Handle content size limit violations globally.
+
+    Args:
+        _request: The incoming request (unused, required by FastAPI handler interface).
+        exc: The ContentSizeError with actual_size, max_size, and content_type.
+
+    Returns:
+        ORJSONResponse: A 413 Payload Too Large response with structured error details.
+    """
+    return ORJSONResponse(status_code=413, content={"detail": {"error": f"{exc.content_type} size limit exceeded", "message": str(exc), "actual_size": exc.actual_size, "max_size": exc.max_size}})
+
+
 # RFC 9110 §5.6.2 'token' pattern for header field names:
 #   token = 1*tchar
 #   tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*"
@@ -5411,6 +5426,9 @@ async def create_resource(
     except IntegrityError as e:
         logger.error(f"Integrity error while creating resource: {e}")
         raise HTTPException(status_code=409, detail=ErrorFormatter.format_database_error(e))
+    except ContentSizeError as e:
+        logger.error(f"Content size exceeded in creating resource: {e}")
+        raise HTTPException(status_code=413, detail={"error": f"{e.content_type} size limit exceeded", "message": str(e), "actual_size": e.actual_size, "max_size": e.max_size})
 
 
 @resource_router.get("/{resource_id}")
@@ -5591,6 +5609,9 @@ async def update_resource(
         raise HTTPException(status_code=409, detail=ErrorFormatter.format_database_error(e))
     except ResourceURIConflictError as e:
         raise HTTPException(status_code=409, detail=str(e))
+    except ContentSizeError as e:
+        logger.error(f"Content size exceeded in updating resource: {e}")
+        raise HTTPException(status_code=413, detail={"error": f"{e.content_type} size limit exceeded", "message": str(e), "actual_size": e.actual_size, "max_size": e.max_size})
     db.commit()
     db.close()
     await invalidate_resource_cache(resource_id)
@@ -5915,6 +5936,9 @@ async def create_prompt(
             # If there is an integrity error, return a 409 Conflict error
             logger.error(f"Integrity error while creating prompt: {e}")
             raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=ErrorFormatter.format_database_error(e))
+        if isinstance(e, ContentSizeError):
+            logger.error(f"Content size exceeded in creating prompt: {e}")
+            raise HTTPException(status_code=413, detail={"error": f"{e.content_type} size limit exceeded", "message": str(e), "actual_size": e.actual_size, "max_size": e.max_size})
         # For any other unexpected errors, return a 500 Internal Server Error
         logger.error(f"Unexpected error while creating prompt: {e}")
         raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="An unexpected error occurred while creating the prompt")
@@ -6109,6 +6133,9 @@ async def update_prompt(
         if isinstance(e, PromptError):
             # If there is a general prompt error, return a 400 Bad Request error
             raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e))
+        if isinstance(e, ContentSizeError):
+            logger.error(f"Content size exceeded in updating prompt: {e}")
+            raise HTTPException(status_code=413, detail={"error": f"{e.content_type} size limit exceeded", "message": str(e), "actual_size": e.actual_size, "max_size": e.max_size})
         # For any other unexpected errors, return a 500 Internal Server Error
         logger.error(f"Unexpected error while updating prompt: {e}")
         raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="An unexpected error occurred while updating the prompt")