QoreSandboxManager Class Reference

Unified sandbox manager combining filesystem, network, and resource controls. More...

#include <QoreSandboxManager.h>

Inheritance diagram for QoreSandboxManager:

Collaboration diagram for QoreSandboxManager:

Public Types
typedef std::function< bool()>	cancel_callback_t
	Cancel callback function type.

Public Member Methods
DLLEXPORT	QoreSandboxManager ()
	Creates a new sandbox manager with default settings.
virtual DLLEXPORT	~QoreSandboxManager ()
	Destroys the sandbox manager.
DLLEXPORT bool	checkFilesystemAccess (const char *path, int mode, ExceptionSink *xsink)
	Checks if filesystem access is allowed.
DLLEXPORT bool	checkIOInterrupt (ExceptionSink *xsink, const char *operation="I/O operation") const
	Checks if interrupt has been requested and raises exception if so.
DLLEXPORT bool	checkNetworkAccess (const hashdecl sockaddr *addr, socklen_t len, int proto, ExceptionSink *xsink)
	Checks if network access is allowed.
DLLEXPORT void	clearInterrupt ()
	Clears the interrupt request.
DLLEXPORT QoreSandboxManager *	copy () const
	Creates a copy with the same or stricter restrictions.
DLLEXPORT QoreFilesystemSecurityManager &	filesystem ()
	Gets the filesystem security manager.
DLLEXPORT const QoreFilesystemSecurityManager &	filesystem () const
	Gets the filesystem security manager (const version)
DLLEXPORT QoreHashNode *	getConfiguration (ExceptionSink *xsink) const
	Returns the full configuration as a hash.
DLLEXPORT int64	getCPUTimeLimit () const
	Gets the CPU time limit.
DLLEXPORT int	getMaxRecursionDepth () const
	Gets the max recursion depth.
DLLEXPORT int	getMaxThreads () const
	Gets the max threads limit.
DLLEXPORT size_t	getMemoryLimit () const
	Gets the memory limit.
DLLEXPORT int64	getWallTimeLimit () const
	Gets the wall time limit.
DLLEXPORT bool	isInterruptRequested () const
	Checks if interrupt has been requested.
DLLEXPORT QoreNetworkSecurityManager &	network ()
	Gets the network security manager.
DLLEXPORT const QoreNetworkSecurityManager &	network () const
	Gets the network security manager (const version)
DLLEXPORT void	registerCancelCallback (void *context, cancel_callback_t callback)
	Registers a cancel callback for interruptible operations.
DLLEXPORT void	requestInterrupt ()
	Requests graceful interruption of sandboxed code.
DLLEXPORT void	setCPUTimeLimit (int64 ms)
	Sets maximum CPU time in milliseconds.
DLLEXPORT void	setMaxRecursionDepth (int depth)
	Sets maximum recursion depth.
DLLEXPORT void	setMaxThreads (int count)
	Sets maximum number of threads.
DLLEXPORT void	setMemoryLimit (size_t bytes)
	Sets maximum memory usage in bytes.
DLLEXPORT void	setWallTimeLimit (int64 ms)
	Sets maximum wall clock time in milliseconds.
DLLEXPORT void	unregisterCancelCallback (void *context)
	Unregisters a cancel callback.
Public Member Methods inherited from AbstractPrivateData
virtual DLLLOCAL void	deref ()
	decrements the reference count of the object without the possibility of throwing a Qore-language exception
virtual DLLLOCAL void	deref (ExceptionSink *xsink)
	decrements the reference count of the object
DLLLOCAL void	ref () const
	increments the reference count of the object
Public Member Methods inherited from QoreReferenceCounter
DLLEXPORT	QoreReferenceCounter ()
	Creates the reference counter object.
DLLEXPORT	QoreReferenceCounter (const QoreReferenceCounter &old)
	Creates a new object with a reference count of 1.
DLLEXPORT	~QoreReferenceCounter ()
	destroys the reference counter object
DLLEXPORT bool	is_unique () const
	Returns true if the reference count is 1.
DLLEXPORT bool	optRef ()
	Make a strong reference only if the object is valid.
DLLEXPORT int	reference_count () const
	Gets the reference count.
DLLEXPORT bool	ROdereference () const
	Atomically decrements the reference count.
DLLEXPORT void	ROreference () const
	Atomically increments the reference count.

Static Public Member Methods
static DLLEXPORT QoreSandboxManager *	createLockdown ()
	Creates a preset for maximum restrictions ("lockdown" mode)
static DLLEXPORT QoreSandboxManager *	createWebSafe ()
	Creates a preset safe for web application sandboxing.

Additional Inherited Members
Private Member Methods inherited from AbstractPrivateData
virtual DLLLOCAL	~AbstractPrivateData ()
	as these objects are reference counted, the destructor should be called only when the reference count = 0 and not manually

Detailed Description

Unified sandbox manager combining filesystem, network, and resource controls.

The QoreSandboxManager class provides a unified interface for all sandboxing features including:

• Filesystem access control via QoreFilesystemSecurityManager
• Network access control via QoreNetworkSecurityManager
• Resource limits (memory, CPU time, wall time, threads)
• Safe interruption of sandboxed code

Example:

QoreSandboxManager sm;
sm.filesystem().setSandboxRoot("/sandbox", xsink);
sm.network().blockPrivateNetworks();
sm.setMemoryLimit(100 * 1024 * 1024);  // 100MB
sm.setWallTimeLimit(30000);            // 30 seconds
 
QoreProgram* pgm = new QoreProgram(PO_NEW_STYLE);
pgm->setSandboxManager(&sm);

Since

Qore 2.1

Member Typedef Documentation

cancel_callback_t

typedef std::function<bool()> QoreSandboxManager::cancel_callback_t

Cancel callback function type.

Cancel callbacks are called when requestInterrupt() is invoked. They should attempt to cancel any ongoing blocking operation.

Returns

true if a cancel was attempted, false otherwise

Member Function Documentation

checkFilesystemAccess()

DLLEXPORT bool QoreSandboxManager::checkFilesystemAccess	(	const char *	path,
		int	mode,
		ExceptionSink *	xsink
	)

Checks if filesystem access is allowed.

Parameters

path	The path to check
mode	The access mode (QSEC_READ, QSEC_WRITE, etc.)
xsink	Exception sink for error reporting

Returns

true if access is allowed, false if denied (exception raised)

checkIOInterrupt()

DLLEXPORT bool QoreSandboxManager::checkIOInterrupt	(	ExceptionSink *	xsink,
		const char *	operation = "I/O operation"
	)		const

Checks if interrupt has been requested and raises exception if so.

This is a convenience method for I/O operations that need to check for interrupts and raise an exception if interrupted.

Parameters

xsink	Exception sink for error reporting
operation	Description of the operation being interrupted (e.g., "reading file")

Returns

true if interrupted (exception raised), false otherwise

Referenced by StderrOutputStream::write(), and StdoutOutputStream::write().

checkNetworkAccess()

DLLEXPORT bool QoreSandboxManager::checkNetworkAccess	(	const hashdecl sockaddr *	addr,
		socklen_t	len,
		int	proto,
		ExceptionSink *	xsink
	)

Checks if network access is allowed.

Parameters

addr	The address to check
len	Length of the address structure
proto	Protocol (QSEC_NET_TCP, QSEC_NET_UDP, etc.)
xsink	Exception sink for error reporting

Returns

true if access is allowed, false if denied (exception raised)

copy()

DLLEXPORT QoreSandboxManager * QoreSandboxManager::copy

(

)

const

Creates a copy with the same or stricter restrictions.

Returns

A new QoreSandboxManager with the same configuration

Note

Used when creating child programs. Children can only make restrictions stricter, never looser.

createLockdown()

static DLLEXPORT QoreSandboxManager * QoreSandboxManager::createLockdown ( )

static

Creates a preset for maximum restrictions ("lockdown" mode)

Returns

A new QoreSandboxManager configured for maximum security

Lockdown mode:

• No filesystem access (empty allow list)
• No network access (empty allow list)
• Memory limit: 10MB
• CPU time limit: 1000ms
• Wall time limit: 5000ms
• Max threads: 1
• Max recursion: 100

createWebSafe()

static DLLEXPORT QoreSandboxManager * QoreSandboxManager::createWebSafe ( )

static

Creates a preset safe for web application sandboxing.

Returns

A new QoreSandboxManager with web-safe defaults

Web-safe mode:

• No filesystem access
• Network allowed but private networks blocked
• Memory limit: 100MB
• CPU time limit: 10000ms
• Wall time limit: 30000ms
• Max threads: 4
• Max recursion: 200

filesystem()

DLLEXPORT QoreFilesystemSecurityManager & QoreSandboxManager::filesystem

(

)

Gets the filesystem security manager.

Returns

Reference to the filesystem security manager

getConfiguration()

DLLEXPORT QoreHashNode * QoreSandboxManager::getConfiguration

(

ExceptionSink *

xsink

)

const

Returns the full configuration as a hash.

Returns

A hash containing all sandbox configuration including filesystem, network, and resource limit settings

isInterruptRequested()

DLLEXPORT bool QoreSandboxManager::isInterruptRequested

(

)

const

Checks if interrupt has been requested.

Returns

true if an interrupt has been requested

network()

DLLEXPORT QoreNetworkSecurityManager & QoreSandboxManager::network

(

)

Gets the network security manager.

Returns

Reference to the network security manager

registerCancelCallback()

DLLEXPORT void QoreSandboxManager::registerCancelCallback	(	void *	context,
		cancel_callback_t	callback
	)

Registers a cancel callback for interruptible operations.

Call this before starting a blocking operation that should be cancellable. The callback will be invoked when requestInterrupt() is called.

Parameters

context	Unique context pointer (used to unregister)
callback	The callback function to invoke on interrupt

Note

Thread-safe. The callback may be invoked from any thread.

The callback should be safe to call even if the operation has already completed.

requestInterrupt()

DLLEXPORT void QoreSandboxManager::requestInterrupt

(

)

Requests graceful interruption of sandboxed code.

This sets an interrupt flag that is checked at various points during execution (statement boundaries, blocking operations).

Interrupted code receives a PROGRAM-INTERRUPTED exception.

When interrupt is requested, all registered cancel callbacks are invoked to cancel any ongoing blocking operations (e.g., database queries).

Note

This is the preferred way to stop runaway sandboxed code. It allows for clean shutdown without corrupting state.

setCPUTimeLimit()

DLLEXPORT void QoreSandboxManager::setCPUTimeLimit

(

int64

ms

)

Sets maximum CPU time in milliseconds.

Parameters

ms	Maximum CPU time in milliseconds (0 = unlimited)

Note

CPU time is checked periodically during execution. Exceeding the limit raises a SANDBOX-TIMEOUT exception.

setMaxRecursionDepth()

DLLEXPORT void QoreSandboxManager::setMaxRecursionDepth

(

int

depth

)

Sets maximum recursion depth.

Parameters

depth

Maximum recursion depth (0 = unlimited)

Note

This limits function call stack depth. Exceeding the limit raises a SANDBOX-RECURSION-LIMIT exception.

setMaxThreads()

DLLEXPORT void QoreSandboxManager::setMaxThreads

(

int

count

)

Sets maximum number of threads.

Parameters

count

Maximum number of threads (0 = unlimited)

Note

This limits threads created by the background statement. Exceeding the limit raises a SANDBOX-THREAD-LIMIT exception.

setMemoryLimit()

DLLEXPORT void QoreSandboxManager::setMemoryLimit

(

size_t

bytes

)

Sets maximum memory usage in bytes.

Parameters

bytes

Maximum memory allocation in bytes (0 = unlimited)

Note

This limit is checked when allocating memory in sandboxed code. Exceeding the limit raises a SANDBOX-MEMORY-LIMIT exception.

setWallTimeLimit()

DLLEXPORT void QoreSandboxManager::setWallTimeLimit

(

int64

ms

)

Sets maximum wall clock time in milliseconds.

Parameters

ms	Maximum wall clock time in milliseconds (0 = unlimited)

Note

Wall time is checked periodically during execution. Exceeding the limit raises a SANDBOX-TIMEOUT exception.

unregisterCancelCallback()

DLLEXPORT void QoreSandboxManager::unregisterCancelCallback

(

void *

context

)

Unregisters a cancel callback.

Call this after the blocking operation completes.

Parameters

context

The context pointer used during registration

---

The documentation for this class was generated from the following file:

• /tmp/qore/include/qore/QoreSandboxManager.h