Protocol: Allowlisting mechanism for Kedro components

Source: kedro-org/kedro#5652 — "Design a unified allowlisting mechanism for Kedro components"

When to add an allowlist — decide this first

Allowlisting is opt-in extra surface for users to manage. It should be applied to as few places as possible, and only when there's a real, identified risk.

If you're unsure whether a new component needs this, raise it for discussion rather than implementing unilaterally — this is a security-surface decision, not just an API choice.

Design principles

1. Where the allowlist config lives

Precedence, highest to lowest:

1. Constructor arguments (where the component can be used standalone in code, e.g. OmegaConfigLoader)
2. settings.py — the default home. Rationale: it's where other project-level component config already lives (component classes, CONFIG_LOADER_ARGS, etc.); it's core/trusted (if an attacker can edit settings.py they're already past the trust boundary); and it's loaded early and available to downstream processes.
3. Environment variable — useful as a fallback for packaged/deployed projects where settings.py can't be edited post-build. Can be used in conjunction with settings.py, not as a replacement.

Whatever is concretely provided at a given level takes precedence; unset levels don't implicitly widen or narrow it.

2. Naming convention

<COMPONENT>_ALLOWLIST (not WHITELIST). Existing RUNNER_MODULES_WHITELIST is to be renamed to RUNNER_MODULE_ALLOWLIST under this convention.

3. Validation logic

• Move/write validation as a shared utility function in kedro.utils (private, so it can change without being a public API commitment) rather than bespoke per-component checks — avoids duplicating the same allow/deny logic across the codebase.
• Applied as a pre-flight check at the point the component actually loads the external thing (e.g. when importing the runner module; for OmegaConfigLoader, presumably at initialisation). Different components come alive at different points in the run cycle, so don't try to force one global validation moment — the utility function gets called wherever the loading happens.
• The exact shape of what's validated differs per component (module path prefix vs. URL scheme/host vs. full URL prefix, etc.) — define that explicitly per component rather than assuming a single format fits all.

4. Backwards compatibility

Default must always be "no restriction" — allowlisting is opt-in, so existing local/single-project workflows are unaffected if the user never sets it.

Current component inventory (as of this writeup)

Component	Status	Mechanism
Runner module (HTTP server)	Live on main	settings.RUNNER_MODULES_WHITELIST (pending rename to RUNNER_MODULE_ALLOWLIST)
Runner module (CLI kedro run)	Discussed, not implemented	Would reuse the same settings + utility
OmegaConfigLoader remote conf_source	Proposed, #5636	allowed_schemes / allowed_hosts constructor args, falling back to settings.py/env
Dataset module loading (custom datasets)	Existing, not user-configurable	Checked against a fixed _DEFAULT_PACKAGES list (["kedro.io.", "kedro_datasets.", ""]) in kedro/io/core.py — no allowlist mechanism needed today
Logging config source (KEDRO_LOGGING_CONFIG)	Identified as a candidate	Not yet designed
Logging class restriction (#5630)	Identified as a candidate	Currently restricted to logging.Handler/Formatter/Filter by type check, not an allowlist
Starters (custom starter templates)	Identified as a candidate	Not yet designed
Catalog / dataset entries	Explicitly out of scope	Covered by config-source restriction instead; treated as platform/IAM concern where data access is involved

Practical checklist for implementing a new component's allowlist

1. Confirm the risk is real and config/code-loading-shaped (not a data-access concern — that's out of scope).
2. Define exactly what gets validated and at what granularity (module path prefix? URL scheme? host? full prefix?).
3. Name the setting <COMPONENT>_ALLOWLIST.
4. Add support in this precedence order, only where it makes sense for that component: constructor arg → settings.py → env var fallback.
5. Implement/reuse a shared validation utility in kedro.utils rather than writing bespoke inline checks.
6. Call the validation as a pre-flight check at the actual load site.
7. Confirm default behaviour is unrestricted (no breaking change for existing projects).
8. Document the new setting alongside the other settings.py entries.

References

• #5652 — this design discussion
• #5636 — OmegaConfigLoader allowlist proposal
• #5568 / #5576 — runner module validation for HTTP server
• #5630 — logging class restriction
• #5726 — catalog-related fix that avoided needing an allowlist