Security

Permissions

Control what untrusted code can reach in Secure Exec: external network access is denied by default and everything else is virtualized.

Permissions are a VM option. Pass permissions on a call, or on createVm.

The default

The guest’s filesystem, processes, environment, and network stack are fully virtualized. Guest code can bind listeners and communicate over loopback inside the VM. External DNS and network connections cross the VM boundary, so they are denied.

import { evaluate } from "secure-exec";

const request = `(async () => {
	const response = await fetch("https://example.com");
	await response.text();
	return response.status;
})()`;

// The network is denied unless you allow it.
const denied = await evaluate<number>(request, {
	output: { capture: "stderr" },
});
if (denied.outcome !== "succeeded") {
	console.log(denied.outcome, denied.stderr?.split("\n")[0]); // failed TypeError: fetch failed
}

Grant the network

Your policy is merged over the default. Granting the network leaves every other scope as it was.

// VM options such as `permissions` go on the call. A policy is merged over the
// defaults, so granting the network keeps everything else working.
const allowed = await evaluate<number>(request, {
	permissions: { network: "allow" },
});
console.log(allowed.outcome === "succeeded" ? allowed.value : allowed.error); // 200

Allow specific hosts

A rule set denies by default and allows matching patterns. A host needs both a dns:// pattern to resolve it and a tcp:// pattern to connect to it.

// Allow a single host instead of the whole network.
const scoped = await evaluate<number>(request, {
	permissions: {
		network: {
			default: "deny",
			rules: [
				{
					mode: "allow",
					operations: ["*"],
					patterns: ["dns://example.com", "tcp://example.com:*"],
				},
			],
		},
	},
});
console.log(scoped.outcome === "succeeded" ? scoped.value : scoped.error); // 200

The full policy model

Secure Exec uses the agentOS permission model unchanged: the fs, network, childProcess, process, env, and hostFunction scopes, rule sets, and operations. Read the agentOS permissions reference for all of it.