From f18f1cf701fae29b85381ac2d28bb38f3b4f0121 Mon Sep 17 00:00:00 2001 From: Alex David Date: Thu, 7 Aug 2025 15:29:16 -0700 Subject: [PATCH] Allow overriding jail base permissions --- base-permissions.nix | 26 ++++++++ combinators.nix | 16 ++--- helpers.nix | 12 ++++ lib.nix | 62 +++++------------- tests/flake.nix | 4 +- tests/test-cases.nix | 16 ++++- website/static-docs/advanced-configuration.md | 64 +++++++++++++++++++ website/static-docs/index.md | 28 ++++---- 8 files changed, 154 insertions(+), 74 deletions(-) create mode 100644 base-permissions.nix create mode 100644 helpers.nix create mode 100644 website/static-docs/advanced-configuration.md diff --git a/base-permissions.nix b/base-permissions.nix new file mode 100644 index 0000000..3c2bf3c --- /dev/null +++ b/base-permissions.nix @@ -0,0 +1,26 @@ +pkgs: let helpers = import ./helpers.nix pkgs; in combinators: with combinators; [ + (unsafe-add-raw-args "--proc /proc") + (unsafe-add-raw-args "--dev /dev") + (unsafe-add-raw-args "--tmpfs /tmp") + (unsafe-add-raw-args "--tmpfs ~") + (unsafe-add-raw-args "--clearenv") + (unsafe-add-raw-args "--die-with-parent") + (readonly "/nix/store") + (readonly "/bin/sh") + (fwd-env "LANG") + (fwd-env "HOME") + (fwd-env "TERM") + + (add-runtime '' + if [ ! -e ${helpers.dataDirSubPath "passwd"} ] || [ ! -e ${helpers.dataDirSubPath "group"} ]; then + NOLOGIN=${pkgs.shadow}/bin/nologin + mkdir -p ${helpers.dataDir} + echo "root:x:0:0:System administrator:/root:$NOLOGIN" > ${helpers.dataDirSubPath "passwd"} + echo "$(id -un):x:$(id -u):$(id -g)::$HOME:$NOLOGIN" >> ${helpers.dataDirSubPath "passwd"} + echo "root:x:0:" > ${helpers.dataDirSubPath "group"} + echo "$(id -gn):x:$(id -g):" >> ${helpers.dataDirSubPath "group"} + fi + '') + (ro-bind (noescape (helpers.dataDirSubPath "passwd")) "/etc/passwd") + (ro-bind (noescape (helpers.dataDirSubPath "group")) "/etc/group") +] diff --git a/combinators.nix b/combinators.nix index 28fb067..7247070 100644 --- a/combinators.nix +++ b/combinators.nix @@ -1,4 +1,7 @@ -{ pkgs, lib, helpers }: rec { +pkgs: let + inherit (pkgs) lib; + helpers = import ./helpers.nix pkgs; +in rec { noescape = { sig = "String -> NoEscapedString"; doc = '' @@ -25,9 +28,7 @@ (readonly (noescape "\"$FOO\"")) ``` ''; - __functor = _: - value: { _noescape = value; } - ; + __functor = _: helpers.noescape; }; escape = { @@ -52,12 +53,7 @@ } ``` ''; - __functor = _: - rawOrStr: - if builtins.typeOf rawOrStr == "set" && rawOrStr ? _noescape - then rawOrStr._noescape - else lib.strings.escapeShellArg rawOrStr - ; + __functor = _: helpers.escape; }; compose = { diff --git a/helpers.nix b/helpers.nix new file mode 100644 index 0000000..60f26ef --- /dev/null +++ b/helpers.nix @@ -0,0 +1,12 @@ +pkgs: rec { + dataDir = "~/.local/share/jail.nix"; + + dataDirSubPath = subPath: "${dataDir}/${escape subPath}"; + + noescape = value: { _noescape = value; }; + + escape = rawOrStr: + if builtins.typeOf rawOrStr == "set" && rawOrStr ? _noescape + then rawOrStr._noescape + else pkgs.lib.strings.escapeShellArg rawOrStr; +} diff --git a/lib.nix b/lib.nix index d183239..9e3d0fa 100644 --- a/lib.nix +++ b/lib.nix @@ -1,21 +1,24 @@ { pkgs , additionalCombinators ? _: {} +, basePermissions ? import ./base-permissions.nix pkgs }: let inherit (pkgs) lib; - helpers = rec { - dataDir = "~/.local/share/jail.nix"; - dataDirSubPath = subPath: "${dataDir}/${builtinCombinators.escape subPath}"; - }; - - builtinCombinators = import ./combinators.nix { inherit pkgs lib helpers; }; + builtinCombinators = import ./combinators.nix pkgs; allCombinators = builtinCombinators // additionalCombinators builtinCombinators; + normalizePermissionsToList = combinators: + let t = builtins.typeOf combinators; in + if t == "lambda" then combinators allCombinators else + if t == "list" then combinators else + if t == "null" then [] + else throw "Unknown combinator type ${t}. Must be a function, list, or null"; + in { combinators = allCombinators; - __functor = _: name: exe: combinatorsToApply: let + __functor = _: name: exe: permissions: let initialState = { name = name; cmd = "${lib.getExe pkgs.bubblewrap}"; @@ -30,47 +33,14 @@ in { included-once = []; # See include-once combinator cleanup = []; # See cleanup combinator }; - - userCombinators = - let t = builtins.typeOf combinatorsToApply; in - if t == "lambda" then combinatorsToApply allCombinators else - if t == "list" then combinatorsToApply else - if t == "null" then [] - else throw "Unknown combinator type ${t}. Must be a function, list, or null"; - in lib.pipe initialState ( - # apply pre-user combinators - (with builtinCombinators; [ - (unsafe-add-raw-args "--proc /proc") - (unsafe-add-raw-args "--dev /dev") - (unsafe-add-raw-args "--tmpfs /tmp") - (unsafe-add-raw-args "--tmpfs ~") - (unsafe-add-raw-args "--clearenv") - (unsafe-add-raw-args "--die-with-parent") - (readonly "/nix/store") - (readonly "/bin/sh") - (fwd-env "LANG") - (fwd-env "HOME") - (fwd-env "TERM") + # Permissions shared by all invocations of jail + (normalizePermissionsToList basePermissions) - (add-runtime '' - if [ ! -e ${helpers.dataDirSubPath "passwd"} ] || [ ! -e ${helpers.dataDirSubPath "group"} ]; then - NOLOGIN=${pkgs.shadow}/bin/nologin - mkdir -p ${helpers.dataDir} - echo "root:x:0:0:System administrator:/root:$NOLOGIN" > ${helpers.dataDirSubPath "passwd"} - echo "$(id -un):x:$(id -u):$(id -g)::$HOME:$NOLOGIN" >> ${helpers.dataDirSubPath "passwd"} - echo "root:x:0:" > ${helpers.dataDirSubPath "group"} - echo "$(id -gn):x:$(id -g):" >> ${helpers.dataDirSubPath "group"} - fi - '') - (ro-bind (noescape (helpers.dataDirSubPath "passwd")) "/etc/passwd") - (ro-bind (noescape (helpers.dataDirSubPath "group")) "/etc/group") - ]) + # Permissions for this specific jail + ++ (normalizePermissionsToList permissions) - # apply user combinators - ++ userCombinators - - # apply post-user combinators + # Finalize everything remaining in state into bwrap args ++ (with builtinCombinators; [ (s: # See `--unshare-*` in BWRAP(1) @@ -89,7 +59,7 @@ in { ) s (builtins.attrNames s.env)) ]) - # build jailed app from state + # Build jailed app from state ++ [ (state: '' RUNTIME_ARGS=() diff --git a/tests/flake.nix b/tests/flake.nix index 343eb11..33f97d4 100644 --- a/tests/flake.nix +++ b/tests/flake.nix @@ -5,7 +5,7 @@ outputs = { nixpkgs, ... }: let pkgs = import nixpkgs { system = "x86_64-linux"; }; lib = pkgs.lib; - jail = import ../lib.nix { inherit pkgs; }; + jail-nix.lib.extend = import ../lib.nix; ansi = clrCode: "[${toString clrCode}m"; green = ansi 32; @@ -36,7 +36,7 @@ if lib.isDerivation testBody then lib.getExe testBody else throw "Unknown test body type ${type}"; - testCases = import ./test-cases.nix { inherit pkgs lib test jail; }; + testCases = import ./test-cases.nix { inherit pkgs lib test jail-nix; }; in { apps.x86_64-linux.runChecks = { type = "app"; diff --git a/tests/test-cases.nix b/tests/test-cases.nix index 7b044d2..dd6338b 100644 --- a/tests/test-cases.nix +++ b/tests/test-cases.nix @@ -1,11 +1,25 @@ -{ pkgs, lib, test, jail }: with test; let +{ pkgs, lib, test, jail-nix }: with test; let sh = script: (pkgs.writeShellApplication { name = "test-script"; text = script; }); defaultPath = "${pkgs.coreutils}/bin"; + jail = jail-nix.lib.extend { inherit pkgs; }; in { "simple jail works" = assertStdout (jail "hello" pkgs.hello []) "Hello, world!"; + "it allows overriding base permissions shared across all jails" = let + jail' = jail-nix.lib.extend { + inherit pkgs; + basePermissions = c: [ + (c.readonly "/build/secret") + (c.readonly "/nix/store") + ]; + }; + in [ + "echo hunter2 > /build/secret" + (assertStdout (jail' "hello" (sh "cat /build/secret") []) "hunter2") + ]; + "it sets a sane default path" = assertStdout (jail "test" (sh ''echo "$PATH"'') []) defaultPath; diff --git a/website/static-docs/advanced-configuration.md b/website/static-docs/advanced-configuration.md new file mode 100644 index 0000000..babe995 --- /dev/null +++ b/website/static-docs/advanced-configuration.md @@ -0,0 +1,64 @@ +# Advanced Configuration + +All configuration options on this page can be passed into `jail-nix.lib.extend`. + +## additionalCombinators + +`additionalCombinators` takes in a list of custom combinators to expose under +`jail.combinators` and in jail definitions. If passed a funciton, jail.nix will +inject the builtin combinators. + +For example, this creates a `jail` function that exposes a `my-combinator` +combinator: + +```nix +jail = jail-nix.lib.extend { + inherit pkgs; + additionalCombinators = builtinCombinators: with builtinCombinators; [ + my-combinator = compose [ + (readonly "/foo") + (readonly "/bar") + ]; + ]; +}; + +# Now my-combinator is exposed in all the places the builtin combinators are exposed: + +jailed-hello = jail "jailed-hello" pkgs.hello (c: with c; [ + my-combinator +]); + +# Alternatively, using jail.combinators: + +jailed-hello = jail "jailed-hello" pkgs.hello [ + jail.combinators.my-combinator +]; +``` + +## basePermissions + +By default, jail.nix comes with a base set of permissions that all jails +inherit by default. This configuration option allows you to override these. + +The goal of the base permissions are to provide a reasonably secure default +with enough permissions to have most software behave correctly. + +Example: +```nix +jail = jail-nix.lib.extend { + inherit pkgs; + basePermissions = builtinCombinators: with builtinCombinators; [ + (unsafe-add-raw-args "--proc /proc") + (unsafe-add-raw-args "--dev /dev") + (unsafe-add-raw-args "--tmpfs /tmp") + (unsafe-add-raw-args "--tmpfs ~") + (unsafe-add-raw-args "--clearenv") + (unsafe-add-raw-args "--die-with-parent") + (readonly "/nix/store") + (readonly "/bin/sh") + (fwd-env "LANG") + (fwd-env "HOME") + (fwd-env "TERM") + ]; +}; +``` diff --git a/website/static-docs/index.md b/website/static-docs/index.md index 452d61c..91ade98 100644 --- a/website/static-docs/index.md +++ b/website/static-docs/index.md @@ -16,6 +16,8 @@ configuration: } ``` +--- + ## Initializing The core functionality of jail.nix is a `jail` function that wraps derivations @@ -37,29 +39,23 @@ jail = jail-nix.lib.init pkgs; You can set more options in the initialization with `jail-nix.lib.extend`. -You must pass in an instantiated nixpkgs attribute `pkgs`. - -For example, the below snippet creates a `jail` function where `my-combinator` -is passed to jail definitions. +This takes in a single attribute set as an argument. The only required key is +`pkgs` which must be an instantiated nixpkgs. +Example: ```nix pkgs = import nixpkgs { system = "x86_64-linux"; }; - jail = jail-nix.lib.extend { inherit pkgs; - additionalCombinators = baseCombinators: with baseCombinators; [ - my-combinator = compose [ - (readonly "/foo") - (readonly "/bar") - ]; - ]; -}; -jailed-hello = jail "jailed-hello" pkgs.hello (c: with c; [ - my-combinator -]); + # Other configuration options here... +}; ``` +For a full list of options see [Advanced Configuration](advanced-configuration). + +--- + ## Usage Once you have an [initialized](#initializing) `jail` function, it takes the @@ -77,6 +73,8 @@ following positional arguments: a function, jail.combinators will be passed in, and the return value will be used. +--- + ## Examples ### Provide jail.nix as a module arg in a Nixos configuration: