hookfs 0.1.0

Safe virtual filesystem for closed-source native libraries, via import-table hooking
Documentation

hookfs

hookfs lets a native library open Rust-owned streams and virtual files through ordinary absolute paths without materializing those files on disk. It patches the selected module's imported file-system functions and routes only paths in a private synthetic namespace to a Rust VirtualFs; every other path is passed to the original operating-system implementation.

This is useful when a closed-source SDK insists on receiving a file name but the application owns the data in memory, an archive, a remote object store, or another custom storage layer.

Features

  • Mount any owned Read + Seek + Send + 'static stream.
  • Give every native open an independent cursor over the shared source.
  • Serve metadata, seeking, directory enumeration, and normal read APIs.
  • Optionally expose in-memory create, write, truncate, and delete operations.
  • Scope hooks to one module, a module allow/deny list, or all loaded modules.
  • Rescan late-loaded modules when a native SDK loads plugins on demand.
  • Implement a custom VirtualFs, or compose providers with OverlayFs.
  • Restore import slots automatically when the installation guard is dropped.

Installation

[dependencies]
hookfs = "0.1.0"

The minimum supported Rust version is 1.96.

Mounting a stream

The normal workflow is to create one context, mount one or more streams, install the hooks, and pass the resulting synthetic paths to the native library. Options::for_module needs an address only to locate the module to patch. It may be the address of any export from that exact DLL, .so, or .dylib, typically an SDK entry point the application already resolved. For example, a BRAW caller can use CreateBlackmagicRawFactoryInstance:

use hookfs::{Hookfs, Options};
use std::ffi::c_void;
use std::io::Cursor;
use std::path::Path;

fn main() -> hookfs::Result<()> {
    let fs = Hookfs::new();
    let clip = fs.mount("clip.bin", Cursor::new(vec![1, 2, 3, 4]))?;

    // The address must belong to the native module that will issue file calls.
    let hooks = fs.install(Options::for_module(sdk_module_anchor()))?;

    sdk_open(&fs.path_for("clip.bin"));

    // Drop hooks before mounts, and keep both alive until native work is finished.
    drop(hooks);
    drop(clip);
    Ok(())
}

fn sdk_module_anchor() -> *const c_void {
    // Return any export address from the SDK module to patch. For example:
    // GetProcAddress(sdk, "CreateBlackmagicRawFactoryInstance") on Windows, or
    // dlsym(sdk, "CreateBlackmagicRawFactoryInstance") on Unix.
    todo!("return an export address from the target SDK module")
}

fn sdk_open(_path: &Path) {
    // Pass the synthetic path to the SDK.
}

For a single stream, mount_read_seek returns a MountedPath convenience value that owns its context and mount guard.

Mount names must be relative and lexically safe. Absolute names, parent traversal, NUL bytes, and Windows drive/device/stream syntax are rejected.

Writable virtual files

Writes are fail-closed by default. Enable them explicitly when the native library must create a sidecar or output file:

use hookfs::{Hookfs, Options};
use std::ffi::c_void;

fn main() -> hookfs::Result<()> {
    let fs = Hookfs::with_capacity(64 * 1024 * 1024);
    let output = fs.mount_writable("result.bin")?;
    let hooks = fs.install(
        Options::for_module(sdk_module_anchor()).allow_writes(true),
    )?;

    // Call the SDK with fs.path_for("result.bin"), then copy the result back.
    let bytes = fs.read_virtual("result.bin");

    drop(hooks);
    drop(output);
    println!("the SDK wrote {} bytes", bytes.map_or(0, |data| data.len()));
    Ok(())
}

fn sdk_module_anchor() -> *const c_void {
    // Any exported function in the exact SDK module that will open the file.
    // The address identifies the module; hookfs does not call this function.
    todo!("return an export address from the target SDK module")
}

with_capacity controls the synthetic volume capacity. Provider errors are translated to the platform ABI, and panics are contained at the FFI boundary.

Hook scope

Options::for_module(address) is the safest default: only the module containing the supplied live address is patched. Other choices are available through Scope:

  • Scope::AllModules patches all supported modules currently loaded.
  • Scope::Only(names) patches matching module file names.
  • Scope::Exclude(names) patches everything except matching file names.
  • Options::auto_rescan(true) also hooks supported modules loaded later.

Only one hookfs installation can be active in a process at a time. Drop the existing InstallGuard before installing another one. InstallGuard::rescan can be used for an explicit late-module scan.

Custom providers

Implement VirtualFs when files should come from application-specific storage. Read operations return Option<io::Result<_>>: None means the path is not owned by that provider, allowing normal passthrough or another overlay layer. Mutation methods have the same not-owned convention and are called only when writes are enabled.

Use hookfs::install(Arc<dyn VirtualFs>, Options) for a provider you manage directly. MemoryFs provides the built-in in-memory tree, while OverlayFs queries multiple providers in first-match order.

Platform support and limitations

Live hooks support Windows/PE32+, Linux/glibc ELF64, macOS Mach-O 64, and iOS/iPadOS Mach-O 64 on x86_64 or aarch64 where the OS supports that architecture. Other targets retain the platform-independent types but return Error::UnsupportedPlatform from installation.

The mechanism redirects imported calls in patched modules. It cannot intercept inlined functions, direct syscalls, static linkage, or calls through modules outside the chosen scope. It is not a sandbox or security boundary. Do not unload a target native module or release mounts while it can still perform file operations.

License

Original work is licensed under either MIT or Apache-2.0, at your option. hookfs depends on plthook-native, a Rust port of kubo/plthook; the dependency carries its upstream BSD-2-Clause notice.