Behaviour to customize the modules and functions that are allowed or restricted.

Warning: security considerations

The default implementation is Dune.Allowlist.Default, and should only allow safe functions: no atom leaks, no execution of arbitrary code, no access to the filesystem / network... Defining or extending a custom Dune.Allowlist module can introduce security risks or bugs.

Please also note that using custom allowlists is still experimental and the API for it might change faster than the rest of the library.

Defining a new allowlist

In order to define a custom allowlist from scratch, use Dune.Allowlist can be used:

defmodule CustomAllowlist do
  use Dune.Allowlist

  allow Kernel, only: [:+, :*, :-, :/, :div, :rem]
end

Dune.eval_string("4 + 9", allowlist: CustomAllowlist)

Extending an existing allowlist

Defining an allowlist from scratch can be both daunting and risky. It is possible to extend an exisiting allowlist instead using the extend option:

defmodule ExtendedAllowlist do
  use Dune.Allowlist, extend: Dune.Allowlist.Default

  allow SomeModule, only: [:authorized]
end

Dune.eval_string("SomeModule.authorized(123)", allowlist: ExtendedAllowlist)

Note: currently, it is not possible to add or restrict functions from modules that have already been specified.

Documentation generation

The list of modules and functions with their status can be generated in the @moduledoc. An example can be found in the Dune.Allowlist.Default documentation.

If the __DUNE_ALLOWLIST_FUNCTIONS__ string is found in the @moduledoc string, it will be replaced.

defmodule CustomAllowlist do
  @moduledoc """
  Only allows simple arithmetic

  ## Allowlist functions

  __DUNE_ALLOWLIST_FUNCTIONS__
  """

  use Dune.Allowlist

  allow Kernel, only: [:+, :*, :-, :/, :div, :rem]
end