PRD 0006: pipelock native TLS interception #9

2026-05-12T14:16:00-04:00

didericis commented

2026-05-12 14:16:00 -04:00

Summary

Turn on pipelock's built-in tls_interception so its DLP / URL / header / MCP scanners fire on the plaintext of HTTPS requests. Per-bottle ephemeral CA generated via pipelock tls init at launch, public cert installed in the agent's trust store, private key dies with the sidecar on teardown. The single-pipelock-sidecar topology from PRD 0001 is otherwise unchanged.

Why a new PR

PR #8 (mitmproxy-tls-interception) is closed. It built a mitmproxy + addon chain on the inherited claim that pipelock could not MITM. That claim is false against pipelock v2.3.0 — empirical proof in the spike (pipelock generated a CA-signed leaf for httpbin.org, terminated TLS, scanned the decrypted body, and blocked the credential POST). The right shape is to use pipelock's native feature instead of putting a second proxy in front of it.

Context

Empirical proof in the PR description of #8 (closed).
docs/research/pipelock-assessment.md corrected in this commit; the stale tls-mitm-for-pipelock.md note is removed.

## Summary Turn on pipelock's built-in `tls_interception` so its DLP / URL / header / MCP scanners fire on the plaintext of HTTPS requests. Per-bottle ephemeral CA generated via `pipelock tls init` at launch, public cert installed in the agent's trust store, private key dies with the sidecar on teardown. The single-pipelock-sidecar topology from PRD 0001 is otherwise unchanged. ## Why a new PR PR #8 (`mitmproxy-tls-interception`) is closed. It built a mitmproxy + addon chain on the inherited claim that pipelock could not MITM. That claim is false against pipelock v2.3.0 — empirical proof in the spike (pipelock generated a CA-signed leaf for `httpbin.org`, terminated TLS, scanned the decrypted body, and blocked the credential POST). The right shape is to use pipelock's native feature instead of putting a second proxy in front of it. ## Context - Empirical proof in the PR description of #8 (closed). - `docs/research/pipelock-assessment.md` corrected in this commit; the stale `tls-mitm-for-pipelock.md` note is removed.

didericis added 1 commit 2026-05-12 14:16:01 -04:00

docs(prd): add 0006, enable pipelock's native TLS interception

test / unit (pull_request) Successful in 12s

Details

test / integration (pull_request) Successful in 13s

Details

6716f091c1

Supersedes the abandoned PR #8 (`mitmproxy-tls-interception`),
which built a mitmproxy + addon chain on the (falsified) premise
that pipelock could not MITM. Empirical proof from the impl-time
spike: with `tls_interception: { enabled: true, ca_cert, ca_key }`
in pipelock's config, pipelock answered a credential POST over
HTTPS with `STATUS=403 / body: blocked: request body contains
secret: GitHub Token` and emitted both `scanner:"tls_intercept"`
and `scanner:"body_dlp"` events. Standalone, no second proxy.

Net change vs PR #8: one sidecar instead of two, no vendored
addon, no addon-verdict pattern matching, no HTTPS-trust /
DNS / lookup workarounds. Same end-state behavior — pipelock's
DLP fires on plaintext for HTTPS hosts in the allowlist.

Also cleaning up the now-stale TLS-research notes:

- `docs/research/tls-mitm-for-pipelock.md` is removed. Its
  entire premise (mitmproxy in front of pipelock) is moot now
  that pipelock does the work natively. The mechanics of CONNECT
  bumping and the CA-lifecycle considerations it documented are
  the same as what pipelock implements; the PRD restates the
  parts that matter for the integration.
- `docs/research/pipelock-assessment.md` had two stale claims
  corrected: the "Pipelock does not perform TLS inspection (no
  CA trust injection)" line in §Scope gaps and the
  "no TLS termination" cell in the comparison table. Both now
  point at the `tls_interception` config and `pipelock tls`
  CLI instead.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

didericis added 1 commit 2026-05-12 14:23:03 -04:00

docs(prd): fold 0006 walkthrough resolutions into the design

test / unit (pull_request) Successful in 15s

Details

test / integration (pull_request) Successful in 14s

Details

f44e884d8a

After the open-question walkthrough, all four collapsed:

- Q1 (mount semantics): resolved to `docker cp` between
  `docker create` and `docker start`, mirroring the existing
  pipelock YAML handling. No bind mount, no UID/permission
  concern. Folded into §Proposed Design > CA lifecycle as
  "Sidecar install".
- Q2 (cert validity / TTL): pre-decided in the question text.
  Per-bottle ephemerality is enforced by regenerating per launch,
  not by short validity windows. Pipelock's defaults are fine.
  Folded into §Proposed Design as a one-line "Per-bottle
  ephemerality" note.
- Q3 (`passthrough_domains` shape): not v1 scope; the shape is
  pre-recorded so the follow-up is mechanical. Moved into
  §Out of scope.
- Q4 (stage-dir cleanup ordering): reading start.py confirmed
  the ExitStack-then-outer-finally order is correct. Folded into
  §Proposed Design as a "Teardown" note.

The §Open questions section is dropped. None of the four was a
real design question — they were verifications and pre-decided
items left in for defensiveness.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

didericis added 2 commits 2026-05-12 14:50:34 -04:00

feat(pipelock): enable tls_interception with per-bottle ephemeral CA 3755e66abe

First step of PRD 0006. Pipelock now does the CONNECT bumping that
PR #8's mitmproxy chain was supposed to provide — natively, in the
same single sidecar PRD 0001 wired up.

- claude_bottle/pipelock.py: pipelock_build_config grows optional
  ca_cert_path / ca_key_path kwargs. When both are passed the
  rendered YAML carries a `tls_interception: { enabled: true,
  ca_cert, ca_key }` block. PipelockProxy gains class-level
  CA_CERT_IN_CONTAINER / CA_KEY_IN_CONTAINER constants that
  subclasses set to wherever they place the CA inside the
  sidecar. PipelockProxyPlan gains ca_cert_host_path /
  ca_key_host_path fields (default empty Path() — sentinel for
  "not yet populated", filled by launch via dataclasses.replace).

- claude_bottle/backend/docker/pipelock.py: new
  pipelock_tls_init(stage_dir) helper runs `pipelock tls init`
  in a one-shot container against a host-mounted scratch dir.
  DockerPipelockProxy sets its class constants to
  /etc/pipelock-ca.pem and /etc/pipelock-ca-key.pem; .start
  docker-cp's the cert + key into those paths between
  `docker create` and `docker start`. Pipelock runs as root in
  its distroless image, so no chown is needed (verified).

- claude_bottle/backend/docker/launch.py: calls pipelock_tls_init
  between network creation and proxy.start. Prepare stays
  side-effect-free on docker; the one-shot ca-init container
  only runs on a real launch, not on `start --dry-run`.

- tests/unit/test_pipelock_yaml.py: new assertions that
  pipelock_build_config emits the tls_interception block only
  when both paths are supplied (and rejects a half-set pair),
  plus a test that the docker proxy's prepare plumbs the
  in-container paths through to the rendered YAML.

The end-to-end "bumping actually fires" assertion lands in
chunk 4 (HTTPS integration tests).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

feat(provision): install pipelock CA into the agent + add curl

test / unit (pull_request) Successful in 16s

Details

test / integration (pull_request) Successful in 15s

Details

86a9b499bc

Second step of PRD 0006. With pipelock now doing the bumping, the
agent's TLS library has to trust pipelock's per-bottle CA — or
every CONNECT to api.anthropic.com is a self-signed-cert error.

- BottleBackend.provision gains a non-abstract `provision_ca`
  with a default no-op (so non-Docker backends aren't forced to
  implement TLS interception) and orchestrates
  ca → prompt → skills → ssh → git. CA install runs first so the
  agent's trust store is rebuilt before anything else in the
  agent makes a TLS call.

- New backend/docker/provision/ca.py: docker-cp's the CA cert
  into the agent at /usr/local/share/ca-certificates/...,
  `update-ca-certificates`, then emits a one-line stderr log
  with the SHA-256 fingerprint (stdlib `ssl` + `hashlib`; no
  subprocess for crypto). Module-level constants AGENT_CA_PATH
  and AGENT_CA_BUNDLE are imported by launch.py so the env
  trio set at docker run time matches the paths the provisioner
  writes.

- launch.py: rebinds `plan` after `dataclasses.replace`s on the
  pipelock proxy plan so provision_ca (which reads
  `plan.proxy_plan.ca_cert_host_path`) sees the populated CA
  paths. Three new -e flags on the agent's docker run for the
  NODE_EXTRA_CA_CERTS / SSL_CERT_FILE / REQUESTS_CA_BUNDLE trio.

- Dockerfile: adds curl to the apt-get install line. curl
  natively respects HTTPS_PROXY and sends CONNECT directly —
  the agent doesn't need OS-level DNS for external hostnames
  (pipelock resolves them on its side of the bumped tunnel).
  This is the "simple HTTPS request" path the earlier turn
  needed and Node's stdlib https.request couldn't provide.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

didericis added 2 commits 2026-05-12 15:01:22 -04:00

feat(bottle-plan): render TLS interception in the dry-run preflight fb10c8dd8a

Third step of PRD 0006. The preflight now surfaces the TLS-
intercept layer so the operator sees it before agreeing to launch.

- Text output: one new line under the egress summary
  ("tls intercept : pipelock (per-bottle ephemeral CA, generated
  at launch)").
- JSON output (--format=json contract): new
  egress.tls_interception: { enabled: true, ca_fingerprint: null }
  block. Fingerprint is always null at dry-run because the CA
  only exists after launch; real launches print it as a stderr
  log line from provision_ca.
- Pin the new shape in the dry-run integration test.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

test(pipelock): HTTPS integration tests for the bumped path

test / unit (pull_request) Successful in 11s

Details

test / integration (pull_request) Successful in 13s

Details

d3115ae5fd

Fourth and final step of PRD 0006. Two new end-to-end tests pin
the two paths through pipelock's tls_interception layer.

- test_pipelock_blocks_secret_https_post: posts a GitHub-PAT-shaped
  body to api.anthropic.com over HTTPS through the bottle. With
  pipelock now bumping the CONNECT and seeing the decrypted body,
  it returns 403 with the documented `blocked: request body
  contains secret: GitHub Token` body. The probe is a single curl
  invocation — curl natively does CONNECT through HTTPS_PROXY, the
  agent's trust store now contains pipelock's CA, no hand-rolled
  TLS in the test.

- test_pipelock_allows_normal_https: GETs git's README from
  raw.githubusercontent.com (a baked-in allowlist host). 200 +
  non-zero body length proves the full chain works:
  pipelock_tls_init → docker cp of CA into sidecar → bumped CONNECT
  → provision_ca installed CA in agent → curl trusts pipelock's
  bumped leaf → body forwarded back through the tunnel.

- test_pipelock_sidecar_smoke: pre-existing direct-start smoke
  test updated to call pipelock_tls_init and populate the CA
  paths on the plan. (The full launch flow does this in launch.py;
  this test exercises the proxy class in isolation.)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

didericis merged commit 235e9ff4ea into main

2026-05-12 15:03:23 -04:00

didericis referenced this pull request

2026-05-12 15:41:51 -04:00

PRD 0007: SSH egress gate #10

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: didericis/bot-bottle#9