From b5477b95df82c1f5392ca31716d38357367d3144 Mon Sep 17 00:00:00 2001 From: RAM PRASAD ATLURI <116977270+ATLURI0001@users.noreply.github.com> Date: Sat, 21 Nov 2026 10:45:49 +0530 Subject: [PATCH] feat(routes): implement route table configuration schema contract and forwarding rules sanitizer --- scripts/route_contract.py | 257 +++++++++++++++++++++++++++++++++++ tests/test_route_contract.py | 153 +++++++++++++++++++++ 2 files changed, 410 insertions(+) create mode 100644 scripts/route_contract.py create mode 100644 tests/test_route_contract.py diff --git a/scripts/route_contract.py b/scripts/route_contract.py new file mode 100644 index 0000000..dbc9bf7 --- /dev/null +++ b/scripts/route_contract.py @@ -0,0 +1,257 @@ +"""Dynamic Route Table Configuration Schema Contract & Forwarding Rules Sanitizer.""" + +from __future__ import annotations + +import re +from dataclasses import dataclass, field +from typing import Any, Dict, List, Optional, Set, Tuple +from urllib.parse import urlparse + + +ROUTE_ID_REGEX = re.compile(r"^[a-zA-Z0-9_-]{1,64}$") +HEADER_NAME_REGEX = re.compile(r"^[a-zA-Z0-9!#$%&'*+\-.^_`|~]+$") + +MIN_TIMEOUT_MS = 10 +MAX_TIMEOUT_MS = 60_000 +MIN_WEIGHT = 1 +MAX_WEIGHT = 100 +MIN_PRIORITY = 0 +MAX_PRIORITY = 1000 +MAX_RETRIES = 10 + + +@dataclass +class RetryPolicy: + max_retries: int = 3 + backoff_multiplier: float = 1.5 + retryable_status_codes: List[int] = field(default_factory=lambda: [502, 503, 504]) + + +@dataclass +class HeadersPolicy: + add: Dict[str, str] = field(default_factory=dict) + remove: List[str] = field(default_factory=list) + + +@dataclass +class SanitizedRoute: + route_id: str + prefix: str + target_upstream: str + weight: int = 100 + priority: int = 100 + timeout_ms: int = 5000 + strip_prefix: bool = False + retry_policy: RetryPolicy = field(default_factory=RetryPolicy) + headers_policy: HeadersPolicy = field(default_factory=HeadersPolicy) + + +def sanitize_path_prefix(raw_prefix: str) -> Tuple[bool, Optional[str], Optional[str]]: + """Sanitizes route prefix against directory traversal and control characters.""" + if not raw_prefix or not isinstance(raw_prefix, str): + return False, None, "Path prefix must be a non-empty string" + + # Block control characters, null bytes, and newlines + if any(ord(c) < 32 or c in "\r\n\0" for c in raw_prefix): + return False, None, "Path prefix contains prohibited control characters or CRLF" + + # Must begin with forward slash + cleaned = raw_prefix.strip() + if not cleaned.startswith("/"): + return False, None, "Path prefix must begin with '/'" + + # Block query strings or fragments + if "?" in cleaned or "#" in cleaned: + return False, None, "Path prefix cannot contain query strings or hash fragments" + + # Block directory traversal sequences: /../ or \..\ + if ".." in cleaned or "\\" in cleaned: + return False, None, "Path prefix cannot contain directory traversal sequences ('..' or '\\')" + + # Collapse multiple consecutive slashes: e.g. ///api//v1 -> /api/v1 + normalized = re.sub(r"/+", "/", cleaned) + # Strip trailing slash unless it's root + if len(normalized) > 1 and normalized.endswith("/"): + normalized = normalized[:-1] + + return True, normalized, None + + +def validate_upstream_url(raw_url: str) -> Tuple[bool, Optional[str], Optional[str]]: + """Validates upstream target URL for protocol, host, port, and CRLF injection.""" + if not raw_url or not isinstance(raw_url, str): + return False, None, "Upstream URL must be a non-empty string" + + trimmed = raw_url.strip() + if re.search(r"[\r\n\0]", trimmed): + return False, None, "Upstream URL contains illegal CRLF or null bytes" + + try: + parsed = urlparse(trimmed) + port = parsed.port + except ValueError as ve: + return False, None, f"Invalid upstream port: {ve}" + except Exception as e: + return False, None, f"Malformed upstream URL: {e}" + + if parsed.scheme not in ("http", "https"): + return False, None, f"Unsupported upstream protocol '{parsed.scheme}': only http and https allowed" + + if not parsed.hostname: + return False, None, "Upstream URL missing valid hostname" + + if port is not None: + if not (1 <= port <= 65535): + return False, None, f"Port {port} out of range [1, 65535]" + + # Reconstruct normalized URL + normalized = f"{parsed.scheme}://{parsed.hostname}" + if port: + normalized += f":{port}" + if parsed.path: + normalized += parsed.path.rstrip("/") + + return True, normalized, None + + +def validate_and_sanitize_route(spec: Dict[str, Any]) -> Tuple[bool, Optional[SanitizedRoute], List[str]]: + """Validates a single route specification against the ingress contract.""" + errors: List[str] = [] + + if not isinstance(spec, dict): + return False, None, ["Route specification must be a dictionary"] + + # 1. Route ID + route_id = spec.get("route_id") + if not route_id or not isinstance(route_id, str) or not ROUTE_ID_REGEX.match(route_id): + errors.append(f"Invalid route_id '{route_id}': must match ^[a-zA-Z0-9_-]{{1,64}}$") + + # 2. Path prefix + prefix_ok, prefix, prefix_err = sanitize_path_prefix(spec.get("prefix", "")) + if not prefix_ok: + errors.append(prefix_err) + + # 3. Upstream URL + upstream_ok, upstream, upstream_err = validate_upstream_url(spec.get("target_upstream", "")) + if not upstream_ok: + errors.append(upstream_err) + + # 4. Weight + weight = spec.get("weight", 100) + if not isinstance(weight, int) or not (MIN_WEIGHT <= weight <= MAX_WEIGHT): + errors.append(f"Weight ({weight}) must be integer in [{MIN_WEIGHT}, {MAX_WEIGHT}]") + + # 5. Priority + priority = spec.get("priority", 100) + if not isinstance(priority, int) or not (MIN_PRIORITY <= priority <= MAX_PRIORITY): + errors.append(f"Priority ({priority}) must be integer in [{MIN_PRIORITY}, {MAX_PRIORITY}]") + + # 6. Timeout + timeout_ms = spec.get("timeout_ms", 5000) + if not isinstance(timeout_ms, int) or not (MIN_TIMEOUT_MS <= timeout_ms <= MAX_TIMEOUT_MS): + errors.append(f"Timeout ({timeout_ms}ms) must be integer in [{MIN_TIMEOUT_MS}, {MAX_TIMEOUT_MS}]") + + strip_prefix = bool(spec.get("strip_prefix", False)) + + # 7. Retry policy + raw_retry = spec.get("retry_policy", {}) + retry_policy = RetryPolicy() + if isinstance(raw_retry, dict): + if "max_retries" in raw_retry: + mr = raw_retry["max_retries"] + if not isinstance(mr, int) or not (0 <= mr <= MAX_RETRIES): + errors.append(f"max_retries ({mr}) must be integer in [0, {MAX_RETRIES}]") + else: + retry_policy.max_retries = mr + + if "backoff_multiplier" in raw_retry: + bm = raw_retry["backoff_multiplier"] + if not isinstance(bm, (int, float)) or not (1.0 <= float(bm) <= 5.0): + errors.append(f"backoff_multiplier ({bm}) must be in [1.0, 5.0]") + else: + retry_policy.backoff_multiplier = float(bm) + + if "retryable_status_codes" in raw_retry: + codes = raw_retry["retryable_status_codes"] + if not isinstance(codes, list) or not all(isinstance(c, int) and 500 <= c <= 599 for c in codes): + errors.append("retryable_status_codes must be a list of 5xx HTTP status integers") + else: + retry_policy.retryable_status_codes = list(codes) + + # 8. Headers policy + raw_headers = spec.get("headers_policy", {}) + headers_policy = HeadersPolicy() + if isinstance(raw_headers, dict): + add_headers = raw_headers.get("add", {}) + if isinstance(add_headers, dict): + for hk, hv in add_headers.items(): + if not HEADER_NAME_REGEX.match(str(hk)): + errors.append(f"Invalid header name to add: '{hk}'") + elif re.search(r"[\r\n\0]", str(hv)): + errors.append(f"CRLF injection detected in header value for '{hk}'") + else: + headers_policy.add[str(hk).lower()] = str(hv).strip() + + rem_headers = raw_headers.get("remove", []) + if isinstance(rem_headers, list): + for hk in rem_headers: + if not HEADER_NAME_REGEX.match(str(hk)): + errors.append(f"Invalid header name to remove: '{hk}'") + else: + headers_policy.remove.append(str(hk).lower()) + + if errors: + return False, None, errors + + sanitized = SanitizedRoute( + route_id=route_id, + prefix=prefix, + target_upstream=upstream, + weight=weight, + priority=priority, + timeout_ms=timeout_ms, + strip_prefix=strip_prefix, + retry_policy=retry_policy, + headers_policy=headers_policy, + ) + return True, sanitized, [] + + +def validate_route_table(routes: List[Dict[str, Any]]) -> Tuple[bool, List[SanitizedRoute], List[str]]: + """Validates an entire route table, detecting duplicate IDs and ambiguous prefix collisions.""" + if not isinstance(routes, list): + return False, [], ["Route table must be a list of route definitions"] + + sanitized_routes: List[SanitizedRoute] = [] + all_errors: List[str] = [] + seen_ids: Set[str] = set() + prefix_priority_map: Dict[Tuple[str, int], str] = {} + + for i, spec in enumerate(routes): + ok, sanitized, errs = validate_and_sanitize_route(spec) + if not ok: + all_errors.extend([f"Route[{i}]: {e}" for e in errs]) + continue + + # Check duplicate ID + if sanitized.route_id in seen_ids: + all_errors.append(f"Duplicate route_id '{sanitized.route_id}' detected at index {i}") + seen_ids.add(sanitized.route_id) + + # Check collision: identical prefix AND priority creates routing ambiguity + key = (sanitized.prefix, sanitized.priority) + if key in prefix_priority_map: + all_errors.append( + f"Routing conflict: routes '{prefix_priority_map[key]}' and '{sanitized.route_id}' share prefix '{sanitized.prefix}' with equal priority ({sanitized.priority})" + ) + else: + prefix_priority_map[key] = sanitized.route_id + + sanitized_routes.append(sanitized) + + if all_errors: + return False, [], all_errors + + # Sort descending by priority (higher priority evaluated first) + sanitized_routes.sort(key=lambda r: r.priority, reverse=True) + return True, sanitized_routes, [] diff --git a/tests/test_route_contract.py b/tests/test_route_contract.py new file mode 100644 index 0000000..20d8ea6 --- /dev/null +++ b/tests/test_route_contract.py @@ -0,0 +1,153 @@ +"""Unit tests for Route Table Configuration Schema Contract & Rules Sanitizer.""" + +import pytest +from scripts.route_contract import ( + sanitize_path_prefix, + validate_upstream_url, + validate_and_sanitize_route, + validate_route_table, +) + + +def test_sanitize_path_prefix(): + # Valid normalizations + ok, p, err = sanitize_path_prefix("/api/v1/users") + assert ok and p == "/api/v1/users" + + ok, p, err = sanitize_path_prefix("///api///v1//service/") + assert ok and p == "/api/v1/service" + + ok, p, err = sanitize_path_prefix("/") + assert ok and p == "/" + + # Rejections + ok, _, err = sanitize_path_prefix("api/v1") + assert not ok and "must begin with '/'" in err + + ok, _, err = sanitize_path_prefix("/api/../etc/passwd") + assert not ok and "traversal" in err + + ok, _, err = sanitize_path_prefix("/api/v1?filter=true") + assert not ok and "query strings" in err + + ok, _, err = sanitize_path_prefix("/api/v1\r\nHost: evil.com") + assert not ok and "CRLF" in err + + +def test_validate_upstream_url(): + ok, u, err = validate_upstream_url("http://auth-service.internal:8080/v1") + assert ok and u == "http://auth-service.internal:8080/v1" + + ok, u, err = validate_upstream_url("https://api.gateway.prod") + assert ok and u == "https://api.gateway.prod" + + # Injections and invalid schemes + ok, _, err = validate_upstream_url("ftp://upstream.local") + assert not ok and "Unsupported upstream protocol" in err + + ok, _, err = validate_upstream_url("http://upstream.local:99999") + assert not ok and "out of range" in err + + ok, _, err = validate_upstream_url("http://upstream.local\r\nEvil: True") + assert not ok and "CRLF" in err + + +def test_validate_and_sanitize_route_success(): + spec = { + "route_id": "auth-service-v1", + "prefix": "/api/v1/auth", + "target_upstream": "http://10.0.1.50:8081", + "weight": 80, + "priority": 500, + "timeout_ms": 3000, + "strip_prefix": True, + "retry_policy": { + "max_retries": 4, + "backoff_multiplier": 2.0, + "retryable_status_codes": [502, 503], + }, + "headers_policy": { + "add": {"X-Forwarded-By": "RouteKernel", "X-Request-Mode": "Proxy"}, + "remove": ["Server", "X-Powered-By"], + }, + } + + ok, route, errors = validate_and_sanitize_route(spec) + assert ok + assert len(errors) == 0 + assert route.route_id == "auth-service-v1" + assert route.prefix == "/api/v1/auth" + assert route.weight == 80 + assert route.priority == 500 + assert route.timeout_ms == 3000 + assert route.strip_prefix is True + assert route.retry_policy.max_retries == 4 + assert route.headers_policy.add["x-forwarded-by"] == "RouteKernel" + assert "server" in route.headers_policy.remove + + +def test_validate_and_sanitize_route_failures(): + spec = { + "route_id": "bad route id with spaces!", + "prefix": "invalid-prefix-no-slash", + "target_upstream": "not-a-url", + "weight": 999, # > 100 + "timeout_ms": 5, # < 10ms + "headers_policy": { + "add": {"X-Bad-Header": "value\r\nSet-Cookie: pwned"}, + }, + } + + ok, route, errors = validate_and_sanitize_route(spec) + assert not ok + assert route is None + assert len(errors) >= 5 + + +def test_validate_route_table_sorting_and_conflicts(): + routes = [ + { + "route_id": "r1", + "prefix": "/api/v1/users", + "target_upstream": "http://users:8080", + "priority": 200, + }, + { + "route_id": "r2", + "prefix": "/api/v1", + "target_upstream": "http://general:8080", + "priority": 100, + }, + { + "route_id": "r3", + "prefix": "/auth", + "target_upstream": "http://auth:8080", + "priority": 300, + }, + ] + + ok, table, errors = validate_route_table(routes) + assert ok + assert len(table) == 3 + # Sorted descending by priority: r3 (300) -> r1 (200) -> r2 (100) + assert table[0].route_id == "r3" + assert table[1].route_id == "r1" + assert table[2].route_id == "r2" + + # Duplicate route_id test + duplicate_routes = [ + {"route_id": "r1", "prefix": "/a", "target_upstream": "http://a:80"}, + {"route_id": "r1", "prefix": "/b", "target_upstream": "http://b:80"}, + ] + ok, _, errors = validate_route_table(duplicate_routes) + assert not ok + assert any("Duplicate route_id 'r1'" in e for e in errors) + + # Collision test: identical prefix and equal priority + collision_routes = [ + {"route_id": "r1", "prefix": "/api", "target_upstream": "http://a:80", "priority": 100}, + {"route_id": "r2", "prefix": "/api", "target_upstream": "http://b:80", "priority": 100}, + ] + ok, _, errors = validate_route_table(collision_routes) + assert not ok + assert any("Routing conflict" in e for e in errors)