diff --git a/README.md b/README.md index 5d62b0f..4d12105 100644 --- a/README.md +++ b/README.md @@ -69,142 +69,104 @@ This adds the `environment.fortify` option: { environment.fortify = { enable = true; - user = "nixos"; - stateDir = "/var/lib/persist/module"; - target = { - chronos = { - launchers = { - weechat.method = "sudo"; - claws-mail.capability.pulse = false; + stateDir = "/var/lib/persist/module/fortify"; + users = { + alice = 0; + nixos = 10; + }; - discord = { - id = "dev.vencord.Vesktop"; - command = "vesktop --ozone-platform-hint=wayland"; - userns = true; - useRealUid = true; - dbus = { - session = - f: - f { - talk = [ "org.kde.StatusNotifierWatcher" ]; - own = [ ]; - call = { }; - broadcast = { }; - }; - system.filter = true; - }; - share = pkgs.vesktop; + apps = [ + { + name = "chromium"; + id = "org.chromium.Chromium"; + packages = [ pkgs.chromium ]; + userns = true; + mapRealUid = true; + dbus = { + system = { + filter = true; + talk = [ + "org.bluez" + "org.freedesktop.Avahi" + "org.freedesktop.UPower" + ]; }; - - chromium = { - id = "org.chromium.Chromium"; - userns = true; - useRealUid = true; - dbus = { - system = { - filter = true; - talk = [ - "org.bluez" - "org.freedesktop.Avahi" - "org.freedesktop.UPower" - ]; - }; - session = f: f { - talk = [ - "org.freedesktop.DBus" - "org.freedesktop.FileManager1" - "org.freedesktop.Notifications" - "org.freedesktop.ScreenSaver" - "org.freedesktop.secrets" - "org.kde.kwalletd5" - "org.kde.kwalletd6" - ]; - own = [ - "org.chromium.Chromium.*" - "org.mpris.MediaPlayer2.org.chromium.Chromium.*" - "org.mpris.MediaPlayer2.chromium.*" - ]; - call = { }; - broadcast = { }; - }; + session = + f: + f { + talk = [ + "org.freedesktop.DBus" + "org.freedesktop.FileManager1" + "org.freedesktop.Notifications" + "org.freedesktop.ScreenSaver" + "org.freedesktop.secrets" + "org.kde.kwalletd5" + "org.kde.kwalletd6" + ]; + own = [ + "org.chromium.Chromium.*" + "org.mpris.MediaPlayer2.org.chromium.Chromium.*" + "org.mpris.MediaPlayer2.chromium.*" + ]; + call = { }; + broadcast = { }; }; - }; }; - packages = with pkgs; [ - weechat - claws-mail - vesktop - chromium - ]; - persistence.directories = [ - ".config/weechat" - ".claws-mail" - ".config/vesktop" + } + { + name = "claws-mail"; + id = "org.claws_mail.Claws-Mail"; + packages = [ pkgs.claws-mail ]; + gpu = false; + capability.pulse = false; + } + { + name = "weechat"; + packages = [ pkgs.weechat ]; + capability = { + wayland = false; + x11 = false; + dbus = true; + pulse = false; + }; + } + { + name = "discord"; + id = "dev.vencord.Vesktop"; + packages = [ pkgs.vesktop ]; + share = pkgs.vesktop; + command = "vesktop --ozone-platform-hint=wayland"; + userns = true; + mapRealUid = true; + capability.x11 = true; + dbus = { + session = + f: + f { + talk = [ "org.kde.StatusNotifierWatcher" ]; + own = [ ]; + call = { }; + broadcast = { }; + }; + system.filter = true; + }; + } + { + name = "looking-glass-client"; + groups = [ "plugdev" ]; + extraPaths = [ + { + src = "/dev/shm/looking-glass"; + write = true; + } ]; extraConfig = { programs.looking-glass-client.enable = true; }; - }; - }; + } + ]; }; } ``` -* `enable` determines whether the module should be enabled or not. Useful when sharing configurations between graphical - and headless systems. Defaults to `false`. - -* `user` specifies the privileged user with access to fortified applications. - -* `stateDir` is the path to your persistent storage location. It is directly passed through to the impermanence module. - -* `target` is an attribute set of submodules, where the attribute name is the username of the unprivileged target user. - - The available options are: - - * `packages`, the list of packages to make available in the target user's environment. - - * `persistence`, user persistence attribute set passed to impermanence. - - * `extraConfig`, extra home-manager configuration for the target user. - - * `launchers`, attribute set where the attribute name is the name of the launcher. - - The available options are: - - * `id`, the freedesktop application ID, primarily used by dbus, null to disable. - - * `script`, application launch script. - - * `command`, the command to run as the target user. Defaults to launcher name. Has no effect when script is set. - - * `dbus.session`, D-Bus session proxy custom configuration. - - * `dbus.configSystem`, D-Bus system proxy custom configuration, null to disable. - - * `env`, attrset of environment variables to set for the initial process in the sandbox. - - * `nix`, whether to allow nix daemon connections from within the sandbox. - - * `userns`, whether to allow userns within the sandbox. - - * `useRealUid`, whether to map to the real UID within the sandbox. - - * `net`, whether to allow network access within the sandbox. - - * `gpu`, target process GPU and driver access, null to follow Wayland or X capability. - - * `dev`, whether to allow full device access within the sandbox. - - * `extraPaths`, a list of extra paths to make available inside the sandbox. - - * `capability.wayland`, whether to share the Wayland socket. - - * `capability.x11`, whether to share the X11 socket and allow connection. - - * `capability.dbus`, whether to proxy D-Bus. - - * `capability.pulse`, whether to share the PulseAudio socket and cookie. - - * `share`, package containing desktop/icon files. Defaults to launcher name. - - * `method`, the launch method for the sandboxed program, can be `"sudo"`, `"systemd"`, `"simple"`. +Full module documentation can be found [here](options.md). diff --git a/flake.nix b/flake.nix index ba6c0c8..69c5514 100644 --- a/flake.nix +++ b/flake.nix @@ -42,6 +42,33 @@ with nixpkgsFor.${system}; self.packages.${system}.fortify.buildInputs ++ [ self.packages.${system}.fortify ]; }; + + generateDoc = + let + pkgs = nixpkgsFor.${system}; + inherit (pkgs) lib; + + doc = + let + eval = lib.evalModules { + specialArgs = { + inherit pkgs; + }; + modules = [ ./options.nix ]; + }; + cleanEval = lib.filterAttrsRecursive (n: v: n != "_module") eval; + in + pkgs.nixosOptionsDoc { inherit (cleanEval) options; }; + docText = pkgs.runCommand "fortify-module-docs.md" { } '' + cat ${doc.optionsCommonMark} > $out + sed -i '/*Declared by:*/,+1 d' $out + ''; + in + nixpkgsFor.${system}.mkShell { + shellHook = '' + exec cat ${docText} > options.md + ''; + }; }); }; } diff --git a/options.md b/options.md new file mode 100644 index 0000000..18acd56 --- /dev/null +++ b/options.md @@ -0,0 +1,531 @@ +## environment\.fortify\.enable + + + +Whether to enable fortify\. + + + +*Type:* +boolean + + + +*Default:* +` false ` + + + +*Example:* +` true ` + + + + +## environment\.fortify\.package + + + +The fortify package to use\. + + + +*Type:* +package + + + +*Default:* +` ` + + + + +## environment\.fortify\.apps + +Declarative fortify apps\. + + + +*Type:* +list of (submodule) + + + +*Default:* +` [ ] ` + + + + +## environment\.fortify\.apps\.\*\.packages + + + +List of extra packages to install via home-manager\. + + + +*Type:* +list of package + + + +*Default:* +` [ ] ` + + + + +## environment\.fortify\.apps\.\*\.capability\.dbus + + + +Whether to proxy D-Bus\. + + + +*Type:* +boolean + + + +*Default:* +` true ` + + + + +## environment\.fortify\.apps\.\*\.capability\.pulse + + + +Whether to share the PulseAudio socket and cookie\. + + + +*Type:* +boolean + + + +*Default:* +` true ` + + + + +## environment\.fortify\.apps\.\*\.capability\.wayland + + + +Whether to share the Wayland socket\. + + + +*Type:* +boolean + + + +*Default:* +` true ` + + + + +## environment\.fortify\.apps\.\*\.capability\.x11 + + + +Whether to share the X11 socket and allow connection\. + + + +*Type:* +boolean + + + +*Default:* +` false ` + + + + +## environment\.fortify\.apps\.\*\.command + + + +Command to run as the target user\. +Setting this to null will default command to launcher name\. +Has no effect when script is set\. + + + +*Type:* +null or string + + + +*Default:* +` null ` + + + + +## environment\.fortify\.apps\.\*\.dbus\.session + + + +D-Bus session bus custom configuration\. +Setting this to null will enable built-in defaults\. + + + +*Type:* +null or (function that evaluates to a(n) anything) + + + +*Default:* +` null ` + + + + +## environment\.fortify\.apps\.\*\.dbus\.system + + + +D-Bus system bus custom configuration\. +Setting this to null will disable the system bus proxy\. + + + +*Type:* +null or anything + + + +*Default:* +` null ` + + + + +## environment\.fortify\.apps\.\*\.dev + + + +Whether to enable access to all devices within the sandbox\. + + + +*Type:* +boolean + + + +*Default:* +` false ` + + + +*Example:* +` true ` + + + + +## environment\.fortify\.apps\.\*\.env + + + +Environment variables to set for the initial process in the sandbox\. + + + +*Type:* +null or (attribute set of string) + + + +*Default:* +` null ` + + + + +## environment\.fortify\.apps\.\*\.extraConfig + + + +Extra home-manager configuration\. + + + +*Type:* +anything + + + +*Default:* +` { } ` + + + + +## environment\.fortify\.apps\.\*\.extraPaths + + + +Extra paths to make available to the sandbox\. + + + +*Type:* +list of anything + + + +*Default:* +` [ ] ` + + + + +## environment\.fortify\.apps\.\*\.gpu + + + +Target process GPU and driver access\. +Setting this to null will enable GPU whenever X or Wayland is enabled\. + + + +*Type:* +null or boolean + + + +*Default:* +` null ` + + + + +## environment\.fortify\.apps\.\*\.groups + + + +List of groups to inherit from the privileged user\. + + + +*Type:* +list of string + + + +*Default:* +` [ ] ` + + + + +## environment\.fortify\.apps\.\*\.id + + + +Freedesktop application ID\. + + + +*Type:* +null or string + + + +*Default:* +` null ` + + + + +## environment\.fortify\.apps\.\*\.mapRealUid + + + +Whether to enable mapping to fortify’s real UID within the sandbox\. + + + +*Type:* +boolean + + + +*Default:* +` false ` + + + +*Example:* +` true ` + + + + +## environment\.fortify\.apps\.\*\.name + + + +Name of the app’s launcher script\. + + + +*Type:* +string + + + + +## environment\.fortify\.apps\.\*\.net + + + +Whether to enable network access within the sandbox\. + + + +*Type:* +boolean + + + +*Default:* +` true ` + + + +*Example:* +` true ` + + + + +## environment\.fortify\.apps\.\*\.nix + + + +Whether to enable nix daemon access within the sandbox\. + + + +*Type:* +boolean + + + +*Default:* +` false ` + + + +*Example:* +` true ` + + + + +## environment\.fortify\.apps\.\*\.script + + + +Application launch script\. + + + +*Type:* +null or string + + + +*Default:* +` null ` + + + + +## environment\.fortify\.apps\.\*\.share + + + +Package containing share files\. +Setting this to null will default package name to wrapper name\. + + + +*Type:* +null or package + + + +*Default:* +` null ` + + + + +## environment\.fortify\.apps\.\*\.userns + + + +Whether to enable userns within the sandbox\. + + + +*Type:* +boolean + + + +*Default:* +` false ` + + + +*Example:* +` true ` + + + + +## environment\.fortify\.stateDir + + + +The state directory where app home directories are stored\. + + + +*Type:* +string + + + + +## environment\.fortify\.users + + + +Users allowed to spawn fortify apps and their corresponding fortify fid\. + + + +*Type:* +attribute set of integer between 0 and 99 (both inclusive) + + +