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:

• 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, add an allow rule, store a credential, mint an agent token, route an agent, and verify.
• The asg CLI — install, configure, output/exit-code contract, and the full asg proxy command tree.
• Egress Rules — the deny-by-default rule model: host/path/method/agent matching, allow/block/require_approval actions, ordering/precedence, and HITL on egress.
• Credentials & Connections — write-only server-side secrets, injection methods (header/query/basic_auth), OAuth connections (GitHub/Notion/Google/Atlassian), AWS SigV4 signing, and preset packs.
• Authorization & Trust — the two gates (egress rules + Permit policy), human consent, per-human 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.

How it was tested

• npm run build (Docusaurus production build) passes, including the hyperlink link/anchor checker: 0 bad links, 0 bad anchors.
• Two parallel review passes (technical accuracy vs. the gateway source, and docs quality/consistency). Findings fixed before publishing:
  • Corrected the credential value-template placeholder to {secret} (single braces; default Bearer {secret}).
  • Corrected AWS SigV4 to dashboard-only via STS-minted temporary credentials.
  • Fixed the asg completion example to include the required --shell flag.
  • Reworked the Quick Start "verify" step so it no longer implies credential injection happens over HTTPS in the default passthrough mode (added an intercept-mode note).

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".

🤖 Generated with Claude Code

[linear-code]

PER-14853

[netlify]

✅ Deploy Preview for permitio-docs ready!

Name	Link
🔨 Latest commit	4991814
🔍 Latest deploy log	https://app.netlify.com/projects/permitio-docs/deploys/6a3302639055ee0008a0a16a
😎 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.

[zeevmoney]

[MEDIUM] asg proxy rules has no update or reorder subcommand

Problem: This row lists asg proxy rules list|add|update|delete|reorder, but the implemented rules group registers only list, add, and delete (agent-security/packages/agent-security-cli/src/commands/proxy.ts, the rulesGroup builder chains rulesListCommand, rulesAddCommand, rulesDeleteCommand). There is no rules update and no rules reorder. The egress-rules.mdx page shows both (asg proxy rules reorder ... and asg proxy rules update ...), which will fail.

Suggestion: Document only list|add|delete. If reorder/update are dashboard-only, say so (the dashboard does support drag-to-reorder and inline edit per the same page) rather than implying CLI parity.

[zeevmoney]

[MEDIUM] asg proxy credentials command group does not exist

Problem: This row documents asg proxy credentials list|create|update|delete, but the asg CLI registers no credentials subcommand under proxy. The actual proxy command tree is config, rules (list/add/delete), container-config, env, doctor, connect, preset (list/apply), token (create), authorize, and ca (status/download/rotate/trust-shell) — verified in agent-security/packages/agent-security-cli/src/commands/proxy.ts (the proxyCommand group registration). Static credentials are created via the dashboard, asg proxy connect (OAuth), or asg proxy preset apply; there is no CLI command to create a static header/query/basic_auth credential. Readers who copy asg proxy credentials create (used throughout Quick Start and Credentials) will hit "unknown command".

Suggestion: Remove the credentials row, or replace it with the real surface (OAuth via asg proxy connect, preset packs via asg proxy preset apply, and the dashboard for static secrets), and fix the dependent examples in quickstart.mdx and credentials.mdx.

[zeevmoney]

[MEDIUM] token create requires --subject and has no --out flag

Problem: This row shows asg proxy token create <host> --client-id <id> with "--out <file> writes it securely". The implemented command (agent-security/packages/agent-security-cli/src/commands/proxy.ts, tokenCreateCommand) requires both --client-id and --subject (both demandOption: true), and defines no --out option — the token is printed to stdout and you redirect it (the command's own example is asg proxy token create acme --client-id ci-runner --subject svc-ci --quiet > token). As written, the documented invocation fails (missing required --subject) and --out is rejected as an unknown flag. The same --out pattern is repeated in quickstart.mdx step 4.

Suggestion: Document --client-id <id> --subject <sub> as required, and replace --out <file> with the redirect form (--quiet > token-file, then chmod 600). Note the optional --ttl (default 900s, max 3600).

[zeevmoney]

[MEDIUM] Step 3 uses a non-existent asg proxy credentials create command

Problem: This step (and the dependent flag list --injection, --header-name, --value-template, --secret-file) is built on asg proxy credentials create, which the CLI does not implement — there is no credentials subcommand under asg proxy at all (agent-security/packages/agent-security-cli/src/commands/proxy.ts). The Quick Start's core "store the upstream credential" step therefore can't be completed via the CLI as shown. Static-credential creation is dashboard-only in the current CLI; OAuth uses asg proxy connect, and bundled secrets use asg proxy preset apply --secret-file.

Suggestion: Rewrite this step against the real surface — point to Proxy → Credentials in the dashboard for a static key, or asg proxy connect/asg proxy preset apply for the CLI paths — and drop the --injection/--header-name/--value-template CLI flags (those are dashboard form fields, not CLI options).

[zeevmoney]

[MEDIUM] token create example omits required --subject and uses a non-existent --out

Problem: agent-security/packages/agent-security-cli/src/commands/proxy.ts (tokenCreateCommand) makes both --client-id and --subject required (demandOption: true) and defines no --out option — the token prints to stdout. This example passes only --client-id and --out ~/.agent-security/tokens/acme.token, so it fails twice: missing --subject, and --out is an unknown flag.

Suggestion:

asg proxy token create acme \
  --client-id ci-runner \
  --subject svc-ci \
  --quiet > ~/.agent-security/tokens/acme.token
chmod 600 ~/.agent-security/tokens/acme.token

Then point AGENT_SECURITY_PROXY_TOKEN_FILE at that file (the CLI emits exactly this reminder).

[zeevmoney]

[MEDIUM] asg proxy rules reorder is not an implemented command

Problem: The CLI's rules group registers only list, add, and delete (agent-security/packages/agent-security-cli/src/commands/proxy.ts, rulesGroup). There is no rules reorder subcommand, so this snippet fails. Reordering is available in the dashboard (drag-to-reorder), but add appends at lowest precedence and there is no CLI reorder/move operation.

Suggestion: Remove the reorder snippet, or replace it with a note that ordering is managed in the dashboard. If CLI reorder is intended, it isn't in the shipped command surface yet.

[zeevmoney]

[MEDIUM] asg proxy rules update is not an implemented command

Problem: agent-security/packages/agent-security-cli/src/commands/proxy.ts registers only rules list|add|delete; there is no rules update. This example (asg proxy rules update acme <rule-id> --action block) will fail with "unknown command". To change a rule via the CLI you delete and re-add it.

Suggestion: Drop the update line (keep delete), or note that editing a rule in place is dashboard-only and the CLI flow is delete + re-add.

[zeevmoney]

[MEDIUM] Static-credential example uses the non-existent asg proxy credentials create command

Problem: Both static-credential examples here invoke asg proxy credentials create ... --injection ... --header-name/--param-name ... --value-template ... --secret-file .... The CLI implements no credentials subcommand under proxy (agent-security/packages/agent-security-cli/src/commands/proxy.ts) — these flags and the command don't exist. The injection methods (header/query/basic_auth) and write-only semantics described in the prose are real (they're dashboard form fields and gateway behavior), but they are not reachable through this CLI command.

Suggestion: Present static-credential creation as a dashboard task (Proxy → Credentials), keep the injection-method table as conceptual reference, and reserve the CLI examples for asg proxy connect (OAuth) and asg proxy preset apply which do exist.

[zeevmoney]

[MEDIUM] authorize uses a required --hosts flag, not repeatable --host; --trust default is low

Problem: The example asg proxy authorize <agent-client-id> --host api.github.com and the prose "Pass multiple --host flags … The optional --trust low|medium|high flag … omit it to default to least privilege" do not match the implementation (agent-security/packages/agent-security-cli/src/commands/proxy.ts, authorizeCommand):

• The option is --hosts (plural), comma-separated and required (demandOption: true), with per-host host:trust syntax — e.g. --hosts api.github.com:medium,api.openai.com:low. There is no repeatable --host.
• --trust sets the default level for hosts given without an explicit :trust, and its default value is low (not an unset "least privilege").
• The command also typically needs --consent-url https://<tenant>.agent.security (or AGENT_SECURITY_CONSENT_URL).

Suggestion:

asg proxy authorize <agent-client-id> \
  --hosts api.github.com:medium \
  --consent-url https://acme.agent.security

Describe --hosts as required/comma-separated with host:trust, and --trust as the default for hosts lacking an explicit level (default low).