A straightforward forward-proxy written in Node.js
- Extremely focused (~200 SLOC), no-fuzz forward proxy
- Support HTTP, HTTPS, CONNECT & Websockets (wss)
- Performant: By default all requests/responses are streamed
- No external dependencies, small, self-contained, tested
- Support both cli and extensible programmatic usage
- Straightforward: no implicit magic or abstractions
- Start an explicit forwarding proxy in seconds that just works
- Optionally use authentication and a white-/blacklist for hosts
- Block requests, fake or modify responses
- Allow others to surf with your IP address
- Use it programmatically to do whatever you want
- A ssl-intercepting proxy (https can be filtered but not modified)
- A reverse proxy to load-balance stuff to internal servers
- A general purpose webserver framework
- A proxy middleware for express
- A transparent forward proxy
- A caching proxy
- A sni proxy
# Use directly with no installation (npx is part of npm):
❯❯❯ npx straightforward --port 9191
# Or install globally:
❯❯❯ npm install -g straightforward
❯❯❯ straightforward --help
Usage: straightforward --port 9191 [options]
Options:
--version Show version number [boolean]
--port, -p Port to bind on [number] [default: 9191]
--auth, -a Enable proxy authentication [string]
--blacklist-host Allow all requests except to blacklist [string]
--whitelist-host Deny all requests except to whitelist [string]
--block-msg Show custom block message (http only) [string]
--replace-text Replace text on websites (http only) [string]
--debug, -d Enabled debug output [boolean]
--cluster, -c Run a cluster of proxies (using number of CPUs) [boolean]
--cluster-count Specify how many cluster workers to spawn [number]
--quiet, -q Suppress request logs [boolean]
--silent, -s Dont print anything to stdout [boolean]
-h, --help Show help [boolean]
Examples:
straightforward --auth "user:pass" Require authentication
straightforward --whitelist-host "a.com,b.net" Allow specific hosts
straightforward --blacklist-host "a.com,b.net" Block specific hosts
straightforward --block-msg "<h1>Nope ಠ_ಠ</h1>" Custom block message
straightforward --replace-text "cloud:butt" Replace all occurences of cloud with butt
Use with cURL:
curl --proxy https://localhost:9191 'http://example.com' -v
const Straightforward = require('straightforward')
;(async () => {
// Start proxy server
const sf = await new Straightforward().listen(9191)
console.log(`Proxy listening on http://localhost:9191`)
// Log http requests
sf.onRequest(async ({ req, res }, next) => {
console.log(`http request: ${req.url}`)
// Note the common middleware pattern, use `next()`
// to pass the request to the next handler.
return next()
})
// Log connect (https) requests
sf.onConnect(async ({ req, res }, next) => {
console.log(`connect request: ${req.url}`)
return next()
})
// Filter some requests dynamically
const blockRequest = sf.middleware.blockRequest({
filterFn: (host, url) => host.includes('malware.com'),
responseMsg: `<h1>None shall pass. 🐗</h1>`
})
sf.onRequest(blockRequest) // for http
sf.onConnect(blockRequest) // for https
// Replace text on http://example.com for fun and glory
sf.onResponse(sf.middleware.replaceText({
filterFn: (host, url) => host.includes('example.com'),
replacerFn: (str) => str.replace(/example/ig, 'FOOBAR')
}))
})()
❯❯❯ straightforward --replace-text "example:FOOBAR"
Let's say you have a fresh linux server and want to use it as an authenticated forward proxy quickly.
- Make sure nvm is installed:
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash
- Make sure a recent version of Node.js is installed:
nvm install node && nvm use node && node --version
- Add forever (process manager) and straightforward:
npm install -g forever straightforward
- Start proxy daemon:
forever start --id "proxy1" $( which straightforward ) --port 9191 --quiet --auth 'user:foobar'
- Test your proxy from a different machine:
curl --proxy http://user:foobar@SERVER:9191/ http://canhazip.com
- List all running forever services:
forever list
- Stop our proxy service daemon:
forever stop proxy1
MIT