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): cloud-metadata egress guard for app containers
Juan Denis4c76d43cb719
diff --git a/backend/app/api/firewall.py b/backend/app/api/firewall.pyindex 2f9a82fa..2087126f 100644--- a/backend/app/api/firewall.py+++ b/backend/app/api/firewall.py@@ -4,6 +4,7 @@ from flask import Blueprint, request, jsonifyfrom ..middleware.rbac import admin_required, viewer_requiredfrom ..services.firewall_service import FirewallService+from ..services.metadata_guard_service import MetadataGuardService, SETTING_KEYfirewall_bp = Blueprint('firewall', __name__)@@ -233,6 +234,35 @@ def set_default_zone():return jsonify(result), 400+@firewall_bp.route('/metadata-guard', methods=['GET'])+@viewer_required+def get_metadata_guard():+ """Get cloud metadata guard status."""+ return jsonify(MetadataGuardService.status()), 200+++@firewall_bp.route('/metadata-guard', methods=['PUT'])+@admin_required+def set_metadata_guard():+ """Enable or disable the cloud metadata egress guard."""+ data = request.get_json()++ if not data or 'enabled' not in data:+ return jsonify({'error': "Request body with 'enabled' required"}), 400++ enabled = bool(data['enabled'])++ from ..services.settings_service import SettingsService+ SettingsService.set(SETTING_KEY, enabled)++ result = MetadataGuardService.ensure()+ status = MetadataGuardService.status()+ if not result.get('success') and result.get('supported', True):+ status['error'] = result.get('error', 'Failed to update metadata guard')+ return jsonify(status), 500+ return jsonify(status), 200++@firewall_bp.route('/install', methods=['POST'])@admin_requireddef install_firewall():diff --git a/backend/app/services/metadata_guard_service.py b/backend/app/services/metadata_guard_service.pynew file mode 100644index 00000000..89069e70--- /dev/null+++ b/backend/app/services/metadata_guard_service.py@@ -0,0 +1,178 @@+"""Cloud metadata egress guard.++Blocks app containers from reaching the cloud metadata endpoint+(169.254.169.254) via the Docker forward path, protecting against+SSRF-to-instance-credentials attacks. Default-on (opt-out via the+``security_block_cloud_metadata`` setting), Linux-only, best-effort:+on unsupported hosts everything degrades gracefully to a no-op.+"""++import logging+import os++from ..utils.system import is_command_available, run_privileged++logger = logging.getLogger(__name__)++METADATA_CIDR = '169.254.169.254/32'+SETTING_KEY = 'security_block_cloud_metadata'+JOB_KIND = 'security.metadata_guard.ensure'++# nftables fallback objects (used only when iptables is absent)+NFT_TABLE = 'serverkit_metadata_guard'++_IPT_RULE = ['DOCKER-USER', '-d', METADATA_CIDR, '-j', 'DROP']+++class MetadataGuardService:+ """Manage the DROP rule for the cloud metadata IP in DOCKER-USER."""++ # ------------------------------------------------------------------ #+ # Backend detection+ # ------------------------------------------------------------------ #++ @staticmethod+ def _detect_backend():+ """Return 'iptables', 'nftables', or None."""+ if os.name == 'nt':+ return None+ if is_command_available('iptables'):+ return 'iptables'+ if is_command_available('nft'):+ return 'nftables'+ return None++ # ------------------------------------------------------------------ #+ # Setting+ # ------------------------------------------------------------------ #++ @staticmethod+ def enabled_setting():+ """Read the opt-out setting (defaults to on)."""+ from .settings_service import SettingsService+ value = SettingsService.get(SETTING_KEY, True)+ if isinstance(value, str):+ return value.strip().lower() not in ('false', '0', 'no', 'off', '')+ return bool(value)++ # ------------------------------------------------------------------ #+ # Rule presence+ # ------------------------------------------------------------------ #++ @classmethod+ def _is_active(cls, backend):+ if backend == 'iptables':+ result = run_privileged(['iptables', '-C'] + _IPT_RULE)+ return result.returncode == 0+ if backend == 'nftables':+ result = run_privileged(['nft', 'list', 'table', 'inet', NFT_TABLE])+ return result.returncode == 0+ return False++ # ------------------------------------------------------------------ #+ # Core ops+ # ------------------------------------------------------------------ #++ @classmethod+ def status(cls):+ """Report support, setting, and live rule state."""+ backend = cls._detect_backend()+ info = {+ 'supported': backend is not None,+ 'enabled_setting': cls.enabled_setting(),+ 'active': False,+ 'backend': backend,+ }+ if backend is None:+ return info+ try:+ info['active'] = cls._is_active(backend)+ except Exception as exc: # pragma: no cover - defensive+ logger.warning('metadata guard status check failed: %s', exc)+ info['error'] = str(exc)+ return info++ @classmethod+ def apply(cls):+ """Idempotently insert the metadata DROP rule."""+ backend = cls._detect_backend()+ if backend is None:+ return {'success': False, 'supported': False,+ 'error': 'No supported firewall backend (iptables/nft) on this host'}+ try:+ if cls._is_active(backend):+ return {'success': True, 'active': True, 'backend': backend}+ if backend == 'iptables':+ result = run_privileged(['iptables', '-I'] + _IPT_RULE)+ if result.returncode != 0:+ return {'success': False, 'backend': backend,+ 'error': (result.stderr or 'iptables insert failed').strip()}+ else:+ # Best-effort nftables equivalent: dedicated table + forward+ # hook chain dropping traffic to the metadata IP.+ steps = [+ ['nft', 'add', 'table', 'inet', NFT_TABLE],+ ['nft', 'add', 'chain', 'inet', NFT_TABLE, 'forward',+ '{', 'type', 'filter', 'hook', 'forward', 'priority', '-10', ';',+ 'policy', 'accept', ';', '}'],+ ['nft', 'add', 'rule', 'inet', NFT_TABLE, 'forward',+ 'ip', 'daddr', '169.254.169.254', 'drop'],+ ]+ for cmd in steps:+ result = run_privileged(cmd)+ if result.returncode != 0:+ return {'success': False, 'backend': backend,+ 'error': (result.stderr or 'nft setup failed').strip()}+ return {'success': True, 'active': True, 'backend': backend}+ except Exception as exc:+ logger.warning('metadata guard apply failed: %s', exc)+ return {'success': False, 'backend': backend, 'error': str(exc)}++ @classmethod+ def remove(cls):+ """Delete the metadata DROP rule if present."""+ backend = cls._detect_backend()+ if backend is None:+ return {'success': False, 'supported': False,+ 'error': 'No supported firewall backend (iptables/nft) on this host'}+ try:+ if not cls._is_active(backend):+ return {'success': True, 'active': False, 'backend': backend}+ if backend == 'iptables':+ result = run_privileged(['iptables', '-D'] + _IPT_RULE)+ else:+ result = run_privileged(['nft', 'delete', 'table', 'inet', NFT_TABLE])+ if result.returncode != 0:+ return {'success': False, 'backend': backend,+ 'error': (result.stderr or 'rule removal failed').strip()}+ return {'success': True, 'active': False, 'backend': backend}+ except Exception as exc:+ logger.warning('metadata guard remove failed: %s', exc)+ return {'success': False, 'backend': backend, 'error': str(exc)}++ @classmethod+ def ensure(cls):+ """Converge the live rule with the setting (apply or remove)."""+ if os.name == 'nt' or cls._detect_backend() is None:+ return {'success': True, 'supported': False, 'active': False,+ 'backend': None}+ if cls.enabled_setting():+ return cls.apply()+ return cls.remove()++ # ------------------------------------------------------------------ #+ # Jobs registration+ # ------------------------------------------------------------------ #++ @classmethod+ def register_jobs(cls):+ """Register the ensure handler so boot/schedules converge the rule."""+ from app.jobs import registry+ registry.register(JOB_KIND, cls._run_ensure_job, replace=True)++ @classmethod+ def _run_ensure_job(cls, job): # noqa: ARG003 - job payload unused+ result = cls.ensure()+ if not result.get('success') and result.get('supported', True):+ raise RuntimeError(result.get('error') or 'metadata guard ensure failed')+ return resultdiff --git a/backend/tests/test_metadata_guard.py b/backend/tests/test_metadata_guard.pynew file mode 100644index 00000000..587d470e--- /dev/null+++ b/backend/tests/test_metadata_guard.py@@ -0,0 +1,263 @@+"""Cloud metadata egress guard — service logic and API endpoints.++Proving points:+- default-on: with no setting stored, ensure() inserts the DROP rule+- idempotent: apply() with the rule already present does not re-insert+- opt-out: setting False makes ensure() remove the rule+- unsupported hosts (no iptables/nft, or Windows) return cleanly+- nftables best-effort fallback when iptables is absent+- endpoint auth (401 unauthenticated, 403 non-admin PUT)+"""+import types++import pytest++import app.services.metadata_guard_service as mgs+from app.services.metadata_guard_service import (+ JOB_KIND,+ SETTING_KEY,+ MetadataGuardService,+)+++class _FakeProc:+ def __init__(self, returncode=0, stdout='', stderr=''):+ self.returncode = returncode+ self.stdout = stdout+ self.stderr = stderr+++class _FakeFirewall:+ """Stateful iptables/nft stub — tracks rule presence + issued commands."""++ def __init__(self):+ self.ipt_rule_present = False+ self.nft_table_present = False+ self.commands = []++ def run(self, cmd, **kwargs):+ # run_privileged never prepends sudo in these tests (patched directly)+ self.commands.append(cmd)+ if cmd[0] == 'iptables':+ flag = cmd[1]+ if flag == '-C':+ return _FakeProc(0 if self.ipt_rule_present else 1)+ if flag == '-I':+ self.ipt_rule_present = True+ return _FakeProc(0)+ if flag == '-D':+ self.ipt_rule_present = False+ return _FakeProc(0)+ if cmd[0] == 'nft':+ verb = cmd[1]+ if verb == 'list':+ return _FakeProc(0 if self.nft_table_present else 1)+ if verb == 'add':+ self.nft_table_present = True+ return _FakeProc(0)+ if verb == 'delete':+ self.nft_table_present = False+ return _FakeProc(0)+ return _FakeProc(1, stderr='unexpected command')+++def linux(monkeypatch):+ """Make the service believe it runs on a Linux host."""+ monkeypatch.setattr(mgs, 'os', types.SimpleNamespace(name='posix'))+++def fw(monkeypatch, linux):+ """Linux host with iptables available; returns the stateful stub."""+ fake = _FakeFirewall()+ monkeypatch.setattr(mgs, 'run_privileged', fake.run)+ monkeypatch.setattr(mgs, 'is_command_available', lambda c: c == 'iptables')+ return fake+++def fw_nft(monkeypatch, linux):+ """Linux host with only nft available."""+ fake = _FakeFirewall()+ monkeypatch.setattr(mgs, 'run_privileged', fake.run)+ monkeypatch.setattr(mgs, 'is_command_available', lambda c: c == 'nft')+ return fake+++def unsupported(monkeypatch, linux):+ """Linux host with neither iptables nor nft."""+ monkeypatch.setattr(mgs, 'is_command_available', lambda c: False)+++# ── service: default-on / idempotency / opt-out ─────────────────────────────++def test_default_on_ensure_inserts_drop_rule(app, fw):+ result = MetadataGuardService.ensure()++ assert result['success'] is True+ assert result['active'] is True+ assert result['backend'] == 'iptables'+ assert fw.ipt_rule_present is True+ assert ['iptables', '-I', 'DOCKER-USER', '-d', '169.254.169.254/32',+ '-j', 'DROP'] in fw.commands+++def test_apply_is_idempotent(app, fw):+ fw.ipt_rule_present = True++ result = MetadataGuardService.apply()++ assert result['success'] is True+ inserts = [c for c in fw.commands if c[:2] == ['iptables', '-I']]+ assert inserts == [] # no double insert+++def test_opt_out_removes_rule(app, fw):+ from app.services.settings_service import SettingsService+ fw.ipt_rule_present = True+ SettingsService.set(SETTING_KEY, False)++ result = MetadataGuardService.ensure()++ assert result['success'] is True+ assert result['active'] is False+ assert fw.ipt_rule_present is False+ assert ['iptables', '-D', 'DOCKER-USER', '-d', '169.254.169.254/32',+ '-j', 'DROP'] in fw.commands+++def test_remove_noop_when_rule_absent(app, fw):+ result = MetadataGuardService.remove()++ assert result['success'] is True+ deletes = [c for c in fw.commands if c[:2] == ['iptables', '-D']]+ assert deletes == []+++def test_status_reports_setting_and_active(app, fw):+ fw.ipt_rule_present = True+ info = MetadataGuardService.status()++ assert info == {'supported': True, 'enabled_setting': True,+ 'active': True, 'backend': 'iptables'}+++# ── service: nftables fallback ───────────────────────────────────────────────++def test_nftables_fallback_apply_and_remove(app, fw_nft):+ result = MetadataGuardService.apply()+ assert result['success'] is True+ assert result['backend'] == 'nftables'+ assert fw_nft.nft_table_present is True+ assert any(c[:2] == ['nft', 'add'] for c in fw_nft.commands)++ result = MetadataGuardService.remove()+ assert result['success'] is True+ assert fw_nft.nft_table_present is False+++# ── service: unsupported paths ───────────────────────────────────────────────++def test_ensure_unsupported_host_returns_cleanly(app, unsupported):+ result = MetadataGuardService.ensure()+ assert result == {'success': True, 'supported': False,+ 'active': False, 'backend': None}+++def test_status_unsupported_host(app, unsupported):+ info = MetadataGuardService.status()+ assert info['supported'] is False+ assert info['backend'] is None+ assert info['active'] is False+ assert info['enabled_setting'] is True # still default-on+++def test_windows_is_unsupported(app, monkeypatch):+ monkeypatch.setattr(mgs, 'os', types.SimpleNamespace(name='nt'))+ assert MetadataGuardService.status()['supported'] is False+ assert MetadataGuardService.ensure()['supported'] is False+++def test_apply_unsupported_reports_error(app, unsupported):+ result = MetadataGuardService.apply()+ assert result['success'] is False+ assert result['supported'] is False+ assert 'error' in result+++# ── jobs registration ────────────────────────────────────────────────────────++def test_register_jobs_registers_ensure_kind(app, unsupported):+ from app.jobs import registry+ MetadataGuardService.register_jobs()+ assert JOB_KIND in registry.registered_kinds()++ handler = registry.get(JOB_KIND) if hasattr(registry, 'get') else None+ if handler:+ result = handler(types.SimpleNamespace(get_payload=lambda: {}))+ assert result['supported'] is False # clean no-op+++# ── API endpoints ────────────────────────────────────────────────────────────++def test_get_metadata_guard_requires_auth(client):+ response = client.get('/api/v1/firewall/metadata-guard')+ assert response.status_code == 401+++def test_get_metadata_guard_status(client, auth_headers, unsupported):+ response = client.get('/api/v1/firewall/metadata-guard',+ headers=auth_headers)+ assert response.status_code == 200+ data = response.get_json()+ assert data['supported'] is False+ assert data['enabled_setting'] is True+++def test_put_metadata_guard_requires_admin(client, app, unsupported):+ from app import db+ from app.models import User+ from flask_jwt_extended import create_access_token++ viewer = User(email='[email protected]', username='viewer',+ password_hash='x', role=User.ROLE_VIEWER, is_active=True)+ db.session.add(viewer)+ db.session.commit()+ token = create_access_token(identity=viewer.id)++ response = client.put('/api/v1/firewall/metadata-guard',+ headers={'Authorization': f'Bearer {token}'},+ json={'enabled': False})+ assert response.status_code == 403+++def test_put_metadata_guard_requires_body(client, auth_headers, unsupported):+ response = client.put('/api/v1/firewall/metadata-guard',+ headers=auth_headers, json={})+ assert response.status_code == 400+ assert 'error' in response.get_json()+++def test_put_metadata_guard_persists_opt_out(client, auth_headers, fw):+ fw.ipt_rule_present = True++ response = client.put('/api/v1/firewall/metadata-guard',+ headers=auth_headers, json={'enabled': False})+ assert response.status_code == 200+ data = response.get_json()+ assert data['enabled_setting'] is False+ assert data['active'] is False+ assert fw.ipt_rule_present is False # rule actually removed+ assert MetadataGuardService.enabled_setting() is False # setting persisted+++def test_put_metadata_guard_enable_applies_rule(client, auth_headers, fw):+ response = client.put('/api/v1/firewall/metadata-guard',+ headers=auth_headers, json={'enabled': True})+ assert response.status_code == 200+ data = response.get_json()+ assert data['enabled_setting'] is True+ assert data['active'] is True+ assert fw.ipt_rule_present is Truediff --git a/frontend/src/components/security/FirewallTab.jsx b/frontend/src/components/security/FirewallTab.jsxindex 890d7e8b..94c60348 100644--- a/frontend/src/components/security/FirewallTab.jsx+++ b/frontend/src/components/security/FirewallTab.jsx@@ -6,6 +6,7 @@ import Modal from '../Modal';import { Button } from '@/components/ui/button';import { Input } from '@/components/ui/input';import { Label } from '@/components/ui/label';+import { Switch } from '@/components/ui/switch';import { Pill, SegControl } from '@/components/ds';import { Shield } from 'lucide-react';import { Select, SelectTrigger, SelectContent, SelectItem, SelectValue } from '@/components/ui/select';@@ -30,6 +31,8 @@ const FirewallTab = () => {const [selectedFirewall, setSelectedFirewall] = useState('ufw');const [actionLoading, setActionLoading] = useState(false);const [confirmDialog, setConfirmDialog] = useState(null);+ const [guard, setGuard] = useState(null);+ const [guardLoading, setGuardLoading] = useState(false);const toast = useToast();const commonPorts = [@@ -51,7 +54,7 @@ const FirewallTab = () => {const loadData = async () => {setLoading(true);try {- await Promise.all([loadStatus(), loadRules(), loadBlockedIPs()]);+ await Promise.all([loadStatus(), loadRules(), loadBlockedIPs(), loadGuard()]);} catch (error) {console.error('Failed to load firewall data:', error);} finally {@@ -86,6 +89,29 @@ const FirewallTab = () => {}};+ const loadGuard = async () => {+ try {+ const data = await api.getMetadataGuard();+ setGuard(data);+ } catch (error) {+ console.error('Failed to load metadata guard status:', error);+ }+ };++ const handleGuardToggle = async (enabled) => {+ setGuardLoading(true);+ try {+ const data = await api.setMetadataGuard(enabled);+ setGuard(data);+ toast.success(`Cloud metadata guard ${enabled ? 'enabled' : 'disabled'}`);+ } catch (error) {+ toast.error(`Failed to update metadata guard: ${error.message}`);+ await loadGuard();+ } finally {+ setGuardLoading(false);+ }+ };+const handleEnable = async () => {setActionLoading(true);try {@@ -445,6 +471,44 @@ const FirewallTab = () => {</>)}+ {guard && (+ <div className="card">+ <div className="card-header">+ <h3>Cloud Metadata Guard</h3>+ {guard.supported ? (+ <Pill kind={guard.active ? 'green' : 'gray'}>+ {guard.active ? 'Active' : 'Inactive'}+ </Pill>+ ) : (+ <Pill kind="gray">Unsupported on this host</Pill>+ )}+ </div>+ <div className="card-body">+ <div className="sec-rows">+ <div className="sk-info-row">+ <span className="k">Block container access to 169.254.169.254</span>+ <Switch+ checked={!!guard.enabled_setting}+ onCheckedChange={handleGuardToggle}+ disabled={guardLoading || !guard.supported}+ aria-label="Toggle cloud metadata guard"+ />+ </div>+ {guard.supported && guard.backend && (+ <div className="sk-info-row">+ <span className="k">Backend</span>+ <span className="v">{guard.backend}</span>+ </div>+ )}+ </div>+ <p className="sec-hint">+ Stops app containers from reaching the cloud metadata endpoint,+ preventing SSRF attacks from stealing instance credentials.+ </p>+ </div>+ </div>+ )}+{/* Block IP Modal */}<Modal open={showBlockIPModal} onClose={() => setShowBlockIPModal(false)} title="Block IP Address"><div className="form-group">diff --git a/frontend/src/services/api/metadataGuard.js b/frontend/src/services/api/metadataGuard.jsnew file mode 100644index 00000000..fdf0ca2f--- /dev/null+++ b/frontend/src/services/api/metadataGuard.js@@ -0,0 +1,12 @@+// Cloud metadata guard API — egress block for the cloud metadata endpoint.++export async function getMetadataGuard() {+ return this.request('/firewall/metadata-guard');+}++export async function setMetadataGuard(enabled) {+ return this.request('/firewall/metadata-guard', {+ method: 'PUT',+ body: { enabled }+ });+}