PER-14853: Add HTTP Egress Proxy customer documentation

[EliMoshkovich]

Why

The HTTP Egress Proxy + asg CLI is shipping toward GA, but customers have no public documentation for it. The capability lets customers govern an agent's arbitrary outbound HTTP/HTTPS traffic (REST APIs, webhooks, third-party services) with the same authentication, authorization, consent, HITL, and audit the gateway already applies to MCP tool calls. This PR adds a complete, customer-facing documentation section so the feature is usable and discoverable.

Linear: PER-14853

What

Adds a new documentation section under Permit MCP Gateway → HTTP Egress Proxy (docs/permit-mcp-gateway/http-egress-proxy/), 8 pages, written against the shipped API workflow model:

• Overview — what the egress proxy is, why it exists, the two-plane (control/data) model, and how a request is governed.
• Quick Start — enable the proxy, store a credential, define an API workflow in the dashboard, mint a workflow-bound agent token, route an agent, and verify.
• The asg CLI — install (@permitio/agent-security-cli, via bunx/npx/global), configure, output/exit-code contract, and the asg proxy command tree.
• Workflows & Rules — the deny-by-default model: a workflow groups the domains an agent may reach and the rules (path + method class + required trust) that govern them. Allow-only; each token is bound to one workflow. Workflows are authored in the dashboard.
• Credentials & Connections — write-only server-side secrets, injection methods (header/query/basic_auth), OAuth connections (GitHub/Notion/Google/Atlassian), and AWS SigV4 signing.
• Authorization & Trust — the two gates (workflow match + Permit policy), human consent bound to a workflow, per-human/per-workflow trust ceilings, and revocation.
• Connecting Agents — HTTP_PROXY setup for shell/Docker/Kubernetes, the proxy token, HTTPS passthrough vs intercept (+ CA trust), and proxy doctor.
• Security — SSRF protection, credential isolation, response scrubbing, TLS modes, rate limiting, audit trail, and an honest "what it does/doesn't do" note.

Also:

• Registers the section in sidebars.js (explicit category, label "HTTP Egress Proxy", landing on the Overview page).
• Links the section from the parent gateway index.mdx "Go Deeper" list for discoverability.

The docs are deliberately scoped for customers — no internal ports, Redis keys, source paths, KMS/crypto internals, Helm/Tilt, or feature-flag names are exposed.

Correction pass (aligned to the shipped CLI + gateway)

The first draft described the earlier flat-rule model, which has since been replaced by the API workflow model in the asg CLI and the gateway. This PR was reviewed page-by-page against the running CLI (asg proxy --help) and the gateway enforcement, and corrected:

• Removed the non-existent asg proxy rules add/list/update/delete/reorder commands. Egress policy is now authored as workflows (domains + rules + required trust) in the dashboard; there is no CLI for workflow authoring yet.
• Fixed the npm package scope to @permitio/agent-security-cli (was @permit-io/…) and added the bunx/npx -y zero-install forms.
• asg proxy token create now shows the required --workflow flag; consent uses asg proxy authorize --workflow (the retired --host/--hosts flags are gone).
• Trust ceilings are per-human, per-workflow (not per-host).
• Dropped block / require_approval rule actions (workflow rules are allow-only) and reframed HITL on egress as an optional per-host capability.
• Removed the asg proxy preset apply path (currently returns 501 / parked).
• Corrected dashboard navigation to the real sections: Overview, Workflows, Credentials, Activity, Setup.

How it was tested

• npm run build (Docusaurus production build) passes, including the hyperlink link/anchor checker: 0 bad links, 0 bad anchors (48,614 links across 2,411 files).
• Every documented command and flag was verified against the live asg CLI --help output; the model was cross-checked against the gateway proxy enforcement and the Platform proxy UI.

Manual test plan

1. npm install && npm run build from the repo root → build succeeds with 0 bad links/anchors.
2. npm run serve and browse to /permit-mcp-gateway/http-egress-proxy/ → the section renders with all 8 pages in the sidebar under "HTTP Egress Proxy".
3. Click through every in-page cross-link and the two Mermaid diagrams (Overview, Authorization) → all resolve and render.
4. From the gateway landing page, confirm the new "HTTP Egress Proxy" entry appears in "Go Deeper".
5. Copy-paste the Quick Start CLI commands against a test tenant → each resolves to a real asg command (proxy config, proxy credentials create, proxy token create --workflow, proxy env, proxy ca …).

🤖 Generated with Claude Code

[linear-code]

PER-14853

[netlify]

✅ Deploy Preview for permitio-docs ready!

Name	Link
🔨 Latest commit	3d5c159
🔍 Latest deploy log	https://app.netlify.com/projects/permitio-docs/deploys/6a690eb3038c9c0008d9a221
😎 Deploy Preview	https://deploy-preview-640--permitio-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

Adds a new customer-facing documentation section for the Permit MCP Gateway “HTTP Egress Proxy” feature so it’s discoverable and usable, and wires it into the site navigation.

Changes:

• Registers a new “HTTP Egress Proxy” docs category in sidebars.js.
• Adds an 8-page documentation section under docs/permit-mcp-gateway/http-egress-proxy/ (overview, quick start, CLI, rules, credentials, authorization, agent connection, security).
• Links the new section from the Permit MCP Gateway landing page for discoverability.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
sidebars.js	Adds a new sidebar category for “HTTP Egress Proxy” and lists its pages.
docs/permit-mcp-gateway/index.mdx	Adds a “Go Deeper” link to the new HTTP Egress Proxy section.
docs/permit-mcp-gateway/http-egress-proxy/index.mdx	Overview page describing the feature model and governance flow.
docs/permit-mcp-gateway/http-egress-proxy/quickstart.mdx	End-to-end CLI-based quickstart for enabling and verifying the proxy.
docs/permit-mcp-gateway/http-egress-proxy/cli.mdx	asg CLI installation/configuration and proxy command reference.
docs/permit-mcp-gateway/http-egress-proxy/egress-rules.mdx	Rule model, ordering/precedence, and HITL behavior.
docs/permit-mcp-gateway/http-egress-proxy/credentials.mdx	Write-only secrets, injection methods, OAuth connections, AWS SigV4, presets.
docs/permit-mcp-gateway/http-egress-proxy/authorization.mdx	Two-gate authorization model and trust ceilings / consent.
docs/permit-mcp-gateway/http-egress-proxy/connecting-agents.mdx	Env var setup, container config, HTTPS interception, diagnostics.
docs/permit-mcp-gateway/http-egress-proxy/security.mdx	SSRF protections, credential isolation, scrubbing, TLS modes, rate limiting, audit.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zeevmoney]

This is an automated review. See comments.

[EliMoshkovich]

Thanks for the thorough pass, @zeevmoney. I went through all 12 findings against the current asg CLI on main and the current PR head (ee087d60), and resolved every thread:

Your 9 findings were accurate on 2026-06-18, but are now overtaken by two changes:

1. The CLI evolved since your review. On current main:

   • asg proxy credentials now exists — asg proxy credentials create <key> ("Create a static proxy credential") with --host/--injection/--header-name/--value-template/--secret-file. (Findings on the missing credentials group.)
   • token create now has --out and --subject is optional (defaults to human-<client-id>); --workflow is required. (Findings on --subject/--out.)
   • authorize now takes --workflow <slug> — the per-host --hosts host:trust flag was retired. (Finding on --hosts/--trust.)
   • The flat asg proxy rules group (incl. update/reorder) was removed in A7. (Findings on rules update/reorder.)

2. The docs were rewritten to the API workflow model (matching the above), so the flat-rule examples you flagged are gone.

Copilot's 3 nits were still valid and are fixed in ee087d60:

• cli.mdx: the Configure example now uses asg login --token-file (matches the process-visible-flag warning).
• quickstart.mdx: the verify step now uses curl -i and explains that a 401 from Stripe in passthrough is expected — it proves the request reached the upstream, versus a denied host the proxy never connects to.

Build (Docusaurus + hyperlink checker) is green: 0 bad links, 0 bad anchors. Re-requesting review from @zeevmoney and @Zivxx.

[zeevmoney]

Changes requested — 1 CRITICAL, 9 HIGH, 17 MEDIUM, 6 LOW.

Every claim in these eight pages was checked against permitio/agent-security at main (6f3a0991, pulled today) — the gateway proxy in gateway/src/proxy/**, the asg CLI in packages/agent-security-cli/, and the dashboard in platform/src/app/(dashboard)/proxy/**. Each finding below cites the implementing file and line.

Two themes account for most of the blocking items: the pages describe the plain-HTTP path as though it were the general case (HTTPS arrives as a CONNECT, which only an all-method, path-less rule can match — so path rules, credential injection, scrubbing, and HITL do not apply in the default passthrough mode), and several security guarantees are stated unconditionally when they are conditional on a setting that is off by default.

Blocking:

• CRITICAL security.mdx:27 — "encrypted at rest using envelope encryption" is false in the default configuration; VAULT_ENABLED defaults to false and credentials are written to Redis as plaintext with only a log warning
• HIGH quickstart.mdx:55 — the workflow rule taught here denies every HTTPS request; the path glob also can't match the URL used to verify
• HIGH quickstart.mdx:87 — these curl commands return 407, not the documented 401; Proxy-Authorization is mandatory and step 5 never supplies it
• HIGH quickstart.mdx:115 — step 7 downloads the CA but never installs it, so the final verification fails TLS validation
• HIGH egress-rules.mdx:25 — the example workflow denies 100% of its traffic: no tunnel rule on either HTTPS-only domain
• HIGH authorization.mdx:73 — revocation is not immediate by default (in-flight cutoff is opt-in), and an open passthrough tunnel is never re-checked
• HIGH authorization.mdx:38 — the method class does not determine required trust; the rule declares its own
• HIGH index.mdx:17 — the dashboard section is CLIs / APIs, not "Proxy", so this note tells enabled customers they lack the feature
• HIGH security.mdx:33 — response scrubbing is best-effort, per-credential, and "fails closed" only on the encoding axis
• HIGH security.mdx:52 — the audit record identifies the agent, not the human, so it cannot answer "on whose behalf"; events can also be dropped

Non-blocking:

• MEDIUM index.mdx:93 — the request pipeline describes plain HTTP; HTTPS is domain-matched only by default (also :36, :97)
• MEDIUM index.mdx:41 — "before any DNS lookup" holds only for IP literals and blocklisted hostnames
• MEDIUM quickstart.mdx:80 — asg proxy env doesn't credential the shell, and the described direction is inverted
• MEDIUM quickstart.mdx:51 — the three listed steps span two pages; the button is "Create workflow"
• MEDIUM credentials.mdx:10 — response scrubbing is a per-credential toggle this section never mentions
• MEDIUM credentials.mdx:78 — the AWS signing flow names none of its four required inputs
• MEDIUM credentials.mdx:45 — host binding is a glob that matches across dots, so "can never be sent to another" depends on the pattern
• MEDIUM connecting-agents.mdx:49 — TLS mode is read from the tunnel rule; setting it elsewhere has no effect (also :47, :68)
• MEDIUM egress-rules.mdx:85 — HITL requires two host flags and never fires on default-mode HTTPS
• MEDIUM security.mdx:48 — the rate limiter fails open and meters only requests that reach a matching rule
• MEDIUM cli.mdx:71 — the --<flag>-file companion rule isn't universal (asg pdp validate --api-key has none)
• MEDIUM cli.mdx:100 — asg proxy connect has two required flags this row omits
• MEDIUM cli.mdx:112 — the --subdomain convention contradicts every worked example in this section
• MEDIUM cli.mdx:54 — nothing anywhere says where the admin token comes from
• MEDIUM cli.mdx:108 — "intent guardian" and "agent identity registration" are defined nowhere on the site
• MEDIUM egress-rules.mdx:10 — "workflow" already means the agent workflow context in this same sidebar category
• MEDIUM authorization.mdx:48 — "trust ceiling" is the Max Trust Level control already documented in Host Setup
• LOW quickstart.mdx:42 — four small fixes grouped (uncreated stripe.key, wrong anchor, ca rotate prompt, -o vs --output)
• LOW cli.mdx:102 — placeholder and token naming drift across the section
• LOW egress-rules.mdx:45 — read also covers OPTIONS; only all matches TRACE
• LOW connecting-agents.mdx:88 — doctor reports pass/warn/fail, not pass/fail
• LOW index.mdx:5 — sidebar_position: 0 on a category index breaks the directory's convention
• LOW security.mdx:14 — "before any network I/O" overstates; several round-trips precede the decision

Verified accurate and deliberately not flagged: the request-pipeline ordering in index.mdx:88-98, the two-stage SSRF design in security.mdx:20-21, the Auto-trust mapping in egress-rules.mdx:55, the OAuth provider list, the package and binary names, the env-var and exit-code tables, the config path and priority order, and the per-human/per-workflow trust-ceiling semantics including the no-cross-human-combination property in authorization.mdx:48-50.

Details are in the inline comments on each line.

[EliMoshkovich]

Thanks @zeevmoney — this was an outstanding, code-cited review. I verified the load-bearing claims against the gateway source (CONNECT authorizes with an empty path + Tunnel class so only an all/no-path tunnel rule matches; the KMS vault is default = false; no Proxy-Authorization → 407; denyInFlight defaults false; the dashboard nav is "CLIs / APIs"), and addressed all 33 findings in 3d5c1596. Each thread has an inline note with the specific fix.

Highlights:

• HTTPS/CONNECT model (the cascading one): new "HTTPS needs a tunnel rule" section, tunnel rules added to the example + Quick Start, and the request-flow / TLS-mode / injection prose qualified for passthrough vs. intercept.
• CRITICAL vault: encryption at rest is now stated as a precondition (KMS vault, off by default), with warnings on security, credentials, and the Quick Start.
• Verify step: Proxy-Authorization on every curl (407 otherwise) + CA install in step 7.
• Revocation: deny-in-flight is opt-in and doesn't re-check an open passthrough tunnel.
• Scrubbing/audit/rate-limit: softened to best-effort / per-credential / agent-not-human / fail-open, with the concrete numbers.
• Nav: every "Proxy → …" breadcrumb is now "CLIs / APIs → …".
• CLI: admin-token source, --<flag>-file scope, connect required flags, --subdomain rule, guardian/identity defined; AWS STS inputs named.

Two I flagged rather than forced: I kept the file name egress-rules.mdx (URL stability) and did a partial token-naming standardization — happy to do the full rename/sweep as a follow-up if you'd like. Build (Docusaurus + hyperlink) is green: 0 bad links, 0 bad anchors. Re-requesting review from @zeevmoney and @Zivxx.