{"id":16554,"library":"tunnel-agent","title":"HTTP Proxy Tunneling Agent","description":"tunnel-agent is an HTTP proxy tunneling agent originally extracted from the now-deprecated `mikeal/request` library. Its primary function is to facilitate HTTP and HTTPS requests through a proxy server, enabling applications to bypass network restrictions or access resources securely via a tunnel. The package's latest version, 0.6.0, was published over nine years ago, in March 2017. It is considered unmaintained and effectively abandoned, with no new versions or significant activity in recent years. Developers should exercise extreme caution or avoid using this package due to its unmaintained status and potential security vulnerabilities, especially given the historical context of its origin from a library with known security issues. Modern alternatives offer better security, maintenance, and features for proxy tunneling. There is an active `@postman/tunnel-agent` fork, but it has its own separate security concerns including detected malware in some versions.","status":"abandoned","version":"0.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/mikeal/tunnel-agent","tags":["javascript"],"install":[{"cmd":"npm install tunnel-agent","lang":"bash","label":"npm"},{"cmd":"yarn add tunnel-agent","lang":"bash","label":"yarn"},{"cmd":"pnpm add tunnel-agent","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is a CommonJS module. Direct ESM `import` statements are not supported without a transpiler or Node.js's native ESM interop (e.g., `import tunnel from 'tunnel-agent/index.js'`) and are generally not recommended for unmaintained CJS libraries.","wrong":"import tunnel from 'tunnel-agent';","symbol":"agent","correct":"const tunnel = require('tunnel-agent');\nconst agent = tunnel.httpOverHttp({ /* options */ });"},{"note":"Used for tunneling HTTPS traffic over an HTTP proxy. Most common use case.","symbol":"httpsOverHttp","correct":"const tunnel = require('tunnel-agent');\nconst agent = tunnel.httpsOverHttp({ proxy: { host: 'proxy.example.com', port: 8080 } });"},{"note":"Used for tunneling HTTP traffic over an HTTP proxy.","symbol":"httpOverHttp","correct":"const tunnel = require('tunnel-agent');\nconst agent = tunnel.httpOverHttp({ proxy: { host: 'proxy.example.com', port: 8080 } });"}],"quickstart":{"code":"const http = require('http');\nconst tunnel = require('tunnel-agent');\n\n// Configure the tunneling agent to go through an HTTP proxy\nconst tunnelingAgent = tunnel.httpOverHttp({\n  proxy: {\n    host: process.env.HTTP_PROXY_HOST ?? '127.0.0.1',\n    port: parseInt(process.env.HTTP_PROXY_PORT ?? '8080', 10),\n    proxyAuth: process.env.HTTP_PROXY_AUTH ?? '' // Optional: 'user:password'\n  }\n});\n\n// Options for the actual HTTP request\nconst requestOptions = {\n  host: 'example.com',\n  port: 80,\n  path: '/',\n  agent: tunnelingAgent,\n  headers: {\n    'User-Agent': 'tunnel-agent-example'\n  }\n};\n\n// Make the request using the tunneling agent\nconst req = http.request(requestOptions, (res) => {\n  console.log(`STATUS: ${res.statusCode}`);\n  console.log(`HEADERS: ${JSON.stringify(res.headers)}`);\n  res.setEncoding('utf8');\n  let data = '';\n  res.on('data', (chunk) => { data += chunk; });\n  res.on('end', () => {\n    console.log('No more data in response.');\n    // console.log(data); // Uncomment to see response body\n  });\n});\n\nreq.on('error', (e) => {\n  console.error(`Problem with request: ${e.message}`);\n});\n\nreq.end();","lang":"javascript","description":"Demonstrates how to configure and use `tunnel-agent` to make an HTTP request through an HTTP proxy. It uses environment variables for proxy configuration for security."},"warnings":[{"fix":"Migrate to a actively maintained HTTP tunneling library like `proxy-agent`, `@fastify/http-proxy`, or `https-proxy-agent`. Ensure your chosen alternative is regularly updated and has a strong security posture.","message":"This package is effectively abandoned. Its last update was over nine years ago (v0.6.0, March 2017). Using unmaintained software can lead to severe security vulnerabilities, compatibility issues with newer Node.js versions, and lack of support for modern web standards.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Avoid using `tunnel-agent` entirely. If migration is not immediately possible, thoroughly audit any indirect dependencies that might pull in vulnerable older versions. Scan your project with tools like Snyk or npm audit.","message":"Older versions of `tunnel-agent` (specifically v0.4.3) have known security vulnerabilities related to 'Uninitialized Memory Exposure' when used with `request/request`. Although v0.6.0 is newer, the unmaintained status means no new vulnerabilities will be patched, posing significant risk.","severity":"gotcha","affected_versions":"<0.6.0"},{"fix":"Always use `const tunnel = require('tunnel-agent');` when integrating `tunnel-agent` into your Node.js application. If your project is pure ESM, consider rewriting the functionality or finding an ESM-native alternative.","message":"As a legacy CommonJS module, `tunnel-agent` does not officially support ES Modules (ESM) `import` syntax. Attempting to use `import` without proper tooling (like Babel) or Node.js's interop features (which can be fragile for older CJS modules) will result in runtime errors.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"For SOCKS proxy support or more robust authentication, you will need to integrate additional specialized proxy agents. For modern and flexible proxying, consider libraries that offer broader protocol and authentication support out-of-the-box.","message":"The functionality of `tunnel-agent` only covers basic HTTP/HTTPS over HTTP proxies. It does not natively support advanced proxy authentication mechanisms (beyond basic `proxyAuth` string), SOCKS proxies, or more complex tunneling scenarios without external libraries or significant manual implementation.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure your file is a CommonJS module (`.js` without `\"type\": \"module\"` in `package.json` or explicitly `.cjs` extension) and use `const tunnel = require('tunnel-agent');`. If your project is ESM-only, a direct `import tunnel from 'tunnel-agent'` might work as Node.js CJS-ESM interop, but it's generally unstable for abandoned packages.","cause":"Attempting to use `require()` in an ES Module context or `import` in a CommonJS context for a package that only supports the other.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module ... from ... not supported."},{"fix":"Verify that `tunnel-agent` is installed (`npm list tunnel-agent`). Ensure `const tunnel = require('tunnel-agent');` is the first interaction with the module. This error can also happen if attempting to use a default import in ESM where only named exports exist (which is not the case for this CJS module).","cause":"The `tunnel-agent` module was not correctly loaded, or `tunnel` is not the expected object.","error":"TypeError: tunnel.httpOverHttp is not a function"}],"ecosystem":"npm"}