Package burp.mcp.util

Class ApprovalManager

java.lang.Object
burp.mcp.util.ApprovalManager
public class ApprovalManager extends Object
Coordinates operator approvals for prompt-gated tool calls and out-of-scope targets.

Flow: a tool call that needs approval creates (or reuses) a ApprovalManager.PendingApproval and waits briefly for a UI decision. If the operator answers in time the decision is applied immediately; if not, the call returns a pending token and the agent retries the same call while the operator can still answer from the Burp UI. Decisions are cached on the pending request until it is consumed or its TTL expires, so nothing executes after the client has stopped waiting.

Thread-safe. UI callbacks (ApprovalManager.Listener) fire on whichever thread triggered the event and must be marshalled to the EDT by the listener.

  • Constructor Details

    • ApprovalManager

      public ApprovalManager()

  • Method Details

    • findOrCreate

      public ApprovalManager.PendingApproval findOrCreate(ApprovalManager.Context ctx, long ttlMs)
      Find the pending approval for this client + fingerprint, or create it. Resolved-but-unconsumed (denied) pendings are returned so retries get the cached decision instead of a second prompt.

    • find

      public ApprovalManager.PendingApproval find(String clientIp, String fingerprint)
      Look up an unconsumed pending by client + fingerprint, or null.

    • await

      public ApprovalManager.Outcome await(ApprovalManager.PendingApproval pending, long waitMs)
      Wait up to waitMs for a decision. Only one waiter per pending request; extra callers are told PENDING immediately so retries cannot tie up worker threads.

    • resolve

      public boolean resolve(String id, ApprovalManager.Decision decision)
      Record an operator decision. Applies session grants and scope additions immediately, so they take effect even if the client never retries.
      Returns:
      true when this call made the decision, false if unknown/already decided.

    • cancel

      public boolean cancel(String id)
      Cancel a pending request (server stop, UI cancel, expiry).

    • consume

      public void consume(ApprovalManager.PendingApproval pending)
      Remove a pending request after its allow decision has been consumed.

    • sweepExpired

      public void sweepExpired()
      Expire unresolved pendings past their TTL and prune resolved ones.

    • cancelAll

      public void cancelAll(String reason)
      Cancel every pending request (e.g. listener shutdown).

    • isToolGranted

      public boolean isToolGranted(String toolName)

    • isOriginGranted

      public boolean isOriginGranted(String origin)

    • getToolGrants

      public Set<String> getToolGrants()

    • getOriginGrants

      public Set<String> getOriginGrants()

    • revokeToolGrant

      public boolean revokeToolGrant(String toolName)

    • revokeOriginGrant

      public boolean revokeOriginGrant(String origin)

    • clearSessionGrants

      public void clearSessionGrants()

    • clearAll

      public void clearAll()
      Cancel pending requests and drop all session grants (test/reset helper).

    • getPending

      public List<ApprovalManager.PendingApproval> getPending()
      Unresolved pending requests, oldest first.

    • pendingCount

      public int pendingCount()

    • getById

      public ApprovalManager.PendingApproval getById(String id)

    • addListener

      public void addListener(ApprovalManager.Listener listener)

    • removeListener

      public void removeListener(ApprovalManager.Listener listener)

    • setScopeAdder

      public void setScopeAdder(Consumer<String> adder)
      Scope mutation callback used for ADD_TO_SCOPE decisions.