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(cache): document the cache signing trust model (#10526)

Dylan Madisetti22983db96ce0
diff --git a/docs/api/caching.md b/docs/api/caching.md
index 2501033eae..f723c15087 100644
--- a/docs/api/caching.md
+++ b/docs/api/caching.md
@@ -263,6 +263,61 @@ def my_decorator(func):
```
In this instance, the cache will work as expected because the decorated function has the same signature and metadata as the original function.
+
+## Cache signing and trust
+
+By default, marimo uses the `pickle` module to serialize and deserialize cache
+entries. This is fast and safe for your local computer, but if you configure a
+shared cache directory or remote store, this may become a security issue since
+unpickling a cache entry is equivalent to running arbitrary code.
+
+marimo has a cache verification mechanism built-in (which is currently opt-in).
+It uses digital signatures to verify that a cache entry was written by a
+trusted key and requires the `cryptography` package. That mechanism is the
+*lazy loader*: the storage backend selected with `loader = "lazy"` (the default)
+or `method="lazy"` on an individual cache. It is the only loader that signs and
+verifies. You can configure the verification level in your user
+configuration file at `~/.config/marimo/marimo.toml` as follows:
+
+```toml title="~/.config/marimo/marimo.toml"
+[signing]
+# Optional: This machine's signing identity.
+# This will be generated if a key is not provided.
+# MARIMO_CACHE_SIGNING_PRIVATE_KEY also sets this value.
+private_key_path = "~/.marimo/cache_key.pem"
+
+[signing.trusted_signers]
+# Optional: If you use multiple caches, you can record trusted keys here.
+# fingerprint = label. The label is a note to yourself
+# Only the fingerprint matters.
+"SHA256:kV9x2c...q8" = "CI cache key"
+"SHA256:abc9f1...4d" = "Alice"
+
+[cache]
+verification = "on" # "off" | "on" | "strict"
+# Default `method` for `mo.persistent_cache`: "lazy" (default), "pickle", or "json".
+# Only "lazy" can sign and verify.
+loader = "lazy"
+```
+
+To sign and verify without a configuration file, set
+`MARIMO_CACHE_SIGNING_PRIVATE_KEY` to your signing key. To trust another key for
+verification only, set `MARIMO_CACHE_SIGNING_PUBLIC_KEY` to that key. Set each
+variable to the key itself in Privacy-Enhanced Mail (PEM) form, not a path.
+
+!!! danger "Trusting a key grants code execution"
+ Restoring a cache entry deserializes it with `pickle`, so trusting a
+ fingerprint lets whoever holds that key run arbitrary code on your machine.
+ There is no narrower "cache-only" version of this grant: add a fingerprint
+ only if you would run any script that person handed you.
+
+| Cache entry | `off` (default) | `on` | `strict` |
+|---|---|---|---|
+| Signed by a trusted key | load | load | load |
+| Unsigned, or signed by an unknown key | load without verifying | recompute | raise an error |
+
+We recommend using `strict` in CI.
+
## Comparison with `functools.cache`
Here is a table comparing marimo's cache with `functools.cache`:
diff --git a/docs/guides/configuration/index.md b/docs/guides/configuration/index.md
index 173cfdc6c4..6ea8f89e71 100644
--- a/docs/guides/configuration/index.md
+++ b/docs/guides/configuration/index.md
@@ -92,7 +92,7 @@ default_width = "full"
default_sql_output = "native"
```
-You can override any user configuration setting in this way. To find these settings run `marimo config show`.
+You can override most user configuration settings in this way. To find these settings run `marimo config show`.
### Additional file browser roots
@@ -110,6 +110,13 @@ cannot be set through notebook script metadata.
!!! note "Overridden settings"
Settings overridden in `pyproject.toml` or script metadata cannot be changed through the marimo editor's settings menu. Any changes made to overridden settings in the editor will not take effect.
+!!! warning "Settings that repositories cannot override"
+ A `pyproject.toml`, a notebook's script metadata, and a `.marimo.toml` inside
+ a project directory all travel with the code, so whoever wrote the repository
+ controls them. marimo reads `signing` and `cache.verification` from your user
+ configuration only, and ignores them in all three, because those two settings
+ decide [whose cached code you unpickle](../../api/caching.md#cache-signing-and-trust).
+
### Script metadata configuration
You can also configure marimo settings directly in your notebook files using script metadata (PEP 723). Add a `script` block at the top of your notebook:
@@ -130,6 +137,10 @@ You can also configure marimo settings directly in your notebook files using scr
**Script config > pyproject.toml config > user config**
+ The ordering covers the settings those layers are allowed to set. `signing`
+ and `cache.verification` come from user configuration whatever any other
+ layer says.
+
## Environment variables
marimo supports the following environment variables for advanced configuration: