Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(security): gate loguru diagnose localvar dumps behind LDR_LOGURU_DIAGNOSE (#4384)

Leoyf92269774fec
diff --git a/changelog.d/+loguru-diagnose-credential-lockdown.security.md b/changelog.d/+loguru-diagnose-credential-lockdown.security.md
new file mode 100644
index 0000000000..dd5043c27f
--- /dev/null
+++ b/changelog.d/+loguru-diagnose-credential-lockdown.security.md
@@ -0,0 +1 @@
+Loguru ``diagnose=True`` exception rendering (which dumps the ``repr()`` of every local variable in every traceback frame) is now gated behind a separate explicit ``LDR_LOGURU_DIAGNOSE`` opt-in instead of riding on ``LDR_APP_DEBUG``. Previously, enabling ``LDR_APP_DEBUG`` for general debug output also turned on localvar dumps, so any exception could write frame-local credentials — API keys, the SQLCipher master password, ``Authorization`` headers — into every log sink. ``LDR_APP_DEBUG`` now controls log *level* only; ``diagnose`` stays off unless the operator additionally sets ``LDR_LOGURU_DIAGNOSE=true``, and an explicit warning is emitted when they do.
diff --git a/docs/env_configuration.md b/docs/env_configuration.md
index 2170e0217c..74f3f0ac85 100644
--- a/docs/env_configuration.md
+++ b/docs/env_configuration.md
@@ -181,6 +181,21 @@ All application data will be organized under this directory:
- `$LDR_DATA_DIR/cache/` - Cached data
- `$LDR_DATA_DIR/logs/` - Application logs
+### Debug Logging (`LDR_APP_DEBUG` and `LDR_LOGURU_DIAGNOSE`)
+
+`LDR_APP_DEBUG=true` raises the log level to `DEBUG` for more informative output. It does **not**, on its own, enable Loguru's `diagnose` mode, which renders the `repr()` of every local variable in every traceback frame on exceptions and can materialise credentials (API keys, the SQLCipher master password, `Authorization` headers) into your logs.
+
+To opt into that variable-level detail, set `LDR_LOGURU_DIAGNOSE=true` **in addition to** `LDR_APP_DEBUG=true`. Keep it disabled in production; a warning is emitted whenever it is active.
+
+```bash
+# Verbose logs, no local-variable dumps (safe default for debugging)
+export LDR_APP_DEBUG=true
+
+# Full exception diagnostics including frame locals (NEVER in production)
+export LDR_APP_DEBUG=true
+export LDR_LOGURU_DIAGNOSE=true
+```
+
### Database Configuration (SQLCipher)
Database encryption settings are configured exclusively via environment variables (they cannot be changed through the Web UI). These settings are applied at database creation time and must remain consistent for the database to be accessible.
diff --git a/src/local_deep_research/utilities/log_utils.py b/src/local_deep_research/utilities/log_utils.py
index 1c3c87e586..7b63132179 100644
--- a/src/local_deep_research/utilities/log_utils.py
+++ b/src/local_deep_research/utilities/log_utils.py
@@ -533,9 +533,22 @@ def config_logger(name: str, debug: bool = False) -> None:
# Log to console (stderr) and database
stderr_level = "DEBUG" if debug else "INFO"
- logger.add(sys.stderr, level=stderr_level, diagnose=debug)
- logger.add(database_sink, level="DEBUG", diagnose=debug)
- logger.add(frontend_progress_sink, diagnose=debug)
+
+ # loguru's diagnose=True renders repr() of every local variable in every
+ # traceback frame on exceptions. Under LDR_APP_DEBUG that would dump
+ # credentials living in frame locals (api_key, SQLCipher password,
+ # Authorization headers) into every sink. Gate diagnose behind a separate
+ # explicit opt-in so enabling LDR_APP_DEBUG for general debug output does
+ # not also enable localvar dumps. Default OFF even when debug is on.
+ diagnose = debug and os.environ.get("LDR_LOGURU_DIAGNOSE", "").lower() in (
+ "1",
+ "true",
+ "yes",
+ )
+
+ logger.add(sys.stderr, level=stderr_level, diagnose=diagnose)
+ logger.add(database_sink, level="DEBUG", diagnose=diagnose)
+ logger.add(frontend_progress_sink, diagnose=diagnose)
if debug:
logger.warning(
@@ -544,6 +557,13 @@ def config_logger(name: str, debug: bool = False) -> None:
"Do NOT use in production."
)
+ if diagnose:
+ logger.warning(
+ "LDR_LOGURU_DIAGNOSE is enabled: exception tracebacks will include "
+ "local variable values, which may contain credentials (API keys, "
+ "passwords, tokens). Do NOT use in production."
+ )
+
# Optionally log to file if enabled (disabled by default for security)
# Check environment variable first, then database setting
enable_file_logging = (
@@ -561,7 +581,7 @@ def config_logger(name: str, debug: bool = False) -> None:
rotation="10 MB",
retention="7 days",
compression="zip",
- diagnose=debug,
+ diagnose=diagnose,
)
logger.warning(
f"File logging enabled - logs will be written to {log_file}. "
diff --git a/tests/utilities/test_log_utils_extended.py b/tests/utilities/test_log_utils_extended.py
index 7ead9bb544..9ae9bdef17 100644
--- a/tests/utilities/test_log_utils_extended.py
+++ b/tests/utilities/test_log_utils_extended.py
@@ -549,11 +549,14 @@ class TestConfigLoggerExtended:
assert mock_logger.add.call_count == 4
def test_debug_mode_sets_diagnose_true(self):
- """When debug=True, all sinks should have diagnose=True."""
+ """diagnose=True requires BOTH debug=True AND LDR_LOGURU_DIAGNOSE opt-in."""
from local_deep_research.utilities.log_utils import config_logger
import local_deep_research.utilities.log_utils as module
- with patch.dict(os.environ, {"LDR_ENABLE_FILE_LOGGING": ""}):
+ with patch.dict(
+ os.environ,
+ {"LDR_ENABLE_FILE_LOGGING": "", "LDR_LOGURU_DIAGNOSE": "true"},
+ ):
with patch.object(module, "logger") as mock_logger:
config_logger("test_app", debug=True)
@@ -561,15 +564,40 @@ class TestConfigLoggerExtended:
for add_call in mock_logger.add.call_args_list:
assert add_call[1].get("diagnose") is True
+ def test_diagnose_off_when_debug_without_optin(self):
+ """debug=True alone must NOT enable diagnose (localvar leak, issue #4185).
+
+ Without the explicit LDR_LOGURU_DIAGNOSE opt-in, enabling LDR_APP_DEBUG
+ must keep diagnose=False on every sink so exception tracebacks do not
+ dump frame-local credentials.
+ """
+ from local_deep_research.utilities.log_utils import config_logger
+ import local_deep_research.utilities.log_utils as module
+
+ with patch.dict(
+ os.environ,
+ {"LDR_ENABLE_FILE_LOGGING": "", "LDR_LOGURU_DIAGNOSE": ""},
+ ):
+ with patch.object(module, "logger") as mock_logger:
+ config_logger("test_app", debug=True)
+
+ assert mock_logger.add.call_args_list # sinks were added
+ for add_call in mock_logger.add.call_args_list:
+ assert add_call[1].get("diagnose") is False
+
def test_non_debug_mode_sets_diagnose_false(self):
"""When debug=False (default), all sinks should have diagnose=False."""
from local_deep_research.utilities.log_utils import config_logger
import local_deep_research.utilities.log_utils as module
- with patch.dict(os.environ, {"LDR_ENABLE_FILE_LOGGING": ""}):
+ with patch.dict(
+ os.environ,
+ {"LDR_ENABLE_FILE_LOGGING": "", "LDR_LOGURU_DIAGNOSE": "true"},
+ ):
with patch.object(module, "logger") as mock_logger:
config_logger("test_app", debug=False)
+ # Even with the opt-in set, diagnose stays off unless debug too.
for add_call in mock_logger.add.call_args_list:
assert add_call[1].get("diagnose") is False