PER-15560: document drift-block recovery (user-driven reconsent) for the HTTP Egress Proxy - #648
Merged
Conversation
…the HTTP Egress Proxy The gateway now recovers drift-blocked agent sessions through the agent's own user: the block response carries a re-approval link to the tenant's consent screen, where the person who authorized the agent reviews its last declared intent and re-approves (or keeps it blocked). - security: new 'Agent identity and drift protection' section (opt-in) covering session intent registration, drift blocking, the browser recovery flow, the operator override, and the review-before-reapprove guidance - index: capability table row + governed-request note + section list - cli: the opt-in capabilities paragraph now describes register-session and the recovery link - connecting-agents + quickstart: doctor now reports a drift-blocked session with the re-approval link - egress-rules: agent identity in the HITL prerequisites now links to the new section
✅ Deploy Preview for permitio-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the HTTP Egress Proxy documentation to describe the opt-in agent identity / drift-block behavior and the user-driven browser re-consent recovery flow introduced by PER-15560, and threads those references through the related setup and troubleshooting pages.
Changes:
- Adds a new Agent identity and drift protection section to Security docs, including recovery flow and operator override.
- Updates the overview/capability table and “governed request” pipeline notes to mention agent identity.
- Extends
asg proxy doctordocumentation (quickstart + connecting agents) to include drift-block detection and the re-approval link behavior.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/permit-mcp-gateway/http-egress-proxy/security.mdx | Adds the new agent identity + drift protection section and updates the Security page description. |
| docs/permit-mcp-gateway/http-egress-proxy/index.mdx | Adds capability-table row and mentions agent identity in the governance pipeline + section list. |
| docs/permit-mcp-gateway/http-egress-proxy/cli.mdx | Updates opt-in capabilities paragraph to reference register-session and recovery link. |
| docs/permit-mcp-gateway/http-egress-proxy/connecting-agents.mdx | Adds doctor bullet for session registration + drift-block detection and re-approval link. |
| docs/permit-mcp-gateway/http-egress-proxy/quickstart.mdx | Updates troubleshooting description of doctor to include agent identity checks when enabled. |
| docs/permit-mcp-gateway/http-egress-proxy/egress-rules.mdx | Links HITL prerequisite “agent identity” mention to the new Security section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| *(Opt-in — [contact us](mailto:support@permit.io) to enable it for your account.)* | ||
|
|
||
| A host can additionally require every agent session to **register its intent**: before its first governed request, the agent declares what it is working on, in exactly twelve distinct words, with [`asg proxy register-session`](./cli). The gateway builds a behavioral baseline from those declarations, and a sharp change in an agent's declared intent — the signature of a hijacked or steered agent — **blocks the session**: registrations and governed requests are denied until a human re-approves the agent. |
| - **Re-approve** — the block lifts, and the agent's next registration starts a clean baseline. | ||
| - **Keep blocked** — nothing changes; the agent stays denied. | ||
|
|
||
| Only the account that originally authorized the agent can unblock it — a link forwarded to anyone else shows an error instead of the review screen. Completing a fresh consent flow ([`asg proxy authorize`](./authorization#human-consent)) clears the block the same way. An operator can always clear a block with `asg proxy identity reconsent` — and for automated agents running under an operator-minted token (no human delegation), that is the only recovery path. Re-approvals — by the user or by an operator — are recorded in the [audit trail](#audit-trail), including who cleared the block. |
Zivxx
approved these changes
Jul 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
PER-15560 (permitio/agent-security#477, merged) changed how a drift-blocked agent session recovers on the HTTP Egress Proxy: recovery is now user-driven — the block response carries a re-approval link to the tenant's consent screen, where the person who authorized the agent reviews its last declared intent and re-approves it (or keeps it blocked). Previously recovery was operator-only. The customer docs under
http-egress-proxydid not describe the identity capability's behavior at all, so a customer with the opt-in enabled had no reference for what a drift block is or how to clear one.What
asg proxy register-session, twelve distinct words), what triggers a block, the browser recovery flow (re-approval link → signed-in review of the agent's declared intent → Re-approve / Keep blocked), who can unblock (self-scope; fresh consent flow; operator overrideasg proxy identity reconsent), audit note, and a review-before-you-reapprove tip.register-sessionand the recovery link.asg proxy doctordocs gain the drift-block check (fails with the re-approval link).Deliberately not documented (customer-appropriateness): drift thresholds and detection internals, protocol/status-code details, internal service names, and full syntax for the opt-in commands (the section's established pattern keeps opt-in detail behind contact-us).
Review
Linear: PER-15560
🤖 Generated with Claude Code