Skip to content

File sandbox.h

Headers > cais > sandbox.h

Go to the source code of this file

  • #include <cais/types.h>
  • #include <stddef.h>

Types

Type Name
enum cais_sandbox_backend_t
enum cais_sandbox_net_t
enum cais_sandbox_perm_t
typedef struct cais_sandbox_policy cais_sandbox_policy_t

Functions

Type Name
cais_sandbox_status_t cais_sandbox_apply (const cais_sandbox_policy_t * policy, char * err_buf, size_t err_cap)
Irrevocably enforces the sandbox policy on the current process and descendants.
cais_sandbox_backend_t cais_sandbox_backend (int * version_out)
Returns the active sandboxing backend type enum.
const char * cais_sandbox_backend_name (int * version_out)
Returns the descriptive name of the active sandboxing backend: "landlock", "seatbelt", "win32", "openbsd", "capsicum", or "none".
cais_bool_t cais_sandbox_is_supported (void)
Checks whether kernel sandboxing is supported on the running platform.
cais_status_t cais_sandbox_policy_allow_path (cais_sandbox_policy_t * policy, const char * path, int perms)
Adds a filesystem path rule to the policy.
cais_sandbox_policy_t * cais_sandbox_policy_create (void)
Allocates and initializes a new empty declarative sandbox policy.
void cais_sandbox_policy_destroy (cais_sandbox_policy_t * policy)
Releases all resources associated with a sandbox policy handle.
cais_status_t cais_sandbox_policy_set_allow_child_processes (cais_sandbox_policy_t * policy, cais_bool_t allow)
Configures whether creating child processes (fork/exec/CreateProcess) is allowed.
cais_status_t cais_sandbox_policy_set_allow_dynamic_code (cais_sandbox_policy_t * policy, cais_bool_t allow)
Configures whether dynamic code generation (W^X / RWX executable memory) is allowed.
cais_status_t cais_sandbox_policy_set_network (cais_sandbox_policy_t * policy, cais_sandbox_net_t net)
Configures network access policy.

Macros

Type Name
define CAIS_SANDBOX_EXEC CAIS\_SANDBOX\_PERM\_EXEC
define CAIS_SANDBOX_READ CAIS\_SANDBOX\_PERM\_READ
define CAIS_SANDBOX_WRITE CAIS\_SANDBOX\_PERM\_WRITE

Type Details

enum cais_sandbox_backend_t

enum cais_sandbox_backend_t {
    CAIS_SANDBOX_BACKEND_NONE = 0,
    CAIS_SANDBOX_BACKEND_LANDLOCK = 1,
    CAIS_SANDBOX_BACKEND_OPENBSD = 2,
    CAIS_SANDBOX_BACKEND_CAPSICUM = 3,
    CAIS_SANDBOX_BACKEND_SEATBELT = 4,
    CAIS_SANDBOX_BACKEND_WIN32 = 5
};

enum cais_sandbox_net_t

enum cais_sandbox_net_t {
    CAIS_SANDBOX_NET_DEFAULT = 0,
    CAIS_SANDBOX_NET_NONE = 1,
    CAIS_SANDBOX_NET_LOOPBACK = 2,
    CAIS_SANDBOX_NET_ALL = 3
};

enum cais_sandbox_perm_t

enum cais_sandbox_perm_t {
    CAIS_SANDBOX_PERM_NONE = 0,
    CAIS_SANDBOX_PERM_READ = (1 << 0),
    CAIS_SANDBOX_PERM_WRITE = (1 << 1),
    CAIS_SANDBOX_PERM_EXEC = (1 << 2)
};

cais_sandbox_policy_t

typedef struct cais_sandbox_policy cais_sandbox_policy_t;

Function Details

cais_sandbox_apply

Irrevocably enforces the sandbox policy on the current process and descendants.

cais_sandbox_status_t cais_sandbox_apply (
    const cais_sandbox_policy_t * policy,
    char * err_buf,
    size_t err_cap
) 

If policy is NULL, enforces a strict default lockdown (no filesystem access, dropping privileges where supported by the operating system).

Parameters:

  • policy The policy configuration to enforce (or NULL for complete lockdown).
  • err_buf Buffer to receive human-readable error description on failure.
  • err_cap Capacity of err_buf in bytes.

Returns:

CAIS_SANDBOX_OK on success, CAIS_SANDBOX_UNSUPPORTED if sandboxing is not supported on this platform, or CAIS_SANDBOX_ERROR on failure.


cais_sandbox_backend

Returns the active sandboxing backend type enum.

cais_sandbox_backend_t cais_sandbox_backend (
    int * version_out
) 

Parameters:

  • version_out Optional pointer to store backend ABI or OS version.

cais_sandbox_backend_name

Returns the descriptive name of the active sandboxing backend: "landlock", "seatbelt", "win32", "openbsd", "capsicum", or "none".

const char * cais_sandbox_backend_name (
    int * version_out
) 

Parameters:

  • version_out Optional pointer to store backend ABI or OS version.

cais_sandbox_is_supported

Checks whether kernel sandboxing is supported on the running platform.

cais_bool_t cais_sandbox_is_supported (
    void
) 

Returns:

CAIS_TRUE if a functional sandbox backend is available, CAIS_FALSE otherwise.


cais_sandbox_policy_allow_path

Adds a filesystem path rule to the policy.

cais_status_t cais_sandbox_policy_allow_path (
    cais_sandbox_policy_t * policy,
    const char * path,
    int perms
) 

Parameters:

  • policy Active policy handle.
  • path Filesystem path (directory or file) to allow.
  • perms Bitmask combination of CAIS_SANDBOX_PERM_READ, WRITE, EXEC.

Returns:

CAIS_OK on success, or CAIS_ERROR on invalid argument/allocation failure.


cais_sandbox_policy_create

Allocates and initializes a new empty declarative sandbox policy.

cais_sandbox_policy_t * cais_sandbox_policy_create (
    void
) 

Returns:

Pointer to new policy handle, or NULL on memory allocation failure.


cais_sandbox_policy_destroy

Releases all resources associated with a sandbox policy handle.

void cais_sandbox_policy_destroy (
    cais_sandbox_policy_t * policy
) 

Parameters:

  • policy Policy handle to destroy (safe to pass NULL).

cais_sandbox_policy_set_allow_child_processes

Configures whether creating child processes (fork/exec/CreateProcess) is allowed.

cais_status_t cais_sandbox_policy_set_allow_child_processes (
    cais_sandbox_policy_t * policy,
    cais_bool_t allow
) 

Parameters:

  • policy Active policy handle.
  • allow CAIS_TRUE to allow child processes, CAIS_FALSE to prohibit.

Returns:

CAIS_OK on success.


cais_sandbox_policy_set_allow_dynamic_code

Configures whether dynamic code generation (W^X / RWX executable memory) is allowed.

cais_status_t cais_sandbox_policy_set_allow_dynamic_code (
    cais_sandbox_policy_t * policy,
    cais_bool_t allow
) 

Parameters:

  • policy Active policy handle.
  • allow CAIS_TRUE to allow, CAIS_FALSE to prohibit (W^X memory hardening).

Returns:

CAIS_OK on success.


cais_sandbox_policy_set_network

Configures network access policy.

cais_status_t cais_sandbox_policy_set_network (
    cais_sandbox_policy_t * policy,
    cais_sandbox_net_t net
) 

Parameters:

  • policy Active policy handle.
  • net Network access level (CAIS_SANDBOX_NET_DEFAULT, NONE, LOOPBACK, ALL).

Returns:

CAIS_OK on success.


Macro Details

CAIS_SANDBOX_EXEC

#define CAIS_SANDBOX_EXEC `CAIS_SANDBOX_PERM_EXEC`

CAIS_SANDBOX_READ

#define CAIS_SANDBOX_READ `CAIS_SANDBOX_PERM_READ`

CAIS_SANDBOX_WRITE

#define CAIS_SANDBOX_WRITE `CAIS_SANDBOX_PERM_WRITE`


The documentation was generated from the following file: include/cais/sandbox.h