docs(prd): add 0006, enable pipelock's native TLS interception
test / unit (pull_request) Successful in 12s
test / integration (pull_request) Successful in 13s

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>
This commit is contained in:
2026-05-12 14:15:44 -04:00
parent e45cd2fb07
commit 6716f091c1
3 changed files with 312 additions and 513 deletions
+9 -5
View File
@@ -222,10 +222,14 @@ The following threat-model items from `network-egress-guard.md` are
intercept raw UDP 53 packets.
- **Domain fronting**: an agent can send `CONNECT allowed-host.com:443`
through the proxy but embed a different SNI inside the TLS session.
Pipelock does not perform TLS inspection (no CA trust injection) and
cannot verify SNI vs. CONNECT header. The same limitation is shared
with smokescreen and is documented in `network-egress-guard.md` as a
known gap for the non-TLS-terminating proxy approach.
Pipelock supports TLS interception via its `tls_interception` config
block (`enabled`, `ca_cert`, `ca_key`, `cert_ttl`, `cert_cache_size`,
`passthrough_domains`, `max_response_bytes`) plus the `pipelock tls
init` / `install-ca` / `show-ca` CLI; with interception on, the
body and inner Host header become visible to its scanner pipeline,
closing the domain-fronting gap. With interception off (default in
the generated config), pipelock relays the CONNECT as an opaque
tunnel and only sees the outer hostname.
- **SSH egress content**: SSH sessions to permitted hosts are opaque.
Same limitation noted in both prior research notes.
- **Agent killing the proxy process**: if pipelock runs inside the same
@@ -385,7 +389,7 @@ pipelock's differentiators.
| Blocks RFC 1918 by default | only if explicitly added to rules | yes | yes, + DNS rebinding | no |
| Content-based DLP (credential patterns) | no | no | yes, 48 patterns + encoding normalization | no |
| MCP / WebSocket scanning | no | no | yes, bidirectional | no |
| Domain fronting bypass | possible | possible | possible (no TLS termination) | n/a |
| Domain fronting bypass | possible | possible | mitigated when `tls_interception` is enabled (CA trust required in client) | n/a |
| macOS Docker Desktop (sidecar mode) | yes | yes | yes | yes |
| macOS Docker Desktop (in-container sandbox) | yes | n/a | degraded (--best-effort) | yes |
| NET_ADMIN / NET_RAW required | yes | no | no (sidecar) | no |