Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions nginx/conf.d/edge.conf
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,19 @@ server {
include /etc/nginx/snippets/proxy.conf;
proxy_pass http://web_pool;
}

error_page 429 = @rate_limited;
error_page 502 503 504 = @gateway_error;

location @rate_limited {
default_type application/problem+json;
return 429 '{"type":"https://httpstatuses.com/429","title":"Too Many Requests","status":429,"detail":"Rate limit exceeded","requestId":"$request_id"}\n';
}

location @gateway_error {
default_type application/problem+json;
return 502 '{"type":"https://httpstatuses.com/502","title":"Bad Gateway","status":502,"detail":"Upstream service temporarily unavailable","requestId":"$request_id"}\n';
}
}

# Internal metrics/health endpoint: port not published to the host.
Expand Down
153 changes: 153 additions & 0 deletions scripts/diagnostics.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,153 @@
#!/usr/bin/env python3
"""RouteKernel Architecture & Configuration Diagnostic Inspector.

Performs static analysis and invariant checks on Nginx edge configurations:
- TLS 1.2 / 1.3 protocol restrictions
- Forward secrecy session cache and ticket handling
- Request-ID traceability across edge headers and proxy passes
- Proxy buffer geometry (preventing unbounded temp file spillover)
- Slowloris and connection exhaustion defenses
- RFC 7807 problem+json error handlers
"""
from __future__ import annotations

import json
import pathlib
import sys
from typing import Any, Dict, List


class DiagnosticRule:
def __init__(self, rule_id: str, description: str, severity: str = "ERROR"):
self.rule_id = rule_id
self.description = description
self.severity = severity # "INFO", "WARN", "ERROR"

def evaluate(self, content_map: Dict[str, str]) -> Dict[str, Any]:
raise NotImplementedError


class ModernTlsRule(DiagnosticRule):
def __init__(self):
super().__init__("RK-TLS-001", "Enforce TLSv1.2 and TLSv1.3 with session caching and ticket disabling", "ERROR")

def evaluate(self, content_map: Dict[str, str]) -> Dict[str, Any]:
nginx_conf = content_map.get("nginx/nginx.conf", "")
passed = (
"ssl_protocols TLSv1.2 TLSv1.3;" in nginx_conf
and "TLSv1.0" not in nginx_conf
and "TLSv1.1" not in nginx_conf
and "ssl_session_cache" in nginx_conf
and "ssl_session_tickets off;" in nginx_conf
)
return {
"ruleId": self.rule_id,
"description": self.description,
"status": "PASS" if passed else "FAIL",
"severity": self.severity,
}


class SecurityHeadersRule(DiagnosticRule):
def __init__(self):
super().__init__("RK-SEC-002", "Enforce defense-in-depth security headers (CSP, X-Frame-Options, X-Request-ID)", "ERROR")

def evaluate(self, content_map: Dict[str, str]) -> Dict[str, Any]:
edge_conf = content_map.get("nginx/conf.d/edge.conf", "")
required = [
"X-Content-Type-Options nosniff",
"X-Frame-Options DENY",
"Referrer-Policy strict-origin-when-cross-origin",
"Content-Security-Policy",
"X-Request-ID $request_id always",
]
missing = [h for h in required if h not in edge_conf]
return {
"ruleId": self.rule_id,
"description": self.description,
"status": "PASS" if not missing else "FAIL",
"missingHeaders": missing,
"severity": self.severity,
}


class ProxyBufferGeometryRule(DiagnosticRule):
def __init__(self):
super().__init__("RK-BUF-003", "Validate proxy buffering dimensions and unbuffered WebSocket bypass", "WARN")

def evaluate(self, content_map: Dict[str, str]) -> Dict[str, Any]:
proxy_conf = content_map.get("nginx/snippets/proxy.conf", "")
edge_conf = content_map.get("nginx/conf.d/edge.conf", "")
passed = (
"proxy_buffering on;" in proxy_conf
and "proxy_buffer_size" in proxy_conf
and "proxy_max_temp_file_size 0;" in edge_conf
)
return {
"ruleId": self.rule_id,
"description": self.description,
"status": "PASS" if passed else "FAIL",
"severity": self.severity,
}


class Rfc7807ErrorPagesRule(DiagnosticRule):
def __init__(self):
super().__init__("RK-ERR-004", "Validate RFC 7807 structured JSON error handling for 429 and 502/503/504", "ERROR")

def evaluate(self, content_map: Dict[str, str]) -> Dict[str, Any]:
edge_conf = content_map.get("nginx/conf.d/edge.conf", "")
has_429 = "error_page 429 = @rate_limited;" in edge_conf and "application/problem+json" in edge_conf
has_502 = "error_page 502 503 504 = @gateway_error;" in edge_conf and "Bad Gateway" in edge_conf
passed = has_429 and has_502
return {
"ruleId": self.rule_id,
"description": self.description,
"status": "PASS" if passed else "FAIL",
"severity": self.severity,
}


def run_diagnostics(root_dir: pathlib.Path) -> Dict[str, Any]:
files_to_load = [
"nginx/nginx.conf",
"nginx/conf.d/edge.conf",
"nginx/snippets/proxy.conf",
]
content_map = {}
for rel_path in files_to_load:
p = root_dir / rel_path
if p.exists():
content_map[rel_path] = p.read_text(encoding="utf-8")
else:
content_map[rel_path] = ""

rules: List[DiagnosticRule] = [
ModernTlsRule(),
SecurityHeadersRule(),
ProxyBufferGeometryRule(),
Rfc7807ErrorPagesRule(),
]

results = [rule.evaluate(content_map) for rule in rules]
passed_count = sum(1 for r in results if r["status"] == "PASS")
failed_count = sum(1 for r in results if r["status"] == "FAIL")

return {
"totalRules": len(rules),
"passed": passed_count,
"failed": failed_count,
"healthy": failed_count == 0,
"results": results,
}


def main():
root = pathlib.Path(__file__).resolve().parents[1]
report = run_diagnostics(root)
print(json.dumps(report, indent=2))
sys.exit(0 if report["healthy"] else 1)


if __name__ == "__main__":
main()
47 changes: 47 additions & 0 deletions tests/test_diagnostics.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
"""Tests for RouteKernel static diagnostic analyzer."""
import pathlib
import unittest

from scripts.diagnostics import (
run_diagnostics,
ModernTlsRule,
SecurityHeadersRule,
ProxyBufferGeometryRule,
Rfc7807ErrorPagesRule,
)

ROOT = pathlib.Path(__file__).resolve().parents[1]


class DiagnosticsTests(unittest.TestCase):
def test_run_diagnostics_on_repo(self):
report = run_diagnostics(ROOT)
self.assertEqual(report["totalRules"], 4)
self.assertEqual(report["failed"], 0)
self.assertTrue(report["healthy"])
for res in report["results"]:
self.assertEqual(res["status"], "PASS")

def test_modern_tls_rule_catches_legacy_tls(self):
rule = ModernTlsRule()
content = {"nginx/nginx.conf": "ssl_protocols TLSv1.0 TLSv1.2 TLSv1.3;"}
res = rule.evaluate(content)
self.assertEqual(res["status"], "FAIL")

def test_security_headers_rule_catches_missing_csp(self):
rule = SecurityHeadersRule()
content = {"nginx/conf.d/edge.conf": "add_header X-Frame-Options DENY always;"}
res = rule.evaluate(content)
self.assertEqual(res["status"], "FAIL")
self.assertIn("Content-Security-Policy", res["missingHeaders"])

def test_rfc7807_error_pages_detected(self):
rule = Rfc7807ErrorPagesRule()
res = rule.evaluate({
"nginx/conf.d/edge.conf": (ROOT / "nginx/conf.d/edge.conf").read_text(encoding="utf-8")
})
self.assertEqual(res["status"], "PASS")


if __name__ == "__main__":
unittest.main()
9 changes: 9 additions & 0 deletions tests/test_project.py
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,15 @@ def test_proxy_forwarding_invariants(self):
self.assertIn('proxy_buffers 8 16k;', proxy)
self.assertIn('proxy_busy_buffers_size 32k;', proxy)

def test_rfc7807_problem_json_error_pages(self):
edge_cfg = load('nginx/conf.d/edge.conf')
self.assertIn('error_page 429 = @rate_limited;', edge_cfg)
self.assertIn('error_page 502 503 504 = @gateway_error;', edge_cfg)
self.assertIn('default_type application/problem+json;', edge_cfg)
self.assertIn('"title":"Too Many Requests"', edge_cfg)
self.assertIn('"title":"Bad Gateway"', edge_cfg)
self.assertIn('"requestId":"$request_id"', edge_cfg)

def test_rate_limiting_and_http_status(self):
nginx_cfg = load('nginx/nginx.conf')
self.assertIn('limit_req_status 429;', nginx_cfg)
Expand Down
Loading