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): scoped file-integrity monitoring

Juan Denis202b310c94e8
diff --git a/backend/app/services/file_integrity_service.py b/backend/app/services/file_integrity_service.py
new file mode 100644
index 00000000..4a613507
--- /dev/null
+++ b/backend/app/services/file_integrity_service.py
@@ -0,0 +1,481 @@
+"""Scoped file-integrity monitoring (FIM).
+
+Baseline-and-diff over the paths ServerKit manages:
+
+- ``nginx`` — /etc/nginx/sites-enabled + /etc/nginx/conf.d
+- ``systemd`` — the serverkit-owned units in /etc/systemd/system
+- ``app:<id>`` — an application docroot, on explicit per-app opt-in
+ (opt-in set stored in SettingsService key 'fim_app_optins')
+
+Baselines are JSON files under ``STATE_DIR`` (``/var/serverkit/security/fim``
+by default, overridable for tests). Everything is best-effort and
+OS-agnostic: hashing works on any existing directory; on dev boxes the
+default Linux paths simply don't exist and the scope reads as empty.
+
+Changes found by the scheduled ``security.fim.check`` job feed the
+Notifications Bus as ``integrity.changed`` events.
+
+This complements — but does not depend on — config drift detection, which
+compares rendered configs against what ServerKit would re-render. FIM only
+answers "did files change since the operator last accepted a baseline?".
+"""
+
+import fnmatch
+import hashlib
+import json
+import logging
+import os
+import re
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+from app import paths
+
+logger = logging.getLogger(__name__)
+
+FIM_JOB_KIND = 'security.fim.check'
+FIM_SCHEDULE_NAME = 'fim-check'
+FIM_EVENT_KEY = 'integrity.changed'
+OPTIN_SETTING_KEY = 'fim_app_optins'
+
+_APP_SCOPE_RE = re.compile(r'^app:(\d+)$')
+
+# Cap the change lists persisted/returned per category so a mass change
+# (e.g. a full redeploy) can't balloon the state file or the API payload.
+MAX_LISTED_CHANGES = 500
+# Sample paths included in a notification.
+NOTIFY_SAMPLE_CAP = 10
+
+
+class FileIntegrityScopeError(ValueError):
+ """Unknown/invalid scope or scope without a usable root (HTTP 400)."""
+
+
+class FileIntegrityService:
+ """Baseline-and-diff file integrity monitoring over managed paths."""
+
+ # Overridable in tests.
+ STATE_DIR = os.path.join(paths.SERVERKIT_DIR, 'security', 'fim')
+
+ NGINX_ROOTS = ['/etc/nginx/sites-enabled', '/etc/nginx/conf.d']
+ SYSTEMD_ROOT = '/etc/systemd/system'
+ # Only serverkit-owned units are in scope for the systemd walk.
+ SYSTEMD_INCLUDE = ['serverkit*']
+
+ # Default exclude patterns, matched (fnmatch) against the file's relative
+ # path within its scope root and against every path segment.
+ DEFAULT_EXCLUDES = {
+ 'nginx': ['*.log'],
+ 'systemd': [],
+ 'app': [
+ '*.log',
+ 'logs/*',
+ 'log/*',
+ 'cache/*',
+ 'tmp/*',
+ 'temp/*',
+ 'node_modules/*',
+ 'vendor/cache/*',
+ '.git/*',
+ '__pycache__/*',
+ '*.pyc',
+ 'wp-content/uploads/*',
+ 'wp-content/cache/*',
+ 'wp-content/upgrade/*',
+ ],
+ }
+
+ # ------------------------------------------------------------------ #
+ # Scope resolution
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def _scope_kind(cls, scope: str) -> str:
+ if scope in ('nginx', 'systemd'):
+ return scope
+ if _APP_SCOPE_RE.match(scope or ''):
+ return 'app'
+ raise FileIntegrityScopeError(f'Unknown scope: {scope!r}')
+
+ @classmethod
+ def _scope_roots(cls, scope: str) -> List[str]:
+ """Existing directories for a scope (may be empty on dev boxes)."""
+ kind = cls._scope_kind(scope)
+ if kind == 'nginx':
+ roots = list(cls.NGINX_ROOTS)
+ elif kind == 'systemd':
+ roots = [cls.SYSTEMD_ROOT]
+ else:
+ app_id = int(_APP_SCOPE_RE.match(scope).group(1))
+ from app.models.application import Application
+ application = Application.query.get(app_id)
+ if not application:
+ raise FileIntegrityScopeError(f'Application {app_id} not found')
+ roots = [application.root_path] if application.root_path else []
+ return [r for r in roots if r and os.path.isdir(r)]
+
+ @classmethod
+ def _scope_excludes(cls, scope: str, options: Optional[Dict] = None) -> List[str]:
+ kind = cls._scope_kind(scope)
+ excludes = list(cls.DEFAULT_EXCLUDES.get(kind, []))
+ if options and isinstance(options.get('exclude'), list):
+ excludes.extend(str(p) for p in options['exclude'])
+ return excludes
+
+ @classmethod
+ def _include_file(cls, scope: str, filename: str) -> bool:
+ """Per-scope include filter on the file name (systemd → serverkit-*)."""
+ if cls._scope_kind(scope) != 'systemd':
+ return True
+ return any(fnmatch.fnmatch(filename, pat) for pat in cls.SYSTEMD_INCLUDE)
+
+ @staticmethod
+ def _excluded(rel_path: str, excludes: List[str]) -> bool:
+ rel = rel_path.replace(os.sep, '/')
+ segments = rel.split('/')
+ for pat in excludes:
+ if fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(segments[-1], pat):
+ return True
+ # Directory patterns like 'cache/*' should also match nested
+ # 'wp-content/cache/…' style trees when written bare.
+ if pat.endswith('/*'):
+ d = pat[:-2]
+ if d in segments[:-1]:
+ return True
+ return False
+
+ # ------------------------------------------------------------------ #
+ # Hashing / snapshot
+ # ------------------------------------------------------------------ #
+
+ @staticmethod
+ def _sha256(path: str) -> str:
+ digest = hashlib.sha256()
+ with open(path, 'rb') as fh:
+ for block in iter(lambda: fh.read(65536), b''):
+ digest.update(block)
+ return digest.hexdigest()
+
+ @classmethod
+ def _snapshot(cls, scope: str, roots: List[str], excludes: List[str]) -> Dict[str, Dict]:
+ """Walk the scope roots → {relpath: {sha256, size, mode, mtime}}.
+
+ With multiple roots (nginx) the relpath is prefixed with the root's
+ basename ('sites-enabled/…', 'conf.d/…') so keys stay unambiguous.
+ """
+ prefix_keys = len(roots) > 1
+ files: Dict[str, Dict] = {}
+ for root in roots:
+ prefix = os.path.basename(root.rstrip('/\\')) if prefix_keys else ''
+ for dirpath, dirnames, filenames in os.walk(root):
+ # Prune excluded directories early (cheap on big docroots).
+ rel_dir = os.path.relpath(dirpath, root)
+ rel_dir = '' if rel_dir == '.' else rel_dir.replace(os.sep, '/')
+ dirnames[:] = [
+ d for d in dirnames
+ if not cls._excluded((rel_dir + '/' + d if rel_dir else d) + '/x', excludes)
+ ]
+ for filename in filenames:
+ if not cls._include_file(scope, filename):
+ continue
+ rel = (rel_dir + '/' + filename) if rel_dir else filename
+ if cls._excluded(rel, excludes):
+ continue
+ key = (prefix + '/' + rel) if prefix else rel
+ full = os.path.join(dirpath, filename)
+ try:
+ stat = os.stat(full)
+ files[key] = {
+ 'sha256': cls._sha256(full),
+ 'size': stat.st_size,
+ 'mode': stat.st_mode,
+ 'mtime': stat.st_mtime,
+ }
+ except (PermissionError, FileNotFoundError, OSError):
+ continue # best-effort: unreadable files are skipped
+ return files
+
+ # ------------------------------------------------------------------ #
+ # State store
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def _state_path(cls, scope: str) -> str:
+ # 'app:3' → 'app_3.json' (keep filenames filesystem-safe).
+ return os.path.join(cls.STATE_DIR, scope.replace(':', '_') + '.json')
+
+ @classmethod
+ def _load_state(cls, scope: str) -> Optional[Dict]:
+ path = cls._state_path(scope)
+ if not os.path.exists(path):
+ return None
+ try:
+ with open(path, 'r') as fh:
+ return json.load(fh)
+ except (ValueError, OSError):
+ logger.warning('FIM state for %s unreadable; treating as no baseline', scope)
+ return None
+
+ @classmethod
+ def _save_state(cls, scope: str, state: Dict) -> None:
+ os.makedirs(cls.STATE_DIR, exist_ok=True)
+ path = cls._state_path(scope)
+ tmp = path + '.tmp'
+ with open(tmp, 'w') as fh:
+ json.dump(state, fh)
+ os.replace(tmp, path)
+
+ @classmethod
+ def _baselined_scopes(cls) -> List[str]:
+ if not os.path.isdir(cls.STATE_DIR):
+ return []
+ scopes = []
+ for name in sorted(os.listdir(cls.STATE_DIR)):
+ if name.endswith('.json'):
+ scopes.append(name[:-5].replace('app_', 'app:', 1)
+ if name.startswith('app_') else name[:-5])
+ return scopes
+
+ # ------------------------------------------------------------------ #
+ # Opt-ins (per-app)
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def get_app_optins(cls) -> List[int]:
+ from app.services.settings_service import SettingsService
+ raw = SettingsService.get(OPTIN_SETTING_KEY)
+ if not raw:
+ return []
+ try:
+ ids = json.loads(raw) if isinstance(raw, str) else raw
+ return sorted({int(i) for i in ids})
+ except (ValueError, TypeError):
+ return []
+
+ @classmethod
+ def set_app_optins(cls, app_ids: List[int]) -> List[int]:
+ try:
+ ids = sorted({int(i) for i in (app_ids or [])})
+ except (ValueError, TypeError):
+ raise FileIntegrityScopeError('app_ids must be a list of integers')
+
+ previous = set(cls.get_app_optins())
+ from app.services.settings_service import SettingsService
+ SettingsService.set(OPTIN_SETTING_KEY, json.dumps(ids))
+
+ # Drop stale baselines for apps that were opted out (best-effort).
+ for removed in previous - set(ids):
+ try:
+ path = cls._state_path(f'app:{removed}')
+ if os.path.exists(path):
+ os.remove(path)
+ except OSError:
+ pass
+ return ids
+
+ # ------------------------------------------------------------------ #
+ # Core operations
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def baseline(cls, scope: str, options: Optional[Dict] = None) -> Dict:
+ """(Re-)create the baseline for a scope. Returns a summary dict."""
+ roots = cls._scope_roots(scope) # raises on unknown scope
+ excludes = cls._scope_excludes(scope, options)
+ files = cls._snapshot(scope, roots, excludes)
+ state = {
+ 'scope': scope,
+ 'created_at': datetime.now(timezone.utc).isoformat(),
+ 'roots': roots,
+ 'excludes': excludes,
+ 'files': files,
+ 'last_check': None,
+ }
+ cls._save_state(scope, state)
+ return {
+ 'scope': scope,
+ 'created_at': state['created_at'],
+ 'file_count': len(files),
+ 'roots': roots,
+ }
+
+ @classmethod
+ def check(cls, scope: str) -> Dict:
+ """Diff current filesystem state against the scope baseline."""
+ cls._scope_kind(scope) # validate early
+ state = cls._load_state(scope)
+ if state is None:
+ raise FileIntegrityScopeError(f'No baseline for scope {scope!r} — baseline it first')
+
+ roots = cls._scope_roots(scope)
+ excludes = state.get('excludes') or cls._scope_excludes(scope)
+ current = cls._snapshot(scope, roots, excludes)
+ baseline_files = state.get('files') or {}
+
+ added = sorted(set(current) - set(baseline_files))
+ removed = sorted(set(baseline_files) - set(current))
+ modified = []
+ for rel in sorted(set(current) & set(baseline_files)):
+ was, now = baseline_files[rel], current[rel]
+ what = []
+ if now['sha256'] != was['sha256']:
+ what.append('hash')
+ if now['size'] != was['size']:
+ what.append('size')
+ if now['mode'] != was['mode']:
+ what.append('mode')
+ if what:
+ modified.append({'path': rel, 'what': what})
+
+ result = {
+ 'scope': scope,
+ 'checked_at': datetime.now(timezone.utc).isoformat(),
+ 'baseline_created_at': state.get('created_at'),
+ 'added': added[:MAX_LISTED_CHANGES],
+ 'removed': removed[:MAX_LISTED_CHANGES],
+ 'modified': modified[:MAX_LISTED_CHANGES],
+ 'counts': {
+ 'added': len(added),
+ 'removed': len(removed),
+ 'modified': len(modified),
+ },
+ 'total_changes': len(added) + len(removed) + len(modified),
+ }
+ state['last_check'] = result
+ cls._save_state(scope, state)
+ return result
+
+ @classmethod
+ def accept(cls, scope: str) -> Dict:
+ """Operator acknowledges changes → re-baseline the scope."""
+ # Preserve any operator-supplied extra excludes across accepts by
+ # re-baselining with the extras the previous baseline carried.
+ state = cls._load_state(scope)
+ options = None
+ if state and state.get('excludes'):
+ defaults = cls._scope_excludes(scope)
+ extra = [e for e in state['excludes'] if e not in defaults]
+ if extra:
+ options = {'exclude': extra}
+ return cls.baseline(scope, options=options)
+
+ @classmethod
+ def check_all(cls) -> Dict:
+ """Check every baselined scope; notify admins when changes are found."""
+ results = {}
+ for scope in cls._baselined_scopes():
+ try:
+ result = cls.check(scope)
+ except FileIntegrityScopeError as exc:
+ results[scope] = {'error': str(exc)}
+ continue
+ except Exception as exc: # never let one scope kill the sweep
+ logger.warning('FIM check for %s failed: %s', scope, exc)
+ results[scope] = {'error': str(exc)}
+ continue
+ results[scope] = result
+ if result['total_changes'] > 0:
+ sample = (result['added'] + result['removed']
+ + [m['path'] for m in result['modified']])[:NOTIFY_SAMPLE_CAP]
+ cls._notify(scope, result['counts'], sample)
+ return results
+
+ # ------------------------------------------------------------------ #
+ # Status (for the API/UI)
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def get_status(cls) -> Dict:
+ """Scopes + baseline metadata + last results, for GET /security/fim."""
+ optins = cls.get_app_optins()
+ scopes = []
+
+ app_names = {}
+ if optins:
+ try:
+ from app.models.application import Application
+ for application in Application.query.filter(Application.id.in_(optins)).all():
+ app_names[application.id] = application.name
+ except Exception:
+ pass # status must degrade gracefully outside a DB context
+
+ for scope in ['nginx', 'systemd'] + [f'app:{i}' for i in optins]:
+ try:
+ roots = cls._scope_roots(scope)
+ except FileIntegrityScopeError:
+ roots = []
+ state = cls._load_state(scope)
+ entry = {
+ 'scope': scope,
+ 'roots': roots,
+ 'available': bool(roots),
+ 'baseline': None,
+ 'last_check': None,
+ }
+ match = _APP_SCOPE_RE.match(scope)
+ if match:
+ app_id = int(match.group(1))
+ entry['app_id'] = app_id
+ entry['app_name'] = app_names.get(app_id)
+ if state:
+ entry['baseline'] = {
+ 'created_at': state.get('created_at'),
+ 'file_count': len(state.get('files') or {}),
+ }
+ entry['last_check'] = state.get('last_check')
+ scopes.append(entry)
+
+ return {'scopes': scopes, 'app_optins': optins}
+
+ # ------------------------------------------------------------------ #
+ # Notifications (best-effort)
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def _notify(cls, scope: str, counts: Dict, sample_paths: List[str]) -> None:
+ try:
+ from app.plugins_sdk import notify
+ notify.send(
+ FIM_EVENT_KEY,
+ to='admins',
+ data={
+ 'scope': scope,
+ 'counts': counts,
+ 'sample_paths': sample_paths,
+ },
+ category='security',
+ )
+ except Exception as exc: # never let a notification failure break a check
+ logger.debug('notify %s failed: %s', FIM_EVENT_KEY, exc)
+
+ # ------------------------------------------------------------------ #
+ # Job registration
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def run_check_job(cls, job) -> Dict:
+ """Job handler for the scheduled sweep (kind: security.fim.check)."""
+ results = cls.check_all()
+ return {
+ 'scopes_checked': len(results),
+ 'scopes_changed': sum(
+ 1 for r in results.values() if r.get('total_changes')
+ ),
+ }
+
+ @classmethod
+ def register_jobs(cls):
+ """Register the FIM job handler + notification event.
+ Called once at app startup (see app/__init__.py)."""
+ from app.jobs import registry
+ registry.register(FIM_JOB_KIND, cls.run_check_job, replace=True)
+ try:
+ from app.notifications import catalog
+ catalog.register(
+ FIM_EVENT_KEY,
+ 'File integrity changes detected',
+ severity='warning',
+ category='security',
+ )
+ except Exception as exc:
+ logger.debug('FIM event registration failed: %s', exc)
diff --git a/backend/tests/test_file_integrity.py b/backend/tests/test_file_integrity.py
new file mode 100644
index 00000000..76c5e61e
--- /dev/null
+++ b/backend/tests/test_file_integrity.py
@@ -0,0 +1,417 @@
+"""Tests for the scoped file-integrity monitoring service + API (task #16)."""
+import json
+import os
+import stat as stat_mod
+
+import pytest
+
+from app.services.file_integrity_service import (
+ FIM_EVENT_KEY,
+ FIM_JOB_KIND,
+ FileIntegrityScopeError,
+ FileIntegrityService,
+ OPTIN_SETTING_KEY,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Helpers / fixtures
+# --------------------------------------------------------------------------- #
+
+def fim(tmp_path, monkeypatch):
+ """FileIntegrityService pointed at tmp dirs for state + nginx/systemd roots."""
+ state_dir = tmp_path / 'state'
+ sites = tmp_path / 'sites-enabled'
+ confd = tmp_path / 'conf.d'
+ systemd = tmp_path / 'systemd'
+ for d in (sites, confd, systemd):
+ d.mkdir()
+
+ monkeypatch.setattr(FileIntegrityService, 'STATE_DIR', str(state_dir))
+ monkeypatch.setattr(FileIntegrityService, 'NGINX_ROOTS', [str(sites), str(confd)])
+ monkeypatch.setattr(FileIntegrityService, 'SYSTEMD_ROOT', str(systemd))
+
+ (sites / 'site-a.conf').write_text('server { listen 80; }')
+ (confd / 'gzip.conf').write_text('gzip on;')
+ (systemd / 'serverkit-agent.service').write_text('[Unit]\nDescription=x\n')
+ (systemd / 'unrelated.service').write_text('[Unit]\nDescription=y\n')
+
+ return {
+ 'sites': sites,
+ 'confd': confd,
+ 'systemd': systemd,
+ 'state': state_dir,
+ }
+
+
+def _make_app(db, name='fimapp', root_path=None):
+ from app.models import User
+ from app.models.application import Application
+ user = User.query.first()
+ if user is None:
+ from werkzeug.security import generate_password_hash
+ user = User(
+ email='[email protected]', username='fimuser',
+ password_hash=generate_password_hash('x'),
+ role=User.ROLE_ADMIN, is_active=True,
+ )
+ db.session.add(user)
+ db.session.commit()
+ application = Application(
+ name=name, app_type='php', user_id=user.id, root_path=root_path,
+ )
+ db.session.add(application)
+ db.session.commit()
+ return application
+
+
+# --------------------------------------------------------------------------- #
+# Baseline + check diffing
+# --------------------------------------------------------------------------- #
+
+def test_baseline_records_files(fim):
+ summary = FileIntegrityService.baseline('nginx')
+ assert summary['scope'] == 'nginx'
+ assert summary['file_count'] == 2
+ # Multi-root scope prefixes relpaths with the root basename.
+ state = FileIntegrityService._load_state('nginx')
+ keys = set(state['files'])
+ assert 'sites-enabled/site-a.conf' in keys
+ assert 'conf.d/gzip.conf' in keys
+ entry = state['files']['sites-enabled/site-a.conf']
+ assert set(entry) == {'sha256', 'size', 'mode', 'mtime'}
+ assert len(entry['sha256']) == 64
+
+
+def test_check_detects_added_removed_modified(fim):
+ FileIntegrityService.baseline('nginx')
+
+ (fim['sites'] / 'site-b.conf').write_text('server { listen 81; }') # added
+ (fim['confd'] / 'gzip.conf').unlink() # removed
+ (fim['sites'] / 'site-a.conf').write_text('server { listen 443; }') # modified
+
+ result = FileIntegrityService.check('nginx')
+ assert result['added'] == ['sites-enabled/site-b.conf']
+ assert result['removed'] == ['conf.d/gzip.conf']
+ assert len(result['modified']) == 1
+ mod = result['modified'][0]
+ assert mod['path'] == 'sites-enabled/site-a.conf'
+ assert 'hash' in mod['what']
+ assert 'size' in mod['what'] # content length changed too
+ assert result['total_changes'] == 3
+ assert result['counts'] == {'added': 1, 'removed': 1, 'modified': 1}
+
+ # Last result is persisted in the scope state.
+ state = FileIntegrityService._load_state('nginx')
+ assert state['last_check']['total_changes'] == 3
+
+
+def test_check_detects_mode_change(fim):
+ target = fim['sites'] / 'site-a.conf'
+ FileIntegrityService.baseline('nginx')
+
+ before = os.stat(target).st_mode
+ os.chmod(target, stat_mod.S_IREAD) # read-only works on every OS
+ if os.stat(target).st_mode == before:
+ os.chmod(target, before)
+ pytest.skip('chmod does not change st_mode on this filesystem')
+
+ try:
+ result = FileIntegrityService.check('nginx')
+ mods = {m['path']: m['what'] for m in result['modified']}
+ assert mods == {'sites-enabled/site-a.conf': ['mode']}
+ finally:
+ os.chmod(target, before)
+
+
+def test_check_without_baseline_raises(fim):
+ with pytest.raises(FileIntegrityScopeError):
+ FileIntegrityService.check('nginx')
+
+
+def test_unknown_scope_rejected(fim):
+ with pytest.raises(FileIntegrityScopeError):
+ FileIntegrityService.baseline('etc-passwd')
+ with pytest.raises(FileIntegrityScopeError):
+ FileIntegrityService.check('app:notanumber')
+
+
+def test_systemd_scope_only_serverkit_units(fim):
+ summary = FileIntegrityService.baseline('systemd')
+ state = FileIntegrityService._load_state('systemd')
+ assert summary['file_count'] == 1
+ assert list(state['files']) == ['serverkit-agent.service']
+
+ # A change to a non-serverkit unit stays invisible.
+ (fim['systemd'] / 'unrelated.service').write_text('changed')
+ result = FileIntegrityService.check('systemd')
+ assert result['total_changes'] == 0
+
+
+def test_accept_rebaselines(fim):
+ FileIntegrityService.baseline('nginx')
+ (fim['sites'] / 'site-b.conf').write_text('new')
+ assert FileIntegrityService.check('nginx')['total_changes'] == 1
+
+ FileIntegrityService.accept('nginx')
+ assert FileIntegrityService.check('nginx')['total_changes'] == 0
+
+
+def test_accept_preserves_extra_excludes(fim):
+ FileIntegrityService.baseline('nginx', options={'exclude': ['*.ignore']})
+ (fim['sites'] / 'x.ignore').write_text('noise')
+ assert FileIntegrityService.check('nginx')['total_changes'] == 0
+
+ FileIntegrityService.accept('nginx')
+ (fim['sites'] / 'y.ignore').write_text('more noise')
+ assert FileIntegrityService.check('nginx')['total_changes'] == 0
+
+
+# --------------------------------------------------------------------------- #
+# Exclusions
+# --------------------------------------------------------------------------- #
+
+def test_nginx_scope_excludes_logs(fim):
+ (fim['sites'] / 'access.log').write_text('GET /')
+ FileIntegrityService.baseline('nginx')
+ state = FileIntegrityService._load_state('nginx')
+ assert 'sites-enabled/access.log' not in state['files']
+
+ (fim['sites'] / 'error.log').write_text('boom')
+ assert FileIntegrityService.check('nginx')['total_changes'] == 0
+
+
+def test_app_scope_excludes_uploads_and_cache(fim, tmp_path, app, db_session):
+ docroot = tmp_path / 'docroot'
+ (docroot / 'wp-content' / 'uploads').mkdir(parents=True)
+ (docroot / 'wp-content' / 'cache').mkdir(parents=True)
+ (docroot / 'index.php').write_text('<?php echo 1;')
+ (docroot / 'wp-content' / 'uploads' / 'img.jpg').write_text('jpegdata')
+ (docroot / 'wp-content' / 'cache' / 'page.html').write_text('cached')
+
+ application = _make_app(db_session, root_path=str(docroot))
+ scope = f'app:{application.id}'
+
+ summary = FileIntegrityService.baseline(scope)
+ assert summary['file_count'] == 1
+ state = FileIntegrityService._load_state(scope)
+ assert list(state['files']) == ['index.php']
+
+ # Churn in excluded trees never shows up as a change.
+ (docroot / 'wp-content' / 'uploads' / 'img2.jpg').write_text('more')
+ assert FileIntegrityService.check(scope)['total_changes'] == 0
+
+ # But real code changes do.
+ (docroot / 'index.php').write_text('<?php echo 2;')
+ result = FileIntegrityService.check(scope)
+ assert result['modified'][0]['path'] == 'index.php'
+
+
+def test_app_scope_unknown_application(fim, app):
+ with pytest.raises(FileIntegrityScopeError):
+ FileIntegrityService.baseline('app:999999')
+
+
+# --------------------------------------------------------------------------- #
+# Opt-ins
+# --------------------------------------------------------------------------- #
+
+def test_optin_round_trip(fim, app, db_session):
+ assert FileIntegrityService.get_app_optins() == []
+ ids = FileIntegrityService.set_app_optins([3, 1, 3])
+ assert ids == [1, 3]
+ assert FileIntegrityService.get_app_optins() == [1, 3]
+
+ from app.services.settings_service import SettingsService
+ assert json.loads(SettingsService.get(OPTIN_SETTING_KEY)) == [1, 3]
+
+ with pytest.raises(FileIntegrityScopeError):
+ FileIntegrityService.set_app_optins(['nope'])
+
+
+def test_optout_drops_stale_baseline(fim, tmp_path, app, db_session):
+ docroot = tmp_path / 'doc2'
+ docroot.mkdir()
+ (docroot / 'a.txt').write_text('a')
+ application = _make_app(db_session, name='fimapp2', root_path=str(docroot))
+ scope = f'app:{application.id}'
+
+ FileIntegrityService.set_app_optins([application.id])
+ FileIntegrityService.baseline(scope)
+ assert FileIntegrityService._load_state(scope) is not None
+
+ FileIntegrityService.set_app_optins([])
+ assert FileIntegrityService._load_state(scope) is None
+
+
+# --------------------------------------------------------------------------- #
+# check_all + notification
+# --------------------------------------------------------------------------- #
+
+def test_check_all_notifies_on_changes(fim, app, monkeypatch):
+ sent = []
+ import app.plugins_sdk as sdk
+ monkeypatch.setattr(
+ sdk.notify, 'send',
+ lambda event, to, data=None, **kw: sent.append((event, to, data)),
+ )
+
+ FileIntegrityService.baseline('nginx')
+ FileIntegrityService.baseline('systemd')
+
+ # No changes → no notification.
+ results = FileIntegrityService.check_all()
+ assert set(results) == {'nginx', 'systemd'}
+ assert sent == []
+
+ (fim['sites'] / 'evil.conf').write_text('server {}')
+ results = FileIntegrityService.check_all()
+ assert results['nginx']['total_changes'] == 1
+ assert len(sent) == 1
+ event, to, data = sent[0]
+ assert event == FIM_EVENT_KEY
+ assert to == 'admins'
+ assert data['scope'] == 'nginx'
+ assert data['counts'] == {'added': 1, 'removed': 0, 'modified': 0}
+ assert data['sample_paths'] == ['sites-enabled/evil.conf']
+
+
+def test_notification_sample_capped_at_ten(fim, app, monkeypatch):
+ sent = []
+ import app.plugins_sdk as sdk
+ monkeypatch.setattr(
+ sdk.notify, 'send',
+ lambda event, to, data=None, **kw: sent.append(data),
+ )
+ FileIntegrityService.baseline('nginx')
+ for i in range(15):
+ (fim['sites'] / f'n{i:02d}.conf').write_text('x')
+ FileIntegrityService.check_all()
+ assert len(sent) == 1
+ assert len(sent[0]['sample_paths']) == 10
+
+
+def test_notify_failure_does_not_break_check(fim, app, monkeypatch):
+ import app.plugins_sdk as sdk
+ def boom(*a, **kw):
+ raise RuntimeError('bus down')
+ monkeypatch.setattr(sdk.notify, 'send', boom)
+ FileIntegrityService.baseline('nginx')
+ (fim['sites'] / 'x.conf').write_text('x')
+ results = FileIntegrityService.check_all()
+ assert results['nginx']['total_changes'] == 1
+
+
+# --------------------------------------------------------------------------- #
+# Job registration
+# --------------------------------------------------------------------------- #
+
+def test_register_jobs_registers_handler_and_event(app):
+ from app.jobs import registry
+ FileIntegrityService.register_jobs()
+ assert registry.is_registered(FIM_JOB_KIND)
+ assert registry.get(FIM_JOB_KIND) == FileIntegrityService.run_check_job
+
+ from app.notifications import catalog
+ entry = catalog.get_entry(FIM_EVENT_KEY) if hasattr(catalog, 'get_entry') else None
+ if entry is None:
+ # Fall back to resolve(): registered events keep their catalog title.
+ meta = catalog.resolve(FIM_EVENT_KEY, {})
+ assert meta['title'] == 'File integrity changes detected'
+ assert meta['category'] == 'security'
+ else:
+ assert entry['severity'] == 'warning'
+
+
+def test_run_check_job_returns_summary(fim, app, monkeypatch):
+ import app.plugins_sdk as sdk
+ monkeypatch.setattr(sdk.notify, 'send', lambda *a, **kw: None)
+ FileIntegrityService.baseline('nginx')
+ (fim['sites'] / 'x.conf').write_text('x')
+ result = FileIntegrityService.run_check_job(job=None)
+ assert result == {'scopes_checked': 1, 'scopes_changed': 1}
+
+
+# --------------------------------------------------------------------------- #
+# API
+# --------------------------------------------------------------------------- #
+
+def test_fim_api_requires_auth(fim, client):
+ assert client.get('/api/v1/security/fim').status_code == 401
+ assert client.post('/api/v1/security/fim/nginx/baseline').status_code == 401
+
+
+def test_fim_api_happy_path(fim, client, auth_headers, db_session):
+ # Status before any baseline: nginx + systemd scopes, no app opt-ins.
+ resp = client.get('/api/v1/security/fim', headers=auth_headers)
+ assert resp.status_code == 200
+ body = resp.get_json()
+ assert body['app_optins'] == []
+ scopes = {s['scope']: s for s in body['scopes']}
+ assert set(scopes) == {'nginx', 'systemd'}
+ assert scopes['nginx']['baseline'] is None
+
+ # Baseline → check → accept round-trip.
+ resp = client.post('/api/v1/security/fim/nginx/baseline', headers=auth_headers)
+ assert resp.status_code == 200
+ assert resp.get_json()['file_count'] == 2
+
+ (fim['sites'] / 'new.conf').write_text('server {}')
+ resp = client.post('/api/v1/security/fim/nginx/check', headers=auth_headers)
+ assert resp.status_code == 200
+ assert resp.get_json()['total_changes'] == 1
+
+ resp = client.post('/api/v1/security/fim/nginx/accept', headers=auth_headers)
+ assert resp.status_code == 200
+ resp = client.post('/api/v1/security/fim/nginx/check', headers=auth_headers)
+ assert resp.get_json()['total_changes'] == 0
+
+ # Status now carries baseline metadata + last result.
+ body = client.get('/api/v1/security/fim', headers=auth_headers).get_json()
+ nginx = next(s for s in body['scopes'] if s['scope'] == 'nginx')
+ assert nginx['baseline']['file_count'] == 3
+ assert nginx['last_check']['total_changes'] == 0
+
+
+def test_fim_api_error_paths(fim, client, auth_headers):
+ # Unknown scope → 400 JSON error.
+ resp = client.post('/api/v1/security/fim/bogus/baseline', headers=auth_headers)
+ assert resp.status_code == 400
+ assert 'error' in resp.get_json()
+
+ # Check without baseline → 400.
+ resp = client.post('/api/v1/security/fim/nginx/check', headers=auth_headers)
+ assert resp.status_code == 400
+
+ # Opt-ins require app_ids.
+ resp = client.put('/api/v1/security/fim/apps', json={}, headers=auth_headers)
+ assert resp.status_code == 400
+
+
+def test_fim_api_app_optins(fim, tmp_path, client, auth_headers, db_session):
+ docroot = tmp_path / 'apidoc'
+ docroot.mkdir()
+ (docroot / 'main.py').write_text('print(1)')
+ application = _make_app(db_session, name='fimapi', root_path=str(docroot))
+
+ resp = client.put(
+ '/api/v1/security/fim/apps',
+ json={'app_ids': [application.id]},
+ headers=auth_headers,
+ )
+ assert resp.status_code == 200
+ assert resp.get_json()['app_optins'] == [application.id]
+
+ body = client.get('/api/v1/security/fim', headers=auth_headers).get_json()
+ scopes = {s['scope']: s for s in body['scopes']}
+ scope_key = f'app:{application.id}'
+ assert scope_key in scopes
+ assert scopes[scope_key]['app_name'] == 'fimapi'
+ assert scopes[scope_key]['available'] is True
+
+ resp = client.post(
+ f'/api/v1/security/fim/{scope_key}/baseline', headers=auth_headers,
+ )
+ assert resp.status_code == 200
+ assert resp.get_json()['file_count'] == 1
diff --git a/frontend/src/components/security/IntegrityTab.jsx b/frontend/src/components/security/IntegrityTab.jsx
index a948ab7d..9bc9aa48 100644
--- a/frontend/src/components/security/IntegrityTab.jsx
+++ b/frontend/src/components/security/IntegrityTab.jsx
@@ -1,129 +1,282 @@
-import { useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
import api from '../../services/api';
import { Button } from '@/components/ui/button';
+import { Switch } from '@/components/ui/switch';
+
+// Scoped file-integrity monitoring: baseline-and-diff over the paths
+// ServerKit manages (nginx configs, serverkit-owned systemd units, and
+// app docroots on explicit per-app opt-in).
+
+const SCOPE_META = {
+ nginx: {
+ label: 'Nginx configuration',
+ hint: 'sites-enabled + conf.d',
+ },
+ systemd: {
+ label: 'Systemd units',
+ hint: 'serverkit-* units in /etc/systemd/system',
+ },
+};
+
+function formatAge(iso) {
+ if (!iso) return null;
+ const ms = Date.now() - new Date(iso).getTime();
+ if (Number.isNaN(ms)) return null;
+ const mins = Math.floor(ms / 60000);
+ if (mins < 1) return 'just now';
+ if (mins < 60) return `${mins}m ago`;
+ const hours = Math.floor(mins / 60);
+ if (hours < 48) return `${hours}h ago`;
+ return `${Math.floor(hours / 24)}d ago`;
+}
+
+function scopeLabel(scope) {
+ if (SCOPE_META[scope.scope]) return SCOPE_META[scope.scope].label;
+ return scope.app_name ? `App: ${scope.app_name}` : `App #${scope.app_id}`;
+}
const IntegrityTab = () => {
- const [checking, setChecking] = useState(false);
- const [initializing, setInitializing] = useState(false);
- const [results, setResults] = useState(null);
+ const [status, setStatus] = useState(null);
+ const [apps, setApps] = useState([]);
+ const [busy, setBusy] = useState(null); // `${scope}:${action}` while a call runs
+ const [savingOptins, setSavingOptins] = useState(false);
const [message, setMessage] = useState(null);
+ const [expanded, setExpanded] = useState(null); // scope whose changes table is open
+
+ const load = useCallback(async () => {
+ try {
+ const data = await api.request('/security/fim');
+ setStatus(data);
+ } catch (err) {
+ setMessage({ type: 'error', text: err.message });
+ }
+ }, []);
- async function handleInitialize() {
- if (!confirm('This will create a new baseline for file integrity monitoring. Continue?')) return;
+ useEffect(() => {
+ load();
+ api.getApps().then(
+ (data) => setApps(data.apps || []),
+ () => {} // apps list is optional chrome; FIM still works without it
+ );
+ }, [load]);
- setInitializing(true);
+ async function runAction(scope, action) {
+ setBusy(`${scope}:${action}`);
setMessage(null);
try {
- const result = await api.initializeIntegrityDatabase();
- setMessage({ type: 'success', text: result.message });
+ const result = await api.request(`/security/fim/${scope}/${action}`, { method: 'POST' });
+ if (action === 'check') {
+ setExpanded(result.total_changes > 0 ? scope : null);
+ setMessage(result.total_changes === 0
+ ? { type: 'success', text: `${scope}: no changes since baseline` }
+ : { type: 'error', text: `${scope}: ${result.total_changes} change(s) detected` });
+ } else {
+ setExpanded(null);
+ setMessage({
+ type: 'success',
+ text: `${scope}: baseline saved (${result.file_count} files)`,
+ });
+ }
+ await load();
} catch (err) {
setMessage({ type: 'error', text: err.message });
} finally {
- setInitializing(false);
+ setBusy(null);
}
}
- async function handleCheck() {
- setChecking(true);
+ async function toggleApp(appId, enabled) {
+ const current = status?.app_optins || [];
+ const next = enabled
+ ? [...new Set([...current, appId])]
+ : current.filter((id) => id !== appId);
+ setSavingOptins(true);
setMessage(null);
try {
- const result = await api.checkFileIntegrity();
- setResults(result);
- if (result.total_changes === 0) {
- setMessage({ type: 'success', text: 'No changes detected' });
- }
+ await api.request('/security/fim/apps', { method: 'PUT', body: { app_ids: next } });
+ await load();
} catch (err) {
setMessage({ type: 'error', text: err.message });
} finally {
- setChecking(false);
+ setSavingOptins(false);
}
}
- return (
- <div className="integrity-tab">
- {message && (
- <div className={`alert alert-${message.type === 'success' ? 'success' : 'danger'}`}>
- {message.text}
- </div>
- )}
+ const scopes = status?.scopes || [];
+ const optins = status?.app_optins || [];
- <div className="card">
+ function renderChanges(scope) {
+ const check = scope.last_check;
+ if (!check || check.total_changes === 0 || expanded !== scope.scope) return null;
+ const rows = [
+ ...(check.added || []).map((p) => ({ kind: 'added', tone: 'green', path: p, what: null })),
+ ...(check.removed || []).map((p) => ({ kind: 'removed', tone: 'red', path: p, what: null })),
+ ...(check.modified || []).map((m) => ({
+ kind: 'modified', tone: 'amber', path: m.path, what: m.what,
+ })),
+ ];
+ const shown = rows.slice(0, 200);
+ return (
+ <table className="sk-dtable">
+ <thead>
+ <tr>
+ <th>Change</th>
+ <th>Path</th>
+ <th>What changed</th>
+ </tr>
+ </thead>
+ <tbody>
+ {shown.map((row, i) => (
+ <tr key={i}>
+ <td><span className={`sec-state sec-state--${row.tone}`}>{row.kind}</span></td>
+ <td className="sk-cell-mono sec-path">{row.path}</td>
+ <td>
+ {row.what ? (
+ <span className="sec-what">
+ {row.what.map((w) => (
+ <span key={w} className="sec-state sec-state--gray">{w}</span>
+ ))}
+ </span>
+ ) : (
+ <span className="sec-dash">—</span>
+ )}
+ </td>
+ </tr>
+ ))}
+ {rows.length > shown.length && (
+ <tr>
+ <td colSpan={3} className="sk-cell-mono sec-faint">
+ … and {rows.length - shown.length} more
+ </td>
+ </tr>
+ )}
+ </tbody>
+ </table>
+ );
+ }
+
+ function renderScopeCard(scope) {
+ const key = scope.scope;
+ const baseline = scope.baseline;
+ const check = scope.last_check;
+ const changed = check && check.total_changes > 0;
+ return (
+ <div className="card sec-flush" key={key}>
<div className="card-header">
- <h3>File Integrity Monitoring</h3>
+ <h3>
+ {scopeLabel(scope)}{' '}
+ <span className="sec-count">
+ · {SCOPE_META[key]?.hint || (scope.roots[0] || 'no docroot')}
+ </span>
+ </h3>
+ {!scope.available && <span className="sec-state sec-state--gray">not present</span>}
+ {scope.available && !baseline && <span className="sec-state sec-state--gray">no baseline</span>}
+ {baseline && !check && <span className="sec-state sec-state--cyan">baselined</span>}
+ {check && (changed
+ ? <span className="sec-state sec-state--amber">{check.total_changes} changes</span>
+ : <span className="sec-state sec-state--green">clean</span>)}
</div>
<div className="card-body">
- <p className="description">
- File integrity monitoring tracks changes to critical system files. Initialize a baseline database,
- then periodically check for unauthorized modifications.
+ <p className="sec-hint--lead sec-hint">
+ {baseline
+ ? `Baseline: ${baseline.file_count} files, ${formatAge(baseline.created_at) || 'unknown age'}`
+ : 'No baseline yet — create one to start tracking changes.'}
+ {check && ` · Last check ${formatAge(check.checked_at) || ''}`}
</p>
-
- <div className="integrity-actions">
+ <div className="card-actions">
<Button
variant="outline"
- onClick={handleInitialize}
- disabled={initializing}
+ size="sm"
+ onClick={() => runAction(key, 'baseline')}
+ disabled={!scope.available || busy !== null}
>
- {initializing ? 'Initializing...' : 'Initialize Baseline'}
+ {busy === `${key}:baseline` ? 'Baselining…' : 'Baseline'}
</Button>
<Button
variant="default"
- onClick={handleCheck}
- disabled={checking}
+ size="sm"
+ onClick={() => runAction(key, 'check')}
+ disabled={!baseline || busy !== null}
>
- {checking ? 'Checking...' : 'Check Integrity'}
+ {busy === `${key}:check` ? 'Checking…' : 'Check now'}
</Button>
+ {changed && (
+ <>
+ <Button
+ variant="outline"
+ size="sm"
+ onClick={() => runAction(key, 'accept')}
+ disabled={busy !== null}
+ >
+ {busy === `${key}:accept` ? 'Accepting…' : 'Accept changes'}
+ </Button>
+ <Button
+ variant="ghost"
+ size="sm"
+ onClick={() => setExpanded(expanded === key ? null : key)}
+ >
+ {expanded === key ? 'Hide changes' : 'View changes'}
+ </Button>
+ </>
+ )}
</div>
</div>
+ {renderChanges(scope)}
</div>
+ );
+ }
+
+ const managedScopes = scopes.filter((s) => !s.scope.startsWith('app:'));
+ const appScopes = scopes.filter((s) => s.scope.startsWith('app:'));
+
+ return (
+ <div className="integrity-tab">
+ {message && (
+ <div className={`alert alert-${message.type === 'success' ? 'success' : 'danger'}`}>
+ {message.text}
+ </div>
+ )}
- {results && results.total_changes > 0 && (() => {
- const changes = results.changes || {};
- const NEW_LIMIT = 50;
- const newFiles = changes.new || [];
- const extraNew = Math.max(0, newFiles.length - NEW_LIMIT);
- // Flatten every change kind into dense-table rows (kind chip + mono path).
- const rows = [
- ...(changes.modified || []).map((f) => ({ kind: 'modified', tone: 'amber', path: f.path })),
- ...(changes.deleted || []).map((f) => ({ kind: 'deleted', tone: 'red', path: f })),
- ...newFiles.slice(0, NEW_LIMIT).map((f) => ({ kind: 'new', tone: 'green', path: f })),
- ...(changes.permission_changed || []).map((f) => ({
- kind: 'permission',
- tone: 'cyan',
- path: `${f.path} (${f.old_mode} → ${f.new_mode})`,
- })),
- ];
-
- return (
- <div className="card sec-flush">
- <div className="card-header">
- <h3>Changes Detected</h3>
- <span className="sec-state sec-state--amber">{results.total_changes} changes</span>
+ <p className="sec-hint sec-hint--lead">
+ Baseline-and-diff monitoring over the paths ServerKit manages. Baseline a
+ scope, then check it (or let the scheduled sweep do it) — any added,
+ removed or modified files are flagged and admins are notified. Accepting
+ changes re-baselines the scope.
+ </p>
+
+ {managedScopes.map(renderScopeCard)}
+ {appScopes.map(renderScopeCard)}
+
+ <div className="card">
+ <div className="card-header">
+ <h3>Application docroots <span className="sec-count">· opt-in</span></h3>
+ </div>
+ <div className="card-body">
+ <p className="sec-hint sec-hint--lead">
+ Watching a docroot hashes every file outside upload/cache
+ directories, so it is opt-in per application.
+ </p>
+ {apps.length === 0 ? (
+ <p className="sec-faint">No applications found.</p>
+ ) : (
+ <div className="sec-finding-list">
+ {apps.map((appItem) => (
+ <div className="sec-finding" key={appItem.id}>
+ <Switch
+ checked={optins.includes(appItem.id)}
+ disabled={savingOptins}
+ onCheckedChange={(checked) => toggleApp(appItem.id, checked)}
+ />
+ <div className="sec-finding__msg">
+ {appItem.name}{' '}
+ <span className="sec-mono">{appItem.root_path || 'no docroot'}</span>
+ </div>
+ </div>
+ ))}
</div>
- <table className="sk-dtable">
- <thead>
- <tr>
- <th>Change</th>
- <th>Path</th>
- </tr>
- </thead>
- <tbody>
- {rows.map((row, i) => (
- <tr key={i}>
- <td><span className={`sec-state sec-state--${row.tone}`}>{row.kind}</span></td>
- <td className="sk-cell-mono sec-path">{row.path}</td>
- </tr>
- ))}
- {extraNew > 0 && (
- <tr>
- <td><span className="sec-state sec-state--green">new</span></td>
- <td className="sk-cell-mono sec-faint">… and {extraNew} more added</td>
- </tr>
- )}
- </tbody>
- </table>
- </div>
- );
- })()}
+ )}
+ </div>
+ </div>
</div>
);
};