Environment Filtering Reference¶

Complete reference for Assay's environment variable filtering system.

Overview¶

Assay scrubs environment variables before spawning sandboxed processes to prevent credential leakage and execution hijacking. This is enabled by default with no configuration required.

Filtering Modes¶

Pattern Scrub (Default)¶

Scrubbed Patterns¶

Variables matching these patterns are removed:

Credentials & Secrets¶

Cloud Providers¶

Version Control & CI¶

Databases & Storage¶

Security Tools¶

Execution Influence¶

Note: Execution-influence variables (such as LD_PRELOAD, PYTHONPATH, NODE_OPTIONS) are not removed by the default Pattern Scrub. They are only stripped when you use --env-strip-exec or strict mode (--env-strict).

Allowed Patterns (Safe Base)¶

These variables pass through by default:

System Essentials¶

Locale & Terminal¶

Temporary Directories¶

XDG Directories¶

Development Tools¶

Strict Mode¶

With --env-strict, only safe base patterns pass through. All other variables are scrubbed.

assay sandbox --env-strict -- ./server

What Passes in Strict Mode¶

• PATH, HOME, USER, SHELL, LOGNAME
• LANG, LC_*, TERM, COLORTERM
• TMPDIR, TMP, TEMP (set to scoped dir)
• XDG_*
• RUST_LOG, RUST_BACKTRACE, CARGO_*
• EDITOR, VISUAL, PAGER
• NO_COLOR, CLICOLOR

What's Blocked in Strict Mode¶

Everything else, including: - Custom application config vars (MY_APP_CONFIG) - Development shortcuts (DEBUG=1) - Non-secret project vars (PROJECT_NAME)

Explicit Allow¶

Use --env-allow to pass specific vars through strict mode:

assay sandbox --env-strict \
  --env-allow MY_CONFIG \
  --env-allow DEBUG \
  -- ./server

Passthrough Mode¶

⚠️ DANGER: Disables all environment filtering.

assay sandbox --env-passthrough -- ./server

Use only for: - Debugging scrubbing issues - Trusted code in controlled environments - When you understand the risks

Never use for: - Untrusted code - CI/CD pipelines - Production environments

Banner Output¶

The sandbox banner shows environment filtering status:

Pattern Scrub¶

Env: scrubbed (42 passed, 7 removed)

Strict Mode¶

Env: strict (12 passed, 47 scrubbed)

Passthrough Mode¶

Env: ⚠ passthrough (59 vars, DANGER)

Programmatic API¶

For the Rust SDK:

use assay::env_filter::{EnvFilter, EnvMode};

// Default pattern scrub
let filter = EnvFilter::default();
let result = filter.filter(&std::env::vars().collect());

println!("Passed: {}", result.passed_count);
println!("Scrubbed: {:?}", result.scrubbed_keys);

// Strict mode
let filter = EnvFilter::strict();

// With explicit allows
let filter = EnvFilter::default()
    .with_allowed(&["MY_VAR", "OTHER_VAR"]);

Common Questions¶

Why is my env var being scrubbed?¶

Check if it matches any scrub pattern: - Contains TOKEN, SECRET, KEY, PASSWORD - Starts with AWS_, GITHUB_, OPENAI_, etc. - Is an execution-influence var (LD_*, PYTHONPATH, etc.)

How do I allow a specific variable?¶

assay sandbox --env-allow MY_VAR -- ./server

Why can't I use --env-allow *?¶

For security. If you need all vars, use --env-passthrough (with caution).

What about .env files?¶

Assay doesn't read .env files. Variables must be in the process environment. Consider:

# Load .env, then sandbox
export $(cat .env | xargs)
assay sandbox --env-allow VAR1 --env-allow VAR2 -- ./server

Can I customize the scrub patterns?¶

Not yet. Future versions may support policy-based env rules. For now: - Use --env-allow for specific allows - Use --env-strict for maximum security

Security Rationale¶

Why Default Scrub?¶

Threat: MCP servers and AI agents may be: - Malicious by design - Compromised via supply chain - Tricked by prompt injection

Risk: Environment variables contain secrets that could be: - Exfiltrated to attacker servers - Used to access cloud resources - Logged or cached insecurely

Mitigation: Remove secrets before the process can access them.

Why Execution-Influence Scrubbing?¶

Threat: Variables like LD_PRELOAD allow code injection:

# Attacker sets:
export LD_PRELOAD=/tmp/keylogger.so

# Victim runs (unknowingly loads malicious code):
./innocent-program

Risk: Even "trusted" programs can be hijacked.

Mitigation: When execution-influence scrubbing is enabled (e.g., via --env-strip-exec or strict mode), Assay strips all execution-influence variables.

Why Strict Mode?¶

Problem: Pattern matching can miss: - Custom secret names (MY_API_KEY_V2) - New cloud provider prefixes - Internal credential conventions

Solution: Default-deny everything, explicit-allow only what's needed.

See Also¶

• assay sandbox CLI Reference
• Sandbox Security Guide
• Sandbox Policies Reference