prototype

Documentation

Overview

Package prototype implements Prototype Pollution detection.

Source reference: PPmap (MIT, kleiton0x00) + prototype-pollution-checker (MIT) + PortSwigger prototype pollution research. Detection logic reimplemented from scratch.

Prototype Pollution occurs when user-controlled input is used to modify JavaScript's Object.prototype, affecting all objects in the application.

This module detects server-side prototype pollution (SSPP) via:

1. JSON body injection: inject {"__proto__":{"canary":"BHJSPP_<random>"}} or {"constructor":{"prototype":{"canary":"..."}}} in POST/PUT requests
2. Query param injection: ?__proto__[canary]=BHJSPP_xxx or ?constructor[prototype][canary]=BHJSPP_xxx
3. Response verification: if canary appears in response → SSPP confirmed
4. HTTP header reflection: inject via arbitrary header values

Client-side prototype pollution (CSPP) detection via DOM clobbering signals:

• Check if response body references globals that could be polluted
• Check for dangerous eval() or Function() patterns with user-controlled data

Architecture:

• Probe struct: ID, Location, Inject (template with {CANARY}), Detect func
• errgroup.SetLimit(Parallelism) fan-out
• io.LimitReader on all reads
• log/slog observability
• sync.Mutex protecting findings
• NewWithClient(*http.Client) + NewWithProbes([]Probe) for testability

Index

• Constants
• type Module
  • func New() *Module
  • func NewWithClient(c *http.Client) *Module
  • func NewWithProbes(probes []Probe) *Module
  • func NewWithProbesAndClient(probes []Probe, c *http.Client) *Module
  • func (m *Module) Name() string
  • func (m *Module) Run(ctx context.Context, input module.Input) ([]module.Finding, error)
• type Probe

Constants

const (
	DefaultTimeout     = 10 * time.Second
	DefaultParallelism = 10

	// LocationQuery injects into query parameters.
	LocationQuery = "query"
	// LocationJSON injects into JSON POST body.
	LocationJSON = "json"
)

Types

type Module

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

Module implements Prototype Pollution detection.

func New

func New() *Module

New returns a Module with all built-in prototype pollution probes.

func NewWithClient

func NewWithClient(c *http.Client) *Module

NewWithClient returns a Module using the supplied HTTP client.

func NewWithProbes

func NewWithProbes(probes []Probe) *Module

NewWithProbes returns a Module with custom probes (testability).

func NewWithProbesAndClient

func NewWithProbesAndClient(probes []Probe, c *http.Client) *Module

NewWithProbesAndClient returns a Module with custom probes and HTTP client.

func (*Module) Name

func (m *Module) Name() string

Name returns the module name.

func (*Module) Run

func (m *Module) Run(ctx context.Context, input module.Input) ([]module.Finding, error)

Run tests all target URLs for prototype pollution vulnerabilities.

Options:

• "parallelism" — max concurrent probes (default: 10)
• "location" — comma-separated filter: "query", "json"

type Probe

type Probe struct {
	// ID is a unique slug.
	ID string
	// Location is where the payload is injected (LocationQuery or LocationJSON).
	Location string
	// InjectTemplate is the injection pattern. {CANARY} is replaced with the unique canary.
	// For JSON: the full JSON body template.
	// For query: the parameter format "param=value".
	InjectTemplate string
	// Severity of the finding.
	Severity module.Severity
	// Tags are metadata tags.
	Tags []string
}

Probe defines a prototype pollution test.