Hackable HTTP proxy: Toxy

ID N0WHERE:42692
Type n0where
Reporter N0where
Modified 2015-08-28T12:52:55


toxy is a fully programmatic and hackable HTTP proxy to simulate server failure scenarios and unexpected network conditions

It was mainly designed for fuzzing/evil testing purposes, when toxy becomes particularly useful to cover fault tolerance and resiliency capabilities of a system, especially in service-oriented architectures, where toxy may act as intermediate proxy among services.

toxy allows you to plug in poisons , optionally filtered by rules , which essentially can intercept and alter the HTTP flow as you need, performing multiple evil actions in the middle of that process, such as limiting the bandwidth, delaying TCP packets, injecting network jitter latency or replying with a custom error or status code.

toxy can be fluently used programmatically or via HTTP API . It’s compatible with connect / express , and it was built on top of rocky , a full-featured middleware-oriented HTTP proxy.

Requires node.js +0.12 or io.js +1.6

Hackable HTTP proxy: Toxy Hackable HTTP proxy: Toxy Hackable HTTP proxy: Toxy Hackable HTTP proxy: Toxy


  • Full-featured HTTP/S proxy (backed by rocky and http-proxy )
  • Hackable and elegant programmatic API (inspired on connect/express)
  • Admin HTTP API for external management and dynamic configuration
  • Featured built-in router with nested configuration
  • Hierarchical and composable poisioning with rule based filtering
  • Hierarchical middleware layer (both global and route scopes)
  • Easily augmentable via middleware (based on connect/express middleware)
  • Built-in poisons (bandwidth, error, abort, latency, slow read…)
  • Rule-based poisoning (probabilistic, HTTP method, headers, body…)
  • Support third-party poisons and rules
  • Built-in balancer and traffic intercept via middleware
  • Inherits API and features from rocky
  • Compatible with connect/express (and most of their middleware)
  • Able to run as standalone HTTP proxy

Why toxy?

There’re some other similar solutions like toxy in the market, but most of them do not provide a proper programmatic control and usually are not easy to hack, configure and/or extend. Additionally, most of the those solutions only operate at TCP level stack instead of providing high-level abstraction to cover common requirements of the specific domain and nature of the HTTP protocol, like toxy does.

toxy provides a powerful hackable and extensible solution with a convenient abstraction, but also a low-level interface and programmatic capabilities exposed as a simple, concise and fluent API, with the implicit power, simplicity and fun of node.js.


toxy introduces two core directives that you can plug in the proxy and should knowing before using: poisons and rules.

Poisons are the specific logic to infect an incoming or outgoing HTTP flow (e.g: injecting a latency, replying with an error). HTTP flow can be poisoned by one or multiple poisons, and poisons can be plugged to infect both global or route level incoming traffic.

Rules are a kind of validation filters that can be reused and applied to global incoming HTTP traffic, route level traffic or into a specific poison. Their responsability is to determine, via inspecting each incoming HTTP request, if the registered poisons should be enabled or not, and therefore infecting or not the HTTP traffic (e.g: match headers, query params, method, body…).

How it works

↓   ( Incoming request )  ↓
↓           |||           ↓
↓     ----------------    ↓
↓     |  Toxy Router |    ↓ --> Match the incoming request
↓     ----------------    ↓
↓           |||           ↓
↓     ----------------    ↓
↓     |  Exec Rules  |    ↓ --> Apply configured rules for the request
↓     ----------------    ↓
↓           |||           ↓
↓     ----------------    ↓
↓     | Exec Poisons |    ↓ --> If all rules passed, then poison the HTTP flow
↓     ----------------    ↓
↓        /       \        ↓
↓        \       /        ↓
↓   -------------------   ↓
↓   | HTTP dispatcher |   ↓ --> Proxy the HTTP traffic, either poisoned or not
↓   -------------------   ↓


npm install toxy


Poisons host specific logic which intercepts and mutates, wraps, modify and/or cancel an HTTP transaction in the proxy server. Poisons can be applied to incoming or outgoing, or even both traffic flows.

Poisons can be composed and reused for different HTTP scenarios. They are executed in FIFO order and asynchronously.


Rules are simple validation filters which inspect an HTTP request and determine, given a certain rules (e.g: method, headers, query params), if the HTTP transaction should be poisoned or not.

Rules are useful to compose, decouple and reuse logic among different scenarios of poisoning. Rules can be applied to the global, route or even poison scope.

Rules are executed in FIFO order. Their evaluation logic is equivalent to Array#every() in JavaScript: all the rules must pass in order to proceed with the poisoning.

Hackable HTTP proxy Download