oob

Documentation

Overview

Package oob is an out-of-band interaction catcher for blind-vulnerability testing (blind SSRF / XXE / SQLi / RCE). It mints unique tokens, records any inbound HTTP request whose path carries one (/oob/<token>/…), and lets the UI poll the captured interactions.

Reachability is the operator's responsibility: the catcher only sees callbacks that actually reach the bound interface. For local testing the control origin works; for a real target, bind externally (or tunnel) and set the base URL so payloads point at a host the target can resolve and reach. (This is the same constraint any collaborator has — we just don't ship a public server.)

Index

• func TokenFromPath(p string) string
• type Catcher
  • func New() *Catcher
  • func (c *Catcher) Clear()
  • func (c *Catcher) CorrelationFor(token string) (Correlation, bool)
  • func (c *Catcher) Count() int
  • func (c *Catcher) InteractionsForToken(token string) []Interaction
  • func (c *Catcher) List() []Interaction
  • func (c *Catcher) MintCorrelated(runID int64, candidateID string, probeFlowID int64) (token, url string)
  • func (c *Catcher) MintCorrelatedURL(runID int64, candidateID string, probeFlowID int64, baseURL string) (token, url string)
  • func (c *Catcher) Record(r *http.Request, bodyPreview string)
  • func (c *Catcher) SetNotifier(fn func())
  • func (c *Catcher) Token() string
• type Correlation
• type Interaction

Functions

func TokenFromPath

func TokenFromPath(p string) string

TokenFromPath extracts the token from a /oob/<token>[/...] request path, or "".

Types

type Catcher

type Catcher struct {
	// contains filtered or unexported fields
}

Catcher records OOB interactions in memory.

The interaction ring (items/seq/notify) is guarded by mu; the token→probe correlation map (corr/corrOrder) is guarded by its own cmu so correlation is purely additive metadata and never contends with the hot recording path.

func New

func New() *Catcher

New returns an empty Catcher.

func (*Catcher) Clear

func (c *Catcher) Clear()

Clear drops all recorded interactions.

func (*Catcher) CorrelationFor

func (c *Catcher) CorrelationFor(token string) (Correlation, bool)

CorrelationFor returns the correlation recorded for a token, if any.

func (*Catcher) Count

func (c *Catcher) Count() int

Count returns how many interactions are stored.

func (*Catcher) InteractionsForToken

func (c *Catcher) InteractionsForToken(token string) []Interaction

InteractionsForToken returns any recorded interactions whose path-token equals token, newest first. This is the poll Gate 3 uses: a non-empty result means the injected payload was dereferenced server-side — proof of a blind vuln.

It reads the existing interaction ring, so it works for both correlated tokens (minted via MintCorrelated) and plain manual-OOB tokens.

func (*Catcher) List

func (c *Catcher) List() []Interaction

List returns the recorded interactions, newest first.

func (*Catcher) MintCorrelated

func (c *Catcher) MintCorrelated(runID int64, candidateID string, probeFlowID int64) (token, url string)

MintCorrelated mints a fresh token, stores its correlation to the injecting probe, and returns the token plus a ready-to-inject callback URL.

baseURL is the operator-configured public OOB base (built by the caller from the request Host + the persisted oob.baseUrl setting — that URL-building lives in internal/control, so it is passed in here to keep the package boundary clean). The returned url is baseURL joined with the token; if baseURL is empty the returned url is empty and the caller can build it from just the token.

The correlation is additive metadata: it does not touch the interaction ring, so the existing manual-OOB Record/List/Count/Clear flow is unchanged.

func (*Catcher) MintCorrelatedURL

func (c *Catcher) MintCorrelatedURL(runID int64, candidateID string, probeFlowID int64, baseURL string) (token, url string)

MintCorrelatedURL is MintCorrelated with a caller-supplied public base URL; it returns the token and the full callback URL (baseURL + "/" + token).

func (*Catcher) Record

func (c *Catcher) Record(r *http.Request, bodyPreview string)

Record stores an interaction for the request (token taken from its path). bodyPreview should be a short, already-truncated snippet (may be empty).

func (*Catcher) SetNotifier

func (c *Catcher) SetNotifier(fn func())

SetNotifier registers a callback fired when a new interaction is recorded.

func (*Catcher) Token

func (c *Catcher) Token() string

Token mints a fresh random token to embed in an OOB payload URL.

type Correlation

type Correlation struct {
	Token       string `json:"token"`
	RunID       int64  `json:"runId"`
	CandidateID string `json:"candidateId"`
	ProbeFlowID int64  `json:"probeFlowId"`
	InjectedAt  int64  `json:"injectedAt"` // unix millis
}

Correlation links a minted OOB token back to the exact probe that injected it, so an arriving interaction is attributable to a specific run/candidate/flow. This is the missing wire for blind-vulnerability verification (§5 Gate 3): the verifier mints a token FOR a probe, injects its URL, then polls for a callback carrying that exact token as proof the payload executed server-side.

type Interaction

type Interaction struct {
	ID         int64  `json:"id"`
	Token      string `json:"token"`
	Method     string `json:"method"`
	Path       string `json:"path"`
	RemoteAddr string `json:"remoteAddr"`
	Host       string `json:"host"`
	UserAgent  string `json:"userAgent"`
	Query      string `json:"query"`
	BodyPrev   string `json:"bodyPreview"`
	TS         int64  `json:"ts"` // unix millis
}

Interaction is one recorded inbound hit.