Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

docs: security clarification on pyproject.toml (#10986)

Dylan Madisetti5120eadc21cb
diff --git a/docs/security.md b/docs/security.md
index 2cf69f280d..d13818b78b 100644
--- a/docs/security.md
+++ b/docs/security.md
@@ -45,6 +45,16 @@ marimo behaves differently depending on how you run it:
This distinction reflects the different threat models: editing is exploratory and may involve untrusted notebooks; deployed apps are intentional publications.
+### Project files
+
+marimo reads configuration settings from three sources: your user config, the nearest `pyproject.toml`, and the notebook's inline script metadata (PEP 723).
+Configuration is merged in order of precedence, as explained in the [configuration guide](guides/configuration/index.md).
+For security reasons marimo applies priority to these settings as follows:
+
+- **Script metadata** or [notebook level settings](guides/configuration/index.md#script-metadata-configuration) strips several settings for security. Since notebooks can be opened from remote sources, marimo intentionally removes certain settings from script metadata to prevent malicious configuration.
+- **In `pyproject.toml` and `.marimo.toml` files most configuration options are respected**. You should only open a notebook from a project you trust. Projects can install arbitrary code, and other settings (including marimo's) may be configured maliciously.
+- **User config** (XDG config) options are always trusted. These configs are stored in your personal directories and only you can modify them.
+
### Authentication
marimo provides token-based authentication:
@@ -61,6 +71,7 @@ See the [Authentication guide](guides/deploying/authentication.md) for more deta
- Auto-running cells is disabled on notebook load (you can disable this during your session)
- Custom head tags are disabled
+- Notebook script metadata is stripped as described under [Project files](#project-files)
These restrictions prevent code execution without explicit user consent.
diff --git a/marimo/_config/manager.py b/marimo/_config/manager.py
index 5e07f458c5..7a9293cbfc 100644
--- a/marimo/_config/manager.py
+++ b/marimo/_config/manager.py
@@ -303,7 +303,9 @@ class ProjectConfigManager(PartialMarimoConfigReader):
project_config = self._resolve_dotenv(project_config)
project_config = self._resolve_custom_css(project_config)
project_config = self._resolve_vimrc(project_config)
- # A cloned repo's pyproject.toml cannot anchor cache-signing trust.
+ # pyproject.toml is honoured as written apart from trust anchors.
+ # Opening a notebook inside a project already means trusting that
+ # project, so an allowlist here adds little protection.
project_config = strip_untrusted_config(project_config)
except Exception as e:
LOGGER.warning("Failed to read project config: %s", e)
diff --git a/marimo/_config/reader.py b/marimo/_config/reader.py
index 5c1651dacc..64cf10146e 100644
--- a/marimo/_config/reader.py
+++ b/marimo/_config/reader.py
@@ -121,9 +121,12 @@ def allowlist_script_config(
return pyproject_dict
-# Settings that an untrusted-origin config layer must not set. Both take effect
-# before any cell runs, so a layer that sets one decides something the operator
-# never agreed to:
+# We typically do not strip pyproject configuration keys on the basis that a
+# malicious project can provide behavior as bad as, if not worse than, our options.
+# However, we are reserving these keys for potential TOFU-style trust anchors.
+# Reporters, do not read into this as a security guarantee for stripping
+# project options. See https://docs.marimo.io/security/#project-files for
+# more discussion.
#
# signing trusting a key is a code-execution grant, because a
# cache restore is `pickle.loads`