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): cloud-metadata egress guard for app containers

Juan Denis4c76d43cb719
diff --git a/backend/app/api/firewall.py b/backend/app/api/firewall.py
index 2f9a82fa..2087126f 100644
--- a/backend/app/api/firewall.py
+++ b/backend/app/api/firewall.py
@@ -4,6 +4,7 @@ from flask import Blueprint, request, jsonify
from ..middleware.rbac import admin_required, viewer_required
from ..services.firewall_service import FirewallService
+from ..services.metadata_guard_service import MetadataGuardService, SETTING_KEY
firewall_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_required
def install_firewall():
diff --git a/backend/app/services/metadata_guard_service.py b/backend/app/services/metadata_guard_service.py
new file mode 100644
index 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 result
diff --git a/backend/tests/test_metadata_guard.py b/backend/tests/test_metadata_guard.py
new file mode 100644
index 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 True
diff --git a/frontend/src/components/security/FirewallTab.jsx b/frontend/src/components/security/FirewallTab.jsx
index 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.js
new file mode 100644
index 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 }
+ });
+}