From be27bfed01f4eb2f0c840ad874948943e48a74b6 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Sun, 24 May 2026 04:25:32 -0700
Subject: [PATCH] security: harden API server key placeholder handling (#30738)

---
 hermes_cli/auth.py                          |  1 +
 tests/hermes_cli/test_auth_usable_secret.py | 13 +++++++++++++
 website/docs/user-guide/docker.md           |  2 +-
 3 files changed, 15 insertions(+), 1 deletion(-)
 create mode 100644 tests/hermes_cli/test_auth_usable_secret.py

diff --git a/hermes_cli/auth.py b/hermes_cli/auth.py
index 073a136c251..04cd6b3ce2f 100644
--- a/hermes_cli/auth.py
+++ b/hermes_cli/auth.py
@@ -553,6 +553,7 @@ _PLACEHOLDER_SECRET_VALUES = {
     "***",
     "changeme",
     "your_api_key",
+    "your_api_key_here",
     "your-api-key",
     "placeholder",
     "example",
diff --git a/tests/hermes_cli/test_auth_usable_secret.py b/tests/hermes_cli/test_auth_usable_secret.py
new file mode 100644
index 00000000000..cb24ef5ee26
--- /dev/null
+++ b/tests/hermes_cli/test_auth_usable_secret.py
@@ -0,0 +1,13 @@
+"""Tests for placeholder API key detection in hermes_cli.auth."""
+
+from hermes_cli.auth import has_usable_secret
+
+
+def test_has_usable_secret_rejects_documented_placeholder_key() -> None:
+    """Network-exposed API server key must reject static documentation placeholders."""
+    assert not has_usable_secret("your_api_key_here", min_length=8)
+
+
+def test_has_usable_secret_accepts_generated_key() -> None:
+    """Random-looking keys should still be accepted."""
+    assert has_usable_secret("b4d59f7fe8b857d0b367ef0f5710b6a4", min_length=8)
diff --git a/website/docs/user-guide/docker.md b/website/docs/user-guide/docker.md
index a2376d9ca1f..2cd931751da 100644
--- a/website/docs/user-guide/docker.md
+++ b/website/docs/user-guide/docker.md
@@ -51,7 +51,7 @@ docker run -d \
   -p 8642:8642 \
   -e API_SERVER_ENABLED=true \
   -e API_SERVER_HOST=0.0.0.0 \
-  -e API_SERVER_KEY=your_api_key_here \
+  -e API_SERVER_KEY="$(openssl rand -hex 32)" \
   -e API_SERVER_CORS_ORIGINS='*' \
   nousresearch/hermes-agent gateway run
 ```