diff --git a/hermes_cli/config.py b/hermes_cli/config.py index 5b166427a7122..9fbe1af0d6c60 100644 --- a/hermes_cli/config.py +++ b/hermes_cli/config.py @@ -215,25 +215,62 @@ def _warn_config_parse_failure( # NOT a HERMES_* blanket: integration credentials (HERMES_GEMINI_*, # HERMES_LANGFUSE_*, HERMES_SPOTIFY_*, ...) ARE allowed. "HERMES_HOME", "HERMES_PROFILE", "HERMES_CONFIG", "HERMES_ENV", + "HERMES_CONFIG_PATH", "HERMES_ENV_PATH", + # MCP catalog trust root. Package-manager wrappers may still provide this + # in the process environment; only generic persistence writes are blocked. + "HERMES_OPTIONAL_MCPS", + # Local ACP subprocess selection. Existing operator/package-manager values + # remain readable; generic writers cannot acquire executable/argv authority. + "HERMES_COPILOT_ACP_COMMAND", "HERMES_COPILOT_ACP_ARGS", + # Hermes security policy / approval-routing context. These remain available + # through their dedicated CLI/config/session controls, but a generic + # credential writer must not persist them for the next process startup. + "HERMES_YOLO_MODE", "HERMES_ACCEPT_HOOKS", "HERMES_REDACT_SECRETS", + "HERMES_INTERACTIVE", "HERMES_EXEC_ASK", "HERMES_GATEWAY_SESSION", + "HERMES_CRON_SESSION", "HERMES_SINGLE_QUERY_SESSION", + "HERMES_SESSION_KEY", "HERMES_SESSION_PLATFORM", }) +def _env_var_policy_name(key: str, *, is_windows: Optional[bool] = None) -> str: + """Return the name used for environment policy comparisons. + + Windows environment names are case-insensitive; POSIX names are not. The + explicit override keeps both semantics directly testable without pretending + the test interpreter is running on another host OS. + """ + windows = _IS_WINDOWS if is_windows is None else is_windows + return key.upper() if windows else key + + def _reject_denylisted_env_var(key: str) -> None: """Raise if ``key`` is in :data:`_ENV_VAR_NAME_DENYLIST`. Centralised so both the regular and "secure" env writers share the same gate, and so the message is consistent for callers. """ - if key in _ENV_VAR_NAME_DENYLIST: + if _env_var_policy_name(key) in _ENV_VAR_NAME_DENYLIST: raise ValueError( f"Environment variable {key!r} is on the writer denylist. " "Names that influence subprocess execution (LD_PRELOAD, " "PYTHONPATH, PATH, EDITOR, ...) or Hermes runtime location " - "(HERMES_HOME, HERMES_PROFILE, ...) cannot be persisted via " + "and security policy (HERMES_HOME, HERMES_YOLO_MODE, ...) " + "cannot be persisted via " "the env writer. If you really need this, edit " "~/.hermes/.env directly." ) + +def validate_env_var_name_for_write(key: str) -> None: + """Validate an environment name before a generic persistence write. + + Exposed separately from :func:`save_env_value` so batch-style callers can + validate their complete request before writing the first value. + """ + if not _ENV_VAR_NAME_RE.match(key): + raise ValueError(f"Invalid environment variable name: {key!r}") + _reject_denylisted_env_var(key) + _LAST_EXPANDED_CONFIG_BY_PATH: Dict[str, Any] = {} # (path, mtime_ns, size) -> cached expanded config dict. # load_config() returns a deepcopy of the cached value when the file @@ -4190,7 +4227,12 @@ def _quote_env_value(value: str) -> str: return f'"{escaped}"' -def _env_line_defines_key(line: str, key: str) -> bool: +def _env_line_defines_key( + line: str, + key: str, + *, + is_windows: Optional[bool] = None, +) -> bool: """True when a .env line assigns ``key`` — plain or ``export``-prefixed. ``load_env()`` accepts the bash-compatible ``export KEY=value`` form @@ -4201,7 +4243,13 @@ def _env_line_defines_key(line: str, key: str) -> bool: stripped = line.strip() if stripped.startswith("export "): stripped = stripped[7:].lstrip() - return stripped.startswith(f"{key}=") + assigned_key, separator, _value = stripped.partition("=") + if not separator: + return False + return _env_var_policy_name( + assigned_key, + is_windows=is_windows, + ) == _env_var_policy_name(key, is_windows=is_windows) def save_env_value(key: str, value: str): @@ -4222,9 +4270,7 @@ def save_env_value(key: str, value: str): file=sys.stderr, ) return - if not _ENV_VAR_NAME_RE.match(key): - raise ValueError(f"Invalid environment variable name: {key!r}") - _reject_denylisted_env_var(key) + validate_env_var_name_for_write(key) value = value.replace("\n", "").replace("\r", "") # API keys / tokens must be ASCII — strip non-ASCII with a warning. value = _check_non_ascii_credential(key, value) diff --git a/hermes_cli/web_routers/mcp.py b/hermes_cli/web_routers/mcp.py index 1dd5875a5887e..97eda0327f779 100644 --- a/hermes_cli/web_routers/mcp.py +++ b/hermes_cli/web_routers/mcp.py @@ -503,8 +503,31 @@ async def install_mcp_catalog_entry(body: MCPCatalogInstall, profile: Optional[s if entry is None: raise HTTPException(status_code=404, detail=f"No catalog entry '{name}'") - # Persist any supplied env vars first (catalog entries declare which names - # they need; we only write the ones the user provided). + # Catalog credentials are a closed schema: configuring one MCP must not + # become a generic write primitive for unrelated process environment. + declared_env = {spec.name for spec in (entry.auth.env or [])} + undeclared_env = sorted(set(body.env) - declared_env) + if undeclared_env: + raise HTTPException( + status_code=400, + detail=( + f"Catalog entry '{name}' does not declare environment " + f"variable(s): {', '.join(undeclared_env)}" + ), + ) + + # Validate the complete map before the first write. This preserves the + # existing writer/install flow while ensuring a mixed valid+invalid request + # cannot partially persist credentials. + from hermes_cli.config import validate_env_var_name_for_write + + try: + for key in body.env: + validate_env_var_name_for_write(key) + except ValueError as exc: + raise HTTPException(status_code=400, detail=str(exc)) from exc + + # Persist any supplied, declared env vars first. effective_profile = body.profile or profile if body.env: def _write_env(): diff --git a/tests/hermes_cli/test_config.py b/tests/hermes_cli/test_config.py index 54910db4728d5..f45fa17be5643 100644 --- a/tests/hermes_cli/test_config.py +++ b/tests/hermes_cli/test_config.py @@ -1043,7 +1043,7 @@ def test_migrate_preserves_custom_providers_and_no_defaults_dump(self, tmp_path) class TestEnvWriteDenylist: """``save_env_value`` refuses to persist env-var names that influence how subprocesses execute — ``LD_PRELOAD``, ``PYTHONPATH``, - ``PATH``, ``EDITOR``, etc. — or any ``HERMES_*`` runtime flag. + ``PATH``, ``EDITOR``, etc. — or selected Hermes runtime/security controls. The dashboard exposes ``PUT /api/env`` to any authed caller (and the session token lives in the SPA's HTML where any future plugin @@ -1073,15 +1073,97 @@ def _hermes_home(self, tmp_path, monkeypatch): ], ) def test_hermes_integration_keys_still_writable(self, allowed_key): - """``HERMES_*`` overall is NOT blocked — only the four runtime - location names (HOME/PROFILE/CONFIG/ENV) are. Integration - credentials following the ``HERMES_*`` convention must keep - working or we'd regress every provider setup wizard that - currently writes one of these (auth.py, Spotify, Langfuse, …).""" + """``HERMES_*`` overall is NOT blocked. + + Integration credentials following that convention must keep working + or we'd regress provider setup flows (auth.py, Spotify, Langfuse, …). + """ save_env_value(allowed_key, "test-value-123") env = load_env() assert env[allowed_key] == "test-value-123" + @pytest.mark.parametrize( + "protected_key", + [ + "HERMES_CONFIG_PATH", + "HERMES_ENV_PATH", + "HERMES_OPTIONAL_MCPS", + "HERMES_COPILOT_ACP_COMMAND", + "HERMES_COPILOT_ACP_ARGS", + "HERMES_YOLO_MODE", + "HERMES_ACCEPT_HOOKS", + "HERMES_REDACT_SECRETS", + "HERMES_INTERACTIVE", + "HERMES_EXEC_ASK", + "HERMES_GATEWAY_SESSION", + "HERMES_CRON_SESSION", + "HERMES_SINGLE_QUERY_SESSION", + "HERMES_SESSION_KEY", + "HERMES_SESSION_PLATFORM", + ], + ) + def test_hermes_security_control_keys_are_not_writable(self, protected_key): + """Generic writers must not persist runtime or approval controls.""" + with pytest.raises(ValueError, match="denylist"): + save_env_value(protected_key, "1") + + assert protected_key not in load_env() + + def test_preexisting_optional_mcps_override_still_loads(self, tmp_path): + """The writer gate must not migrate or ignore operator-owned .env state.""" + from hermes_cli.config import invalidate_env_cache + + catalog = tmp_path / "custom-mcp-catalog" + (tmp_path / ".env").write_text( + f"HERMES_OPTIONAL_MCPS={catalog}\n", + encoding="utf-8", + ) + invalidate_env_cache() + + assert load_env()["HERMES_OPTIONAL_MCPS"] == str(catalog) + + @pytest.mark.parametrize( + ("key", "expected"), + [ + ("Path", "PATH"), + ("Hermes_Yolo_Mode", "HERMES_YOLO_MODE"), + ("Hermes_Optional_Mcps", "HERMES_OPTIONAL_MCPS"), + ("Hermes_Copilot_Acp_Command", "HERMES_COPILOT_ACP_COMMAND"), + ("Hermes_Copilot_Acp_Args", "HERMES_COPILOT_ACP_ARGS"), + ], + ) + def test_windows_policy_names_are_case_insensitive(self, key, expected): + from hermes_cli.config import _env_var_policy_name + + assert _env_var_policy_name(key, is_windows=True) == expected + + def test_posix_policy_names_remain_case_sensitive(self): + from hermes_cli.config import _env_var_policy_name + + assert _env_var_policy_name("Path", is_windows=False) == "Path" + + @pytest.mark.parametrize("prefix", ["", "export "]) + def test_windows_env_assignment_matching_is_case_insensitive(self, prefix): + from hermes_cli.config import _env_line_defines_key + + line = f"{prefix}Path=C:\\Windows\\System32\n" + assert _env_line_defines_key(line, "PATH", is_windows=True) + assert not _env_line_defines_key(line, "PATH", is_windows=False) + + @pytest.mark.windows_only + @pytest.mark.parametrize( + "protected_key", + [ + "Hermes_Yolo_Mode", + "Hermes_Optional_Mcps", + "Hermes_Copilot_Acp_Command", + "Hermes_Copilot_Acp_Args", + ], + ) + def test_windows_writer_rejects_mixed_case_protected_name(self, protected_key): + with pytest.raises(ValueError, match="denylist"): + save_env_value(protected_key, "1") + def test_save_env_value_secure_inherits_denylist(self): diff --git a/tests/hermes_cli/test_mcp_catalog_env_boundary.py b/tests/hermes_cli/test_mcp_catalog_env_boundary.py new file mode 100644 index 0000000000000..7e131f83edfb8 --- /dev/null +++ b/tests/hermes_cli/test_mcp_catalog_env_boundary.py @@ -0,0 +1,254 @@ +"""Security boundary tests for dashboard MCP catalog credential writes.""" + +from __future__ import annotations + +import os +from pathlib import Path + +import pytest +import yaml +from fastapi.testclient import TestClient + +from hermes_cli.web_server import _SESSION_TOKEN, app + + +HEADERS = {"X-Hermes-Session-Token": _SESSION_TOKEN} + + +@pytest.fixture +def catalog_env(tmp_path: Path, monkeypatch: pytest.MonkeyPatch, _isolate_hermes_home): + """Install one synthetic API-key catalog entry in the isolated test home.""" + from hermes_constants import get_hermes_home + from hermes_cli.config import invalidate_env_cache + + catalog = tmp_path / "optional-mcps" + entry_dir = catalog / "demo" + entry_dir.mkdir(parents=True) + (entry_dir / "manifest.yaml").write_text( + yaml.safe_dump( + { + "manifest_version": 1, + "name": "demo", + "description": "Synthetic dashboard boundary fixture", + "source": "https://example.test/demo", + "transport": { + "type": "stdio", + "command": "demo-mcp", + }, + "auth": { + "type": "api_key", + "env": [ + { + "name": "DEMO_API_KEY", + "prompt": "Demo API key", + "secret": True, + } + ], + }, + } + ), + encoding="utf-8", + ) + monkeypatch.setenv("HERMES_OPTIONAL_MCPS", str(catalog)) + invalidate_env_cache() + return get_hermes_home() + + +@pytest.fixture +def client(): + with TestClient(app) as test_client: + yield test_client + + +def test_catalog_rejects_undeclared_key_before_any_write_or_install( + client: TestClient, + catalog_env: Path, + monkeypatch: pytest.MonkeyPatch, +): + import hermes_cli.mcp_catalog as mcp_catalog + + installs: list[str] = [] + monkeypatch.setattr( + mcp_catalog, + "install_entry", + lambda entry, enable=True: installs.append(entry.name), + ) + + response = client.post( + "/api/mcp/catalog/install", + headers=HEADERS, + json={ + "name": "demo", + "env": { + "DEMO_API_KEY": "valid-demo-value", + "UNRELATED_SETTING": "must-not-land", + }, + }, + ) + + assert response.status_code == 400 + detail = response.json()["detail"] + assert "UNRELATED_SETTING" in detail + assert "valid-demo-value" not in detail + assert "must-not-land" not in detail + assert installs == [] + env_path = catalog_env / ".env" + assert not env_path.exists() or env_path.read_text(encoding="utf-8") == "" + + +def test_catalog_cannot_declare_reserved_control_key( + client: TestClient, + catalog_env: Path, + monkeypatch: pytest.MonkeyPatch, +): + import hermes_cli.mcp_catalog as mcp_catalog + + catalog_root = Path(os.environ["HERMES_OPTIONAL_MCPS"]) + manifest_path = catalog_root / "demo" / "manifest.yaml" + manifest = yaml.safe_load(manifest_path.read_text(encoding="utf-8")) + manifest["auth"]["env"].append( + { + "name": "HERMES_YOLO_MODE", + "prompt": "Unsafe control", + "secret": False, + } + ) + manifest_path.write_text(yaml.safe_dump(manifest), encoding="utf-8") + + installs: list[str] = [] + monkeypatch.setattr( + mcp_catalog, + "install_entry", + lambda entry, enable=True: installs.append(entry.name), + ) + + response = client.post( + "/api/mcp/catalog/install", + headers=HEADERS, + json={"name": "demo", "env": {"HERMES_YOLO_MODE": "1"}}, + ) + + assert response.status_code == 400 + assert "denylist" in response.json()["detail"] + assert installs == [] + env_path = catalog_env / ".env" + assert not env_path.exists() or "HERMES_YOLO_MODE" not in env_path.read_text( + encoding="utf-8" + ) + + +def test_catalog_accepts_declared_credential( + client: TestClient, + catalog_env: Path, + monkeypatch: pytest.MonkeyPatch, +): + import hermes_cli.mcp_catalog as mcp_catalog + + installs: list[str] = [] + monkeypatch.setattr( + mcp_catalog, + "install_entry", + lambda entry, enable=True: installs.append(entry.name), + ) + + response = client.post( + "/api/mcp/catalog/install", + headers=HEADERS, + json={"name": "demo", "env": {"DEMO_API_KEY": "valid-demo-value"}}, + ) + + assert response.status_code == 200 + assert installs == ["demo"] + assert "DEMO_API_KEY=valid-demo-value" in ( + catalog_env / ".env" + ).read_text(encoding="utf-8") + + +@pytest.mark.parametrize( + "protected_key", + [ + "HERMES_YOLO_MODE", + "HERMES_OPTIONAL_MCPS", + "HERMES_COPILOT_ACP_COMMAND", + "HERMES_COPILOT_ACP_ARGS", + ], +) +def test_generic_env_endpoint_rejects_protected_key( + client: TestClient, + catalog_env: Path, + protected_key: str, +): + response = client.put( + "/api/env", + headers=HEADERS, + json={"key": protected_key, "value": "must-not-land"}, + ) + + assert response.status_code == 400 + env_path = catalog_env / ".env" + assert not env_path.exists() or protected_key not in env_path.read_text( + encoding="utf-8" + ) + + +def test_process_supplied_catalog_root_remains_supported(catalog_env: Path): + from hermes_cli.mcp_catalog import get_entry + + assert get_entry("demo") is not None + + +def test_rejected_copilot_controls_do_not_change_live_resolvers( + client: TestClient, + catalog_env: Path, + monkeypatch: pytest.MonkeyPatch, +): + from agent.copilot_acp_client import _resolve_args, _resolve_command + + monkeypatch.setenv("HERMES_COPILOT_ACP_COMMAND", "/opt/trusted/copilot") + monkeypatch.setenv("HERMES_COPILOT_ACP_ARGS", "--acp --stdio") + expected_command = _resolve_command() + expected_args = _resolve_args() + + attempts = { + "HERMES_COPILOT_ACP_COMMAND": "/tmp/attacker-command", + "HERMES_COPILOT_ACP_ARGS": "--malicious-transport", + } + for key, value in attempts.items(): + response = client.put( + "/api/env", + headers=HEADERS, + json={"key": key, "value": value}, + ) + assert response.status_code == 400 + + assert _resolve_command() == expected_command + assert _resolve_args() == expected_args + env_path = catalog_env / ".env" + if env_path.exists(): + env_text = env_path.read_text(encoding="utf-8") + assert "/tmp/attacker-command" not in env_text + assert "--malicious-transport" not in env_text + + +def test_preexisting_copilot_controls_remain_usable( + catalog_env: Path, + monkeypatch: pytest.MonkeyPatch, +): + from agent.copilot_acp_client import _resolve_args, _resolve_command + from hermes_cli.env_loader import load_hermes_dotenv + + monkeypatch.setenv("HERMES_COPILOT_ACP_COMMAND", "parent-placeholder") + monkeypatch.setenv("HERMES_COPILOT_ACP_ARGS", "--parent-placeholder") + (catalog_env / ".env").write_text( + "HERMES_COPILOT_ACP_COMMAND=/opt/operator/copilot\n" + "HERMES_COPILOT_ACP_ARGS=--acp --stdio --operator-mode\n", + encoding="utf-8", + ) + + load_hermes_dotenv( + hermes_home=catalog_env, + load_external_secrets=False, + ) + + assert _resolve_command() == "/opt/operator/copilot" + assert _resolve_args() == ["--acp", "--stdio", "--operator-mode"]