fix(codex): preserve sandbox certificate trust in Codex shell commands (#20364)

<!-- Written in ASD-STE100 style: short sentences, active voice. -->

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The Paperclip Runner and the Codex adapters run agent shell commands
inside a sandboxed Codex session with a strict environment allowlist
> - The controller builds `shell_environment_policy.include_only` before
the sandbox injects certificate-trust variables such as `SSL_CERT_FILE`
and `GIT_SSL_CAINFO`
> - The allowlist drops the injected variables, so managed `git` and
`gh` commands cannot verify HTTPS against a runtime-provided CA
> - This pull request allows the certificate-trust variable names
through every environment policy stage, from the Rust process supervisor
to the shell allowlist
> - The benefit is that managed `git` and `gh` work again in sandboxes
that require a runtime CA, while provider-credential isolation and the
bounded allowlist stay in place

## Linked Issues or Issue Description

- Fixes: #20019
- Refs #20038 — community pull request for the same defect. This change
reviews the approach independently. The commit credits the community
author as co-author.

## What Changed

- Add `CERTIFICATE_ENVIRONMENT_KEYS` (`SSL_CERT_FILE`, `SSL_CERT_DIR`,
`GIT_SSL_CAINFO`, `NODE_EXTRA_CA_CERTS`, `DENO_CERT`,
`REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`) to
`packages/paperclip-runner/src/configured-environment.ts`
- Native Codex shell policy (`codex-security-config.ts`): always put the
certificate names in `include_only`; set inheritance to `"all"` with
`ignore_default_excludes=true`, bounded by the explicit allowlist
- Pass the certificate names through the app-server environment filter,
the ACPX spawn environment filter, the ACPX runtime sandbox
`include_only`, the runner platform environment keys, and the Rust
process supervisor base key list
- Legacy and ACPX-engine Codex shell allowlists
(`packages/adapter-utils/src/codex-shell-environment.ts`): always
include the certificate names
- Add a synthetic private-CA HTTPS journey test: a real `git ls-remote`
fails TLS verification without the injected CA and succeeds with it,
through the policy-filtered child environment
- Document the contract in `doc/sandbox-shell-environment.md` and link
it from `doc/DEVELOPING.md`

## Verification

- `pnpm --filter @paperclipai/paperclip-runner exec vitest run
src/drivers/codex/codex-security-config.test.ts
src/configured-environment.test.ts
src/drivers/codex/codex-shell-certificate-trust.test.ts
src/drivers/codex/codex-app-server-driver.context-control.test.ts
src/drivers/acpx/runtime-sandbox.test.ts` — 104 tests pass
- `pnpm --filter @paperclipai/adapter-utils exec vitest run
src/codex-shell-environment.test.ts src/acpx-engine/execute.test.ts` —
270 tests pass
- `pnpm --filter @paperclipai/adapter-codex-local exec vitest run
src/server/execute.test.ts` — 10 tests pass
- Codex driver lifecycle, conformance, recovery, and boundaries suites
pass (103 tests); environment-builder suites pass (307 tests)
- Red proof: with only the source fix reverted, the new regressions
fail. The journey test shows `GIT_SSL_CAINFO` is undefined in the shell
environment, and `git` fails TLS verification against the private-CA
fixture
- `cargo check` passes for `paperclip-runner-core`; `rustfmt --check`
passes for the edited Rust file
- The journey test needs `git` and `openssl`; it skips when either tool
is absent

## Risks

- The native shell policy now always sets
`shell_environment_policy.inherit="all"` with
`ignore_default_excludes=true`. Before, it set `"none"` when no
credentials or task keys were projected. The explicit `include_only`
allowlist still bounds every inherited name, so no new secret names can
cross
- The allowlist grows by seven non-secret certificate-trust names. Their
values point at CA files. The sandbox filesystem policy still controls
access to those files; this change grants no filesystem access
- No persisted run, session, or launch identity changes shape. Sessions
saved by the previous release resume unchanged; the new policy applies
when the next launch builds its arguments
- Provider credentials keep their existing exclusions at every stage

## Model Used

- Claude Fable 5 (Anthropic, model ID `claude-fable-5`), extended
thinking, agentic tool use, run through Claude Code. The implementation
was written and reviewed independently against the community design in
#20038; the community author is credited as co-author in the commit.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green (pending: checks run after this
PR opens)
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
(pending review)
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: everlastingcrown <everlastingcrown@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
authored and GitHub committed 2026-11-13 14:13:01 -06:00
1 parent d018a9d1cd
commit 7773b52f05
18 files changed
+312 -28

No files matched your search

+5
View File
@@ -2579,6 +2579,11 @@ For `codex_local`, Paperclip assigns new and updated agents an isolated Codex ho
Paperclip also persists an empty `OPENAI_API_KEY` override for those agents so a host-level `OPENAI_API_KEY` cannot leak into Codex runs through process inheritance. If an operator explicitly configures `adapterConfig.env.CODEX_HOME`, it must not point at the shared company `codex-home`, `$CODEX_HOME`, or `~/.codex`.
Codex shell commands keep sandbox-injected certificate-trust variables (for
example `SSL_CERT_FILE` and `GIT_SSL_CAINFO`) even though the shell environment
allowlist is constructed before the sandbox injects them. See
[Codex shell certificate trust](sandbox-shell-environment.md).
If the `codex` CLI is not installed or not on `PATH`, `codex_local` agent runs fail at execution time with a clear adapter error. Quota polling uses a short-lived `codex app-server` subprocess: when `codex` cannot be spawned, that provider reports `ok: false` in aggregated quota results and the API server keeps running (it must not exit on a missing binary).
Local adapters require their corresponding CLI/session setup on the machine running Paperclip. Self-hosted instances can install external adapters through the adapter/plugin flow without hardcoded imports in `server/` or `ui/`.
+26
View File
@@ -0,0 +1,26 @@
# Codex shell certificate trust
Codex shell environment policies always allow these certificate-trust variable
names through `shell_environment_policy.include_only`:
`SSL_CERT_FILE`, `SSL_CERT_DIR`, `GIT_SSL_CAINFO`, `NODE_EXTRA_CA_CERTS`,
`DENO_CERT`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`.
Sandbox runtimes inject these variables into the execution environment when
they launch the agent, after the controller has already constructed the shell
environment policy. The policy therefore allows the names even when no value
exists on the controller at policy-construction time. Values come from the
execution environment at launch; missing variables remain unset; values are
never serialized into Codex arguments or configuration. The same names pass
the supervised-process and app-server environment filters so an injected value
survives every stage down to the model-issued shell command.
This list carries trust configuration only. Provider credentials keep their
existing exclusions, and shell inheritance stays bounded by the explicit
`include_only` allowlist. Allowing the names also grants no filesystem access:
the CA file or directory a variable points at must already be readable under
the sandbox's existing filesystem policy.
The canonical name list is `CERTIFICATE_ENVIRONMENT_KEYS` in
`packages/paperclip-runner/src/configured-environment.ts`; the legacy adapter
mirror lives in `packages/adapter-utils/src/codex-shell-environment.ts`.
@@ -703,7 +703,7 @@ describe("shared ACPX engine runtime behavior", () => {
} : {}),
});
const config = JSON.parse(String((meta[0]?.env as Record<string, string>).CODEX_CONFIG ?? "{}"));
expect(config.shell_environment_policy?.include_only).toContain("SLACK_BOT_TOKEN");
expect(config.shell_environment_policy?.include_only).toEqual(expect.arrayContaining(["SLACK_BOT_TOKEN", "SSL_CERT_FILE", "SSL_CERT_DIR", "GIT_SSL_CAINFO", "NODE_EXTRA_CA_CERTS", "DENO_CERT", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE"]));
if (withIdentity) expect(config.shell_environment_policy.include_only).toEqual(expect.arrayContaining([
"PAPERCLIP_API_KEY", "PAPERCLIP_AGENT_PRIVATE_KEY",
]));
@@ -42,3 +42,11 @@ it("passes the run's GitHub broker capability so the gh and git launchers can fe
expect(names).not.toContain("PAPERCLIP_GITHUB_BRIDGE_TOKEN");
expect(JSON.stringify(names)).not.toContain("capability");
});
it.each([false, true])("keeps certificate-trust names allowed before sandbox values exist (identity %s)", (identity) => {
const names = codexShellEnvironmentKeys({}, {}, identity);
expect(names).toEqual(expect.arrayContaining([
"SSL_CERT_FILE", "SSL_CERT_DIR", "GIT_SSL_CAINFO", "NODE_EXTRA_CA_CERTS", "DENO_CERT", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE",
]));
expect(names).not.toContain("OPENAI_API_KEY");
});
@@ -26,6 +26,9 @@ export function codexShellEnvironmentKeys(
.map(([key]) => key));
return [...new Set([
"PATH", "HOME", "LANG", "LANGUAGE", "LC_ALL", "LC_CTYPE", "TZ", "TMPDIR", "TEMP", "TMP", "CODEX_HOME",
// Certificate-trust names stay inheritable even when the launch environment
// does not carry them yet: sandboxes inject the values at execution time.
"SSL_CERT_FILE", "SSL_CERT_DIR", "GIT_SSL_CAINFO", "NODE_EXTRA_CA_CERTS", "DENO_CERT", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE",
...Object.keys(environment).filter(key => ENVIRONMENT_NAME.test(key) && !PROVIDER_ONLY_KEYS.has(key.toUpperCase())
&& (key === "PAPERCLIP_API_KEY" || configuredSecrets.has(key) || !SECRET_NAME.test(key))),
...GITHUB_LAUNCHER_KEYS.filter(key => environment[key]),
@@ -198,7 +198,7 @@ describe("codex execute — outbound auth copy-back restore contribution", () =>
});
const policy = commandArgs.find(arg => arg.startsWith("shell_environment_policy.include_only="));
const keys = policy ? JSON.parse(policy.slice(policy.indexOf("=") + 1)) : [];
expect(keys).toContain("SLACK_BOT_TOKEN");
expect(keys).toEqual(expect.arrayContaining(["SLACK_BOT_TOKEN", "SSL_CERT_FILE", "SSL_CERT_DIR", "GIT_SSL_CAINFO", "NODE_EXTRA_CA_CERTS", "DENO_CERT", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE"]));
if (withIdentity) expect(keys).toEqual(expect.arrayContaining([
"PAPERCLIP_API_KEY", "PAPERCLIP_AGENT_PRIVATE_KEY",
]));
@@ -1078,6 +1078,15 @@ impl SupervisedProcess {
"TEMP",
"TMP",
"TZ",
// Certificate-trust names flow to every supervised process so
// execution-side injected values survive the cleared environment.
"SSL_CERT_FILE",
"SSL_CERT_DIR",
"GIT_SSL_CAINFO",
"NODE_EXTRA_CA_CERTS",
"DENO_CERT",
"REQUESTS_CA_BUNDLE",
"CURL_CA_BUNDLE",
]
.into_iter()
.chain(additional_environment_keys.iter().copied())
@@ -1,4 +1,4 @@
import { CONFIGURED_ENVIRONMENT_KEYS, SECRET_ENVIRONMENT_KEYS, configuredEnvironment, configuredEnvironmentProjection, configuredSecretEnvironment } from './configured-environment.js';
import { CERTIFICATE_ENVIRONMENT_KEYS, CONFIGURED_ENVIRONMENT_KEYS, SECRET_ENVIRONMENT_KEYS, configuredEnvironment, configuredEnvironmentProjection, configuredSecretEnvironment } from './configured-environment.js';
import { describe, expect, it, vi } from 'vitest';
import { createSanitizedCodexEnvironment } from './drivers/codex/app-server-transport.js';
import { createIsolatedCodexAppServerArgs } from './drivers/codex/codex-security-config.js';
@@ -164,3 +164,16 @@ describe("configured secret names", () => {
expect(JSON.parse(opencode[CONFIGURED_ENVIRONMENT_KEYS]!)).not.toContain(SECRET_ENVIRONMENT_KEYS);
});
});
it("preserves sandbox certificate trust injected after policy construction", async () => {
const args = createIsolatedCodexAppServerArgs({ PATH: "/bin" });
const setting = args.find(value => value.startsWith("shell_environment_policy.include_only="))!;
const keys = JSON.parse(setting.slice(setting.indexOf("=") + 1)) as string[];
expect(keys).toEqual(expect.arrayContaining([...CERTIFICATE_ENVIRONMENT_KEYS]));
const injected = Object.fromEntries(CERTIFICATE_ENVIRONMENT_KEYS.map(key => [key, `/execution/${key.toLowerCase()}`]));
expect(createSanitizedCodexEnvironment(injected)).toMatchObject(injected);
const { createSanitizedAcpxSpawnInput } = await import("./drivers/acpx/environment.js");
expect({ ...createSanitizedAcpxSpawnInput(injected, "codex").env }).toMatchObject(injected);
// Names cross as policy; the injected values never serialize into argv.
for (const value of Object.values(injected)) expect(args.join("\n")).not.toContain(value);
});
@@ -7,6 +7,15 @@ export const CONFIGURED_ENVIRONMENT_KEYS = "PAPERCLIP_CONFIGURED_ENV_KEYS";
/** Names, never values, of configured entries the controller resolved from secrets. */
export const SECRET_ENVIRONMENT_KEYS = "PAPERCLIP_SECRET_ENV_KEYS";
/** Certificate-trust variable names preserved across environment policies.
* Sandboxes inject these at execution time, after controller-side policy
* construction, so policies allow the names even when no value exists yet.
* Values stay in the process environment, never in argv or configuration. */
export const CERTIFICATE_ENVIRONMENT_KEYS = [
"SSL_CERT_FILE", "SSL_CERT_DIR", "GIT_SSL_CAINFO", "NODE_EXTRA_CA_CERTS",
"DENO_CERT", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE",
] as const;
export const GENERATED_RUNTIME_ENVIRONMENT_KEYS: ReadonlySet<string> = new Set([
CONFIGURED_ENVIRONMENT_KEYS,
SECRET_ENVIRONMENT_KEYS,
@@ -1,6 +1,6 @@
import { safeErrorCauseCode } from "./safe-error-cause.js";
import { AGENT_OBSERVABILITY_ENV_KEYS } from "../drivers/agent-observability.js";
import { configuredEnvironment } from "../configured-environment.js";
import { CERTIFICATE_ENVIRONMENT_KEYS, configuredEnvironment } from "../configured-environment.js";
import { spawn } from "node:child_process";
import {
createCipheriv,
@@ -4843,8 +4843,7 @@ const runnerPlatformEnvironmentKeys = [
"HTTPS_PROXY",
"NO_PROXY",
"ALL_PROXY",
"SSL_CERT_FILE",
"SSL_CERT_DIR",
...CERTIFICATE_ENVIRONMENT_KEYS,
"RUST_BACKTRACE",
] as const;
@@ -1,7 +1,7 @@
import { isOpenRouterUrl, openRouterClaudeHeaders } from "../openrouter-attribution.js";
import { sanitizeAntigravityEnvironment } from "./antigravity-environment.js";
import { providerObservabilityEnvironment } from "../agent-observability.js";
import { CONFIGURED_ENVIRONMENT_KEYS, configuredEnvironment, configuredEnvironmentKeys } from "../../configured-environment.js";
import { CERTIFICATE_ENVIRONMENT_KEYS, CONFIGURED_ENVIRONMENT_KEYS, configuredEnvironment, configuredEnvironmentKeys } from "../../configured-environment.js";
import { PI_CREDENTIAL_NAMES, PI_GENERAL_IAM_CREDENTIAL_NAMES, piCredentialNames } from "./pi-provider-config.js";
import { PRECONFIGURED_HOME_KEYS, usesPreconfiguredHome } from "../preconfigured-home.js";
import type { QualifiedAcpxAgent } from "./qualified-profiles.js";
@@ -127,6 +127,7 @@ export function createSanitizedAcpxSpawnInput(
const result: NodeJS.ProcessEnv = { ...configuredEnvironment(environment), ...providerObservabilityEnvironment(environment, agent) };
const credentialNames = agent === "pi" ? piCredentialNames(environment) : ACPX_CREDENTIAL_NAMES[agent];
const allowed = new Set([
...CERTIFICATE_ENVIRONMENT_KEYS,
"PATH",
"LANG",
"LANGUAGE",
@@ -134,9 +135,6 @@ export function createSanitizedAcpxSpawnInput(
"TMPDIR",
"TEMP",
"TMP",
"SSL_CERT_FILE",
"SSL_CERT_DIR",
"NODE_EXTRA_CA_CERTS",
"HTTP_PROXY",
"HTTPS_PROXY",
"NO_PROXY",
@@ -50,7 +50,7 @@ describe("ACPX runtime sandbox", () => {
} });
const config = await readFile(join(sandbox.agentHomeDirectory, "config.toml"), "utf8");
const keys = JSON.parse(config.split("\n").find(line => line.startsWith("include_only = "))?.slice("include_only = ".length) ?? "[]");
expect(keys).toEqual(expect.arrayContaining(Object.keys(pages)));
expect(keys).toEqual(expect.arrayContaining([...Object.keys(pages), "SSL_CERT_FILE", "SSL_CERT_DIR", "GIT_SSL_CAINFO", "NODE_EXTRA_CA_CERTS", "DENO_CERT", "REQUESTS_CA_BUNDLE", "CURL_CA_BUNDLE"]));
expect(keys).not.toContain("OPENAI_API_KEY");
expect(keys).not.toContain("HOST_SECRET");
expect(keys).not.toContain("PAPERCLIP_OBSERVABILITY_CODEX_CONFIG");
@@ -2,7 +2,7 @@ import { kimiManagedConfiguration } from "./kimi-config.js";
import { kimiInstructionBinding } from "./kimi-instructions.js";
import { AGENT_OBSERVABILITY_ENV_KEYS, codexObservabilityToml } from "../agent-observability.js";
import { piProviderConfiguration } from "./pi-provider-config.js";
import { configuredEnvironmentKeys } from "../../configured-environment.js";
import { CERTIFICATE_ENVIRONMENT_KEYS, configuredEnvironmentKeys } from "../../configured-environment.js";
import { COPILOT_SYSTEM_INSTRUCTIONS_FILE } from "./copilot-profile.js";
import { preparedHarnessHome, preconfiguredHomeEnvironment, usesPreconfiguredHome } from "../preconfigured-home.js";
import { randomBytes } from "node:crypto";
@@ -513,6 +513,8 @@ export async function prepareAcpxRuntimeSandbox(input: {
`include_only = ${JSON.stringify([...new Set([
"PATH", "HOME", "LANG", "LANGUAGE", "TZ", "TMPDIR", "TEMP", "TMP", "CODEX_HOME",
"PAPERCLIP_AGENT_KEY_ID", "PAPERCLIP_AGENT_PUBLIC_KEY", "PAPERCLIP_AGENT_PRIVATE_KEY",
// Certificate-trust names stay inheritable for execution-side injection.
...CERTIFICATE_ENVIRONMENT_KEYS,
...taskEnvironmentKeys,
// Unselected provider/config secrets keep Codex's default shell exclusions;
// only Paperclip's scoped API token is required by Bash/curl skills.
@@ -1,4 +1,4 @@
import { configuredEnvironment } from "../../configured-environment.js";
import { CERTIFICATE_ENVIRONMENT_KEYS, configuredEnvironment } from "../../configured-environment.js";
import type { DurableRecoveryIdentity } from "../../contracts/durable-recovery.js";
import type { NativeTurnControlCapabilities } from "../../contracts/types.js";
import type { NativeRunRuntimeGrant } from "../../contracts/runtime-context.js";
@@ -230,6 +230,7 @@ class BoundedLineDecoder {
}
const SAFE_ENVIRONMENT_KEYS = [
...CERTIFICATE_ENVIRONMENT_KEYS,
"OTEL_EXPORTER_OTLP_LOGS_TIMEOUT", "OTEL_EXPORTER_OTLP_TRACES_TIMEOUT",
"AGENT_HOME",
"ALL_PROXY",
@@ -242,7 +243,6 @@ const SAFE_ENVIRONMENT_KEYS = [
"LANG",
"LC_ALL",
"NO_PROXY",
"NODE_EXTRA_CA_CERTS",
"PAPERCLIP_RUNNER_EXTERNAL_SANDBOX",
"PAPERCLIP_RUNNER_HOME_MODE",
"XDG_CONFIG_HOME",
@@ -250,7 +250,6 @@ const SAFE_ENVIRONMENT_KEYS = [
"XDG_CACHE_HOME",
"PATH",
"PATHEXT",
"SSL_CERT_FILE",
"SystemRoot",
"TEMP",
"TMP",
@@ -155,7 +155,8 @@ describe("Codex app-server Codex driver", () => {
"permissions.paperclip-runner-workspace-only.filesystem=",
),
"permissions.paperclip-runner-workspace-only.network.enabled=false",
'shell_environment_policy.inherit="none"',
'shell_environment_policy.inherit="all"',
"shell_environment_policy.ignore_default_excludes=true",
expect.stringContaining(
'shell_environment_policy.set={PATH="/bin",LANG="C.UTF-8"}',
),
@@ -1,3 +1,4 @@
import { CERTIFICATE_ENVIRONMENT_KEYS } from "../../configured-environment.js";
import { createRequire } from "node:module";
import { execFileSync } from "node:child_process";
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
@@ -336,7 +337,7 @@ describe("Codex security configuration", () => {
SSH_AUTH_SOCK: "/agent/socket", PAPERCLIP_GIT_METADATA_ROOTS: '["/repo/.git","/repo/.git"]',
}).join("\n");
const allowlist = JSON.parse(args.split("\n").find((arg) => arg.startsWith("shell_environment_policy.include_only="))!.split("=", 2)[1]!);
expect(allowlist).toEqual(["GH_CONFIG_DIR", "HOME", "PAPERCLIP_GITHUB_AUTH_MODE", "PAPERCLIP_GITHUB_HOST_HOME", "PAPERCLIP_GIT_METADATA_ROOTS", "PATH", "SSH_AUTH_SOCK"]);
expect(allowlist).toEqual([...CERTIFICATE_ENVIRONMENT_KEYS, "GH_CONFIG_DIR", "HOME", "PAPERCLIP_GITHUB_AUTH_MODE", "PAPERCLIP_GITHUB_HOST_HOME", "PAPERCLIP_GIT_METADATA_ROOTS", "PATH", "SSH_AUTH_SOCK"].sort());
expect(args).not.toContain("must-not-cross");
expect(args).not.toContain("OPENAI_API_KEY");
expect(args).not.toContain("DATABASE_URL");
@@ -439,7 +440,7 @@ describe("Codex security configuration", () => {
expect(serialized).toContain('":workspace_roots"={"."="write"}');
expect(serialized).toContain('":workspace_roots"={"."="read"}');
expect(serialized).toContain("network.enabled=true");
expect(serialized).toContain('shell_environment_policy.include_only=["LANG","PAPERCLIP_RUNNER_NETWORK_ACCESS","PATH"]');
expect(serialized).toContain(`shell_environment_policy.include_only=${JSON.stringify([...CERTIFICATE_ENVIRONMENT_KEYS, "LANG", "PAPERCLIP_RUNNER_NETWORK_ACCESS", "PATH"].sort())}`);
expect(serialized).toContain('PATH="/safe/bin"');
expect(serialized).toContain('LANG="C.UTF-8"');
expect(serialized).not.toContain("OPENAI_API_KEY");
@@ -521,7 +522,7 @@ describe("Codex security configuration", () => {
expect(exclude).toEqual([...CODEX_PROVIDER_CREDENTIAL_ENVIRONMENT_KEYS]);
expect(serialized).not.toContain("fixture-secret-value");
expect(createIsolatedCodexAppServerArgs({ PAPERCLIP_CONFIGURED_ENV_KEYS: '["STRIPE_SECRET_KEY"]', STRIPE_SECRET_KEY: "fixture-secret-value" }).join("\n"))
.toContain('shell_environment_policy.include_only=["STRIPE_SECRET_KEY"]');
.toContain(`shell_environment_policy.include_only=${JSON.stringify([...CERTIFICATE_ENVIRONMENT_KEYS, "STRIPE_SECRET_KEY"].sort())}`);
});
it("excludes every credential the Runner passes to Codex", () => {
@@ -624,3 +625,12 @@ describe("Codex security configuration", () => {
.toBe("permissions.paperclip-runner-workspace-read-only.network.enabled=true");
});
});
it("keeps certificate-trust names in the shell allowlist before sandbox injection", () => {
const args = createIsolatedCodexAppServerArgs({ PATH: "/safe/bin" });
const setting = args.find(value => value.startsWith("shell_environment_policy.include_only="))!;
const allowlist = JSON.parse(setting.slice(setting.indexOf("=") + 1)) as string[];
expect(allowlist).toEqual(expect.arrayContaining([...CERTIFICATE_ENVIRONMENT_KEYS]));
expect(args).toContain('shell_environment_policy.inherit="all"');
expect(args).toContain("shell_environment_policy.ignore_default_excludes=true");
});
@@ -1,5 +1,5 @@
import { usesPreconfiguredHome } from "../preconfigured-home.js";
import { configuredEnvironmentKeys } from "../../configured-environment.js";
import { CERTIFICATE_ENVIRONMENT_KEYS, configuredEnvironmentKeys } from "../../configured-environment.js";
import { resolve, isAbsolute, join, dirname, delimiter, relative, sep } from "node:path";
import { closeSync, constants, existsSync, fstatSync, openSync, realpathSync, readFileSync, statSync } from "node:fs";
import { createRequire } from "node:module";
@@ -272,19 +272,21 @@ export function createIsolatedCodexAppServerArgs(
readOnlyRoots = [...new Set([...readOnlyRoots, ...codexNetworkReadOnlyRoots(source)])];
const networkAccess = codexNetworkAccess(source);
const externalRunnerSandbox = usesExternalRunnerSandbox(source);
const inheritedGitHubKeys = [
const inheritedEnvironmentKeys = [
// Certificate-trust names stay inheritable: sandboxes inject their values
// into the execution environment after this policy is constructed.
...CERTIFICATE_ENVIRONMENT_KEYS,
...githubCredentialEnvironmentKeys(source),
...configuredEnvironmentKeys(explicitSource),
...["PAPERCLIP_AGENT_KEY_ID", "PAPERCLIP_AGENT_PUBLIC_KEY", "PAPERCLIP_AGENT_PRIVATE_KEY"].filter(key => source[key] !== undefined),
];
const hasProjectedEnvironment = inheritedGitHubKeys.length > 0;
// Codex filters the configured `set` values through include_only as well.
// Retain the explicit command PATH/HOME/locale settings, not ambient secrets.
const commandEnvironment = codexCommandEnvironment(source);
// Selected task values are inherited, never serialized into configuration argv.
for (const key of configuredEnvironmentKeys(explicitSource)) delete commandEnvironment[key];
if (instructionWorkingCopyRoot && source.AGENT_HOME === instructionWorkingCopyRoot) commandEnvironment.AGENT_HOME = instructionWorkingCopyRoot;
const shellEnvironmentKeys = [...new Set([...inheritedGitHubKeys, ...Object.keys(commandEnvironment)])].sort();
const shellEnvironmentKeys = [...new Set([...inheritedEnvironmentKeys, ...Object.keys(commandEnvironment)])].sort();
if (source.PAPERCLIP_GITHUB_LAUNCHER_DIR) readOnlyRoots = [...readOnlyRoots, source.PAPERCLIP_GITHUB_LAUNCHER_DIR];
const deniedHostRoots = usesPreconfiguredHome(source) ? [] : [
...new Set(
@@ -370,11 +372,13 @@ export function createIsolatedCodexAppServerArgs(
? ["-c", 'shell_environment_policy.inherit="all"',
"-c", "shell_environment_policy.ignore_default_excludes=true",
"-c", `shell_environment_policy.exclude=${JSON.stringify(CODEX_PROVIDER_CREDENTIAL_ENVIRONMENT_KEYS)}`]
: ["-c", `shell_environment_policy.inherit=${tomlString(hasProjectedEnvironment ? "all" : "none")}`,
"-c", `shell_environment_policy.ignore_default_excludes=${hasProjectedEnvironment}`,
// Codex applies include_only after inheritance. Always emit the bounded
// allowlist: neither host mode nor a broker enables ambient secret access.
// Keep values in the process environment, never in argv/config diagnostics.
// Inheritance stays enabled so execution-side injected values (sandbox
// certificate trust) reach shells; include_only is the strict bound.
// Codex applies include_only after inheritance. Always emit the bounded
// allowlist: neither host mode nor a broker enables ambient secret access.
// Keep values in the process environment, never in argv/config diagnostics.
: ["-c", 'shell_environment_policy.inherit="all"',
"-c", "shell_environment_policy.ignore_default_excludes=true",
"-c", `shell_environment_policy.include_only=${JSON.stringify(shellEnvironmentKeys)}`]),
...(commandEnv.length > 0
? ["-c", `shell_environment_policy.set={${commandEnv}}`]
@@ -0,0 +1,198 @@
import { execFile, execFileSync } from "node:child_process";
import { mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
import { createServer, type Server } from "node:https";
import { tmpdir } from "node:os";
import { join, normalize } from "node:path";
import { promisify } from "node:util";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { createIsolatedCodexAppServerArgs } from "./codex-security-config.js";
import { createSanitizedCodexEnvironment } from "./app-server-transport.js";
import { resolveCodexCommand } from "./codex-command.js";
const execFileAsync = promisify(execFile);
const gitBinary = existsSync("/usr/bin/git") ? "/usr/bin/git" : "git";
const toolsAvailable = (() => {
try {
execFileSync("openssl", ["version"], { stdio: "ignore", timeout: 10_000 });
execFileSync(gitBinary, ["--version"], { stdio: "ignore", timeout: 10_000 });
return true;
} catch {
return false;
}
})();
/** Codex applies the configured policy to the app-server's own environment:
* `inherit` seeds the shell environment, `include_only` filters it by name,
* and `set` entries override afterwards (also bounded by `include_only`). */
function shellEnvironmentFromPolicy(
args: string[],
appServerEnvironment: NodeJS.ProcessEnv,
): Record<string, string> {
const serialized = args.join("\n");
expect(serialized).toContain('shell_environment_policy.inherit="all"');
const includeOnlySetting = args.find((value) =>
value.startsWith("shell_environment_policy.include_only="),
)!;
const includeOnly = new Set<string>(
JSON.parse(includeOnlySetting.slice(includeOnlySetting.indexOf("=") + 1)),
);
const environment: Record<string, string> = {};
for (const [key, value] of Object.entries(appServerEnvironment)) {
if (value !== undefined && includeOnly.has(key)) environment[key] = value;
}
const setSetting = args.find((value) =>
value.startsWith("shell_environment_policy.set={"),
);
if (setSetting) {
const body = setSetting.slice("shell_environment_policy.set={".length, -1);
for (const match of body.matchAll(/([A-Za-z_][A-Za-z0-9_]*)=("(?:[^"\\]|\\.)*")/g)) {
if (includeOnly.has(match[1]!)) environment[match[1]!] = JSON.parse(match[2]!) as string;
}
}
return environment;
}
describe.skipIf(!toolsAvailable)("Codex shell certificate trust (synthetic private-CA journey)", () => {
let root: string;
let caCertificatePath: string;
let server: Server;
let remoteUrl: string;
let launchEnvironment: NodeJS.ProcessEnv;
beforeAll(async () => {
root = mkdtempSync(join(tmpdir(), "codex-ca-trust-"));
const home = join(root, "home");
mkdirSync(home);
const setupEnvironment = { PATH: process.env.PATH!, HOME: home, GIT_CONFIG_NOSYSTEM: "1" };
// Synthetic private CA and a 127.0.0.1 server certificate signed by it.
caCertificatePath = join(root, "ca.pem");
execFileSync("openssl", ["req", "-x509", "-newkey", "rsa:2048", "-sha256", "-days", "2", "-nodes",
"-keyout", join(root, "ca.key"), "-out", caCertificatePath, "-subj", "/CN=paperclip-test-ca"], { stdio: "ignore" });
execFileSync("openssl", ["req", "-newkey", "rsa:2048", "-sha256", "-nodes",
"-keyout", join(root, "server.key"), "-out", join(root, "server.csr"), "-subj", "/CN=127.0.0.1"], { stdio: "ignore" });
writeFileSync(join(root, "ext.cnf"), "subjectAltName=IP:127.0.0.1\n");
execFileSync("openssl", ["x509", "-req", "-in", join(root, "server.csr"), "-CA", caCertificatePath,
"-CAkey", join(root, "ca.key"), "-CAcreateserial", "-out", join(root, "server.pem"), "-days", "2",
"-sha256", "-extfile", join(root, "ext.cnf")], { stdio: "ignore" });
// A bare repository served over the dumb HTTP protocol.
const work = join(root, "work");
execFileSync(gitBinary, ["init", work], { env: setupEnvironment, stdio: "ignore" });
execFileSync(gitBinary, ["-C", work, "-c", "user.email=test@example.invalid", "-c", "user.name=test",
"commit", "--allow-empty", "-m", "fixture"], { env: setupEnvironment, stdio: "ignore" });
const bare = join(root, "repo.git");
execFileSync(gitBinary, ["clone", "--bare", work, bare], { env: setupEnvironment, stdio: "ignore" });
execFileSync(gitBinary, ["--git-dir", bare, "update-server-info"], { env: setupEnvironment, stdio: "ignore" });
server = createServer(
{ key: readFileSync(join(root, "server.key")), cert: readFileSync(join(root, "server.pem")) },
(request, response) => {
const path = normalize((request.url ?? "/").split("?")[0]!);
if (!path.startsWith("/repo.git/") || path.includes("..")) {
response.writeHead(404).end();
return;
}
try {
const body = readFileSync(join(bare, path.slice("/repo.git/".length)));
response.writeHead(200, { "content-type": "text/plain" }).end(body);
} catch {
response.writeHead(404).end();
}
},
);
await new Promise<void>((resolveListen) => server.listen(0, "127.0.0.1", resolveListen));
const address = server.address();
remoteUrl = `https://127.0.0.1:${typeof address === "object" && address ? address.port : 0}/repo.git`;
launchEnvironment = {
PATH: process.env.PATH,
PAPERCLIP_GITHUB_AUTH_MODE: "host",
PAPERCLIP_GITHUB_HOST_HOME: home,
};
}, 120_000);
afterAll(async () => {
await new Promise<void>((resolveClose) => server?.close(() => resolveClose()));
rmSync(root, { recursive: true, force: true });
});
it("fails TLS verification when the shell environment carries no CA trust", async () => {
const args = createIsolatedCodexAppServerArgs(launchEnvironment);
const untrusted = shellEnvironmentFromPolicy(args, createSanitizedCodexEnvironment(launchEnvironment));
const result = await execFileAsync(gitBinary, ["ls-remote", remoteUrl], {
env: untrusted, timeout: 30_000,
}).catch((error: Error & { stderr?: string; code?: number }) => error);
expect(result).toBeInstanceOf(Error);
expect(String((result as { stderr?: string }).stderr ?? "")).toMatch(/SSL|certificate|CA/i);
}, 60_000);
it("verifies TLS through git when the sandbox injects CA trust after policy construction", async () => {
// The policy is constructed from the launch environment, which carries no
// CA variables. The sandbox injects them into the execution environment
// afterwards; the shell policy must still let them through by name.
const args = createIsolatedCodexAppServerArgs(launchEnvironment);
const injectedEnvironment = {
...createSanitizedCodexEnvironment(launchEnvironment),
GIT_SSL_CAINFO: caCertificatePath,
SSL_CERT_FILE: caCertificatePath,
};
const shellEnvironment = shellEnvironmentFromPolicy(args, injectedEnvironment);
expect(shellEnvironment.GIT_SSL_CAINFO).toBe(caCertificatePath);
expect(shellEnvironment.SSL_CERT_FILE).toBe(caCertificatePath);
const { stdout } = await execFileAsync(gitBinary, ["ls-remote", remoteUrl], {
env: shellEnvironment, timeout: 30_000,
});
expect(stdout).toContain("refs/heads/");
}, 60_000);
it("keeps injected certificate trust and drops ambient secrets through the pinned Codex binary", async (context) => {
// The cases above replay the policy semantics; this one hands the computed
// overrides to the pinned Codex binary and lets it spawn the child command,
// so a Codex-side change to inherit/include_only/ignore_default_excludes
// handling fails here rather than only in production.
let codexBinary: string;
try {
codexBinary = resolveCodexCommand();
} catch {
return context.skip();
}
const codexHome = join(root, "codex-home");
mkdirSync(join(codexHome, ".codex"), { recursive: true });
const args = createIsolatedCodexAppServerArgs(launchEnvironment);
const policyOverrides: string[] = [];
for (let index = 0; index < args.length - 1; index += 1) {
if (args[index] === "-c" && args[index + 1]!.startsWith("shell_environment_policy.")) {
policyOverrides.push("-c", args[index + 1]!);
}
}
expect(policyOverrides.length).toBeGreaterThanOrEqual(6);
const secretValue = "synthetic-ambient-secret";
const injectedEnvironment = {
...createSanitizedCodexEnvironment(launchEnvironment),
HOME: codexHome,
CODEX_HOME: join(codexHome, ".codex"),
GIT_SSL_CAINFO: caCertificatePath,
SSL_CERT_FILE: caCertificatePath,
PAPERCLIP_AI_PROVIDER_KEY: secretValue,
};
try {
// Codex sandboxes commands with host kernel facilities; hosts without
// them keep coverage through the policy-replay cases above.
await execFileAsync(codexBinary, ["sandbox", "--", "/usr/bin/true"], {
env: injectedEnvironment, cwd: root, timeout: 60_000,
});
} catch {
return context.skip();
}
const { stdout } = await execFileAsync(
codexBinary,
["sandbox", ...policyOverrides, "--", "/usr/bin/env"],
{ env: injectedEnvironment, cwd: root, timeout: 60_000 },
);
const lines = stdout.split("\n");
expect(lines).toContain(`GIT_SSL_CAINFO=${caCertificatePath}`);
expect(lines).toContain(`SSL_CERT_FILE=${caCertificatePath}`);
expect(stdout).not.toContain(secretValue);
expect(lines.some((line) => line.startsWith("PAPERCLIP_AI_PROVIDER_KEY="))).toBe(false);
}, 120_000);
});