rappct

Stable (main branch)

Rust toolkit for working with Windows AppContainer (AC) and Low Privilege AppContainer (LPAC) security boundaries.

rappct packages the underlying Windows APIs into a cohesive crate so that you can create, manage, and launch AppContainer-aware workloads from Rust with minimal boilerplate. It is designed for security-sensitive automation that needs to compose profiles, capabilities, process launches, ACL helpers, and diagnostics in one place.

• Status: Actively developed. Windows paths are implemented first; non-Windows hosts return UnsupportedPlatform.
• MSRV: Rust 1.90 (stable).

Highlights

• AppContainer profile lifecycle helpers (create, open, delete) and profile path resolution.
• Capability derivation via DeriveCapabilitySidsFromName, with ergonomic builders for known and custom capability SIDs.
• Secure process launch helpers (AC/LPAC) with STARTUPINFOEX, optional job object integration, and stdio redirection.
• Token inspection helpers to understand the effective AppContainer/LPAC context at runtime.
• Optional modules for diagnostics (introspection) and network loopback management (net).
• ACL utilities to grant/revoke filesystem and registry access for package SIDs.

What To Expect

• Network isolation by default; use capability sets and optional loopback exemption for localhost-only testing.
• DNS/HTTP behavior varies by capability and Windows version; LPAC is stricter.
• File system and registry are isolated; grant specific paths/keys via ACL helpers when needed.
• Examples and docs show cleanup patterns to avoid lingering policy changes.

Release & Branching

• Single-branch flow. Pushes to main run CI; when green, the release workflow cuts a GitHub release and publishes to crates.io automatically.

Prerequisites

Getting Started

# Clone the repository
git clone https://github.com/cpjet64/rappct.git
cd rappct

# Build the library
cargo build

# Run the example CLI
cargo run --example acrun -- --help

The crate is structured as a binary-agnostic library. Add it to your project:

# Stable release from crates.io (recommended)
cargo add rappct

# Pin a specific version (optional)
# See the latest on crates.io or the release badge
cargo add rappct@<x.y.z>

# Development version from git (optional)
cargo add rappct --git https://github.com/cpjet64/rappct.git --branch main

Usage Snapshot

use rappct::{AppContainerProfile, KnownCapability, LaunchOptions, SecurityCapabilitiesBuilder, launch_in_container};

fn main() -> rappct::Result<()> {
    let profile = AppContainerProfile::ensure("demo.rappct", "Demo", Some("rappct example"))?;
    let caps = SecurityCapabilitiesBuilder::new(&profile.sid)
        .with_known(&[KnownCapability::InternetClient])
        .with_lpac_defaults() // opt in to LPAC defaults when required
        .build()?;

    let opts = LaunchOptions { exe: "C:/Windows/System32/notepad.exe".into(), ..Default::default() };
    let child = launch_in_container(&caps, &opts)?;
    println!("child pid: {}", child.pid);
    Ok(())
}

Examples

The examples/ directory contains runnable demonstrations of rappct features:

rappct_demo.rs

Simple demonstration of essential features:

• Creating AppContainer profiles
• Launching sandboxed processes
• Granting specific capabilities
• Automatic network configuration (with net feature)

cargo run --example rappct_demo --all-features

comprehensive_demo.rs

Comprehensive demonstrations with isolated examples for each capability:

• Individual demos for filesystem, registry, network, and COM capabilities
• PowerShell in AppContainers (output redirection pattern)
• Combined multi-capability example
• Best for understanding each feature in isolation

cargo run --example comprehensive_demo --all-features

advanced_features.rs

Advanced and less common features:

• Profile path resolution (folder_path, named_object_path)
• Custom named capabilities
• Configuration diagnostics
• Advanced launch options with custom environment variables
• Network enumeration
• Direct SID derivation

cargo run --example advanced_features --all-features

network_demo.rs

Network capability demonstration with automatic firewall configuration:

• Built-in firewall loopback exemption functionality
• PowerShell network testing in AppContainers
• Automatic cleanup patterns

cargo run --example network_demo --features net

acrun.rs

Developer CLI tool for managing AppContainer profiles and launching sandboxed processes:

# Create a profile
cargo run --example acrun -- ensure demo.app

# Launch a process in an AppContainer
cargo run --example acrun -- launch demo.app notepad.exe

# View help for all commands
cargo run --example acrun -- --help

Feature Flags

Disable unused features for the leanest runtime surface; APIs gracefully return AcError::Unimplemented when a feature is not compiled in.

Diagnostics & Security Considerations

• LPAC capabilities are opt-in; call SecurityCapabilitiesBuilder::with_lpac_defaults() explicitly.
• Loopback exemptions via the net feature are meant for debug scenarios only. Production use should rely on standard firewall policy.
• When something fails due to missing capabilities or OS prerequisites, rappct surfaces detailed error messages instead of falling back silently. Use supports_lpac() to guard LPAC-specific code paths. For tests/CI, you can set RAPPCT_TEST_LPAC_STATUS=ok|unsupported to force detection.

See also: docs/capabilities.md for common capability SIDs and starter sets.

Repository Layout

• src/ — core library modules (capabilities, launch, ACLs, diagnostics).
• examples/ — runnable samples such as acrun for quick CLI exploration.
• tests/ — integration tests covering launch/ACL/token behaviours on Windows.

Development Workflow

cargo fmt
cargo clippy --all-targets --all-features
cargo test --all-targets --all-features

Run Windows-specific scenarios in an elevated PowerShell session when the tests require loopback exemptions or ACL adjustments.

Local Test Toggles

These environment variables help diagnose local environment quirks during AppContainer launches. They are intended for local testing only and are not required on CI.

• RAPPCT_TEST_FORCE_ENV=1

  • Passes an explicit, Unicode environment block to CreateProcessW built from the current process environment (sorted case-insensitively).
  • Use if you see Win32 error 203 (environment option not found) on your machine.

• RAPPCT_TEST_NO_CWD=1

  • Skips passing an explicit current directory to CreateProcessW.
  • Use to rule out cwd issues on machines with unusual default directories.

• RAPPCT_DEBUG_LAUNCH=1

  • Prints verbose CreateProcessW diagnostics (flags, env bytes, HRESULT) to stderr during tests.

Examples:

$env:RAPPCT_TEST_FORCE_ENV='1'
$env:RAPPCT_TEST_NO_CWD='1'
$env:RAPPCT_DEBUG_LAUNCH='1'
cargo test --test windows_launch -- --nocapture

Contributing

Contributions are welcome! Please:

1. Open an issue using the provided template before starting major work.
2. Discuss API-affecting changes early to avoid churn.
3. Include tests and documentation updates alongside code changes.
4. Run the checks listed in the PR template before submitting.

See CONTRIBUTING.md for style and review guidelines.

Security

Please report vulnerabilities privately through the GitHub Security Advisory workflow.

License

This project is licensed under the MIT license.