fix(install): write deployment secrets owner-only and disclose the --env path

`headroom install --env KEY=VALUE` is the only channel that reaches a
supervised proxy (launchd/systemd/cron start it from a bare environment), so
it is the supported way to hand one a provider API key. Every value is then
persisted verbatim: into `~/.headroom/deploy/<profile>/manifest.json` and,
in cleartext `export` lines, into the generated runner scripts.

Those scripts were written 0755 and the profile directory 0755, so a live
API key was world-readable; the manifest was 0600 only incidentally, via
`mkstemp`, with nothing pinning it.

Keep the persistence — removing it would leave supervised proxies with no
credential at runtime — but restrict it (manifest 0600, runner scripts 0700,
profile directory 0700, narrowed on every save so upgrades are fixed too) and
disclose it accurately. SECURITY.md previously claimed keys are not written to
disk, which this path falsifies.

Tests read the documented octal modes back out of SECURITY.md and compare them
with what a real install writes, so policy and code cannot drift again.
This commit is contained in:
Tejas Chopra
2026-09-23 11:10:32 +02:00
parent 86ae04c5a4
commit 3da8b95543
8 changed files with 363 additions and 13 deletions
+26 -6
View File
@@ -57,12 +57,32 @@ The following are out of scope:
Headroom includes several security features:
- **Credential handling**: Provider API keys are read from the environment and
forwarded upstream; Headroom does not write them to disk. One credential is
persisted deliberately: `headroom copilot login` stores the GitHub Copilot
OAuth refresh token in `~/.headroom/copilot_auth.json`, created with mode
`0600`. Request and response bodies may be written to the runtime log when
logging is enabled, so treat that log as sensitive.
- **Credential handling**: In interactive use (`headroom proxy`, `headroom
wrap`) provider API keys are read from the process environment and forwarded
upstream; that path writes no credential to disk. Two paths do persist
credentials, both deliberately:
- `headroom copilot login` stores the GitHub Copilot OAuth refresh token in
`~/.headroom/copilot_auth.json`, created with mode `0600`.
- A persistent install stores every value passed to `headroom install --env
KEY=VALUE`, verbatim and in cleartext. Supervisors (launchd, systemd, Task
Scheduler, cron) start the proxy from a bare environment, so `--env` is the
only channel by which a provider API key reaches a supervised proxy — and
if you pass one, it is written to
`~/.headroom/deploy/<profile>/manifest.json` (mode `0600`) and `export`ed in
cleartext by the generated runner scripts `run-headroom.sh` /
`ensure-headroom.sh` (mode `0700`) in the same directory (mode `0700`).
These files are owner-only, not encrypted: anything that can read the
account — the user themself, root, a home-directory backup or sync — can
read the key, and rotating it requires re-running `headroom install apply`.
With the Docker runtime the same values are additionally passed as `docker
run --env NAME=VALUE`, which places them in the container process's command
line and so in `ps` output for other users on the host. Prefer a
supervisor-native secret facility (systemd `LoadCredential=` /
`EnvironmentFile=` on an owner-only file, a macOS keychain helper) over
`--env` for long-lived provider keys.
Request and response bodies may be written to the runtime log when logging is
enabled, so treat that log as sensitive.
- **Passthrough mode**: Sensitive content passes through unchanged by default
- **Input validation**: All inputs are validated before processing
- **Safe defaults**: Security-conscious defaults out of the box
+4 -1
View File
@@ -593,7 +593,10 @@ def _echo_installed(manifest: DeploymentManifest, *, prefix: str = "Installed pe
"--env HEADROOM_WORKSPACE_DIR=/path. Supervisors (launchd, systemd, cron) "
"start with a bare environment and do not inherit the interactive shell's "
"exports, so anything the runtime needs beyond the flags above must be set "
"here. Repeatable."
"here. Repeatable. Values are stored in cleartext in the profile's "
"manifest and runner scripts under ~/.headroom/deploy/<profile>/ "
"(owner-only, not encrypted); see SECURITY.md before passing a provider "
"API key this way."
),
)
def install_apply(
+32
View File
@@ -13,6 +13,38 @@ from headroom import paths as _paths
_PROFILE_RE = re.compile(r"^[A-Za-z0-9._-]+$")
# A deployment profile directory holds secrets. `headroom install --env
# KEY=VALUE` is the supported way to give a supervised proxy a provider API key
# — supervisors (launchd, systemd, Task Scheduler, cron) start from a bare
# environment, so nothing else reaches the process — and every such value is
# persisted verbatim, both into `manifest.json` and into the generated runner
# scripts that `export` it before the exec. Those files are therefore written
# owner-only rather than at the process umask (which leaves them world-readable
# at the common 022). The supervisor always runs them as the installing user
# (user scope) or as root (system scope), and neither needs the group/other
# bits, so this is not a functional restriction.
#
# SECURITY.md documents these modes; `tests/test_packaging_extras_and_security_docs.py`
# reads the octal values back out of that document and compares them with what
# an install actually writes, so the policy and the code cannot drift apart.
SECRET_FILE_MODE = 0o600
SECRET_SCRIPT_MODE = 0o700
SECRET_DIR_MODE = 0o700
def chmod_owner_only(path: Path, mode: int) -> None:
"""Best-effort ``chmod`` to an owner-only ``mode``.
POSIX permission bits are advisory on Windows (access is governed by ACLs)
and some filesystems reject ``chmod`` outright; a deployment must not fail
to install over it, so a failure is logged by the caller's context rather
than raised.
"""
try:
path.chmod(mode)
except OSError: # pragma: no cover - platform/filesystem dependent
pass
def validate_profile_name(profile: str) -> str:
"""Validate and normalize a deployment profile name."""
+27 -1
View File
@@ -12,7 +12,14 @@ from pathlib import Path
from typing import Any
from .models import ArtifactRecord, DeploymentManifest, ManagedMutation, iso_utc_now
from .paths import deploy_root, manifest_path, profile_root
from .paths import (
SECRET_DIR_MODE,
SECRET_FILE_MODE,
chmod_owner_only,
deploy_root,
manifest_path,
profile_root,
)
logger = logging.getLogger(__name__)
@@ -29,6 +36,15 @@ def _atomic_write_text(path: Path, data: str) -> None:
both POSIX and Windows). A crash between truncate and full write therefore
leaves either the previous file or the complete new one on disk, never a
truncated manifest.
The file is owner-only. ``manifest.base_env`` holds whatever
``headroom install --env KEY=VALUE`` was given, and that is the supported
way to hand a provider API key to a supervised proxy (supervisors start
from a bare environment), so the manifest must be assumed to contain
secrets. :func:`tempfile.mkstemp` already creates the temporary file 0600
and :func:`os.replace` carries that mode across, but the chmod is explicit
so the guarantee survives a future rewrite of this function and is pinned
by a test rather than inherited by accident.
"""
directory = path.parent
fd, tmp_name = tempfile.mkstemp(dir=directory, prefix=f".{path.name}.", suffix=".tmp")
@@ -38,6 +54,7 @@ def _atomic_write_text(path: Path, data: str) -> None:
handle.write(data)
handle.flush()
os.fsync(handle.fileno())
chmod_owner_only(tmp_path, SECRET_FILE_MODE)
os.replace(tmp_path, path)
except BaseException:
tmp_path.unlink(missing_ok=True)
@@ -50,10 +67,19 @@ def save_manifest(manifest: DeploymentManifest) -> None:
The write is atomic so an interrupted save (SIGKILL, system restart, OOM)
cannot leave a truncated ``manifest.json`` behind. Gracefully handles
read-only filesystems by logging a warning instead of crashing.
The profile directory and the manifest are owner-only: ``base_env`` carries
whatever ``headroom install --env`` was given, which is the supported way to
hand a provider API key to a supervised proxy. See
:data:`headroom.install.paths.SECRET_DIR_MODE`.
"""
try:
root = profile_root(manifest.profile)
root.mkdir(parents=True, exist_ok=True)
# `exist_ok=True` leaves a pre-existing directory's mode alone, and a
# profile created before this change is 0755, so narrow it every save
# rather than only at creation.
chmod_owner_only(root, SECRET_DIR_MODE)
manifest.updated_at = iso_utc_now()
path = manifest_path(manifest.profile)
_atomic_write_text(path, json.dumps(asdict(manifest), indent=2) + "\n")
+42 -5
View File
@@ -20,6 +20,9 @@ from headroom._subprocess import run
from .models import ArtifactRecord, DeploymentManifest, SupervisorKind
from .paths import (
SECRET_FILE_MODE,
SECRET_SCRIPT_MODE,
chmod_owner_only,
unix_ensure_script_path,
unix_run_script_path,
windows_ensure_cmd_path,
@@ -46,6 +49,27 @@ def _is_windows() -> bool:
return sys.platform.startswith("win")
def _write_private_text(path: Path, data: str, mode: int) -> None:
"""Write ``data`` to ``path`` without ever exposing it at the umask.
The runner scripts ``export`` every entry of ``manifest.base_env`` in
cleartext, and ``headroom install --env KEY=VALUE`` is the supported way to
put a provider API key there, so these files are secret-bearing. Creating
the file with :func:`os.open` and an explicit mode — rather than writing
first and chmod'ing after — closes the window in which a world-readable
file holding a live API key exists on disk. An existing file keeps its old
mode through ``O_TRUNC``, so chmod afterwards as well to narrow scripts
written by an earlier version.
"""
path.parent.mkdir(parents=True, exist_ok=True)
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, mode)
# Newline handling is left at the default so the bytes written match what
# `Path.write_text` produced before, on every platform.
with os.fdopen(fd, "w", encoding="utf-8") as handle:
handle.write(data)
chmod_owner_only(path, mode)
def _validated_env_items(env: dict[str, str] | None) -> list[tuple[str, str]]:
items = list((env or {}).items())
for name, _value in items:
@@ -100,14 +124,19 @@ def _render_unix_runner(
export_lines = "".join(
f"export {name}={shlex.quote(value)}\n" for name, value in _validated_env_items(env)
)
path.write_text(
# 0700, not 0755: `export_lines` can contain a provider API key in
# cleartext (see `_write_private_text`). The supervisor runs this script as
# the installing user for a user-scope install and as root for a
# system-scope one, so dropping group/other loses nothing.
_write_private_text(
path,
"#!/usr/bin/env bash\nset -euo pipefail\n"
+ export_lines
+ "exec "
+ " ".join(shlex.quote(x) for x in command)
+ "\n"
+ "\n",
SECRET_SCRIPT_MODE,
)
path.chmod(0o755)
return ArtifactRecord(kind="script", path=str(path))
@@ -123,9 +152,17 @@ def _render_windows_runner(
env_lines = "".join(
f"$env:{name} = {_powershell_literal(value)}\n" for name, value in _validated_env_items(env)
)
ps1_path.write_text(
f"$ErrorActionPreference = 'Stop'\n{env_lines}& {escaped}\nexit $LASTEXITCODE\n"
# The .ps1 carries `$env:` assignments that can include a provider API key,
# so it is owner-only like its POSIX counterpart. Windows resolves access
# by ACL rather than by these bits, but the mode still matters when the
# profile directory is read from WSL, a backup, or a synced home.
_write_private_text(
ps1_path,
f"$ErrorActionPreference = 'Stop'\n{env_lines}& {escaped}\nexit $LASTEXITCODE\n",
SECRET_FILE_MODE,
)
# The .cmd shim holds no secrets — it only invokes the .ps1 — so it keeps a
# conventional mode.
cmd_path.write_text(
'@echo off\r\npowershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0'
+ ps1_path.name
+44
View File
@@ -1,11 +1,13 @@
from __future__ import annotations
import json
import sys
from pathlib import Path
import pytest
from headroom.install.models import ArtifactRecord, DeploymentManifest, ManagedMutation
from headroom.install.paths import manifest_path, profile_root
from headroom.install.state import (
ManifestError,
delete_manifest,
@@ -154,3 +156,45 @@ def test_delete_manifest_removes_profile_root(monkeypatch, tmp_path: Path) -> No
assert load_manifest("default") is None
assert not extra_file.parent.exists()
@pytest.mark.skipif(
sys.platform.startswith("win"),
reason="POSIX mode bits are advisory on Windows, where access is governed by ACLs",
)
def test_save_manifest_writes_owner_only(monkeypatch, tmp_path: Path) -> None:
"""`base_env` can hold a provider API key, so the manifest is 0600/0700.
`headroom install --env ANTHROPIC_API_KEY=...` is the supported way to give
a supervised proxy a credential (supervisors start from a bare
environment), and the value is serialized verbatim. At the common 022 umask
a plain write would leave a live key world-readable.
"""
monkeypatch.setattr(Path, "home", lambda: tmp_path)
manifest = _manifest()
manifest.base_env = {"ANTHROPIC_API_KEY": "sk-ant-api03-not-a-real-key"}
save_manifest(manifest)
path = manifest_path("default")
assert "sk-ant-api03-not-a-real-key" in path.read_text(encoding="utf-8")
assert path.stat().st_mode & 0o777 == 0o600
assert path.parent.stat().st_mode & 0o777 == 0o700
@pytest.mark.skipif(
sys.platform.startswith("win"),
reason="POSIX mode bits are advisory on Windows, where access is governed by ACLs",
)
def test_save_manifest_narrows_a_profile_directory_created_before_this_change(
monkeypatch, tmp_path: Path
) -> None:
"""An upgrade must fix an existing 0755 profile directory, not only new ones."""
monkeypatch.setattr(Path, "home", lambda: tmp_path)
root = profile_root("default")
root.mkdir(parents=True)
root.chmod(0o755)
save_manifest(_manifest())
assert root.stat().st_mode & 0o777 == 0o700
+52
View File
@@ -1,5 +1,6 @@
from __future__ import annotations
import sys
from pathlib import Path
import click
@@ -736,3 +737,54 @@ def test_remove_supervisor_darwin_and_windows(monkeypatch, tmp_path: Path) -> No
["schtasks", "/Delete", "/TN", "headroom-default-startup", "/F"],
["schtasks", "/Delete", "/TN", "headroom-default-health", "/F"],
]
@pytest.mark.skipif(
sys.platform.startswith("win"),
reason="POSIX mode bits are advisory on Windows, where access is governed by ACLs",
)
def test_render_runner_scripts_are_owner_only_because_they_export_secrets(
monkeypatch, tmp_path: Path
) -> None:
"""0700, not 0755: the export lines can carry a provider API key.
`headroom install --env ANTHROPIC_API_KEY=...` lands in `base_env`, and
these scripts `export` every entry in cleartext because launchd/systemd
hand the process a bare environment. At 0755 that put a live key in a
world-readable file. The supervisor runs the script as the installing user
(user scope) or as root (system scope), so neither needs the other bits.
"""
monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
monkeypatch.setattr(
"headroom.install.supervisors.resolve_headroom_command", lambda: ["headroom"]
)
monkeypatch.setattr(Path, "home", lambda: tmp_path)
manifest = _manifest(base_env={"ANTHROPIC_API_KEY": "sk-ant-api03-not-a-real-key"})
records = render_runner_scripts(manifest)
assert records
for record in records:
path = Path(record.path)
content = path.read_text(encoding="utf-8")
assert "export ANTHROPIC_API_KEY=sk-ant-api03-not-a-real-key" in content
mode = path.stat().st_mode & 0o777
assert mode == 0o700, f"{path.name} is {mode:04o}, exposing an API key"
@pytest.mark.skipif(
sys.platform.startswith("win"),
reason="POSIX mode bits are advisory on Windows, where access is governed by ACLs",
)
def test_render_unix_runner_narrows_a_script_written_by_an_earlier_version(
monkeypatch, tmp_path: Path
) -> None:
"""Re-running `install apply` must fix an existing 0755 runner script."""
monkeypatch.setattr("headroom.install.supervisors.sys.platform", "linux")
path = tmp_path / "run-headroom.sh"
path.write_text("#!/usr/bin/env bash\n")
path.chmod(0o755)
_render_unix_runner(path, ["headroom", "proxy"], {"ANTHROPIC_API_KEY": "sk-ant-x"})
assert path.stat().st_mode & 0o777 == 0o700
@@ -10,8 +10,10 @@ that silently rots — a build failure instead of a reviewer's job.
from __future__ import annotations
import re
import sys
from pathlib import Path
import pytest
import tomllib
_ROOT = Path(__file__).resolve().parents[1]
@@ -84,3 +86,137 @@ def test_security_policy_does_not_claim_blanket_no_credential_storage() -> None:
"headroom/copilot_auth.py, which persists the Copilot OAuth refresh token"
)
assert "copilot_auth.json" in text, "the one stored credential must stay documented"
# --- The persistent-install credential path -------------------------------
#
# The assertions above are negative string checks: they stop the *old* wording
# coming back, but they would happily pass while the replacement wording is
# itself false (review of PR #3727 — the first correction claimed Headroom
# "does not write [API keys] to disk", which `headroom install --env` falsifies).
#
# So the tests below drive the real install path with a provider key, read what
# actually lands in `~/.headroom/deploy/<profile>/`, and compare it against the
# claims parsed out of SECURITY.md. A change to either side that is not matched
# on the other fails here.
_SECRET = "sk-ant-api03-not-a-real-key"
_MANIFEST_MODE_CLAIM = re.compile(
r"`~/\.headroom/deploy/<profile>/manifest\.json` \(mode `(0[0-7]{3})`\)"
)
_SCRIPT_MODE_CLAIM = re.compile(
r"`run-headroom\.sh` / `ensure-headroom\.sh` \(mode `(0[0-7]{3})`\)"
)
_DIR_MODE_CLAIM = re.compile(r"in the same directory \(mode `(0[0-7]{3})`\)")
def _security_policy_prose() -> str:
"""SECURITY.md with its line wrapping flattened, so claims match as written."""
return re.sub(r"\s+", " ", (_ROOT / "SECURITY.md").read_text(encoding="utf-8"))
def _claimed_mode(pattern: re.Pattern[str]) -> int:
match = pattern.search(_security_policy_prose())
assert match is not None, (
f"SECURITY.md no longer states the mode matched by {pattern.pattern!r}. The "
"persistent-install credential path must keep documenting where a key "
"passed to `headroom install --env` is written and how it is protected."
)
return int(match.group(1), 8)
def _install_with_a_provider_key(home: Path) -> tuple[Path, Path, Path]:
"""Run the real planner/state/supervisor path with a key in ``--env``.
Returns the profile directory, its manifest and its foreground runner
script. Imports are local so the module-level packaging assertions above
still run if the install package fails to import.
"""
from headroom.install.paths import manifest_path, profile_root, unix_run_script_path
from headroom.install.planner import build_manifest
from headroom.install.state import save_manifest
from headroom.install.supervisors import render_runner_scripts
assert Path.home() == home, "the fake HOME monkeypatch did not take effect"
manifest = build_manifest(
profile="default",
preset="persistent-service",
runtime_kind="python",
scope="user",
provider_mode="manual",
targets=[],
port=8787,
backend="anthropic",
anyllm_provider=None,
region=None,
proxy_mode="passthrough",
memory_enabled=False,
telemetry_enabled=False,
image="ghcr.io/headroomlabs-ai/headroom:latest",
extra_env={"ANTHROPIC_API_KEY": _SECRET},
)
save_manifest(manifest)
render_runner_scripts(manifest)
return profile_root("default"), manifest_path("default"), unix_run_script_path("default")
@pytest.mark.skipif(
sys.platform.startswith("win"),
reason="POSIX mode bits are advisory on Windows, where access is governed by ACLs",
)
def test_install_env_persists_a_provider_key_exactly_as_the_policy_describes(
monkeypatch: pytest.MonkeyPatch, tmp_path: Path
) -> None:
"""`--env ANTHROPIC_API_KEY=...` really does write the key to disk.
This is deliberate — supervisors start from a bare environment, so `--env`
is the only channel that reaches a supervised proxy — but it means the
policy may not claim keys are never written. Pin both halves: that the key
lands where SECURITY.md says, and that it lands owner-only.
"""
monkeypatch.setattr(Path, "home", lambda: tmp_path)
profile_dir, manifest_file, run_script = _install_with_a_provider_key(tmp_path)
# 1. What lands on disk. Both files carry the key in cleartext; the runner
# script `export`s it because launchd/systemd hand the process nothing.
assert manifest_file.exists(), "a persistent install must write a manifest"
assert _SECRET in manifest_file.read_text(encoding="utf-8"), (
"the key passed to --env is stored verbatim in manifest.json; if that "
"stopped being true, SECURITY.md and the --env help must change with it"
)
assert run_script.exists(), "a persistent install must write a runner script"
assert f"export ANTHROPIC_API_KEY={_SECRET}" in run_script.read_text(encoding="utf-8")
# 2. With what protection — read back out of the policy document, so the
# two cannot drift.
assert manifest_file.stat().st_mode & 0o777 == _claimed_mode(_MANIFEST_MODE_CLAIM)
assert run_script.stat().st_mode & 0o777 == _claimed_mode(_SCRIPT_MODE_CLAIM)
assert profile_dir.stat().st_mode & 0o777 == _claimed_mode(_DIR_MODE_CLAIM)
# 3. And, concretely: nothing in that directory is readable by group or
# other, whatever the umask was.
for path in [profile_dir, *profile_dir.iterdir()]:
assert not path.stat().st_mode & 0o077, f"{path.name} is readable beyond its owner"
def test_security_policy_discloses_the_persistent_install_credential_path() -> None:
"""The policy must name the `--env` path, not just the Copilot token."""
prose = _security_policy_prose()
assert "does not write them to disk" not in prose, (
"`headroom install --env ANTHROPIC_API_KEY=...` writes the key to "
"~/.headroom/deploy/<profile>/, so a blanket 'not written to disk' "
"claim is false"
)
assert "headroom install --env KEY=VALUE" in prose, (
"the supported way to hand a supervised proxy a provider key must be "
"documented as a credential-persistence path"
)
assert "~/.headroom/deploy/<profile>/manifest.json" in prose
assert "owner-only, not encrypted" in prose, (
"owner-only file modes are not encryption; the policy must say so "
"rather than let a reader infer the key is protected at rest"
)