ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(security): per-app WAF (ModSecurity v3 + OWASP CRS)
Juan Denisada030553a7d
diff --git a/backend/app/__init__.py b/backend/app/__init__.pyindex 9923c473..b4fad5ce 100644--- a/backend/app/__init__.py+++ b/backend/app/__init__.py@@ -311,6 +311,10 @@ def create_app(config_name=None):from app.api.image_updates import image_updates_bpapp.register_blueprint(image_updates_bp, url_prefix='/api/v1/image-updates')+ # Register blueprints - Per-application WAF (ModSecurity + OWASP CRS)+ from app.api.waf import waf_bp+ app.register_blueprint(waf_bp, url_prefix='/api/v1/waf')+# Register blueprints - GPU monitoringfrom app.api.gpu import gpu_bpapp.register_blueprint(gpu_bp, url_prefix='/api/v1/gpu')diff --git a/backend/app/api/waf.py b/backend/app/api/waf.pynew file mode 100644index 00000000..ba9a61b3--- /dev/null+++ b/backend/app/api/waf.py@@ -0,0 +1,124 @@+"""Per-application WAF (ModSecurity v3 + OWASP CRS) API.++Routes are mounted at ``/api/v1/waf``. Reads require a valid JWT; mutations and+install require an admin user (mirrors ``app/api/dns_zones.py``). Service+``ValueError``s map to HTTP 400.+"""+from flask import Blueprint, request, jsonify+from flask_jwt_extended import jwt_required++from app.models.application import Application+from app.services.waf_service import WafService++waf_bp = Blueprint('waf', __name__)+++def get_current_user():+ from flask_jwt_extended import get_jwt_identity+ from app.models.user import User+ return User.query.get(get_jwt_identity())+++def _require_admin():+ """Return None if the caller is an admin, else a (response, status) tuple."""+ user = get_current_user()+ if not user or not user.is_admin:+ return jsonify({'error': 'Admin access required'}), 403+ return None+++def _get_application_or_404(app_id):+ application = Application.query.get(app_id)+ if not application:+ return None, (jsonify({'error': 'Application not found'}), 404)+ return application, None+++@waf_bp.route('/applications/<int:app_id>/policy', methods=['GET'])+@jwt_required()+def get_policy(app_id):+ _, err = _get_application_or_404(app_id)+ if err:+ return err+ policy = WafService.get_or_create_policy(app_id)+ return jsonify(policy.to_dict())+++@waf_bp.route('/applications/<int:app_id>/policy', methods=['PUT'])+@jwt_required()+def update_policy(app_id):+ admin_err = _require_admin()+ if admin_err:+ return admin_err+ _, err = _get_application_or_404(app_id)+ if err:+ return err++ data = request.get_json() or {}+ try:+ policy = WafService.set_policy(+ app_id,+ mode=data.get('mode'),+ paranoia_level=data.get('paranoia_level'),+ anomaly_threshold=data.get('anomaly_threshold'),+ disabled_rule_ids=data.get('disabled_rule_ids'),+ )+ except ValueError as e:+ return jsonify({'error': str(e)}), 400++ # Best-effort enforcement: never fail the policy write because nginx /+ # ModSecurity isn't present on the host.+ try:+ apply_result = WafService.apply(app_id)+ except Exception as e: # pragma: no cover - defensive+ apply_result = {'success': False, 'error': str(e)}++ response = policy.to_dict()+ response['apply'] = apply_result+ return jsonify(response)+++@waf_bp.route('/applications/<int:app_id>/apply', methods=['POST'])+@jwt_required()+def apply_policy(app_id):+ admin_err = _require_admin()+ if admin_err:+ return admin_err+ _, err = _get_application_or_404(app_id)+ if err:+ return err+ result = WafService.apply(app_id)+ status = 200 if result.get('success') else 400+ return jsonify(result), status+++@waf_bp.route('/applications/<int:app_id>/events', methods=['GET'])+@jwt_required()+def get_events(app_id):+ _, err = _get_application_or_404(app_id)+ if err:+ return err+ try:+ limit = int(request.args.get('limit', 50))+ except (TypeError, ValueError):+ limit = 50+ limit = max(1, min(500, limit))+ events = WafService.events(app_id, limit=limit)+ return jsonify({'events': events, 'count': len(events)})+++@waf_bp.route('/status', methods=['GET'])+@jwt_required()+def status():+ return jsonify({'installed': WafService.modsecurity_installed()})+++@waf_bp.route('/install', methods=['POST'])+@jwt_required()+def install():+ admin_err = _require_admin()+ if admin_err:+ return admin_err+ result = WafService.install_modsecurity()+ status_code = 200 if result.get('success') else 400+ return jsonify(result), status_codediff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.pyindex 2dd53349..e1bb6893 100644--- a/backend/app/models/__init__.py+++ b/backend/app/models/__init__.py@@ -41,6 +41,7 @@ from app.models.image_scan import ImageVulnerabilityScan, SbomArtifactfrom app.models.passkey import PasskeyCredentialfrom app.models.secret_vault import SecretVault, Secretfrom app.models.webhook_gateway import WebhookEndpoint, WebhookDelivery+from app.models.waf_policy import WafPolicy__all__ = ['User', 'Application', 'Domain', 'EnvironmentVariable', 'EnvironmentVariableHistory',@@ -68,4 +69,5 @@ __all__ = ['PasskeyCredential','SecretVault', 'Secret','WebhookEndpoint', 'WebhookDelivery',+ 'WafPolicy',]diff --git a/backend/app/models/waf_policy.py b/backend/app/models/waf_policy.pynew file mode 100644index 00000000..c69da0a3--- /dev/null+++ b/backend/app/models/waf_policy.py@@ -0,0 +1,73 @@+"""Per-application WAF policy (ModSecurity v3 + OWASP Core Rule Set).++One row per :class:`~app.models.application.Application`. Stores the desired+engine mode, OWASP CRS paranoia level / anomaly threshold, and the list of CRS+rule IDs to disable. The :class:`~app.services.waf_service.WafService` renders+these into ModSecurity rules and an nginx snippet.+"""+from datetime import datetime+import json++from app import db+++class WafPolicy(db.Model):+ """ModSecurity / OWASP CRS configuration for a single application."""+ __tablename__ = 'waf_policies'++ # Allowed engine modes. 'off' disables the WAF, 'detect' logs only+ # (DetectionOnly), 'block' enforces (SecRuleEngine On).+ MODES = ('off', 'detect', 'block')++ id = db.Column(db.Integer, primary_key=True)+ application_id = db.Column(+ db.Integer,+ db.ForeignKey('applications.id'),+ nullable=False,+ unique=True,+ index=True,+ )++ mode = db.Column(db.String(10), default='off', nullable=False)+ paranoia_level = db.Column(db.Integer, default=1, nullable=False) # 1-4+ anomaly_threshold = db.Column(db.Integer, default=5, nullable=False)++ # JSON-encoded list of OWASP CRS rule IDs to disable (SecRuleRemoveById).+ disabled_rule_ids = db.Column(db.Text, nullable=True)++ updated_at = db.Column(db.DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)++ @property+ def disabled_rules(self):+ """Return the disabled rule IDs as a list (empty list when unset)."""+ if not self.disabled_rule_ids:+ return []+ try:+ value = json.loads(self.disabled_rule_ids)+ return value if isinstance(value, list) else []+ except (ValueError, TypeError):+ return []++ @disabled_rules.setter+ def disabled_rules(self, value):+ if not value:+ self.disabled_rule_ids = None+ else:+ # Normalise to a list of strings, dropping blanks.+ self.disabled_rule_ids = json.dumps(+ [str(v).strip() for v in value if str(v).strip()]+ )++ def to_dict(self):+ return {+ 'id': self.id,+ 'application_id': self.application_id,+ 'mode': self.mode,+ 'paranoia_level': self.paranoia_level,+ 'anomaly_threshold': self.anomaly_threshold,+ 'disabled_rule_ids': self.disabled_rules,+ 'updated_at': self.updated_at.isoformat() if self.updated_at else None,+ }++ def __repr__(self):+ return f'<WafPolicy app={self.application_id} mode={self.mode}>'diff --git a/backend/app/services/waf_service.py b/backend/app/services/waf_service.pynew file mode 100644index 00000000..fac011b9--- /dev/null+++ b/backend/app/services/waf_service.py@@ -0,0 +1,535 @@+"""Per-application WAF management (ModSecurity v3 + OWASP Core Rule Set).++Mirrors :class:`~app.services.image_scanner_service.ImageScannerService`:+classmethods that shell out to install an external tool and return+``{'success': ...}`` dicts, degrading gracefully when the host lacks+ModSecurity. The rule/snippet renderers are pure functions so they are+unit-testable without nginx or libmodsecurity present.++Integration note (nginx wiring)+-------------------------------+ServerKit writes one full ``server { ... }`` block per managed app into+``/etc/nginx/sites-available/<vhost>`` via ``NginxService.create_site``. That+file is regenerated wholesale, and the only additive include hook that exists+today (``/etc/nginx/serverkit-locations/*.conf``) is *location*-level inside the+**panel's** server block — the wrong scope for per-app, server-level WAF+directives. To stay additive and never rewrite the app's generated vhost, we:++ 1. render the ModSecurity rules to ``WAF_RULES_DIR/<app>.conf``;+ 2. render the nginx snippet (``modsecurity on; modsecurity_rules_file ...``)+ to ``WAF_RULES_DIR/<app>.include.conf``;+ 3. idempotently inject a single ``include <snippet>;`` line into the app's own+ vhost inside the first ``server { ... }`` block, guarded by a sentinel+ marker so re-applies are no-ops.++If the app's vhost file cannot be found, ``apply`` degrades gracefully: it still+writes the rules + snippet and returns ``manual_include`` so an operator (or a+future ``create_site`` hook) can wire it up. We never regenerate or rewrite the+existing config.+"""+import json+import logging+import os+import re+import threading+from datetime import datetime+from typing import Dict, List, Optional++logger = logging.getLogger(__name__)++# Serverkit-managed WAF artifacts live under the conf.d dir install.sh creates.+WAF_RULES_DIR = os.environ.get('SERVERKIT_WAF_DIR', '/etc/nginx/serverkit-conf.d/waf')++# Path to the OWASP CRS entrypoint (Include'd by the per-app rules file).+OWASP_CRS_PATH = os.environ.get(+ 'SERVERKIT_OWASP_CRS_PATH',+ '/usr/share/modsecurity-crs/owasp-crs.load',+)++# ModSecurity JSON audit log. Injectable for tests via the ``log_path`` arg of+# ``events`` or the SERVERKIT_MODSEC_AUDIT_LOG env var.+MODSEC_AUDIT_LOG = os.environ.get('SERVERKIT_MODSEC_AUDIT_LOG', '/var/log/modsec_audit.log')++# Where managed app vhosts live (mirrors NginxService.SITES_AVAILABLE).+NGINX_CONF_DIR = os.environ.get('NGINX_CONF_DIR', '/etc/nginx')+SITES_AVAILABLE = os.path.join(NGINX_CONF_DIR, 'sites-available')++# Sentinel marking our additive include so re-applies are idempotent.+_INCLUDE_MARKER = '# serverkit-waf'++# nginx package names per package manager, used by the best-effort installer.+_PKG_BY_MANAGER = {+ 'apt': ['libmodsecurity3', 'modsecurity-crs'],+ 'dnf': ['mod_security', 'mod_security_crs'],+ 'yum': ['mod_security', 'mod_security_crs'],+}+++class WafService:+ """Install ModSecurity and manage per-application WAF policies."""++ _install_lock = threading.Lock()++ # ------------------------------------------------------------------+ # Installation (best-effort; not unit-tested)+ # ------------------------------------------------------------------+ @classmethod+ def modsecurity_installed(cls) -> bool:+ """Return True when libmodsecurity / the nginx connector look present.++ Checked without invoking nginx: we look for the connector module and+ the OWASP CRS entrypoint. This is intentionally lenient — enforcement+ ultimately depends on the host's nginx build including+ ``ngx_http_modsecurity_module``.+ """+ module_candidates = [+ '/usr/lib/nginx/modules/ngx_http_modsecurity_module.so',+ '/usr/share/nginx/modules/ngx_http_modsecurity_module.so',+ '/etc/nginx/modules/ngx_http_modsecurity_module.so',+ ]+ if any(os.path.exists(p) for p in module_candidates):+ return True+ # Fall back to the system utility check for the shared lib / CRS.+ try:+ from app.utils.system import is_command_available+ if is_command_available('modsecurity'):+ return True+ except Exception:+ pass+ return os.path.exists(OWASP_CRS_PATH)++ @classmethod+ def install_modsecurity(cls) -> Dict:+ """Install libmodsecurity, the nginx connector, and the OWASP CRS.++ Distro-aware via ``app.utils.system`` package helpers. Best-effort: on+ hosts without a supported package manager (or on Windows dev boxes) it+ returns a ``success: False`` dict rather than raising.+ """+ with cls._install_lock:+ if cls.modsecurity_installed():+ return {'success': True, 'message': 'ModSecurity already installed'}+ try:+ from app.utils.system import PackageManager+ except Exception as e: # pragma: no cover - import guard+ return {'success': False, 'error': f'system utils unavailable: {e}'}++ manager = PackageManager.detect()+ if manager is None:+ return {+ 'success': False,+ 'error': 'No supported package manager found (apt/dnf/yum)',+ }+ packages = _PKG_BY_MANAGER.get(manager, [])+ try:+ result = PackageManager.install(packages, timeout=600)+ if result.returncode != 0:+ return {+ 'success': False,+ 'error': (result.stderr or 'package install failed')[:300],+ }+ return {+ 'success': True,+ 'message': f'Installed {", ".join(packages)} via {manager}',+ 'note': (+ 'nginx must load ngx_http_modsecurity_module for '+ 'enforcement; install the connector if your distro '+ 'ships it separately.'+ ),+ }+ except Exception as e:+ return {'success': False, 'error': str(e)[:300]}++ # ------------------------------------------------------------------+ # Pure renderers (unit-testable, no I/O)+ # ------------------------------------------------------------------+ @staticmethod+ def _engine_directive(mode: str) -> str:+ return {+ 'block': 'On',+ 'detect': 'DetectionOnly',+ 'off': 'Off',+ }.get(mode, 'Off')++ @classmethod+ def render_rules(cls, policy, crs_path: str = OWASP_CRS_PATH) -> str:+ """Render the ModSecurity rules for one application as a string.++ Includes the engine directive, the OWASP CRS include, the paranoia+ level + anomaly threshold (set before the CRS is included so the CRS+ picks them up), and one ``SecRuleRemoveById`` per disabled rule (after+ the include, so the targeted rules exist when removed).+ """+ mode = getattr(policy, 'mode', 'off')+ paranoia = max(1, min(4, int(getattr(policy, 'paranoia_level', 1) or 1)))+ anomaly = int(getattr(policy, 'anomaly_threshold', 5) or 5)+ engine = cls._engine_directive(mode)++ lines = [+ '# ServerKit-managed WAF rules. Do not edit by hand.',+ f'# application_id={getattr(policy, "application_id", "?")} mode={mode}',+ f'SecRuleEngine {engine}',+ ]++ if mode != 'off':+ # CRS reads these tx vars during its own initialisation, so they+ # must be set *before* the CRS Include.+ lines.append(+ 'SecAction "id:900000,phase:1,nolog,pass,t:none,'+ f'setvar:tx.blocking_paranoia_level={paranoia},'+ f'setvar:tx.detection_paranoia_level={paranoia},'+ f'setvar:tx.inbound_anomaly_score_threshold={anomaly},'+ f'setvar:tx.outbound_anomaly_score_threshold={anomaly}"'+ )+ lines.append(f'Include {crs_path}')++ for rule_id in cls._normalize_rule_ids(getattr(policy, 'disabled_rules', [])):+ lines.append(f'SecRuleRemoveById {rule_id}')++ return '\n'.join(lines) + '\n'++ @staticmethod+ def _normalize_rule_ids(rule_ids) -> List[str]:+ """Keep only sane, injection-safe numeric CRS rule IDs."""+ out = []+ for rid in rule_ids or []:+ rid = str(rid).strip()+ if rid.isdigit():+ out.append(rid)+ return out++ @classmethod+ def nginx_snippet(cls, policy, rules_path: str) -> str:+ """Render the nginx directives that activate the WAF for this app.++ When the policy is enforcing/detecting, emit ``modsecurity on;`` plus+ the rules-file include. When off, emit ``modsecurity off;`` so the+ directive is explicit (and an existing include can be neutralised+ without removal).+ """+ mode = getattr(policy, 'mode', 'off')+ if mode == 'off':+ return f'{_INCLUDE_MARKER}\nmodsecurity off;\n'+ return (+ f'{_INCLUDE_MARKER}\n'+ 'modsecurity on;\n'+ f'modsecurity_rules_file {rules_path};\n'+ )++ # ------------------------------------------------------------------+ # Policy persistence+ # ------------------------------------------------------------------+ @classmethod+ def get_or_create_policy(cls, app_id: int):+ """Return the app's WafPolicy, creating a default (off) one if absent."""+ from app import db+ from app.models.waf_policy import WafPolicy++ policy = WafPolicy.query.filter_by(application_id=app_id).first()+ if policy is None:+ policy = WafPolicy(application_id=app_id, mode='off')+ db.session.add(policy)+ db.session.commit()+ return policy++ @classmethod+ def set_policy(cls, app_id: int, **fields):+ """Validate and persist policy fields. Raises ValueError on bad input."""+ from app import db+ from app.models.waf_policy import WafPolicy++ policy = cls.get_or_create_policy(app_id)++ if 'mode' in fields and fields['mode'] is not None:+ mode = fields['mode']+ if mode not in WafPolicy.MODES:+ raise ValueError(+ f"Invalid mode '{mode}'; expected one of {', '.join(WafPolicy.MODES)}"+ )+ policy.mode = mode++ if 'paranoia_level' in fields and fields['paranoia_level'] is not None:+ try:+ level = int(fields['paranoia_level'])+ except (TypeError, ValueError):+ raise ValueError('paranoia_level must be an integer 1-4')+ policy.paranoia_level = max(1, min(4, level))++ if 'anomaly_threshold' in fields and fields['anomaly_threshold'] is not None:+ try:+ policy.anomaly_threshold = int(fields['anomaly_threshold'])+ except (TypeError, ValueError):+ raise ValueError('anomaly_threshold must be an integer')++ if 'disabled_rule_ids' in fields and fields['disabled_rule_ids'] is not None:+ ids = fields['disabled_rule_ids']+ if not isinstance(ids, (list, tuple)):+ raise ValueError('disabled_rule_ids must be a list')+ policy.disabled_rules = list(ids)++ db.session.commit()+ return policy++ # ------------------------------------------------------------------+ # Filesystem / nginx side-effects (isolated for monkeypatching)+ # ------------------------------------------------------------------+ @classmethod+ def _ensure_rules_dir(cls) -> None:+ from app.utils.system import run_privileged+ run_privileged(['mkdir', '-p', WAF_RULES_DIR])++ @classmethod+ def _write_file(cls, path: str, content: str) -> Dict:+ """Write *content* to *path* with privilege escalation (via tee)."""+ from app.utils.system import run_privileged+ result = run_privileged(['tee', path], input=content)+ if result.returncode != 0:+ return {'success': False, 'error': result.stderr or f'failed to write {path}'}+ return {'success': True, 'path': path}++ @classmethod+ def _nginx_test_and_reload(cls) -> Dict:+ """Run ``nginx -t`` then reload, reusing NginxService's helper."""+ from app.services.nginx_service import NginxService+ return NginxService.reload()++ @classmethod+ def _vhost_path(cls, application_id: int) -> Optional[str]:+ """Locate the app's vhost file in sites-available.++ ServerKit names vhosts by hostname/app name (not DB id), so we search+ sites-available for the first server block that is clearly this app's:+ we match the app name or any of its domains against ``server_name``.+ Returns None when nothing matches (caller then defers wiring).+ """+ from app.models.application import Application++ application = Application.query.get(application_id)+ if not application:+ return None++ candidates = set()+ if application.name:+ candidates.add(application.name)+ for domain in getattr(application, 'domains', []) or []:+ if getattr(domain, 'domain', None):+ candidates.add(domain.domain)++ if not os.path.isdir(SITES_AVAILABLE):+ return None++ for filename in os.listdir(SITES_AVAILABLE):+ if filename.startswith('.'):+ continue+ path = os.path.join(SITES_AVAILABLE, filename)+ if not os.path.isfile(path):+ continue+ # Fast path: the vhost file is named after the app.+ if filename in candidates:+ return path+ try:+ with open(path, 'r') as fh:+ content = fh.read()+ except OSError:+ continue+ match = re.search(r'server_name\s+([^;]+);', content)+ if not match:+ continue+ names = set(match.group(1).split())+ if names & candidates:+ return path+ return None++ @classmethod+ def _inject_include(cls, vhost_path: str, include_path: str) -> Dict:+ """Idempotently add ``include <include_path>;`` into the first server block.++ Guarded by ``_INCLUDE_MARKER`` so repeated applies don't duplicate the+ line, and we replace any prior serverkit-waf include for this app rather+ than stacking. Never touches anything outside the inserted line.+ """+ try:+ with open(vhost_path, 'r') as fh:+ content = fh.read()+ except OSError as e:+ return {'success': False, 'error': f'cannot read vhost: {e}'}++ include_line = f' {_INCLUDE_MARKER}\n include {include_path};'++ # Drop any existing serverkit-waf include line(s) first (idempotent).+ cleaned = re.sub(+ r'\n[ \t]*' + re.escape(_INCLUDE_MARKER) + r'\n[ \t]*include\s+[^;]+;',+ '',+ content,+ )++ # Insert right after the first "server {".+ match = re.search(r'server\s*\{', cleaned)+ if not match:+ return {'success': False, 'error': 'no server block found in vhost'}+ idx = match.end()+ new_content = cleaned[:idx] + '\n' + include_line + cleaned[idx:]++ return cls._write_file(vhost_path, new_content)++ @classmethod+ def apply(cls, application_id: int) -> Dict:+ """Render + persist the WAF artifacts for an app and reload nginx.++ Always writes the rules file and the nginx snippet. Then tries to+ additively wire the snippet into the app's vhost; if the vhost can't be+ located, returns ``manual_include`` describing how to wire it by hand.+ Finally validates + reloads nginx (skipped when there was nothing to+ enforce and no vhost wiring happened).+ """+ from app.models.application import Application+ from app.models.waf_policy import WafPolicy++ application = Application.query.get(application_id)+ if not application:+ return {'success': False, 'error': 'Application not found'}++ policy = WafPolicy.query.filter_by(application_id=application_id).first()+ if policy is None:+ policy = cls.get_or_create_policy(application_id)++ rules_path = os.path.join(WAF_RULES_DIR, f'app-{application_id}.conf')+ include_path = os.path.join(WAF_RULES_DIR, f'app-{application_id}.include.conf')++ rules = cls.render_rules(policy)+ snippet = cls.nginx_snippet(policy, rules_path)++ cls._ensure_rules_dir()+ wrote_rules = cls._write_file(rules_path, rules)+ if not wrote_rules['success']:+ return wrote_rules+ wrote_snippet = cls._write_file(include_path, snippet)+ if not wrote_snippet['success']:+ return wrote_snippet++ result = {+ 'success': True,+ 'rules_path': rules_path,+ 'include_path': include_path,+ 'mode': policy.mode,+ }++ vhost_path = cls._vhost_path(application_id)+ if vhost_path:+ injected = cls._inject_include(vhost_path, include_path)+ if not injected['success']:+ # Wiring failed but artifacts exist — surface for manual fix.+ result['wired'] = False+ result['manual_include'] = {+ 'include_path': include_path,+ 'reason': injected.get('error'),+ }+ else:+ result['wired'] = True+ result['vhost_path'] = vhost_path+ else:+ result['wired'] = False+ result['manual_include'] = {+ 'include_path': include_path,+ 'reason': (+ "no app vhost found in sites-available; add "+ f"'include {include_path};' inside the app's server block"+ ),+ }++ # Reload nginx so the change (or its removal) takes effect.+ reload_result = cls._nginx_test_and_reload()+ result['nginx_reloaded'] = reload_result.get('success', False)+ if not reload_result.get('success'):+ result['nginx_error'] = reload_result.get('error') or reload_result.get('message')+ return result++ # ------------------------------------------------------------------+ # Audit-log parsing (unit-testable via injectable path)+ # ------------------------------------------------------------------+ @classmethod+ def events(cls, application_id: int, limit: int = 50, log_path: str = None) -> List[Dict]:+ """Parse recent ModSecurity events from the JSON audit log.++ ModSecurity's JSON audit log writes one JSON object per line. We read+ the file, tolerate malformed lines, normalise each transaction into a+ flat event (rule id, message, severity, uri, client ip, timestamp), and+ return the most recent *limit* entries (newest first).++ *log_path* is injectable so tests can point at a fixture; it defaults to+ the module/env-configured ``MODSEC_AUDIT_LOG``.+ """+ path = log_path or MODSEC_AUDIT_LOG+ if not path or not os.path.isfile(path):+ return []++ events: List[Dict] = []+ try:+ with open(path, 'r', errors='ignore') as fh:+ for line in fh:+ line = line.strip()+ if not line:+ continue+ try:+ entry = json.loads(line)+ except (ValueError, TypeError):+ continue # tolerate malformed lines+ parsed = cls._parse_audit_entry(entry)+ if parsed:+ events.extend(parsed)+ except OSError as e:+ logger.warning('Failed to read modsec audit log %s: %s', path, e)+ return []++ # Newest first; cap to limit.+ events.reverse()+ return events[:limit]++ @staticmethod+ def _parse_audit_entry(entry: Dict) -> List[Dict]:+ """Flatten one ModSecurity JSON transaction into 0..n event dicts."""+ if not isinstance(entry, dict):+ return []+ txn = entry.get('transaction', {}) if isinstance(entry.get('transaction'), dict) else {}+ request = entry.get('request', {}) if isinstance(entry.get('request'), dict) else {}+ audit = entry.get('audit_data') or entry.get('audit', {})+ if not isinstance(audit, dict):+ audit = {}++ client_ip = txn.get('client_ip') or txn.get('remote_address')+ timestamp = txn.get('time') or entry.get('time') or txn.get('timestamp')+ uri = request.get('uri') or txn.get('uri')++ messages = audit.get('messages') or entry.get('messages') or []+ if isinstance(messages, str):+ messages = [messages]++ out: List[Dict] = []+ for msg in messages:+ rule_id = None+ severity = None+ text = None+ if isinstance(msg, dict):+ details = msg.get('details', {}) if isinstance(msg.get('details'), dict) else {}+ rule_id = details.get('ruleId') or details.get('id') or msg.get('id')+ severity = details.get('severity') or msg.get('severity')+ text = msg.get('message') or msg.get('msg')+ else:+ text = str(msg)+ # Best-effort: pull "[id "942100"]" / "[severity ...]" out of the line.+ id_match = re.search(r'\[id "?(\d+)"?\]', text)+ if id_match:+ rule_id = id_match.group(1)+ sev_match = re.search(r'\[severity "?([^"\]]+)"?\]', text)+ if sev_match:+ severity = sev_match.group(1)++ out.append({+ 'rule_id': str(rule_id) if rule_id is not None else None,+ 'message': text,+ 'severity': severity,+ 'uri': uri,+ 'client_ip': client_ip,+ 'timestamp': timestamp,+ })+ return outdiff --git a/backend/tests/test_waf.py b/backend/tests/test_waf.pynew file mode 100644index 00000000..cea5f5bc--- /dev/null+++ b/backend/tests/test_waf.py@@ -0,0 +1,304 @@+"""Tests for the per-application WAF (ModSecurity v3 + OWASP CRS) feature."""+import json+import uuid++import pytest++from app import db+from app.models import Application+from app.models.waf_policy import WafPolicy+from app.services.waf_service import WafService+++def _seed_app(name='web'):+ """Create a user + Application like other backend tests do."""+ from app.models import User+ uid = uuid.uuid4().hex[:8]+ user = User(email=f'{uid}@t.local', username=f'u{uid}',+ password_hash='x', role=User.ROLE_ADMIN, is_active=True)+ db.session.add(user)+ db.session.commit()+ row = Application(name=name, app_type='docker', source='manual',+ docker_image='nginx:latest', user_id=user.id)+ db.session.add(row)+ db.session.commit()+ return row+++# ---------------------------------------------------------------------------+# Pure renderer: render_rules+# ---------------------------------------------------------------------------+class TestRenderRules:+ def test_block_mode_engine_on(self, app):+ a = _seed_app()+ policy = WafService.get_or_create_policy(a.id)+ policy.mode = 'block'+ rules = WafService.render_rules(policy)+ assert 'SecRuleEngine On' in rules+ assert 'DetectionOnly' not in rules++ def test_detect_mode_detection_only(self, app):+ a = _seed_app()+ policy = WafService.get_or_create_policy(a.id)+ policy.mode = 'detect'+ rules = WafService.render_rules(policy)+ assert 'SecRuleEngine DetectionOnly' in rules++ def test_off_mode_engine_off(self, app):+ a = _seed_app()+ policy = WafService.get_or_create_policy(a.id)+ policy.mode = 'off'+ rules = WafService.render_rules(policy)+ assert 'SecRuleEngine Off' in rules+ # 'off' must not pull in the CRS.+ assert 'Include' not in rules++ def test_disabled_rule_ids_produce_remove_lines(self, app):+ a = _seed_app()+ policy = WafService.get_or_create_policy(a.id)+ policy.mode = 'block'+ policy.disabled_rules = ['942100', '920350']+ rules = WafService.render_rules(policy)+ assert 'SecRuleRemoveById 942100' in rules+ assert 'SecRuleRemoveById 920350' in rules++ def test_paranoia_and_anomaly_appear(self, app):+ a = _seed_app()+ policy = WafService.get_or_create_policy(a.id)+ policy.mode = 'block'+ policy.paranoia_level = 3+ policy.anomaly_threshold = 10+ rules = WafService.render_rules(policy)+ assert 'tx.blocking_paranoia_level=3' in rules+ assert 'tx.inbound_anomaly_score_threshold=10' in rules++ def test_crs_included_when_enforcing(self, app):+ a = _seed_app()+ policy = WafService.get_or_create_policy(a.id)+ policy.mode = 'block'+ rules = WafService.render_rules(policy, crs_path='/custom/crs.load')+ assert 'Include /custom/crs.load' in rules++ def test_non_numeric_disabled_rules_are_dropped(self, app):+ a = _seed_app()+ policy = WafService.get_or_create_policy(a.id)+ policy.mode = 'block'+ policy.disabled_rules = ['942100', 'evil; rm -rf /']+ rules = WafService.render_rules(policy)+ assert 'SecRuleRemoveById 942100' in rules+ assert 'rm -rf' not in rules+++# ---------------------------------------------------------------------------+# Pure renderer: nginx_snippet+# ---------------------------------------------------------------------------+class TestNginxSnippet:+ def test_snippet_on(self, app):+ a = _seed_app()+ policy = WafService.get_or_create_policy(a.id)+ policy.mode = 'block'+ snippet = WafService.nginx_snippet(policy, '/etc/nginx/serverkit-conf.d/waf/app-1.conf')+ assert 'modsecurity on;' in snippet+ assert 'modsecurity_rules_file /etc/nginx/serverkit-conf.d/waf/app-1.conf;' in snippet++ def test_snippet_off(self, app):+ a = _seed_app()+ policy = WafService.get_or_create_policy(a.id)+ policy.mode = 'off'+ snippet = WafService.nginx_snippet(policy, '/x.conf')+ assert 'modsecurity off;' in snippet+ assert 'modsecurity_rules_file' not in snippet++ def test_detect_mode_turns_modsecurity_on(self, app):+ a = _seed_app()+ policy = WafService.get_or_create_policy(a.id)+ policy.mode = 'detect'+ snippet = WafService.nginx_snippet(policy, '/x.conf')+ assert 'modsecurity on;' in snippet+++# ---------------------------------------------------------------------------+# Policy validation: set_policy+# ---------------------------------------------------------------------------+class TestSetPolicy:+ def test_rejects_invalid_mode(self, app):+ a = _seed_app()+ with pytest.raises(ValueError):+ WafService.set_policy(a.id, mode='nonsense')++ def test_clamps_paranoia_high(self, app):+ a = _seed_app()+ policy = WafService.set_policy(a.id, paranoia_level=99)+ assert policy.paranoia_level == 4++ def test_clamps_paranoia_low(self, app):+ a = _seed_app()+ policy = WafService.set_policy(a.id, paranoia_level=0)+ assert policy.paranoia_level == 1++ def test_accepts_valid_mode_and_persists(self, app):+ a = _seed_app()+ WafService.set_policy(a.id, mode='block', anomaly_threshold=7)+ policy = WafPolicy.query.filter_by(application_id=a.id).first()+ assert policy.mode == 'block'+ assert policy.anomaly_threshold == 7++ def test_disabled_rule_ids_round_trip(self, app):+ a = _seed_app()+ policy = WafService.set_policy(a.id, disabled_rule_ids=['942100', '920350'])+ assert policy.disabled_rules == ['942100', '920350']+ # Survives a reload from the DB.+ again = WafPolicy.query.filter_by(application_id=a.id).first()+ assert again.to_dict()['disabled_rule_ids'] == ['942100', '920350']++ def test_disabled_rule_ids_must_be_list(self, app):+ a = _seed_app()+ with pytest.raises(ValueError):+ WafService.set_policy(a.id, disabled_rule_ids='942100')+++# ---------------------------------------------------------------------------+# Audit-log parsing: events+# ---------------------------------------------------------------------------+SAMPLE_AUDIT_LINES = [+ json.dumps({+ "transaction": {+ "client_ip": "203.0.113.7",+ "time": "2026-06-19T12:00:01Z",+ },+ "request": {"uri": "/login?id=1' OR '1'='1"},+ "audit_data": {+ "messages": [+ {+ "message": "SQL Injection Attack Detected",+ "details": {"ruleId": "942100", "severity": "CRITICAL"},+ }+ ]+ },+ }),+ "this is not valid json {{{", # malformed line — must be tolerated+ json.dumps({+ "transaction": {+ "client_ip": "198.51.100.4",+ "time": "2026-06-19T12:00:05Z",+ },+ "request": {"uri": "/admin"},+ "audit_data": {+ "messages": [+ "ModSecurity: Access denied [id \"920350\"] [severity \"WARNING\"]"+ ]+ },+ }),+]+++class TestEvents:+ def _write_log(self, tmp_path):+ log = tmp_path / 'modsec_audit.log'+ log.write_text('\n'.join(SAMPLE_AUDIT_LINES) + '\n')+ return str(log)++ def test_parses_expected_count(self, app, tmp_path):+ log = self._write_log(tmp_path)+ events = WafService.events(application_id=1, log_path=log)+ # Two valid transactions -> two events; malformed line skipped.+ assert len(events) == 2++ def test_parses_structured_fields(self, app, tmp_path):+ log = self._write_log(tmp_path)+ events = WafService.events(application_id=1, log_path=log)+ # Newest first.+ ids = {e['rule_id'] for e in events}+ assert '942100' in ids+ assert '920350' in ids+ sqli = next(e for e in events if e['rule_id'] == '942100')+ assert sqli['client_ip'] == '203.0.113.7'+ assert sqli['severity'] == 'CRITICAL'+ assert sqli['uri'].startswith('/login')+ assert sqli['timestamp'] == '2026-06-19T12:00:01Z'++ def test_parses_string_message_fields(self, app, tmp_path):+ log = self._write_log(tmp_path)+ events = WafService.events(application_id=1, log_path=log)+ denied = next(e for e in events if e['rule_id'] == '920350')+ assert denied['severity'] == 'WARNING'+ assert denied['client_ip'] == '198.51.100.4'++ def test_limit_is_respected(self, app, tmp_path):+ log = self._write_log(tmp_path)+ events = WafService.events(application_id=1, log_path=log, limit=1)+ assert len(events) == 1++ def test_missing_log_returns_empty(self, app):+ assert WafService.events(application_id=1, log_path='/no/such/file.log') == []+++# ---------------------------------------------------------------------------+# API+# ---------------------------------------------------------------------------+class TestWafApi:+ def test_put_policy_round_trips(self, client, auth_headers, app, monkeypatch):+ a = _seed_app()+ # Don't touch nginx / the filesystem.+ monkeypatch.setattr(WafService, 'apply', lambda app_id: {'success': True})+ resp = client.put(+ f'/api/v1/waf/applications/{a.id}/policy',+ headers=auth_headers,+ json={'mode': 'block', 'paranoia_level': 2, 'disabled_rule_ids': ['942100']},+ )+ assert resp.status_code == 200+ body = resp.get_json()+ assert body['mode'] == 'block'+ assert body['paranoia_level'] == 2+ assert body['disabled_rule_ids'] == ['942100']+ assert body['apply'] == {'success': True}++ def test_get_policy_returns_default(self, client, auth_headers, app):+ a = _seed_app()+ resp = client.get(+ f'/api/v1/waf/applications/{a.id}/policy', headers=auth_headers)+ assert resp.status_code == 200+ assert resp.get_json()['mode'] == 'off'++ def test_put_invalid_mode_returns_400(self, client, auth_headers, app, monkeypatch):+ a = _seed_app()+ monkeypatch.setattr(WafService, 'apply', lambda app_id: {'success': True})+ resp = client.put(+ f'/api/v1/waf/applications/{a.id}/policy',+ headers=auth_headers,+ json={'mode': 'bogus'},+ )+ assert resp.status_code == 400++ def test_status_reports_installed(self, client, auth_headers, app, monkeypatch):+ monkeypatch.setattr(WafService, 'modsecurity_installed', classmethod(lambda cls: True))+ resp = client.get('/api/v1/waf/status', headers=auth_headers)+ assert resp.status_code == 200+ assert resp.get_json()['installed'] is True++ def test_apply_endpoint(self, client, auth_headers, app, monkeypatch):+ a = _seed_app()+ monkeypatch.setattr(WafService, 'apply',+ lambda app_id: {'success': True, 'wired': True})+ resp = client.post(+ f'/api/v1/waf/applications/{a.id}/apply', headers=auth_headers)+ assert resp.status_code == 200+ assert resp.get_json()['wired'] is True++ def test_events_endpoint(self, client, auth_headers, app, monkeypatch):+ a = _seed_app()+ monkeypatch.setattr(WafService, 'events',+ lambda application_id, limit=50: [{'rule_id': '942100'}])+ resp = client.get(+ f'/api/v1/waf/applications/{a.id}/events', headers=auth_headers)+ assert resp.status_code == 200+ body = resp.get_json()+ assert body['count'] == 1+ assert body['events'][0]['rule_id'] == '942100'++ def test_put_requires_auth(self, client, app):+ resp = client.put('/api/v1/waf/applications/1/policy', json={'mode': 'block'})+ assert resp.status_code == 401++ def test_status_requires_auth(self, client, app):+ assert client.get('/api/v1/waf/status').status_code == 401