Add environment variable support to CLI and Docker configuration

Signed-off-by: Jiaxiao (mossaka) Zhou <duibao55328@gmail.com>

Author: Mossaka

CLAUDE.md

@@ -9,6 +9,7 @@ This is a firewall for GitHub Copilot CLI (package name: `@github/awf`) that pro
 ### Documentation Files
 
 - **[README.md](README.md)** - Main project documentation and usage guide
+- **[ENVIRONMENT.md](ENVIRONMENT.md)** - Environment variable configuration and security best practices
 - **[LOGGING.md](LOGGING.md)** - Comprehensive logging documentation
 - **[docs/LOGGING_QUICKREF.md](docs/LOGGING_QUICKREF.md)** - Quick reference for log queries and monitoring
 

ENVIRONMENT.md

@@ -0,0 +1,58 @@
+# Environment Variables
+
+## Usage
+
+```bash
+# Pass specific variables
+awf -e MY_API_KEY=secret 'command'
+
+# Pass multiple variables
+awf -e FOO=1 -e BAR=2 'command'
+
+# Pass all host variables (development only)
+awf --env-all 'command'
+```
+
+## Default Behavior
+
+When using `sudo -E`, these host variables are automatically passed: `GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_PERSONAL_ACCESS_TOKEN`, `USER`, `TERM`, `HOME`, `XDG_CONFIG_HOME`.
+
+The following are always set/overridden: `HTTP_PROXY`, `HTTPS_PROXY` (Squid proxy), `PATH`, `DOCKER_HOST`, `DOCKER_CONTEXT` (container values).
+
+Variables from `--env` flags override everything else.
+
+## Security Warning: `--env-all`
+
+Using `--env-all` passes all host environment variables to the container, which creates security risks:
+
+1. **Credential Exposure**: All variables (API keys, tokens, passwords) are written to `/tmp/awf-<timestamp>/docker-compose.yml` in plaintext
+2. **Log Leakage**: Sharing logs or debug output exposes sensitive credentials
+3. **Unnecessary Access**: Extra variables increase attack surface (violates least privilege)
+4. **Accidental Sharing**: Easy to forget what's in your environment when sharing commands
+
+**Excluded variables** (even with `--env-all`): `PATH`, `DOCKER_HOST`, `DOCKER_CONTEXT`, `DOCKER_CONFIG`, `PWD`, `OLDPWD`, `SHLVL`, `_`, `SUDO_*`
+
+## Best Practices
+
+✅ **Use `--env` for specific variables:**
+```bash
+sudo awf --allow-domains github.com -e MY_API_KEY="$MY_API_KEY" 'command'
+```
+
+✅ **Use `sudo -E` for auth tokens:**
+```bash
+sudo -E awf --allow-domains github.com 'copilot --prompt "..."'
+```
+
+⚠️ **Use `--env-all` only in trusted local development** (never in production/CI/CD)
+
+❌ **Avoid `--env-all` when:**
+- Sharing logs or configs
+- Working with untrusted code
+- In production/CI environments
+
+## Troubleshooting
+
+**Variable not accessible:** Use `sudo -E` or pass explicitly with `--env VAR="$VAR"`
+
+**Variable empty:** Check if it's in the excluded list or wasn't exported on host (`export VAR=value`)

src/cli.ts

@@ -75,6 +75,17 @@ program
     'Container image tag',
     'latest'
   )
+  .option(
+    '-e, --env <KEY=VALUE>',
+    'Additional environment variables to pass to container (can be specified multiple times)',
+    (value, previous: string[] = []) => [...previous, value],
+    []
+  )
+  .option(
+    '--env-all',
+    'Pass all host environment variables to container (excludes system vars like PATH, DOCKER_HOST)',
+    false
+  )
   .argument('<command>', 'Copilot command to execute (wrap in quotes)')
   .action(async (copilotCommand: string, options) => {
     // Parse and validate options
@@ -96,6 +107,20 @@ program
       process.exit(1);
     }
 
+    // Parse additional environment variables from --env flags
+    const additionalEnv: Record<string, string> = {};
+    if (options.env && Array.isArray(options.env)) {
+      for (const envVar of options.env) {
+        const match = envVar.match(/^([^=]+)=(.*)$/);
+        if (!match) {
+          logger.error(`Invalid environment variable format: ${envVar} (expected KEY=VALUE)`);
+          process.exit(1);
+        }
+        const [, key, value] = match;
+        additionalEnv[key] = value;
+      }
+    }
+
     const config: WrapperConfig = {
       allowedDomains,
       copilotCommand,
@@ -105,8 +130,16 @@ program
       buildLocal: options.buildLocal,
       imageRegistry: options.imageRegistry,
       imageTag: options.imageTag,
+      additionalEnv: Object.keys(additionalEnv).length > 0 ? additionalEnv : undefined,
+      envAll: options.envAll,
     };
 
+    // Warn if --env-all is used
+    if (config.envAll) {
+      logger.warn('⚠️  Using --env-all: All host environment variables will be passed to container');
+      logger.warn('   This may expose sensitive credentials if logs or configs are shared');
+    }
+
     // Log config with redacted secrets
     const redactedConfig = {
       ...config,

src/docker-manager.ts

@@ -154,6 +154,57 @@ export function generateDockerCompose(
     };
   }
 
+  // Build environment variables for copilot container
+  // System variables that must be overridden or excluded (would break container operation)
+  const EXCLUDED_ENV_VARS = new Set([
+    'PATH',           // Must use container's PATH
+    'DOCKER_HOST',    // Must use container's socket path
+    'DOCKER_CONTEXT', // Must use default context
+    'DOCKER_CONFIG',  // Must use clean config
+    'PWD',            // Container's working directory
+    'OLDPWD',         // Not relevant in container
+    'SHLVL',          // Shell level not relevant
+    '_',              // Last command executed
+    'SUDO_COMMAND',   // Sudo metadata
+    'SUDO_USER',      // Sudo metadata
+    'SUDO_UID',       // Sudo metadata
+    'SUDO_GID',       // Sudo metadata
+  ]);
+
+  // Start with required/overridden environment variables
+  const environment: Record<string, string> = {
+    HTTP_PROXY: `http://${networkConfig.squidIp}:${SQUID_PORT}`,
+    HTTPS_PROXY: `http://${networkConfig.squidIp}:${SQUID_PORT}`,
+    SQUID_PROXY_HOST: 'squid-proxy',
+    SQUID_PROXY_PORT: SQUID_PORT.toString(),
+    HOME: process.env.HOME || '/root',
+    PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
+    DOCKER_HOST: 'unix:///var/run/docker.sock',
+    DOCKER_CONTEXT: 'default',
+  };
+
+  // If --env-all is specified, pass through all host environment variables (except excluded ones)
+  if (config.envAll) {
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined && !EXCLUDED_ENV_VARS.has(key) && !environment.hasOwnProperty(key)) {
+        environment[key] = value;
+      }
+    }
+  } else {
+    // Default behavior: selectively pass through specific variables
+    if (process.env.GITHUB_TOKEN) environment.GITHUB_TOKEN = process.env.GITHUB_TOKEN;
+    if (process.env.GH_TOKEN) environment.GH_TOKEN = process.env.GH_TOKEN;
+    if (process.env.GITHUB_PERSONAL_ACCESS_TOKEN) environment.GITHUB_PERSONAL_ACCESS_TOKEN = process.env.GITHUB_PERSONAL_ACCESS_TOKEN;
+    if (process.env.USER) environment.USER = process.env.USER;
+    if (process.env.TERM) environment.TERM = process.env.TERM;
+    if (process.env.XDG_CONFIG_HOME) environment.XDG_CONFIG_HOME = process.env.XDG_CONFIG_HOME;
+  }
+
+  // Additional environment variables from --env flags (these override everything)
+  if (config.additionalEnv) {
+    Object.assign(environment, config.additionalEnv);
+  }
+
   // Copilot service configuration
   const copilotService: any = {
     container_name: 'awf-copilot',
@@ -179,30 +230,7 @@ export function generateDockerCompose(
       // Mount copilot logs directory to workDir for persistence
       `${config.workDir}/copilot-logs:${process.env.HOME}/.copilot/logs:rw`,
     ],
-    environment: {
-      HTTP_PROXY: `http://${networkConfig.squidIp}:${SQUID_PORT}`,
-      HTTPS_PROXY: `http://${networkConfig.squidIp}:${SQUID_PORT}`,
-      SQUID_PROXY_HOST: 'squid-proxy',
-      SQUID_PROXY_PORT: SQUID_PORT.toString(),
-      // Preserve important env vars
-      HOME: process.env.HOME || '/root',
-      // Use container's PATH, not host's PATH
-      PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
-      // Docker socket path - override host's DOCKER_HOST to use mounted socket
-      // Clean .docker config is mounted over $HOME/.docker to prevent reading host's context
-      DOCKER_HOST: 'unix:///var/run/docker.sock',
-      // Force default context to prevent Docker CLI from using host's context (e.g., desktop-linux)
-      // which may point to incorrect socket paths like ~/.docker/run/docker.sock
-      DOCKER_CONTEXT: 'default',
-      // Pass through GitHub authentication tokens
-      ...(process.env.GITHUB_TOKEN && { GITHUB_TOKEN: process.env.GITHUB_TOKEN }),
-      ...(process.env.GH_TOKEN && { GH_TOKEN: process.env.GH_TOKEN }),
-      ...(process.env.GITHUB_PERSONAL_ACCESS_TOKEN && { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_PERSONAL_ACCESS_TOKEN }),
-      // Pass through other common environment variables
-      ...(process.env.USER && { USER: process.env.USER }),
-      ...(process.env.TERM && { TERM: process.env.TERM }),
-      ...(process.env.XDG_CONFIG_HOME && { XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME }),
-    },
+    environment,
     depends_on: {
       'squid-proxy': {
         condition: 'service_healthy',

src/types.ts

@@ -11,6 +11,8 @@ export interface WrapperConfig {
   imageRegistry?: string;  // Default: 'ghcr.io/mossaka/gh-aw-firewall'
   imageTag?: string;       // Default: 'latest'
   buildLocal?: boolean;    // Default: false (use GHCR images)
+  additionalEnv?: Record<string, string>; // Additional environment variables to pass to container
+  envAll?: boolean;        // Pass all host environment variables (excluding system vars)
 }
 
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';