Skip to content

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.

feat(security): per-app WAF (ModSecurity v3 + OWASP CRS)

Juan Denisada030553a7d
diff --git a/backend/app/__init__.py b/backend/app/__init__.py
index 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_bp
app.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 monitoring
from app.api.gpu import gpu_bp
app.register_blueprint(gpu_bp, url_prefix='/api/v1/gpu')
diff --git a/backend/app/api/waf.py b/backend/app/api/waf.py
new file mode 100644
index 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_code
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index 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, SbomArtifact
from app.models.passkey import PasskeyCredential
from app.models.secret_vault import SecretVault, Secret
from 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 out
diff --git a/backend/tests/test_waf.py b/backend/tests/test_waf.py
new file mode 100644
index 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