Wardstone

https://docs.rs/wardstone/0.1.0
Admin
Wardstone is a cross-platform sandboxing system for secure tool execution, providing magical...
Tokens:15,777
Snippets:231
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Sandbox Usage Example

Source: https://docs.rs/wardstone/0.1.0/wardstone/index.html

Demonstrates how to create a SandboxPolicy, configure permissions, instantiate a Sandbox, and wrap a command for execution within the sandbox.

```APIDOC
## Usage Example

This example shows how to use the `wardstone` crate to create a sandboxed environment.

### Code
```rust
use wardstone::{Sandbox, SandboxPolicy};

let policy = SandboxPolicy::new()
    .allow_read("/usr")
    .allow_write("./")
    .deny_network();

let sandbox = Sandbox::new(policy)?;
let wrapped_cmd = sandbox.wrap_command(cmd);
```

### Explanation
1.  **`SandboxPolicy::new()`**: Initializes a new sandbox policy.
2.  **`.allow_read("/usr")`**: Grants read access to the `/usr` directory.
3.  **`.allow_write("./")`**: Grants write access to the current directory.
4.  **`.deny_network()`**: Denies all network access.
5.  **`Sandbox::new(policy)?`**: Creates a new sandbox instance with the defined policy. This operation can fail, hence the `?` operator.
6.  **`sandbox.wrap_command(cmd)`**: Wraps a given command (`cmd`) to be executed within the created sandbox.
```

--------------------------------

### Create New SandboxPolicy

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Initializes a new, empty SandboxPolicy. Use this as a starting point before applying specific permissions and configurations.

```rust
pub fn new() -> Self
```

--------------------------------

### Get LandlockSandbox type name

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/struct.LandlockSandbox.html

Returns the static string name of the sandbox type. This can be used for identification or logging purposes.

```rust
fn sandbox_type(&self) -> &'static str
```

--------------------------------

### Get TypeId of a type

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/struct.LandlockSandbox.html

Gets the `TypeId` of `self`. This is part of the `Any` trait implementation and is useful for dynamic type checking.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Test NetworkRule Creation

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Demonstrates creating a NetworkRule with a specific host, port, and protocol.

```rust
#[test]
fn test_network_rule() {
    let rule = NetworkRule {
        host: "localhost".into(),
        port: Some(8080),
        protocol: NetworkProtocol::Tcp,
    };
    
    assert_eq!(rule.host, "localhost");
    assert_eq!(rule.port, Some(8080));
    assert_eq!(rule.protocol, NetworkProtocol::Tcp);
}
```

--------------------------------

### Test Custom Network Allowlist Policy

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Demonstrates setting a custom network policy using `with_network`, specifying an allowlist with host, port, and protocol.

```rust
#[test]
fn test_with_network_allowlist() {
    let policy = SandboxPolicy::new()
        .with_network(NetworkPolicy::Allowlist(vec![
            NetworkRule {
                host: "api.example.com".into(),
                port: Some(443),
                protocol: NetworkProtocol::Tcp,
            },
        ]));
    
}
```

--------------------------------

### create_sandbox

Source: https://docs.rs/wardstone/0.1.0/wardstone/fn.create_sandbox.html

Creates the appropriate sandbox for the current platform.

```APIDOC
## Function create_sandbox

### Description
Creates the appropriate sandbox for the current platform.

### Signature
```rust
pub fn create_sandbox(
    policy: SandboxPolicy,
) -> Result<Box<dyn Sandbox>, SandboxError>
```

### Parameters
#### Path Parameters
- **policy** (SandboxPolicy) - Required - The policy to apply to the sandbox.

### Returns
- **Result<Box<dyn Sandbox>, SandboxError>** - Ok containing a boxed sandbox if successful, or an Err containing a SandboxError if creation fails.
```

--------------------------------

### LandlockSandbox::new

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/landlock.rs.html

Creates a new Landlock sandbox. It checks for Landlock availability on the system before proceeding.

```APIDOC
## LandlockSandbox::new

### Description
Creates a new Landlock sandbox with the given policy. It checks if Landlock is supported on the current kernel.

### Signature
```rust
pub fn new(policy: SandboxPolicy) -> Result<Self, SandboxError>
```

### Parameters
* **policy** (`SandboxPolicy`) - The security policy to apply to the sandbox.

### Returns
* `Result<LandlockSandbox, SandboxError>` - Ok containing the new `LandlockSandbox` on success, or a `SandboxError` if Landlock is not available.
```

--------------------------------

### LandlockSandbox::new

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/struct.LandlockSandbox.html

Creates a new Landlock sandbox with the specified policy. This is the primary way to initialize a sandbox.

```APIDOC
## LandlockSandbox::new

### Description
Create a new Landlock sandbox with the given policy.

### Signature
`pub fn new(policy: SandboxPolicy) -> Result<Self, SandboxError>`

### Parameters
* `policy` (SandboxPolicy) - The policy to apply to the sandbox.

### Returns
* `Result<LandlockSandbox, SandboxError>` - Ok(LandlockSandbox) on success, Err(SandboxError) on failure.
```

--------------------------------

### SandboxPolicy Usage

Source: https://docs.rs/wardstone/0.1.0/index.html

Demonstrates how to create a SandboxPolicy, configure read/write permissions, and deny network access.

```APIDOC
## SandboxPolicy Usage

### Description
This example shows how to create a `SandboxPolicy` object, configure it with specific file system permissions (allowing read access to `/usr` and write access to the current directory), and explicitly deny all network access. This policy can then be used to initialize a `Sandbox`.

### Code
```rust
use wardstone::{Sandbox, SandboxPolicy};

let policy = SandboxPolicy::new()
    .allow_read("/usr")
    .allow_write("./")
    .deny_network();

let sandbox = Sandbox::new(policy)?;
let wrapped_cmd = sandbox.wrap_command(cmd);
```

### Parameters
- `allow_read(path)`: Allows read access to the specified path.
- `allow_write(path)`: Allows write access to the specified path.
- `deny_network()`: Denies all network access.
```

--------------------------------

### Test PathPermission Creation

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Demonstrates creating a new PathPermission with a specified path. The permission is recursive by default.

```rust
#[test]
fn test_path_permission_new() {
    let perm = PathPermission::new("/usr/lib");
    assert_eq!(perm.path, PathBuf::from("/usr/lib"));
    assert!(perm.recursive);
}
```

--------------------------------

### Create a Sandbox Policy and Sandbox

Source: https://docs.rs/wardstone/0.1.0/index.html

Defines a sandbox policy allowing read access to /usr, write access to the current directory, and denying network access. It then creates a sandbox instance with this policy and wraps a command to be executed within the sandbox.

```rust
use wardstone::{Sandbox, SandboxPolicy};

let policy = SandboxPolicy::new()
    .allow_read("/usr")
    .allow_write("./")
    .deny_network();

let sandbox = Sandbox::new(policy)?;
let wrapped_cmd = sandbox.wrap_command(cmd);
```

--------------------------------

### Create Platform-Specific Sandbox

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/lib.rs.html

Creates the appropriate sandbox implementation based on the current operating system (macOS, Linux, or Windows). Returns a `SandboxError` if no sandbox is available or implemented for the platform.

```rust
pub fn create_sandbox(policy: SandboxPolicy) -> Result<Box<dyn Sandbox>, SandboxError> {
    #[cfg(target_os = "macos")]
    {
        Ok(Box::new(seatbelt::SeatbeltSandbox::new(policy)?))
    }
    
    #[cfg(target_os = "linux")]
    {
        Ok(Box::new(landlock::LandlockSandbox::new(policy)?))
    }
    
    #[cfg(windows)]
    {
        // Windows sandbox not yet implemented
        Err(SandboxError::NotAvailable("Windows sandbox not implemented".into()))
    }
    
    #[cfg(not(any(target_os = "macos", target_os = "linux", windows)))]
    {
        Err(SandboxError::NotAvailable("No sandbox available for this platform".into()))
    }
}
```

--------------------------------

### SandboxPolicy::new()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Creates a new, empty SandboxPolicy.

```APIDOC
## fn new() -> Self

### Description
Create a new empty policy.
```

--------------------------------

### Test SandboxPolicy Spawn Permissions

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Demonstrates how to control the ability to spawn new processes within the sandbox. The default is false, but it can be explicitly enabled or disabled.

```rust
let policy = SandboxPolicy::new();
        assert!(!policy.allow_spawn);
```

```rust
let policy = SandboxPolicy::new().allow_spawn(true);
        assert!(policy.allow_spawn);
```

```rust
let policy = SandboxPolicy::new()
            .allow_spawn(true)
            .allow_spawn(false);
        assert!(!policy.allow_spawn);
```

--------------------------------

### Create Landlock Sandbox

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/landlock.rs.html

Creates a new Landlock sandbox instance. It checks for Landlock support on the current kernel before initialization.

```rust
pub fn new(policy: SandboxPolicy) -> Result<Self, SandboxError> {
        // Check if Landlock is supported
        if !Self::is_available() {
            return Err(SandboxError::NotAvailable(
                "Landlock not supported on this kernel".into()
            ));
        }
        
        debug!("Created Landlock sandbox");
        Ok(Self { policy })
    }
```

--------------------------------

### Test Default Policy for Tools

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Verifies the default policy generated by `default_for_tools` for a given project path, checking for basic read/write access, network restrictions, timeouts, and spawn permissions.

```rust
#[test]
fn test_default_for_tools() {
    let policy = SandboxPolicy::default_for_tools(PathBuf::from("/home/user/project"));
    
    assert!(!policy.read_paths.is_empty());
    assert!(!policy.write_paths.is_empty());
    assert_eq!(policy.network, NetworkPolicy::None);
    assert!(policy.timeout.is_some());
    assert!(policy.allow_spawn);
}
```

--------------------------------

### Test SandboxPolicy Initialization

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Verifies that a new SandboxPolicy is created with default empty or None values.

```rust
#[test]
fn test_policy_new() {
    let policy = SandboxPolicy::new();
    assert!(policy.read_paths.is_empty());
    assert!(policy.write_paths.is_empty());
    assert_eq!(policy.network, NetworkPolicy::None);
    assert!(!policy.allow_spawn);
}
```

--------------------------------

### Test Allow Full Network Policy

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Confirms that calling `allow_full_network()` correctly sets the network policy to `NetworkPolicy::Full`.

```rust
#[test]
fn test_allow_full_network() {
    let policy = SandboxPolicy::new().allow_full_network();
    assert_eq!(policy.network, NetworkPolicy::Full);
}
```

--------------------------------

### PathPermission Constructor Methods

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Provides methods to create PathPermission instances, defaulting to recursive inclusion or allowing explicit non-recursive settings.

```rust
impl PathPermission {
    pub fn new(path: impl Into<PathBuf>) -> Self {
        Self {
            path: path.into(),
            recursive: true,
        }
    }

    pub fn non_recursive(path: impl Into<PathBuf>) -> Self {
        Self {
            path: path.into(),
            recursive: false,
        }
    }
}
```

--------------------------------

### Test Default NetworkProtocol

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Verifies that the default NetworkProtocol is NetworkProtocol::Both.

```rust
#[test]
fn test_network_protocol_default() {
    let protocol: NetworkProtocol = Default::default();
    assert_eq!(protocol, NetworkProtocol::Both);
}
```

--------------------------------

### Test SandboxPolicy Builder Chaining

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Demonstrates chaining multiple builder methods to configure a policy, including path permissions, network settings, and timeouts.

```rust
#[test]
fn test_policy_builder() {
    let policy = SandboxPolicy::new()
        .allow_read("/usr")
        .allow_write("./src")
        .deny_network()
        .with_timeout(Duration::from_secs(60));

    assert_eq!(policy.read_paths.len(), 1);
    assert_eq!(policy.write_paths.len(), 1);
    assert_eq!(policy.network, NetworkPolicy::None);
    assert_eq!(policy.timeout, Some(Duration::from_secs(60)));
}
```

--------------------------------

### SandboxPolicy::allow_spawn()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures whether process spawning is allowed within the sandbox.

```APIDOC
## fn allow_spawn(self, allow: bool) -> Self

### Description
Allow process spawning.
```

--------------------------------

### Process Spawning Control

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Configure whether the sandboxed process is allowed to spawn new processes.

```APIDOC
## allow_spawn

### Description
Control whether the sandboxed process is allowed to spawn new processes.

### Method
`allow_spawn(allow: bool)`

### Endpoint
N/A (Method on Policy Builder)

### Parameters
- **allow** (bool) - Required - `true` to allow spawning, `false` to disallow.

### Request Example
```rust
SandboxPolicy::new().allow_spawn(true)
```

### Response
Returns the modified `SandboxPolicy` builder instance.
```

--------------------------------

### Test NetworkProtocol Serialization and Deserialization

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Tests the serialization and deserialization of various NetworkProtocol variants using serde_json.

```rust
#[test]
fn test_network_protocol_variants() {
    let protocols = vec![
        NetworkProtocol::Both,
        NetworkProtocol::Tcp,
        NetworkProtocol::Udp,
    ];
    
    for protocol in protocols {
        let json = serde_json::to_string(&protocol).unwrap();
        let parsed: NetworkProtocol = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, protocol);
    }
}
```

--------------------------------

### Test Non-Recursive PathPermission Creation

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Demonstrates creating a PathPermission that is not recursive.

```rust
#[test]
fn test_path_permission_non_recursive() {
    let perm = PathPermission::non_recursive("/etc/passwd");
    assert_eq!(perm.path, PathBuf::from("/etc/passwd"));
    assert!(!perm.recursive);
}
```

--------------------------------

### Test Allow Localhost Network Policy

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Confirms that calling `allow_localhost()` correctly sets the network policy to `NetworkPolicy::Localhost`.

```rust
#[test]
fn test_allow_localhost() {
    let policy = SandboxPolicy::new().allow_localhost();
    assert_eq!(policy.network, NetworkPolicy::Localhost);
}
```

--------------------------------

### Create new LandlockSandbox

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/struct.LandlockSandbox.html

Creates a new Landlock sandbox with a specified policy. Returns a Result which is Ok with the sandbox or Err with a SandboxError.

```rust
pub fn new(policy: SandboxPolicy) -> Result<Self, SandboxError>
```

--------------------------------

### Check Sandbox Availability

Source: https://docs.rs/wardstone/0.1.0/wardstone/fn.is_sandbox_available.html

Use this function to determine if the current operating system supports sandboxing. This is useful for security-sensitive applications.

```rust
pub fn is_sandbox_available() -> bool
```

--------------------------------

### Sandbox Trait Methods

Source: https://docs.rs/wardstone/0.1.0/wardstone/trait.Sandbox.html

This section details the methods available on the Sandbox trait.

```APIDOC
## fn wrap_command(&self, cmd: Command) -> Result<Command, SandboxError>

### Description
Wrap a command with sandbox restrictions

### Method
`wrap_command`

### Parameters
#### Path Parameters
- `cmd` (Command) - Required - The command to wrap.

#### Return Value
- `Result<Command, SandboxError>` - The wrapped command or an error if wrapping fails.
```

```APIDOC
## fn is_available() -> bool

### Description
Check if sandbox is available on this platform

### Method
`is_available`

### Parameters
None

#### Return Value
- `bool` - True if the sandbox is available, false otherwise.
```

```APIDOC
## fn sandbox_type(&self) -> &'static str

### Description
Get the sandbox type name

### Method
`sandbox_type`

### Parameters
None

#### Return Value
- `&'static str` - The name of the sandbox type.
```

--------------------------------

### Allow Execute Access from a Path

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the sandbox policy to permit executing files from a specified path. This method is chainable.

```rust
pub fn allow_exec(self, path: impl Into<PathBuf>) -> Self
```

--------------------------------

### is_sandbox_available

Source: https://docs.rs/wardstone/0.1.0/wardstone/fn.is_sandbox_available.html

Checks if sandboxing is available on the current platform. Returns a boolean value indicating availability.

```APIDOC
## Function is_sandbox_available

### Summary
```
pub fn is_sandbox_available() -> bool
```

### Description
Check if sandboxing is available on this platform
```

--------------------------------

### SandboxPolicy Builder Methods

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Provides builder-style methods to incrementally configure a SandboxPolicy, allowing specific paths to be read, written, or executed from, and to set the network policy.

```rust
impl SandboxPolicy {
    /// Allow reading a path
    pub fn allow_read(mut self, path: impl Into<PathBuf>) -> Self {
        self.read_paths.push(PathPermission::new(path));
        self
    }

    /// Allow writing a path
    pub fn allow_write(mut self, path: impl Into<PathBuf>) -> Self {
        self.write_paths.push(PathPermission::new(path));
        self
    }

    /// Allow executing from a path
    pub fn allow_exec(mut self, path: impl Into<PathBuf>) -> Self {
        self.exec_paths.push(PathPermission::new(path));
        self
    }

    /// Set network policy
    pub fn with_network(mut self, policy: NetworkPolicy) -> Self {
        self.network = policy;
        self
    }
}
```

--------------------------------

### Check Sandbox Availability

Source: https://docs.rs/wardstone/0.1.0/wardstone/trait.Sandbox.html

Implement this method to check if a sandbox implementation is available on the current platform. Requires the implementor to be Sized.

```rust
fn is_available() -> bool
       where Self: Sized;
```

--------------------------------

### SandboxPolicy::allow_exec()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the policy to allow execution from a specified path.

```APIDOC
## fn allow_exec(self, path: impl Into<PathBuf>) -> Self

### Description
Allow executing from a path.
```

--------------------------------

### Test Custom PolicyFlags

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Demonstrates setting custom boolean values for PolicyFlags.

```rust
#[test]
fn test_policy_flags_custom() {
    let flags = PolicyFlags {
        allow_system_read: true,
        allow_tmp: true,
        allow_home: false,
        allow_devices: false,
    };
    
    assert!(flags.allow_system_read);
    assert!(flags.allow_tmp);
    assert!(!flags.allow_home);
}
```

--------------------------------

### SandboxPolicy::allow_localhost()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the policy to allow network access to localhost.

```APIDOC
## fn allow_localhost(self) -> Self

### Description
Allow localhost network access.
```

--------------------------------

### Sandbox::is_available

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/landlock.rs.html

Checks if the Landlock feature is available on the current system.

```APIDOC
## Sandbox::is_available

### Description
Checks if the Landlock security feature is available on the current operating system. This typically involves checking kernel version and features.

### Signature
```rust
fn is_available() -> bool
```

### Returns
* `bool` - `true` if Landlock is available, `false` otherwise.
```

--------------------------------

### Sandbox::wrap_command

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/landlock.rs.html

Wraps a command to be executed within the Landlock sandbox. Currently, this is a passthrough due to incomplete implementation.

```APIDOC
## Sandbox::wrap_command

### Description
Wraps a given `std::process::Command` to be executed within the Landlock sandbox. In a full implementation, this would involve creating a Landlock ruleset, applying it in a child process, and then executing the target command. Currently, this method acts as a passthrough with a warning.

### Signature
```rust
fn wrap_command(&self, cmd: Command) -> Result<Command, SandboxError>
```

### Parameters
* **cmd** (`Command`) - The command to wrap.

### Returns
* `Result<Command, SandboxError>` - The (potentially modified) command, or an error if wrapping fails.
```

--------------------------------

### Create Default SandboxPolicy for Tools

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Generates a restrictive default SandboxPolicy suitable for agent tools, based on the current working directory.

```rust
pub fn default_for_tools(cwd: PathBuf) -> Self
```

--------------------------------

### Test NetworkRule Without Port

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Demonstrates creating a NetworkRule where the port is not specified (None).

```rust
#[test]
fn test_network_rule_no_port() {
    let rule = NetworkRule {
        host: "*.example.com".into(),
        port: None,
        protocol: NetworkProtocol::Both,
    };
    
    assert!(rule.port.is_none());
}
```

--------------------------------

### Test Default Policy Includes Current Working Directory

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Ensures that the `default_for_tools` policy includes read and write permissions for the current working directory.

```rust
#[test]
fn test_default_for_tools_includes_cwd() {
    let cwd = PathBuf::from("/my/project");
    let policy = SandboxPolicy::default_for_tools(cwd.clone());
    
    let has_cwd_read = policy.read_paths.iter().any(|p| p.path == cwd);
    let has_cwd_write = policy.write_paths.iter().any(|p| p.path == cwd);
    
    assert!(has_cwd_read, "Policy should allow reading cwd");
    assert!(has_cwd_write, "Policy should allow writing to cwd");
}
```

--------------------------------

### Network Policy Configuration

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Methods to configure the network access policy for the sandbox. This includes denying all access, allowing only localhost, or permitting full network connectivity.

```APIDOC
## deny_network

### Description
Deny all network access for the sandbox.

### Method
`deny_network()`

### Endpoint
N/A (Method on Policy Builder)

### Parameters
None

### Request Example
```rust
SandboxPolicy::new().deny_network()
```

### Response
Returns the modified `SandboxPolicy` builder instance.
```

```APIDOC
## allow_localhost

### Description
Allow only localhost network access for the sandbox.

### Method
`allow_localhost()`

### Endpoint
N/A (Method on Policy Builder)

### Parameters
None

### Request Example
```rust
SandboxPolicy::new().allow_localhost()
```

### Response
Returns the modified `SandboxPolicy` builder instance.
```

```APIDOC
## allow_full_network

### Description
Allow full network access for the sandbox.

### Method
`allow_full_network()`

### Endpoint
N/A (Method on Policy Builder)

### Parameters
None

### Request Example
```rust
SandboxPolicy::new().allow_full_network()
```

### Response
Returns the modified `SandboxPolicy` builder instance.
```

--------------------------------

### PartialEq Implementation for NetworkRule

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.NetworkRule.html

Defines equality comparison for NetworkRule instances.

```rust
fn eq(&self, other: &NetworkRule) -> bool
```

--------------------------------

### CloneToUninit Implementation for Generic Type T

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.PolicyFlags.html

Nightly-only experimental API for performing copy-assignment from self to uninitialized memory.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### SandboxPolicy::default_for_tools()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Creates a restrictive default SandboxPolicy suitable for agent tools, with the current working directory specified.

```APIDOC
## fn default_for_tools(cwd: PathBuf) -> Self

### Description
Create a restrictive default policy for agent tools.
```

--------------------------------

### Allow Read Access to a Path

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the sandbox policy to permit reading from a specified path. This method is chainable.

```rust
pub fn allow_read(self, path: impl Into<PathBuf>) -> Self
```

--------------------------------

### SandboxPolicy Builder Methods

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

These methods are used to configure various aspects of the SandboxPolicy. They can be chained together to build a complex policy.

```rust
/// Deny all network access
pub fn deny_network(mut self) -> Self {
    self.network = NetworkPolicy::None;
    self
}

/// Allow localhost network access
pub fn allow_localhost(mut self) -> Self {
    self.network = NetworkPolicy::Localhost;
    self
}

/// Allow full network access
pub fn allow_full_network(mut self) -> Self {
    self.network = NetworkPolicy::Full;
    self
}

/// Set execution timeout
pub fn with_timeout(mut self, timeout: Duration) -> Self {
    self.timeout = Some(timeout);
    self
}

/// Allow process spawning
pub fn allow_spawn(mut self, allow: bool) -> Self {
    self.allow_spawn = allow;
    self
}

/// Pass through environment variable
pub fn pass_env(mut self, var: impl Into<String>) -> Self {
    self.env_passthrough.push(var.into());
    self
}
```

--------------------------------

### SandboxPolicy::with_network()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Sets a specific network policy for the sandbox.

```APIDOC
## fn with_network(self, policy: NetworkPolicy) -> Self

### Description
Set network policy.
```

--------------------------------

### Clone Implementation for NetworkRule

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.NetworkRule.html

Provides functionality to create a duplicate of a NetworkRule instance.

```rust
fn clone(&self) -> NetworkRule
```

--------------------------------

### Allow Full Network Access

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the sandbox policy to permit unrestricted network access. This method is chainable.

```rust
pub fn allow_full_network(self) -> Self
```

--------------------------------

### Check Sandbox Availability

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/lib.rs.html

Checks if a sandbox implementation is available on the current platform. Returns `true` if a sandbox is supported and available, `false` otherwise.

```rust
pub fn is_sandbox_available() -> bool {
    #[cfg(target_os = "macos")]
    {
        seatbelt::SeatbeltSandbox::is_available()
    }
    
    #[cfg(target_os = "linux")]
    {
        landlock::LandlockSandbox::is_available()
    }
    
    #[cfg(not(any(target_os = "macos", target_os = "linux")))]
    {
        false
    }
}
```

--------------------------------

### Test SandboxPolicy Timeout

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Demonstrates setting a timeout for a SandboxPolicy.

```rust
#[test]
fn test_with_timeout() {
    let policy = SandboxPolicy::new()
        .with_timeout(Duration::from_secs(300));
    
}
```

--------------------------------

### Serialize Implementation for NetworkRule

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.NetworkRule.html

Enables serialization of a NetworkRule to a Serde serializer.

```rust
fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>
where __S: Serializer
```

--------------------------------

### SandboxPolicy::allow_full_network()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the policy to allow unrestricted network access.

```APIDOC
## fn allow_full_network(self) -> Self

### Description
Allow full network access.
```

--------------------------------

### Allow Write Access to a Path

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the sandbox policy to permit writing to a specified path. This method is chainable.

```rust
pub fn allow_write(self, path: impl Into<PathBuf>) -> Self
```

--------------------------------

### Test Deny Network Policy

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Confirms that calling `deny_network()` correctly sets the network policy to `NetworkPolicy::None`.

```rust
#[test]
fn test_deny_network() {
    let policy = SandboxPolicy::new().deny_network();
    assert_eq!(policy.network, NetworkPolicy::None);
}
```

--------------------------------

### Deny All Network Access

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the sandbox policy to deny all network access. This is a convenient shorthand for setting a restrictive network policy. This method is chainable.

```rust
pub fn deny_network(self) -> Self
```

--------------------------------

### Allow Localhost Network Access

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the sandbox policy to permit network access specifically to localhost. This method is chainable.

```rust
pub fn allow_localhost(self) -> Self
```

--------------------------------

### Test Default Policy Includes System Paths

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Checks if the `default_for_tools` policy grants read access to common system paths like /usr.

```rust
#[test]
fn test_default_for_tools_has_system_paths() {
    let policy = SandboxPolicy::default_for_tools(PathBuf::from("/project"));
    
    let has_usr = policy.read_paths.iter().any(|p| p.path == PathBuf::from("/usr"));
    assert!(has_usr, "Should have /usr read access");
}
```

--------------------------------

### LandlockSandbox::is_available

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/struct.LandlockSandbox.html

Checks if the Landlock sandbox feature is available on the current platform.

```APIDOC
## LandlockSandbox::is_available

### Description
Check if sandbox is available on this platform.

### Signature
`fn is_available() -> bool`

### Returns
* `bool` - `true` if Landlock sandbox is available, `false` otherwise.
```

--------------------------------

### Check LandlockSandbox availability

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/struct.LandlockSandbox.html

Determines if the Landlock sandbox feature is available on the current platform. Returns true if available, false otherwise.

```rust
fn is_available() -> bool
```

--------------------------------

### Implement Display for SandboxError

Source: https://docs.rs/wardstone/0.1.0/wardstone/error/enum.SandboxError.html

Provides a Display implementation for SandboxError, enabling user-friendly string representations of the errors.

```rust
impl Display for SandboxError {
    fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result
}
```

--------------------------------

### SandboxPolicy::allow_read()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the policy to allow reading from a specified path.

```APIDOC
## fn allow_read(self, path: impl Into<PathBuf>) -> Self

### Description
Allow reading a path.
```

--------------------------------

### SandboxPolicy Default Methods

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Provides methods to create a new empty policy or a restrictive default policy suitable for agent tools.

```rust
impl SandboxPolicy {
    /// Create a new empty policy
    pub fn new() -> Self {
        Self::default()
    }

    /// Create a restrictive default policy for agent tools
    pub fn default_for_tools(cwd: PathBuf) -> Self {
        Self {
            read_paths: vec![
                PathPermission::new(&cwd),
                PathPermission::new("/usr"),
                PathPermission::new("/lib"),
                PathPermission::new("/lib64"),
            ],
            write_paths: vec![
                PathPermission::new(&cwd),
            ],
            exec_paths: vec![
                PathPermission::new("/usr/bin"),
                PathPermission::new("/bin"),
                PathPermission::new("/usr/local/bin"),
            ],
            network: NetworkPolicy::None,
            timeout: Some(Duration::from_secs(120)),
            allow_spawn: true,
            env_passthrough: vec![
                "PATH".into(),
                "HOME".into(),
                "USER".into(),
                "SHELL".into(),
                "TERM".into(),
                "LANG".into(),
            ],
            flags: PolicyFlags {
                allow_system_read: true,
                allow_tmp: true,
                allow_home: false,
                allow_devices: false,
            },
        }
    }
}
```

--------------------------------

### SandboxPolicy::deny_network()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the policy to deny all network access.

```APIDOC
## fn deny_network(self) -> Self

### Description
Deny all network access.
```

--------------------------------

### Try convert from U to T

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/struct.LandlockSandbox.html

Performs the conversion from `U` to `T`. Returns a `Result` which is Ok with the converted value or Err if the conversion fails.

```rust
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
```

--------------------------------

### Deserialize Implementation for NetworkRule

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.NetworkRule.html

Enables deserialization of a NetworkRule from a Serde deserializer.

```rust
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>
```

--------------------------------

### Implement From<Error> for SandboxError

Source: https://docs.rs/wardstone/0.1.0/wardstone/error/enum.SandboxError.html

Allows conversion from a standard Error type into a SandboxError, simplifying error handling by automatically wrapping underlying I/O errors.

```rust
impl From<Error> for SandboxError {
    fn from(source: Error) -> Self
}
```

--------------------------------

### Try convert into U from T

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/struct.LandlockSandbox.html

Performs the conversion from `T` to `U`. Returns a `Result` which is Ok with the converted value or Err if the conversion fails.

```rust
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
```

--------------------------------

### Convert Into

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Calls `U::from(self)` to convert the SandboxPolicy into another type `U` that implements `From<SandboxPolicy>`.

```rust
fn into(self) -> U
where U: From<T>
```

--------------------------------

### Test Default NetworkPolicy

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Verifies that the default NetworkPolicy is NetworkPolicy::None.

```rust
#[test]
fn test_network_policy_default() {
    let policy: NetworkPolicy = Default::default();
    assert_eq!(policy, NetworkPolicy::None);
}
```

--------------------------------

### Test PathPermission Serialization

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Tests the serialization and deserialization of a PathPermission.

```rust
#[test]
fn test_path_permission_serialization() {
    let perm = PathPermission::new("/test/path");
    let json = serde_json::to_string(&perm).unwrap();
    let parsed: PathPermission = serde_json::from_str(&json).unwrap();
    
    assert_eq!(parsed.path, PathBuf::from("/test/path"));
    assert!(parsed.recursive);
}
```

--------------------------------

### Test NetworkPolicy Serialization and Deserialization

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Tests the serialization and deserialization of various NetworkPolicy variants using serde_json.

```rust
#[test]
fn test_network_policy_variants() {
    let policies = vec![
        NetworkPolicy::None,
        NetworkPolicy::Localhost,
        NetworkPolicy::Full,
        NetworkPolicy::Allowlist(vec![]),
    ];
    
    for policy in policies {
        let json = serde_json::to_string(&policy).unwrap();
        let parsed: NetworkPolicy = serde_json::from_str(&json).unwrap();
        assert_eq!(parsed, policy);
    }
}
```

--------------------------------

### Timeout Configuration

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Set a custom execution timeout for the sandboxed process.

```APIDOC
## with_timeout

### Description
Set the execution timeout for the sandboxed process.

### Method
`with_timeout(timeout: Duration)`

### Endpoint
N/A (Method on Policy Builder)

### Parameters
- **timeout** (Duration) - Required - The duration after which the sandbox execution will be terminated.

### Request Example
```rust
use std::time::Duration;
SandboxPolicy::new().with_timeout(Duration::from_secs(60))
```

### Response
Returns the modified `SandboxPolicy` builder instance.
```

--------------------------------

### Debug Implementation for PolicyFlags

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.PolicyFlags.html

Allows formatting PolicyFlags for debugging purposes.

```rust
fn fmt(&self, f: &mut Formatter<'_>) -> Result
```

--------------------------------

### Test Environment Passthrough

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Verifies that specified environment variables are correctly passed through to the sandbox environment.

```rust
let policy = SandboxPolicy::new()
            .pass_env("PATH")
            .pass_env("HOME")
            .pass_env("USER");
        
        assert_eq!(policy.env_passthrough.len(), 3);
        assert!(policy.env_passthrough.contains(&"PATH".to_string()));
```

--------------------------------

### LandlockSandbox::wrap_command

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/struct.LandlockSandbox.html

Wraps a given command with the restrictions defined by the Landlock sandbox policy.

```APIDOC
## LandlockSandbox::wrap_command

### Description
Wrap a command with sandbox restrictions.

### Signature
`fn wrap_command(&self, cmd: Command) -> Result<Command, SandboxError>`

### Parameters
* `&self` - A reference to the LandlockSandbox instance.
* `cmd` (Command) - The command to be wrapped.

### Returns
* `Result<Command, SandboxError>` - Ok(Command) with the wrapped command on success, Err(SandboxError) if wrapping fails.
```

--------------------------------

### Environment Variable Passthrough

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Specify environment variables that should be passed through to the sandboxed environment.

```APIDOC
## pass_env

### Description
Pass through a specific environment variable to the sandboxed process.

### Method
`pass_env(var: impl Into<String>)`

### Endpoint
N/A (Method on Policy Builder)

### Parameters
- **var** (impl Into<String>) - Required - The name of the environment variable to pass through.

### Request Example
```rust
SandboxPolicy::new().pass_env("PATH").pass_env("HOME")
```

### Response
Returns the modified `SandboxPolicy` builder instance.
```

--------------------------------

### Test Default PolicyFlags

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Verifies the default values for PolicyFlags, which are all false.

```rust
#[test]
fn test_policy_flags_default() {
    let flags: PolicyFlags = Default::default();
    assert!(!flags.allow_system_read);
    assert!(!flags.allow_tmp);
    assert!(!flags.allow_home);
    assert!(!flags.allow_devices);
}
```

--------------------------------

### Pass Through Environment Variable

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Specifies an environment variable to be passed through from the host to the sandbox. This method is chainable.

```rust
pub fn pass_env(self, var: impl Into<String>) -> Self
```

--------------------------------

### PathPermission Structure Definition

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Represents a permission for a specific file system path, with an option to include subdirectories.

```rust
pub struct PathPermission {
    /// The path
    pub path: PathBuf,
    /// Whether to include subdirectories
    pub recursive: bool,
}
```

--------------------------------

### Control Process Spawning

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Determines whether the sandbox is allowed to spawn new processes. This method is chainable.

```rust
pub fn allow_spawn(self, allow: bool) -> Self
```

--------------------------------

### apply_landlock_policy

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/fn.apply_landlock_policy.html

Applies Landlock restrictions to the current process. This function should be called after fork() but before exec().

```APIDOC
## apply_landlock_policy

### Description
Applies Landlock restrictions to the current process.
This should be called after fork() but before exec().

### Signature
```rust
pub fn apply_landlock_policy(policy: &SandboxPolicy) -> Result<(), SandboxError>
```

### Parameters
#### Path Parameters
- **policy** (*SandboxPolicy*) - Required - The Landlock policy to apply.

### Returns
- **Result<(), SandboxError>** - Ok(()) if the policy was applied successfully, or a SandboxError if an error occurred.
```

--------------------------------

### SandboxPolicy::allow_write()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the policy to allow writing to a specified path.

```APIDOC
## fn allow_write(self, path: impl Into<PathBuf>) -> Self

### Description
Allow writing a path.
```

--------------------------------

### Clone From SandboxPolicy

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Performs copy-assignment from a source SandboxPolicy into the current one.

```rust
fn clone_from(&mut self, source: &Self)
```

--------------------------------

### Set Network Policy

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Applies a specific NetworkPolicy to the sandbox. This method is chainable.

```rust
pub fn with_network(self, policy: NetworkPolicy) -> Self
```

--------------------------------

### Apply Landlock Policy to Current Process

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/landlock.rs.html

Applies Landlock restrictions to the current process. This function should be called after forking but before executing a new command. It configures read, write, and execute permissions based on the provided SandboxPolicy.

```rust
pub fn apply_landlock_policy(policy: &SandboxPolicy) -> Result<(), SandboxError> {
    use landlock::{
        Access,
        AccessFs,
        PathBeneath,
        PathFd,
        Ruleset,
        RulesetAttr,
        RulesetCreatedAttr,
        ABI,
    };
    
    // Create a ruleset with the appropriate ABI
    let abi = ABI::V3; // Use latest stable ABI
    
    let mut ruleset = Ruleset::default()
        .handle_access(AccessFs::from_all(abi))
        .map_err(|e| SandboxError::PolicyError(format!("Failed to create ruleset: {}", e)))?;
    
    let ruleset = ruleset.create()
        .map_err(|e| SandboxError::PolicyError(format!("Failed to create ruleset: {}", e)))?;
    
    // Add read rules
    for perm in &policy.read_paths {
        let path = &perm.path;
        if path.exists() {
            if let Ok(fd) = PathFd::new(path) {
                let access = AccessFs::ReadFile | AccessFs::ReadDir;
                let _ = ruleset.add_rule(PathBeneath::new(fd, access));
            }
        }
    }
    
    // Add write rules  
    for perm in &policy.write_paths {
        let path = &perm.path;
        if path.exists() {
            if let Ok(fd) = PathFd::new(path) {
                let access = AccessFs::WriteFile | AccessFs::RemoveFile |
                            AccessFs::RemoveDir | AccessFs::MakeDir;
                let _ = ruleset.add_rule(PathBeneath::new(fd, access));
            }
        }
    }
    
    // Add execute rules
    for perm in &policy.exec_paths {
        let path = &perm.path;
        if path.exists() {
            if let Ok(fd) = PathFd::new(path) {
                let access = AccessFs::Execute;
                let _ = ruleset.add_rule(PathBeneath::new(fd, access));
            }
        }
    }
    
    // Restrict the process
    ruleset.restrict_self()
        .map_err(|e| SandboxError::PolicyError(format!("Failed to restrict: {}", e)))?;
    
    info!("Applied Landlock restrictions");
    Ok(())
}
```

--------------------------------

### Wrap command with LandlockSandbox

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/struct.LandlockSandbox.html

Wraps a given command with the sandbox restrictions defined by the LandlockSandbox. Returns a Result which is Ok with the modified command or Err with a SandboxError.

```rust
fn wrap_command(&self, cmd: Command) -> Result<Command, SandboxError>
```

--------------------------------

### Sandbox::sandbox_type

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/landlock.rs.html

Returns the type of the sandbox implementation.

```APIDOC
## Sandbox::sandbox_type

### Description
Returns a static string identifying the type of sandbox implementation.

### Signature
```rust
fn sandbox_type(&self) -> &'static str
```

### Returns
* `&'static str` - The string "landlock".
```

--------------------------------

### Implement Debug for SandboxError

Source: https://docs.rs/wardstone/0.1.0/wardstone/error/enum.SandboxError.html

Provides a Debug implementation for SandboxError, allowing it to be formatted for debugging purposes.

```rust
impl Debug for SandboxError {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result
}
```

--------------------------------

### Check Landlock Sandbox Availability

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/landlock.rs.html

Use this function to determine if the Landlock sandbox feature is available on the system. The availability is system-dependent.

```rust
fn test_availability_check() {
        // This will depend on the system
        let _ = LandlockSandbox::is_available();
    }
```

--------------------------------

### Sandbox Trait

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/lib.rs.html

Defines the interface for platform-specific sandbox implementations, including wrapping commands and checking availability.

```APIDOC
/// Platform-specific sandbox implementation
pub trait Sandbox: Send + Sync {
    /// Wrap a command with sandbox restrictions
    fn wrap_command(&self, cmd: Command) -> Result<Command, SandboxError>;
    
    /// Check if sandbox is available on this platform
    fn is_available() -> bool where Self: Sized;
    
    /// Get the sandbox type name
    fn sandbox_type(&self) -> &'static str;
}
```

--------------------------------

### Define NetworkRule Struct

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.NetworkRule.html

Defines the structure for a network access rule, including host, optional port, and protocol.

```rust
pub struct NetworkRule {
    pub host: String,
    pub port: Option<u16>,
    pub protocol: NetworkProtocol,
}
```

--------------------------------

### SandboxPolicy::pass_env()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Configures the policy to pass through a specific environment variable to the sandbox.

```APIDOC
## fn pass_env(self, var: impl Into<String>) -> Self

### Description
Pass through environment variable.
```

--------------------------------

### SandboxPolicy::with_timeout()

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Sets the execution timeout for the sandbox.

```APIDOC
## fn with_timeout(self, timeout: Duration) -> Self

### Description
Set execution timeout.
```

--------------------------------

### PathPermission Struct Definition

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.PathPermission.html

Defines a permission for a specific file system path. Use this struct to specify a path and whether the permission should apply recursively to its subdirectories.

```rust
pub struct PathPermission {
    pub path: PathBuf,
    pub recursive: bool,
}
```

--------------------------------

### PathPermission Struct Definition

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.PathPermission.html

Defines a permission for a specific path, indicating whether it should be applied recursively.

```APIDOC
## Struct PathPermission

### Summary

```rust
pub struct PathPermission {
    pub path: PathBuf,
    pub recursive: bool,
}
```

### Description

Permission for a specific path

### Fields

* `path: PathBuf` - The path.
* `recursive: bool` - Whether to include subdirectories.

### Implementations

#### `fn new(path: impl Into<PathBuf>) -> Self`

Creates a new `PathPermission`.

#### `fn non_recursive(path: impl Into<PathBuf>) -> Self`

Creates a new `PathPermission` that is not recursive.
```

--------------------------------

### Clone Implementation for PolicyFlags

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.PolicyFlags.html

Enables creating a duplicate of a PolicyFlags value.

```rust
fn clone(&self) -> PolicyFlags
```

--------------------------------

### Test Comprehensive SandboxPolicy Builder Chaining

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Tests a more extensive chain of builder methods, including multiple path allowances, spawn control, environment variable passthrough, and timeouts.

```rust
#[test]
fn test_policy_builder_chaining() {
    let policy = SandboxPolicy::new()
        .allow_read("/usr")
        .allow_read("/lib")
        .allow_write("./src")
        .allow_write("./tests")
        .allow_exec("/usr/bin")
        .allow_spawn(true)
        .pass_env("PATH")
        .pass_env("HOME")
        .with_timeout(Duration::from_secs(120));

    assert_eq!(policy.read_paths.len(), 2);
    assert_eq!(policy.write_paths.len(), 2);
    assert_eq!(policy.exec_paths.len(), 1);
    assert!(policy.allow_spawn);
    assert_eq!(policy.env_passthrough.len(), 2);
}
```

--------------------------------

### apply_landlock_policy

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/index.html

Applies Landlock restrictions to the current process. This function is the primary interface for setting up a Landlock sandbox.

```APIDOC
## Function: apply_landlock_policy

### Description
Apply Landlock restrictions to the current process.

### Signature
```rust
fn apply_landlock_policy(policy: &LandlockPolicy) -> Result<(), LandlockError>
```

### Parameters
* `policy` (&LandlockPolicy): A reference to the LandlockPolicy struct defining the restrictions to apply.

### Returns
* `Result<(), LandlockError>`: Ok(()) if the policy was applied successfully, or a LandlockError if an error occurred.
```

--------------------------------

### Convert into U

Source: https://docs.rs/wardstone/0.1.0/wardstone/landlock/struct.LandlockSandbox.html

Calls `U::from(self)`. This conversion is determined by the specific `From<T> for U` implementation.

```rust
fn into(self) -> U
```

--------------------------------

### Test SandboxPolicy Serialization

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Tests the serialization and deserialization of a SandboxPolicy, including read/write paths and timeout.

```rust
#[test]
fn test_sandbox_policy_serialization() {
    let policy = SandboxPolicy::new()
        .allow_read("/usr")
        .allow_write("./src")
        .with_timeout(Duration::from_secs(60));
    
    let json = serde_json::to_string(&policy).unwrap();
    let parsed: SandboxPolicy = serde_json::from_str(&json).unwrap();
    
    assert_eq!(parsed.read_paths.len(), 1);
    assert_eq!(parsed.write_paths.len(), 1);
    assert_eq!(parsed.timeout, Some(Duration::from_secs(60)));
}
```

--------------------------------

### SandboxPolicy Struct Definition

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Defines the structure for sandbox policy configuration, including read, write, and execute paths, network policy, timeout, process spawning allowance, environment variable passthrough, and additional flags.

```APIDOC
## Struct SandboxPolicy

### Description
Sandbox policy configuration.

### Fields
- `read_paths`: Vec<PathPermission> - Paths with read access.
- `write_paths`: Vec<PathPermission> - Paths with write access.
- `exec_paths`: Vec<PathPermission> - Paths with execute access.
- `network`: NetworkPolicy - Network access policy.
- `timeout`: Option<Duration> - Execution timeout.
- `allow_spawn`: bool - Allow process spawning.
- `env_passthrough`: Vec<String> - Environment variables to pass through.
- `flags`: PolicyFlags - Additional policy flags.
```

--------------------------------

### NetworkRule Structure Definition

Source: https://docs.rs/wardstone/0.1.0/src/wardstone/policy.rs.html

Specifies a rule for network access, including host, port, and protocol.

```rust
pub struct NetworkRule {
    /// Host (IP or domain)
    pub host: String,
    /// Port (None = all ports)
    pub port: Option<u16>,
    /// Protocol (tcp, udp, or both)
    pub protocol: NetworkProtocol,
}
```

--------------------------------

### TryFrom<U> for T

Source: https://docs.rs/wardstone/0.1.0/wardstone/policy/struct.SandboxPolicy.html

Implementation of `TryFrom` trait for converting between types where `U` can be converted into `T`.

```APIDOC
## impl<T, U> TryFrom<U> for T
where U: Into<T>

### Associated Types
#### type Error = Infallible
The type returned in the event of a conversion error.

### Methods
#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
Performs the conversion.
```
Tokens:
Raw