dev -> master

Author: RX0FA

.github/workflows/build.yml

@@ -21,7 +21,7 @@ jobs:
       id: tag_step
       run: |-
         program_version=$(./dist/raptor-cage -V | awk '{print $2}')
-        tag_name="${program_version}-$(date +%y%m%d%H%M)-$(git rev-parse HEAD | head -c 7)"
+        tag_name="${program_version}-$(date +%y%m%d%H%M)"
         printf "tag_name=${tag_name}\nprogram_version=${program_version}\n" | tee -a "$GITHUB_OUTPUT"
         mv dist/raptor-cage.tgz dist/raptor-cage-${tag_name}.tgz
         mv dist/raptor-cage.sha256 dist/raptor-cage-${tag_name}.sha256

.gitignore

@@ -2,3 +2,4 @@ debug/
 target/
 dist/
 .SRCINFO
+id_ed25519

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "raptor-cage"
-version = "1.0.1"
+version = "1.0.2"
 edition = "2021"
 license = "CIL-1.0"
 

Cargo.toml

@@ -5,6 +5,9 @@
   <p>
     Run games in a secure sandbox, various native and non-native titles are supported.
   </p>
+  <img alt="Downloads" src="https://img.shields.io/github/downloads/RX0FA/raptor-cage/total?style=flat-square&label=DOWNLOADS&labelColor=0567ff&color=696969" />
+  <img alt="Latest Release" src="https://img.shields.io/github/v/release/RX0FA/raptor-cage?style=flat-square&label=LATEST%20RELEASE&labelColor=0567ff&color=696969" />
+  <img alt="AUR" src="https://img.shields.io/aur/version/raptor-cage-bin?style=flat-square&label=AUR&labelColor=0567ff&color=696969" />
 </div>
 
 ## ⬇️ Installation
@@ -32,22 +35,45 @@ sudo install -Dm755 raptor-cage "/usr/local/bin/rcage"
 
 ## 💡 Usage
 
-### Command Line
+> ⚠️ Network access is denied by default
+
+### Command Line Examples
 
 ```bash
 # Run Windows game, runner and prefix paths are relative to Bottles data directory.
 rcage run -r soda-9.0-1 -p my_prefix -d ~/games/some_game -b game.exe
 
 # Run native binary, and pass custom parameters.
 rcage run -r soda-9.0-1 -p my_prefix -d ~/games/some_game -b native_binary -- --param1
+
+# Mount game path as read-write, mount installer path as read-only, then start interactive shell.
+rcage run -r soda-9.0-1 -p my_prefix  -d ~/games/some_game:rw -v ~/installers:/installers:
+
+# Mount game path as read-write, mount installer path as read-only, then start "setup.exe".
+rcage run -r soda-9.0-1 -p my_prefix  -d ~/games/some_game:rw -v ~/installers:/installers: -b /installers/setup.exe
 ```
 
+### `rcage run` Enum Parameters
+
+* --network-mode:
+  * `full_access`: no network restrictions at all.
+  * `restricted_access`: restricts access to some network features such as DNS resolving and SSL certificates, however internet connection is still possible through direct IPs.
+  * `no_access`: network access is completely blocked, this is the default value if no option is passed.
+* --device-access:
+  * `all`: sandboxed program will have access to all devices i.e., `/dev` is completely exposed inside the sandbox.
+  * `minimal`: a limited amount of devices are exposed inside the sandbox i.e., GPU, gamepads, etc; this is the default value.
+* --upscale-mode:
+  * `none`: no upscaling applied, this is the default value.
+  * `dlss`: enable NVIDIA DLSS, **support depends on the wine runner**, raptor-cage only configures the necessary flags.
+  * `fsr`: enable FSR, it requires additional options separated by `:`, the command value should look like `fsr:mode:strength`. Mode can be one of `none`, `quality`, `balanced`, `performance` or `ultra`; strength is a value that goes from 0 to 5; (example command: `--upscale-mode=fsr:balanced:1`). **Support depends on the wine runner** being used.
+* --sync-mode: one of `none`, `fsync` or `esync`. The default value depends on the runner being used.
+
 ## 📌 Frequently Asked Questions
 
 * How to enable MangoHud?  
   Use the `-e MANGOHUD=1` parameter for games that use DXVK and VK3D, other games (OpenGL and WineD3D) may require to prepend `mangohud` before the binary (e.g., `mangohud wine game.exe`).
 * What is the difference with Bottles?  
-  Bottles is a GUI to manage Wine/Proton instances and their dependencies, it runs under Flatpak and it uses the same sandbox permissions as Bottles itself, that means that applications that are launched from Bottles have access to everything Bottles has access to (you can see what can Bottles access [here](https://github.com/flathub/com.usebottles.bottles/blob/master/com.usebottles.bottles.yml#L9)), raptor-cage launches applications with a restricted sandbox by default, and allows the user to adjust permissions independently.
+  Bottles is a GUI to manage Wine/Proton instances and their dependencies, and it runs under Flatpak; applications that are launched from Bottles have access to everything Bottles has access to (you can see what can Bottles access [here](https://github.com/flathub/com.usebottles.bottles/blob/master/com.usebottles.bottles.yml#L9)), raptor-cage launches applications with a restricted sandbox by default, and allows the user to adjust permissions independently.
 * Do I need Bottles in order to use raptor-cage?  
   No, Bottles is not needed, although is highly recommended in order to manage Wine/Proton versions and dependencies. If you don't want to use Bottles, you can download any Wine/Proton version you like, extract it anywhere and choose the respective path when running raptor-cage (`-r`).
 * What is the difference with Bubblewrap?  
@@ -83,11 +109,10 @@ cargo upgrade --dry-run
 #### General
 
 * Some games (like HC2, DXM) create a detached sub-process, since we are using `--die-with-parent`, said games will not run when executed directly (with `-b` parameter, executing a shell and launching manually still works); so we need to think in a way to detect child processes and wait for them, or at least add a flag to enable this feature. Disabling `--die-with-parent` is another option, but that would undermine security a bit and leave lingering wine processes all over the place. Maybe add a `--lead-process=NAME_EXE:TIMEOUT` to wait for another process inside the sandbox.
-* Implement bash autocompletion, should be able to autocomplete prefix and runner names based on the ones detected under Bottles.
+* Implement bash autocompletion, should be able to autocomplete prefix and runner names based on the ones detected under Bottles. Also consider using [clap_complete](https://crates.io/crates/clap_complete).
 * Add `integrate` sub-command to create integrations e.g., `.desktop` shortcut, entry on Heroic launcher.
 * Native wayland support, see https://www.phoronix.com/news/Wine-9.22-Released and https://wiki.archlinux.org/title/Wine#Wayland. Also consider bringing back `--unshare-ipc` if using Wayland prevents the issue described in bwrap.rs#90.
 * Add `kill` sub-command to terminate all processes in a sandbox, need to connect to existing bwrap container.
-* Add argument to mount additional paths (needed for installers and maintenance), syntax can be similar to Docker's `-v PATH:FLAGS`.
 * When using the `integrate` sub-command to create a `.desktop` shortcut, extract executable icon and set it respectively. It can be done with a small windows executable calling a win32 API call or natively on Linux by using `wrestool`.
 * Add NTSYNC support, see also https://www.phoronix.com/news/Linux-6.14-NTSYNC-Driver-Ready.
 

README.md

@@ -18,6 +18,9 @@ pub enum Commands {
     /// Environment variable overrides.
     #[arg(short = 'e', long = "setenv", value_name="KEY=VALUE", action = ArgAction::Append)]
     environment: Vec<String>,
+    /// Additional mount points.
+    #[arg(short = 'v', long = "volume", value_name="PATH", action = ArgAction::Append)]
+    volumes: Vec<String>,
     /// Disable namespace isolation.
     #[arg(long, default_value = "false")]
     no_namespace_isolation: bool,
@@ -31,7 +34,7 @@ pub enum Commands {
     #[arg(long, value_name = "ACCESS", default_value = "minimal", value_parser)]
     device_access: DeviceAccess,
     /// Print additional troubleshooting information.
-    #[arg(short, long, default_value = "false")]
+    #[arg(long, default_value = "false")]
     verbose: bool,
     /// One of none, dlss, fsr:mode:stre.
     #[arg(long, value_name = "MODE", default_value = "none", value_parser)]

src/cli.rs

@@ -1,15 +1,25 @@
 use crate::sandbox::{
   bwrap,
-  sandbox::{
-    DeviceAccess, LaunchConfig, LaunchParams, MountConfig, NetworkMode, RuntimeEnv, SandboxConfig,
-  },
+  mount::{MountConfig, MountMapping},
+  sandbox::{DeviceAccess, LaunchConfig, LaunchParams, NetworkMode, RuntimeEnv, SandboxConfig},
   user_mapping::UserMapping,
   wine::{SyncMode, UpscaleMode},
 };
 use std::{collections::HashMap, path::PathBuf, str::FromStr};
 
+fn parse_mappings(volumes: &[String]) -> anyhow::Result<Vec<MountMapping>> {
+  let mut mappings: Vec<MountMapping> = Vec::with_capacity(volumes.len());
+  for volume in volumes {
+    let mapping =
+      MountMapping::from_str(volume).map_err(|e| anyhow::anyhow!("volume error: {}", e))?;
+    mappings.push(mapping);
+  }
+  Ok(mappings)
+}
+
 pub fn run(
-  environment: Vec<String>,
+  environment: &[String],
+  volumes: &[String],
   no_namespace_isolation: bool,
   user_mapping: UserMapping,
   network_mode: NetworkMode,
@@ -57,5 +67,11 @@ pub fn run(
     .collect();
   let mut runtime_env = RuntimeEnv::from_env()?;
   runtime_env.overrides = Some(env_overrides);
-  bwrap::run(&sandbox_config, &launch_config, &runtime_env)
+  let mount_mappings = parse_mappings(volumes)?;
+  bwrap::run(
+    &sandbox_config,
+    &launch_config,
+    &runtime_env,
+    &mount_mappings,
+  )
 }

src/invoker.rs

@@ -11,6 +11,7 @@ fn main() -> anyhow::Result<()> {
   match args.command {
     Commands::Run {
       environment,
+      volumes,
       no_namespace_isolation,
       user_mapping,
       network_mode,
@@ -24,7 +25,8 @@ fn main() -> anyhow::Result<()> {
       app_bin,
       app_args,
     } => invoker::run(
-      environment,
+      &environment,
+      &volumes,
       no_namespace_isolation,
       user_mapping,
       network_mode,

src/main.rs

@@ -1,4 +1,5 @@
 use super::display::Display;
+use super::mount::MountMapping;
 use super::sandbox::{
   DeviceAccess, LaunchConfig, LaunchParams, NetworkMode, RuntimeEnv, SandboxConfig,
 };
@@ -68,6 +69,21 @@ pub fn get_device_args(device_access: &DeviceAccess) -> anyhow::Result<Vec<Strin
   }
 }
 
+fn get_mount_args(mount_mappings: &[MountMapping]) -> Vec<String> {
+  let mut args: Vec<String> = Vec::with_capacity(mount_mappings.len() * 3);
+  for mapping in mount_mappings {
+    let bind_param = if mapping.target_config.writable {
+      "--bind"
+    } else {
+      "--ro-bind"
+    };
+    let source = mapping.source_path.to_string_lossy();
+    let target = mapping.target_config.path.to_string_lossy();
+    args.extend(vec![bind_param.into(), source.into(), target.into()]);
+  }
+  args
+}
+
 const INNER_WINE_ROOT: &str = "/opt/wine";
 const INNER_WINE_PREFIX: &str = "/var/lib/wine";
 const INNER_APP_DIR: &str = "/app";
@@ -76,6 +92,7 @@ fn build_args(
   sandbox_config: &SandboxConfig,
   launch_config: &LaunchConfig,
   runtime_env: &RuntimeEnv,
+  mount_mappings: &[MountMapping],
   empty_file_path: &str,
 ) -> anyhow::Result<Vec<String>> {
   let mut args = vec![
@@ -350,6 +367,9 @@ fn build_args(
   let term = env::var("TERM").unwrap_or("xterm-256color".into());
   let shell = env::var("SHELL").unwrap_or("bash".into());
   let shell_params: Vec<String> = vec!["--setenv".into(), "TERM".into(), term, shell];
+  // Additional mounts.
+  let mount_args = get_mount_args(mount_mappings);
+  final_args.extend(mount_args);
   // Depending on the launch params, add the necessary arguments to start a regular shell or execute
   // the specified command.
   match &launch_config.launch_params {
@@ -408,14 +428,21 @@ pub fn run(
   sandbox_config: &SandboxConfig,
   launch_config: &LaunchConfig,
   runtime_env: &RuntimeEnv,
+  mount_mappings: &[MountMapping],
 ) -> anyhow::Result<()> {
   // Temporary file will be automatically removed when variable goes out of scope.
   let temp_file = NamedTempFile::new()?;
   let temp_file_path = temp_file
     .path()
     .to_str()
     .context("could not get temporary file path")?;
-  let args = build_args(sandbox_config, launch_config, &runtime_env, temp_file_path)?;
+  let args = build_args(
+    sandbox_config,
+    launch_config,
+    runtime_env,
+    mount_mappings,
+    temp_file_path,
+  )?;
   let mut cmd = Command::new("bwrap")
     .args(args)
     .stdout(Stdio::inherit())

src/sandbox/bwrap.rs

@@ -1,6 +1,7 @@
 pub mod bottles;
 pub mod bwrap;
 mod display;
+pub mod mount;
 pub mod sandbox;
 pub mod user_mapping;
 pub mod wine;