with.permissions · Execution permissions

Since Esquie may import and execute arbitrary third-party code from virtually any source, each step is sandboxed by default.

- https://françois.esquie.app/module:
    api_key: ${Deno.env.get("API_KEY")}
  with:
    # Ensure the api key doesn't get sent elsewhere
    permissions:
      net: api.example.com
      env: API_KEY
      import: jsr.io

CAUTION

Since these restrictions are enforced by the runtime, THEY CANNOT BE BYPASSED.

However it DOES NOT PROTECT AGAINST USERLAND ATTACKS, such as consuming excessive resources or messing up with the expedition progress.

As long as the principle of least privilege is respected, this approach greatly reduces the attack surface.

NOTE

Source files from @esquie/core (including builtins modules) are always trusted with read permissions even if not explicitly specified. This is to ensure Esquie can run properly.

Supported permissions

Any valid Deno.PermissionOptions descriptor is supported. Refer to the table below for a list of available permissions.

Permission	Description	Flag used
read	File system access (read)	--allow-read
write	File system access (write)	--allow-write
net	Network access	--allow-net
env	Environment variables	--allow-env
sys	System Information	--allow-sys
run	Subprocesses	--allow-run
ffi	FFI (Foreign Function Interface)	--allow-ffi
import	Calls to import()	--allow-import

CAUTION

As explained in Deno's documentation, subprocesses and dynamic libraries are not subject to the security restrictions imposed by Deno's sandboxing.

Use run and ffi permissions with extreme caution.

Child steps inheritance and restrictions

As explained in the sandboxing rules, a child step cannot request more permissions than its parent step.

Attempting to do so will throw an error at runtime.

- with:
    permissions:
      read: true
      net: [ example.com, example.org ]
  tasks:
    - _: This will throw an error at runtime
      with:
        permissions:
          read: true            # allowed
          net: [ example.com ]  # allowed
          write: true           # not allowed