Container security hardening (phase 3, breaking) (#24081)

* Run the frigate service as the frigate user

* Run go2rtc as its own restricted user

* Run nginx as the frigate user with writable state in /tmp/nginx

* Disable bandwidth stats gracefully when not running as root

* Hand TensorRT model cache ownership to the runtime user

* Document non-root operation and per-hardware device access

* Create /media/frigate after the ownership sweep

* Assert non-root services, JWT migration, and escape hatch in CI

* only write the sweep sentinel when a media volume is mounted

* tolerate homekit config chown failures in the go2rtc run script

* chown the s6 log pipe so non-root nginx can reopen /dev/stdout

* set HOME to /config for non-root services

* run smoke nginx -t and the write probe as the runtime user

* re-own the nginx shm cache on service restart

* discard stdout for the unprivileged smoke nginx -t

* unwrap hard-wrapped prose in the installation docs

* report progress during the ownership sweep

* document EXTRA_GROUPS as the only device access path for dropped services

* expand the non-root device access docs with diagnosis steps and udev rules

* document network storage ownership and the remaining detector hardware

* skip lost+found during the ownership sweep

* hand /tmp/cache to the runtime user before services start

* make bundled models readable by the runtime user

* reload nginx by signaling the master instead of parsing its config as root

* harden root writes into unprivileged-owned paths

Restrict the sweep sentinel to a mount at or below /media/frigate so a
parent /media mount cannot bless a later-shadowed volume. Rebuild
/tmp/nginx root-owned each start so root's cp and tempio writes cannot
follow a symlink an unprivileged nginx planted in the previous run.

* collapse the duplicated sentinel comment

* add a service-runs-as-root helper for granular root services

* validate FRIGATE_ROOT_SERVICES and fail fast on unknown names

* let services listed in FRIGATE_ROOT_SERVICES skip the privilege drop

* record the root-services mode in the sentinel and sweep small trees each boot

* cache the runtime ids in the ownership helper

* chown recordings, previews, and exports to the runtime user at create

* chown the database files after init

* recommend FRIGATE_ROOT_SERVICES in the bandwidth stats warning

* assert granular root services in CI

* document FRIGATE_ROOT_SERVICES

* own every directory level created for a recording segment

* clear the cached runtime ids when ownership tests finish

* skip missing media paths in the per-boot ownership sweep

* clarify granular root services docs

* clean up

* install acl for device access grants

* grant runtime users access to mapped device nodes at boot

* assert device access grants in CI

* document automatic device access grants

* stop telling users device access needs host side setup

* clarify the non-root docs

* link the migration script to the repo

* group the manual device setup under one section

* harden against symlink attacks

/config is owned by the unprivileged runtime user after the ownership sweep, so root operations on files there could be redirected by a planted symlink.

- go2rtc HomeKit setup: replace the root yq/jq normalization and chown with an O_NOFOLLOW helper (prepare_homekit.py), so a symlink at go2rtc_homekit.yml can't redirect a root write or chown onto another file
- go2rtc binary override: ignore /config/go2rtc whenever the service runs as root, so a planted binary can't exec as root under FRIGATE_ROOT_SERVICES
- sweep sentinel: read and write it through safe-sentinel, which trusts only a root-owned regular file and never follows a symlink, so it can't be forged to skip the migration or symlinked to clobber a root file
- ownership sweep: chown with -execdir so a parent directory swapped for a symlink mid-walk can't redirect the chown out of the volume
- validate inputs: restrict DEVICE_ACL_PATHS to /dev, require nonzero numeric EXTRA_GROUPS, and reject PUID/PGID that collide with the go2rtc ids
- docs: correct the TLS key ownership note to match what actually happens

* tweak docs

* stop the ownership sweep chasing entries other mechanisms own

* keep custom binaries out of root services only under granular root
This commit is contained in:
Josh Hawkins
2026-09-12 07:30:04 -06:00
committed by Nicolas Mowen
parent 1693415375
commit 3be59c9c18
38 changed files with 1427 additions and 83 deletions
+26
View File
@@ -0,0 +1,26 @@
"""Tests for bandwidth stats privilege handling."""
import unittest
from unittest.mock import MagicMock, patch
from frigate.util import services
class TestBandwidthStatsPrivileges(unittest.TestCase):
def setUp(self):
services._bandwidth_warning_logged = False
@patch("frigate.util.services.sp.run")
@patch("frigate.util.services.os.geteuid", return_value=1000)
def test_returns_empty_and_warns_once_without_root(self, _, sp_run):
config = MagicMock()
with self.assertLogs("frigate.util.services", level="WARNING") as logs:
assert services.get_bandwidth_stats(config) == {}
assert services.get_bandwidth_stats(config) == {}
sp_run.assert_not_called()
warnings = [m for m in logs.output if "require root" in m]
assert len(warnings) == 1
if __name__ == "__main__":
unittest.main()
+154
View File
@@ -0,0 +1,154 @@
"""Tests for custom ffmpeg path resolution and the root-mode guard."""
import unittest
from unittest.mock import patch
from frigate.const import DEFAULT_FFMPEG_VERSION
from frigate.util.config import (
_warn_ignored_ffmpeg_path,
frigate_service_is_granular_root,
resolve_ffmpeg_path,
)
BUNDLED = f"/usr/lib/ffmpeg/{DEFAULT_FFMPEG_VERSION}/bin/ffmpeg"
CUSTOM = "/config/custom-ffmpeg"
class TestConfigFfmpegRootGuard(unittest.TestCase):
"""A user-writable ffmpeg must not run as root under FRIGATE_ROOT_SERVICES."""
def setUp(self) -> None:
# the warning is memoized so it fires once per path, not per camera
_warn_ignored_ffmpeg_path.cache_clear()
def _resolve(self, path: str, *, euid: int, env: dict, binary: str = "ffmpeg"):
with (
patch("os.geteuid", return_value=euid),
patch.dict("os.environ", env, clear=True),
):
return resolve_ffmpeg_path(path, binary)
def test_custom_path_used_when_service_is_unprivileged(self) -> None:
self.assertEqual(
self._resolve(CUSTOM, euid=1000, env={}), f"{CUSTOM}/bin/ffmpeg"
)
def test_escape_hatch_keeps_working_exactly_as_before(self) -> None:
# FRIGATE_RUN_AS_ROOT never sweeps /config and leaves no unprivileged
# service, so a custom build there is as safe as it was pre-drop
self.assertEqual(
self._resolve(CUSTOM, euid=0, env={"FRIGATE_RUN_AS_ROOT": "true"}),
f"{CUSTOM}/bin/ffmpeg",
)
def test_custom_path_ignored_when_frigate_is_a_root_service(self) -> None:
self.assertEqual(
self._resolve(CUSTOM, euid=0, env={"FRIGATE_ROOT_SERVICES": "frigate"}),
BUNDLED,
)
def test_ffprobe_is_guarded_too(self) -> None:
self.assertEqual(
self._resolve(
CUSTOM,
euid=0,
env={"FRIGATE_ROOT_SERVICES": "frigate"},
binary="ffprobe",
),
f"/usr/lib/ffmpeg/{DEFAULT_FFMPEG_VERSION}/bin/ffprobe",
)
def test_another_root_service_does_not_trigger_the_guard(self) -> None:
# go2rtc running as root says nothing about who spawns ffmpeg
self.assertEqual(
self._resolve(CUSTOM, euid=0, env={"FRIGATE_ROOT_SERVICES": "go2rtc"}),
f"{CUSTOM}/bin/ffmpeg",
)
def test_root_services_has_no_effect_under_docker_user(self) -> None:
# docker's own user: means the service never had root to keep, which is
# also the case for get_ffmpeg_path.py in a --user container
self.assertEqual(
self._resolve(CUSTOM, euid=1000, env={"FRIGATE_ROOT_SERVICES": "frigate"}),
f"{CUSTOM}/bin/ffmpeg",
)
def test_path_outside_config_is_left_alone(self) -> None:
# only /config is runtime-user-owned; a root-owned tree stays usable
self.assertEqual(
self._resolve(
"/opt/custom-ffmpeg", euid=0, env={"FRIGATE_ROOT_SERVICES": "frigate"}
),
"/opt/custom-ffmpeg/bin/ffmpeg",
)
def test_traversal_out_of_config_does_not_evade_the_guard(self) -> None:
self.assertEqual(
self._resolve(
"/config/../config/custom-ffmpeg",
euid=0,
env={"FRIGATE_ROOT_SERVICES": "frigate"},
),
BUNDLED,
)
def test_media_tree_is_guarded_too(self) -> None:
# config.yml is uid-1000-writable, so ffmpeg.path can be pointed at any
# writable tree; /config alone would be an evasion, not a guard
self.assertEqual(
self._resolve(
"/media/frigate/evil", euid=0, env={"FRIGATE_ROOT_SERVICES": "frigate"}
),
BUNDLED,
)
def test_config_dir_itself_is_guarded(self) -> None:
self.assertEqual(
self._resolve("/config", euid=0, env={"FRIGATE_ROOT_SERVICES": "frigate"}),
BUNDLED,
)
def test_default_alias_is_unaffected(self) -> None:
self.assertEqual(
self._resolve("default", euid=0, env={"FRIGATE_ROOT_SERVICES": "frigate"}),
BUNDLED,
)
class TestFrigateServiceIsGranularRoot(unittest.TestCase):
"""Root via FRIGATE_ROOT_SERVICES only, never via the escape hatch."""
def _check(self, *, euid: int, env: dict) -> bool:
with (
patch("os.geteuid", return_value=euid),
patch.dict("os.environ", env, clear=True),
):
return frigate_service_is_granular_root()
def test_false_without_any_root_signal(self) -> None:
self.assertFalse(self._check(euid=0, env={}))
def test_escape_hatch_is_not_granular_root(self) -> None:
# the escape hatch restores old behavior wholesale, sweep included
self.assertFalse(self._check(euid=0, env={"FRIGATE_RUN_AS_ROOT": "true"}))
self.assertFalse(
self._check(
euid=0,
env={"FRIGATE_RUN_AS_ROOT": "true", "FRIGATE_ROOT_SERVICES": "frigate"},
)
)
def test_membership_ignores_whitespace_and_other_entries(self) -> None:
self.assertTrue(
self._check(euid=0, env={"FRIGATE_ROOT_SERVICES": "go2rtc, frigate"})
)
self.assertFalse(
self._check(euid=0, env={"FRIGATE_ROOT_SERVICES": "go2rtc,nginx"})
)
def test_substring_of_a_service_name_does_not_match(self) -> None:
self.assertFalse(self._check(euid=0, env={"FRIGATE_ROOT_SERVICES": "frigatee"}))
if __name__ == "__main__":
unittest.main()
+18
View File
@@ -14,6 +14,11 @@ class FakePwEntry:
# The devcontainer image exports FRIGATE_RUN_AS_ROOT, so any test that has to
# reach past the escape-hatch check pins the variable instead of inheriting it.
class TestGetRuntimeIds(unittest.TestCase):
def setUp(self) -> None:
ownership.get_runtime_ids.cache_clear()
# a value cached under this test's patches must not leak into later modules
self.addCleanup(ownership.get_runtime_ids.cache_clear)
@patch("frigate.util.ownership.os.geteuid", return_value=1000)
def test_returns_none_when_not_root(self, _):
assert ownership.get_runtime_ids() is None
@@ -35,8 +40,21 @@ class TestGetRuntimeIds(unittest.TestCase):
def test_returns_frigate_ids_as_root(self, *_):
assert ownership.get_runtime_ids() == (1500, 1500)
@patch.dict("os.environ", {"FRIGATE_RUN_AS_ROOT": "false"})
@patch("frigate.util.ownership.pwd.getpwnam", return_value=FakePwEntry())
@patch("frigate.util.ownership.os.geteuid", return_value=0)
def test_caches_lookup(self, _geteuid, getpwnam):
assert ownership.get_runtime_ids() == (1500, 1500)
assert ownership.get_runtime_ids() == (1500, 1500)
getpwnam.assert_called_once()
class TestChownToRuntime(unittest.TestCase):
def setUp(self) -> None:
ownership.get_runtime_ids.cache_clear()
# a value cached under this test's patches must not leak into later modules
self.addCleanup(ownership.get_runtime_ids.cache_clear)
@patch("frigate.util.ownership.os.chown")
@patch("frigate.util.ownership.get_runtime_ids", return_value=None)
def test_noop_when_no_runtime_ids(self, _, chown):
@@ -442,6 +442,71 @@ class TestSegmentPathTime(unittest.IsolatedAsyncioTestCase):
self.assertTrue(paths[1].endswith("30.23.mp4"), paths[1])
class TestMoveSegmentOwnership(unittest.IsolatedAsyncioTestCase):
"""Every directory level makedirs creates must be handed to the runtime user."""
def _build_maintainer(self) -> RecordingMaintainer:
camera_config = MagicMock()
camera_config.record.enabled = True
camera_config.record.continuous.days = 1
camera_config.record.motion.days = 0
config = MagicMock()
config.cameras = {"test_cam": camera_config}
maintainer = RecordingMaintainer.__new__(RecordingMaintainer)
maintainer.config = config
maintainer.end_time_cache = {}
maintainer.object_recordings_info = defaultdict(list)
maintainer.audio_recordings_info = defaultdict(list)
maintainer.recordings_publisher = MagicMock()
maintainer.last_segment_end = {("test_cam", "main"): 0.0}
return maintainer
async def test_move_segment_chowns_all_created_levels(self):
maintainer = self._build_maintainer()
maintainer.config.ffmpeg.ffmpeg_path = "ffmpeg"
start_time = datetime.datetime(2026, 6, 10, 14, 30, 22, tzinfo=datetime.UTC)
proc = MagicMock()
proc.returncode = 0
proc.wait = AsyncMock(return_value=0)
chown = MagicMock()
with tempfile.TemporaryDirectory() as tmpdir:
record_dir = os.path.join(tmpdir, "recordings")
cache_path = os.path.join(tmpdir, "test_cam@20260610143022+0000.mp4")
with open(cache_path, "wb") as f:
f.write(b"\x00" * 16)
with (
patch("frigate.record.maintainer.RECORD_DIR", record_dir),
patch(
"frigate.record.maintainer.asyncio.create_subprocess_exec",
AsyncMock(return_value=proc),
),
patch("frigate.record.maintainer.chown_to_runtime", chown),
):
result = await maintainer.move_segment(
"test_cam",
"main",
start_time,
start_time + datetime.timedelta(seconds=10),
10.0,
cache_path,
SegmentInfo(0, 0, 0, 0),
)
self.assertIsNotNone(result)
camera_dir = os.path.join(record_dir, "2026-06-10", "14", "test_cam")
hour_dir = os.path.dirname(camera_dir)
date_dir = os.path.dirname(hour_dir)
file_path = os.path.join(camera_dir, "30.22.mp4")
chowned = [call.args[0] for call in chown.call_args_list]
self.assertEqual(chowned, [camera_dir, hour_dir, date_dir, file_path])
class TestSegmentStartChaining(unittest.IsolatedAsyncioTestCase):
"""Contiguous segments must chain start times across filename truncation.