File sandbox.h¶
Go to the documentation of this file
/*
* cais - Communication Abstraction & I/O Substrate
* Projectum Lunare <https://github.com/projectum-lunare/cais>
* Copyright (C) 2026 Gustavo Veiga <gustavo.veiga@outlook.com.br>
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at https://mozilla.org/MPL/2.0/.
*/
#ifndef CAIS_SANDBOX_H
#define CAIS_SANDBOX_H
#include <cais/types.h>
#include <stddef.h>
/*
* =============================================================================
* Sandbox Backend Identifiers
* =============================================================================
*/
typedef enum {
CAIS_SANDBOX_BACKEND_NONE = 0,
CAIS_SANDBOX_BACKEND_LANDLOCK = 1, /* Linux Landlock LSM */
CAIS_SANDBOX_BACKEND_OPENBSD = 2, /* OpenBSD pledge & unveil */
CAIS_SANDBOX_BACKEND_CAPSICUM = 3, /* FreeBSD Capsicum capability mode */
CAIS_SANDBOX_BACKEND_SEATBELT = 4, /* Apple Darwin / macOS Seatbelt (sandbox_init) */
CAIS_SANDBOX_BACKEND_WIN32 = 5 /* Windows NT Process Mitigations & Token Lockdown */
} cais_sandbox_backend_t;
/*
* =============================================================================
* Filesystem Permission Flags for Allowed Paths
* =============================================================================
*/
typedef enum {
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_perm_t;
#define CAIS_SANDBOX_READ CAIS_SANDBOX_PERM_READ
#define CAIS_SANDBOX_WRITE CAIS_SANDBOX_PERM_WRITE
#define CAIS_SANDBOX_EXEC CAIS_SANDBOX_PERM_EXEC
/*
* =============================================================================
* Network Access Policy Level
* =============================================================================
*/
typedef enum {
CAIS_SANDBOX_NET_DEFAULT = 0, /* Unmodified / allow network */
CAIS_SANDBOX_NET_NONE = 1, /* Completely deny socket & network operations */
CAIS_SANDBOX_NET_LOOPBACK = 2, /* Allow only local loopback communication */
CAIS_SANDBOX_NET_ALL = 3 /* Explicitly allow all network access */
} cais_sandbox_net_t;
/*
* Opaque declaration of the declarative sandbox policy handle.
*/
typedef struct cais_sandbox_policy cais_sandbox_policy_t;
#ifdef __cplusplus
extern "C" {
#endif
/*
* =============================================================================
* Introspection & Platform Capability
* =============================================================================
*/
cais_sandbox_backend_t cais_sandbox_backend(int *version_out);
const char *cais_sandbox_backend_name(int *version_out);
cais_bool_t cais_sandbox_is_supported(void);
/*
* =============================================================================
* Declarative Policy Lifecycle & Configuration
* =============================================================================
*/
cais_sandbox_policy_t *cais_sandbox_policy_create(void);
void cais_sandbox_policy_destroy(cais_sandbox_policy_t *policy);
cais_status_t cais_sandbox_policy_allow_path(cais_sandbox_policy_t *policy, const char *path, int perms);
cais_status_t cais_sandbox_policy_set_network(cais_sandbox_policy_t *policy, cais_sandbox_net_t net);
cais_status_t cais_sandbox_policy_set_allow_child_processes(cais_sandbox_policy_t *policy, cais_bool_t allow);
cais_status_t cais_sandbox_policy_set_allow_dynamic_code(cais_sandbox_policy_t *policy, cais_bool_t allow);
/*
* =============================================================================
* Enforcement
* =============================================================================
*/
cais_sandbox_status_t cais_sandbox_apply(const cais_sandbox_policy_t *policy, char *err_buf, size_t err_cap);
#ifdef __cplusplus
}
#endif
#endif /* CAIS_SANDBOX_H */