From 51dd8958b3043ba7d871bd9b8c7effb9d5a3df4d Mon Sep 17 00:00:00 2001 From: Documentation Bot Date: Mon, 16 Feb 2026 06:42:21 +0000 Subject: [PATCH] docs: add AWF_ONE_SHOT_TOKEN_DEBUG documentation Document the AWF_ONE_SHOT_TOKEN_DEBUG environment variable in user-facing documentation to help users troubleshoot token caching issues. Changes: - docs/environment.md: Add Debugging Environment Variables section with AWF_ONE_SHOT_TOKEN_DEBUG documentation and usage examples - docs/troubleshooting.md: Add Token Caching Issues section with troubleshooting steps for one-shot-token library Related to commit 2d90521 which added the AWF_ONE_SHOT_TOKEN_DEBUG feature to both C and Rust implementations of the one-shot-token library. --- docs/environment.md | 27 +++++++++++++++++++++++++++ docs/troubleshooting.md | 26 ++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) diff --git a/docs/environment.md b/docs/environment.md index 2bbe8b762..cd449e369 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -68,6 +68,33 @@ The following environment variables are set internally by the firewall and used **Note:** These are set automatically based on CLI options and should not be overridden manually. +## Debugging Environment Variables + +The following environment variables control debugging behavior: + +| Variable | Description | Default | Example | +|----------|-------------|---------|---------| +| `AWF_ONE_SHOT_TOKEN_DEBUG` | Enable debug logging for one-shot-token library | `off` | `1` or `true` | + +### One-Shot Token Debug Logging + +The one-shot-token library protects sensitive tokens (GITHUB_TOKEN, OPENAI_API_KEY, etc.) from environment variable inspection. By default, it operates silently. To troubleshoot token caching issues, enable debug logging: + +```bash +# Enable debug logging +export AWF_ONE_SHOT_TOKEN_DEBUG=1 + +# Run AWF with sudo -E to preserve the variable +sudo -E awf --allow-domains github.com 'your-command' +``` + +When enabled, the library logs: +- Token initialization messages +- Token access and caching events +- Environment cleanup confirmations + +**Note:** Debug output goes to stderr and does not interfere with command stdout. See `containers/agent/one-shot-token/README.md` for complete documentation. + **Historical note:** Prior to v0.13.5, `HTTP_PROXY` and `HTTPS_PROXY` were set to point to Squid. These have been removed in favor of transparent iptables-based redirection, which is more reliable and avoids conflicts with tools that don't honor proxy environment variables. ## Troubleshooting diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index fc12fb8cd..93a8dd1d6 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -87,6 +87,32 @@ echo $GITHUB_TOKEN # Should print the token ``` +### Token Caching Issues + +**Problem:** Sensitive tokens (GITHUB_TOKEN, OPENAI_API_KEY, etc.) not being properly cached or cleared + +**Solution:** +1. Enable debug logging for the one-shot-token library: + ```bash + export AWF_ONE_SHOT_TOKEN_DEBUG=1 + sudo -E awf --allow-domains ... 'your-command' + ``` +2. Check the debug output for: + - `Initialized with N default token(s)` - Library loaded successfully + - `Token accessed and cached` - Token was read and cached + - `INFO: Token cleared from process environment` - Token removed from /proc/environ + - `WARNING: Token still exposed` - Token cleanup failed (security concern) +3. If tokens are still exposed, check: + - The token name is in the default protected list (see `containers/agent/one-shot-token/README.md`) + - Or set `AWF_ONE_SHOT_TOKENS` to explicitly protect custom tokens: + ```bash + export AWF_ONE_SHOT_TOKENS="MY_CUSTOM_TOKEN,ANOTHER_TOKEN" + export AWF_ONE_SHOT_TOKEN_DEBUG=1 + sudo -E awf --allow-domains ... 'your-command' + ``` + +**Note:** Debug output goes to stderr. Use `2>&1 | tee debug.log` to capture it. + ## MCP Server Issues ### MCP Server Can't Connect