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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
docs(cache): document the cache signing trust model (#10526)
Dylan Madisetti22983db96ce0
diff --git a/docs/api/caching.md b/docs/api/caching.mdindex 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.mdindex 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 configurationYou 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 variablesmarimo supports the following environment variables for advanced configuration: