PQS command execution sandbox configuration helpers. More...

#include "pqscommon.h"

Data Structures
struct	pqs_sandbox_profile
	The PQS command execution sandbox profile. More...

Macros
#define	PQS_SANDBOX_DEFAULT_TIMEOUT_SECONDS 120U
	The default maximum runtime for a command executed by the PQS server.
#define	PQS_SANDBOX_MIN_TIMEOUT_SECONDS 5U
	The minimum accepted non-zero command timeout.
#define	PQS_SANDBOX_MAX_TIMEOUT_SECONDS 3600U
	The maximum accepted command timeout.
#define	PQS_SANDBOX_DEFAULT_OUTPUT_BYTES 1048576U
	The default maximum number of command-output bytes returned for one command.
#define	PQS_SANDBOX_MIN_OUTPUT_BYTES 4096U
	The minimum accepted non-zero command-output byte limit.
#define	PQS_SANDBOX_MAX_OUTPUT_BYTES 16777216U
	The maximum accepted command-output byte limit.

Typedefs
typedef PQS_EXPORT_API struct pqs_sandbox_profile	pqs_sandbox_profile
	The PQS command execution sandbox profile.

Functions
PQS_EXPORT_API void	pqs_sandbox_profile_defaults (pqs_sandbox_profile *profile)
	Initialize a sandbox profile with safe defaults.
PQS_EXPORT_API void	pqs_sandbox_profile_configure (pqs_sandbox_profile profile, bool enabled, bool clear_environment, uint32_t timeout_seconds, const char working_directory)
	Configure a sandbox profile.
PQS_EXPORT_API void	pqs_sandbox_profile_configure_security (pqs_sandbox_profile profile, bool enabled, bool clear_environment, uint32_t timeout_seconds, const char working_directory, const char run_as_user, const char run_as_group, bool chroot_enabled)
	Configure a sandbox profile with platform privilege-separation fields.
PQS_EXPORT_API bool	pqs_sandbox_profile_canonicalize_working_directory (pqs_sandbox_profile *profile)
	Canonicalize the configured sandbox working directory in place.
PQS_EXPORT_API void	pqs_sandbox_profile_set_allow_same_user (pqs_sandbox_profile *profile, bool allow_same_user)
	Set the same-user execution override for a sandbox profile.
PQS_EXPORT_API void	pqs_sandbox_profile_set_output_limit (pqs_sandbox_profile *profile, uint32_t max_output_bytes)
	Set the maximum command-output byte count for a sandbox profile.
PQS_EXPORT_API bool	pqs_sandbox_working_directory_valid (const pqs_sandbox_profile *profile)
	Test whether a sandbox profile has a usable working directory.
PQS_EXPORT_API uint32_t	pqs_sandbox_timeout_milliseconds (const pqs_sandbox_profile *profile)
	Get the command timeout in milliseconds.
PQS_EXPORT_API uint32_t	pqs_sandbox_output_limit_bytes (const pqs_sandbox_profile *profile)
	Get the configured command-output byte limit.

Detailed Description

PQS command execution sandbox configuration helpers.

Function Documentation

◆ pqs_sandbox_output_limit_bytes()

PQS_EXPORT_API uint32_t pqs_sandbox_output_limit_bytes ( const pqs_sandbox_profile * profile )

Get the configured command-output byte limit.

Parameters

profile [const struct] The sandbox profile.

Returns: [uint32_t] Returns the output byte limit, or zero if disabled.

◆ pqs_sandbox_profile_canonicalize_working_directory()

PQS_EXPORT_API bool pqs_sandbox_profile_canonicalize_working_directory ( pqs_sandbox_profile * profile )

Canonicalize the configured sandbox working directory in place.

Parameters

profile [struct] The sandbox profile.

Returns: [bool] Returns true if the configured working directory exists and was canonicalized.

◆ pqs_sandbox_profile_configure()

PQS_EXPORT_API void pqs_sandbox_profile_configure	(	pqs_sandbox_profile *	profile,
		bool	enabled,
		bool	clear_environment,
		uint32_t	timeout_seconds,
		const char *	working_directory )

Configure a sandbox profile.

Parameters

profile	[struct] The sandbox profile.
enabled	[bool] Enables sandbox controls.
clear_environment	[bool] Enables minimal environment execution.
timeout_seconds	[uint32_t] The command timeout in seconds.
working_directory	[const] The confined working directory.

◆ pqs_sandbox_profile_configure_security()

PQS_EXPORT_API void pqs_sandbox_profile_configure_security	(	pqs_sandbox_profile *	profile,
		bool	enabled,
		bool	clear_environment,
		uint32_t	timeout_seconds,
		const char *	working_directory,
		const char *	run_as_user,
		const char *	run_as_group,
		bool	chroot_enabled )

Configure a sandbox profile with platform privilege-separation fields.

Parameters

profile	[struct] The sandbox profile.
enabled	[bool] Enables sandbox controls.
clear_environment	[bool] Enables minimal environment execution.
timeout_seconds	[uint32_t] The command timeout in seconds.
working_directory	[const] The confined working directory.
run_as_user	[const] The POSIX user name used for privilege drop, or NULL/empty.
run_as_group	[const] The POSIX group name used for privilege drop, or NULL/empty.
chroot_enabled	[bool] Enables POSIX chroot confinement when the server has the required privilege.

◆ pqs_sandbox_profile_defaults()

PQS_EXPORT_API void pqs_sandbox_profile_defaults ( pqs_sandbox_profile * profile )

Initialize a sandbox profile with safe defaults.

Parameters

profile [struct] The sandbox profile to initialize.

◆ pqs_sandbox_profile_set_allow_same_user()

PQS_EXPORT_API void pqs_sandbox_profile_set_allow_same_user	(	pqs_sandbox_profile *	profile,
		bool	allow_same_user )

Set the same-user execution override for a sandbox profile.

When disabled, POSIX command execution requires an explicit run-as identity. This prevents unconfined same-user command execution from being enabled accidentally. The override may be enabled for development or deliberately single-user deployments.

Parameters

profile	[struct] The sandbox profile.
allow_same_user	[bool] Enables execution as the server process user when no run-as identity is configured.

◆ pqs_sandbox_profile_set_output_limit()

PQS_EXPORT_API void pqs_sandbox_profile_set_output_limit	(	pqs_sandbox_profile *	profile,
		uint32_t	max_output_bytes )

Set the maximum command-output byte count for a sandbox profile.

Parameters

profile	[struct] The sandbox profile.
max_output_bytes	[uint32_t] The maximum command-output byte count.

◆ pqs_sandbox_timeout_milliseconds()

PQS_EXPORT_API uint32_t pqs_sandbox_timeout_milliseconds ( const pqs_sandbox_profile * profile )

Get the command timeout in milliseconds.

Parameters

profile [const struct] The sandbox profile.

Returns: [uint32_t] Returns the timeout in milliseconds, or zero if disabled.

◆ pqs_sandbox_working_directory_valid()

PQS_EXPORT_API bool pqs_sandbox_working_directory_valid ( const pqs_sandbox_profile * profile )

Test whether a sandbox profile has a usable working directory.

Parameters

profile [const struct] The sandbox profile.

Returns: [bool] Returns true if the disabled profile needs no directory, or if the enabled profile has an existing canonicalizable directory.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Function Documentation

◆ pqs_sandbox_output_limit_bytes()

◆ pqs_sandbox_profile_canonicalize_working_directory()

◆ pqs_sandbox_profile_configure()

◆ pqs_sandbox_profile_configure_security()

◆ pqs_sandbox_profile_defaults()

◆ pqs_sandbox_profile_set_allow_same_user()

◆ pqs_sandbox_profile_set_output_limit()

◆ pqs_sandbox_timeout_milliseconds()

◆ pqs_sandbox_working_directory_valid()