{"id":13509286,"url":"https://github.com/v-byte-cpu/sx","last_synced_at":"2025-04-08T12:07:46.891Z","repository":{"id":37022973,"uuid":"323087102","full_name":"v-byte-cpu/sx","owner":"v-byte-cpu","description":":vulcan_salute: Fast, modern, easy-to-use network scanner","archived":false,"fork":false,"pushed_at":"2023-10-13T06:49:57.000Z","size":311,"stargazers_count":1489,"open_issues_count":16,"forks_count":109,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-01T10:16:36.602Z","etag":null,"topics":["arp","docker","go","icmp","infosec","ipv4","lan","network","pentest","proxy","recon","scan","scanner","security","socks","socks5","syn","tcp","udp","wan"],"latest_commit_sha":null,"homepage":"","language":"Go","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/v-byte-cpu.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,"governance":null}},"created_at":"2020-12-20T14:11:17.000Z","updated_at":"2025-03-27T19:44:43.000Z","dependencies_parsed_at":"2023-02-18T22:00:45.631Z","dependency_job_id":"6a717511-ae2c-4e2a-85b9-2cd6ac385988","html_url":"https://github.com/v-byte-cpu/sx","commit_stats":{"total_commits":93,"total_committers":4,"mean_commits":23.25,"dds":"0.22580645161290325","last_synced_commit":"56457bfaa49eb6fbb7a33d7092d9c636b9c85895"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/v-byte-cpu%2Fsx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/v-byte-cpu%2Fsx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/v-byte-cpu%2Fsx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/v-byte-cpu%2Fsx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/v-byte-cpu","download_url":"https://codeload.github.com/v-byte-cpu/sx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247838444,"owners_count":21004580,"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":["arp","docker","go","icmp","infosec","ipv4","lan","network","pentest","proxy","recon","scan","scanner","security","socks","socks5","syn","tcp","udp","wan"],"created_at":"2024-08-01T02:01:05.675Z","updated_at":"2025-04-08T12:07:46.871Z","avatar_url":"https://github.com/v-byte-cpu.png","language":"Go","funding_links":[],"categories":["开源类库","Go","Open source library","\u003ca name=\"infra\"\u003e\u003c/a\u003einfra","Related Lists","security","Repositories"],"sub_categories":["网络","The Internet"],"readme":"\n\u003ch1 align=\"center\"\u003e\n  \u003ca href=\"https://github.com/v-byte-cpu/sx#readme\"\u003e\n    \u003cimg alt=\"sx\" width=\"400\" src=\"assets/logo.svg\"\u003e\n  \u003c/a\u003e\n\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/v-byte-cpu/sx/blob/master/LICENSE)\n[![Build Status](https://cloud.drone.io/api/badges/v-byte-cpu/sx/status.svg)](https://cloud.drone.io/v-byte-cpu/sx)\n[![GoReportCard Status](https://goreportcard.com/badge/github.com/v-byte-cpu/sx)](https://goreportcard.com/report/github.com/v-byte-cpu/sx)\n![Platform](https://img.shields.io/badge/platform-linux%2Fdocker-blue)\n\n\u003c/div\u003e\n\n**sx** is the command-line network scanner designed to follow the UNIX philosophy.\n\nThe goal of this project is to create the fastest network scanner with clean and simple code.\n\n## 📖 Table of Contents\n\n* [Features](https://github.com/v-byte-cpu/sx#-features)\n* [Install](https://github.com/v-byte-cpu/sx#-install)\n* [Build from source](https://github.com/v-byte-cpu/sx#-build-from-source)\n* [Quick Start](https://github.com/v-byte-cpu/sx#-quick-start)\n* [References](https://github.com/v-byte-cpu/sx#-references)\n* [Contributing](https://github.com/v-byte-cpu/sx#-contributing)\n* [Credits](https://github.com/v-byte-cpu/sx#-credits)\n* [License](https://github.com/v-byte-cpu/sx#license)\n\n## ✨ Features\n\n  * **⚡ 30x times faster** than nmap\n  * **ARP scan**: Scan your local networks to detect live devices\n  * **ICMP scan**: Use advanced ICMP scanning techniques to detect live hosts and firewall rules\n  * **TCP SYN scan**: Traditional half-open scan to find open TCP ports\n  * **TCP FIN / NULL / Xmas scans**: Scan techniques to bypass some firewall rules\n  * **Custom TCP scans with any TCP flags**: Send whatever exotic packets you want and get a result with all the TCP flags set in the reply packet\n  * **UDP scan**: Scan UDP ports and get full ICMP replies to detect open ports or firewall rules\n  * **Application scans**:\n    * **SOCKS5 scan**: Detect live SOCKS5 proxies by scanning ip range or list of ip/port pairs from a file\n    * **Docker scan**: Detect open Docker daemons listening on TCP ports and get information about the docker node\n    * **Elasticsearch scan**: Detect open Elasticsearch nodes and pull out cluster information with all index names\n  * **Randomized iteration** over IP addresses using finite cyclic multiplicative groups\n  * **JSON output support**: sx is designed specifically for convenient automatic processing of results\n\n## 📦 Install\n\nThe simplest way is to download from [GitHub Releases](https://github.com/v-byte-cpu/sx/releases) and place the executable file in your PATH.\n\n## 🛠 Build from source\n\nRequirements:\n\n  * [Go 1.15 or newer](https://golang.org/dl/)\n  * [libpcap](https://www.tcpdump.org/) (already installed if you use **wireshark**)\n\nFrom the root of the source tree, run:\n\n```\ngo build\n```\n\n## 🚀 Quick Start\n\nHere's a quick examples showing how you can scan networks with `sx`.\n\n### ARP scan\n\nScan your local network and display the IP address, MAC address and associated hardware vendor of connected devices:\n\n```\nsx arp 192.168.0.1/24\n```\n\nsample output:\n\n```\n192.168.0.1          b0:be:76:40:05:8d    TP-LINK TECHNOLOGIES CO.,LTD.\n192.168.0.111        80:c5:f2:0b:02:e3    AzureWave Technology Inc.\n192.168.0.171        88:53:95:2d:3c:af    Apple, Inc.\n```\n\nwith JSON output:\n\n```\nsx arp --json 192.168.0.1/24\n```\n\nsample output:\n\n```\n{\"ip\":\"192.168.0.1\",\"mac\":\"b0:be:76:40:05:8d\",\"vendor\":\"TP-LINK TECHNOLOGIES CO.,LTD.\"}\n{\"ip\":\"192.168.0.111\",\"mac\":\"80:c5:f2:0b:02:e3\",\"vendor\":\"AzureWave Technology Inc.\"}\n{\"ip\":\"192.168.0.171\",\"mac\":\"88:53:95:2d:3c:af\",\"vendor\":\"Apple, Inc.\"}\n```\n\nwait 5 seconds before exiting to receive delayed reply packets, by default `sx` waits 300 milliseconds:\n\n```\nsx arp --exit-delay 5s 192.168.0.1/24\n```\n\nLive scan mode that rescans network every 10 seconds:\n\n```\nsx arp 192.168.0.1/24 --live 10s\n```\n\n### TCP scan\n\nUnlike nmap and other scanners that implicitly perform ARP requests to resolve IP addresses to MAC addresses before the actual scan, `sx` explicitly uses the **ARP cache** concept. ARP cache file is a simple text file containing JSON string on each line ([JSONL](https://jsonlines.org/) file), which has the same JSON fields as the ARP scan JSON output described above. Scans of higher-level protocols like TCP and UDP read the ARP cache file from the stdin and then start the actual scan.\n\nThis not only simplifies the design of the program, but also speeds up the scanning process, since it is not necessary to perform an ARP scan every time.\n\nLet's assume that the actual ARP cache is in the `arp.cache` file. We can create it manually\nor use ARP scan as shown below:\n\n```\nsx arp 192.168.0.1/24 --json | tee arp.cache\n```\n\nOnce we have the ARP cache file, we can run scans of higher-level protocols like TCP SYN scan:\n\n```\ncat arp.cache | sx tcp -p 1-65535 192.168.0.171\n```\n\nsample output:\n\n```\n192.168.0.171        22\n192.168.0.171        443\n```\n\nIn this case we find out that ports 22 and 443 are open.\n\nscan with JSON output:\n\n```\ncat arp.cache | sx tcp  --json -p 1-65535 192.168.0.171\n```\n\nsample output:\n\n```\n{\"scan\":\"tcpsyn\",\"ip\":\"192.168.0.171\",\"port\":22}\n{\"scan\":\"tcpsyn\",\"ip\":\"192.168.0.171\",\"port\":443}\n```\n\nscan multiple port ranges:\n\n```\ncat arp.cache | sx tcp -p 1-23,25-443 192.168.0.171\n```\n\nor individual ports:\n\n```\ncat arp.cache | sx tcp -p 22,443 192.168.0.171\n```\n\nor use the `--ports-file` option to specify a file with ports or port ranges to scan, one per line.\n\nscan ip/port pairs from a file with JSON output:\n\n```\ncat arp.cache | sx tcp --json -f ip_ports_file.jsonl\n```\n\nEach line of the input file is a json string, which must contain the **ip** and **port** fields.\n\nsample input file:\n\n```\n{\"ip\":\"10.0.1.1\",\"port\":1080}\n{\"ip\":\"10.0.2.2\",\"port\":1081}\n```\n\nIt is possible to specify the ARP cache file using the `-a` or `--arp-cache` options:\n\n```\nsx tcp -a arp.cache -p 22,443 192.168.0.171\n```\n\nor stdin redirect:\n\n```\nsx tcp -p 22,443 192.168.0.171 \u003c arp.cache\n```\n\nYou can also use the `tcp syn` subcommand instead of the `tcp`:\n\n```\ncat arp.cache | sx tcp syn -p 22 192.168.0.171\n```\n\n`tcp` subcomand is just a shorthand for `tcp syn` subcommand unless `--flags` option is passed, see below.\n\n### VPN interfaces\n\n`sx` supports scanning with virtual network interfaces (wireguard, openvpn, etc.) and in this case it is **not** necessary to use the arp cache, since these interfaces require raw IP packets instead of Ethernet frames as input. For instance, scanning an IP address on a vpn network:\n\n```\nsx tcp 10.1.27.1 -p 80 --json\n```\n\n### TCP FIN scan\n\nMost network scanners try to interpret results of the scan. For instance they say \"this port is closed\" instead of \"I received a RST\". Sometimes they are right. Sometimes not. It's easier for beginners, but when you know what you're doing, you keep on trying to deduce what really happened from the program's interpretation, especially for more advanced scan techniques. \n\n`sx` tries to overcome those problems. It returns information about all reply packets for TCP FIN, NULL, Xmas and custom TCP scans. The information contains IP address, TCP port and all TCP flags set in the reply packet.\n\nTCP FIN scan and its other variations (NULL and Xmas) exploit RFC793 Section 3.9:\n\n\u003e  SEGMENT ARRIVES\n\u003e\n\u003e    If the state is CLOSED (i.e., TCB does not exist) then\n\u003e\n\u003e      all data in the incoming segment is discarded.  An incoming\n\u003e      segment containing a RST is discarded.  An incoming segment not\n\u003e      containing a RST causes a RST to be sent in response.  The\n\u003e      acknowledgment and sequence field values are selected to make the\n\u003e      reset sequence acceptable to the TCP that sent the offending\n\u003e      segment.\n\nso closed port should return packet with RST flag.\n\nThis section also states that:\n\n\u003e If the state is LISTEN then\n\u003e\n\u003e   ...\n\u003e\n\u003e   Any other control or text-bearing segment (not containing SYN)\n\u003e   must have an ACK and thus would be discarded by the ACK\n\u003e   processing.  An incoming RST segment could not be valid, since\n\u003e   it could not have been sent in response to anything sent by this\n\u003e   incarnation of the connection.  So you are unlikely to get here,\n\u003e   but if you do, drop the segment, and return.\n\nthe main phrase here: **drop the segment**, and return. So an open port on most operating systems\nwill drop the TCP packet containing any flags except SYN,ACK and RST.\n\n\nLet's scan some closed port with TCP FIN scan:\n\n```\ncat arp.cache | sx tcp fin --json -p 23 192.168.0.171\n```\n\nsample output:\n\n```\n{\"scan\":\"tcpfin\",\"ip\":\"192.168.0.171\",\"port\":23,\"flags\":\"ar\"}\n```\n\n`flags` field contains all TCP flags in the reply packet, where each letter represents one of the TCP flags:\n  * `s` - SYN flag\n  * `a` - ACK flag\n  * `f` - FIN flag\n  * `r` - RST flag\n  * `p` - PSH flag\n  * `u` - URG flag\n  * `e` - ECE flag\n  * `c` - CWR flag\n  * `n` - NS flag\n\nIn this case we find out that port 23 sent reply packet with ACK and RST flags set (typical response for a closed port according to the rfc793).\n\nIf we scan an open port, we get no response (unless the firewall is spoofing the responses).\n\nOther types of TCP scans can be conducted by analogy.\n\nTCP NULL scan:\n\n```\ncat arp.cache | sx tcp null --json -p 23 192.168.0.171\n```\n\nTCP Xmas scan:\n\n```\ncat arp.cache | sx tcp xmas --json -p 23 192.168.0.171\n```\n\n### Custom TCP scans\n\nIt is possible to send TCP packets with custom TCP flags using `--flags` option.\n\nLet's send TCP packet with SYN, FIN and ACK flags set to fingerprint remote OS:\n\n```\ncat arp.cache | sx tcp --flags syn,fin,ack --json -p 23 192.168.0.171\n```\n\nWindows and MacOS will not respond to this packet, but Linux will send reply packet with RST flag.\n\nPossible arguments to `--flags` option:\n  * `syn` - SYN flag\n  * `ack` - ACK flag\n  * `fin` - FIN flag\n  * `rst` - RST flag\n  * `psh` - PSH flag\n  * `urg` - URG flag\n  * `ece` - ECE flag\n  * `cwr` - CWR flag\n  * `ns` - NS flag\n\n\n### UDP scan\n\n`sx` can help investigate open UDP ports. UDP scan exploits RFC1122 Section 4.1.3.1:\n\n\u003e If a datagram arrives addressed to a UDP port for which\n\u003e there is no pending LISTEN call, UDP SHOULD send an ICMP\n\u003e Port Unreachable message.\n\nSimilar to TCP scans, `sx` returns information about all reply ICMP packets for UDP scan. The information contains IP address, ICMP packet type and code set in the reply packet.\n\n\nFor instance, to detect DNS server on host, run:\n\n```\ncat arp.cache | sx udp --json -p 53 192.168.0.171\n```\n\nsample output:\n\n```\n{\"scan\":\"udp\",\"ip\":\"192.168.0.171\",\"icmp\":{\"type\":3,\"code\":3}}\n```\n\nIn this case we find out that host sent ICMP reply packet with **Destination Unreachable** type and **Port Unreachable** code (typical response for a closed port according to the rfc1122).\n\nFirewalls typically set ICMP code distinct from **Port Unreachanble** and so can be easily detected.\n\n\n### Rate limiting\n\nSometimes you need to limit the speed at which generated packets are sent. This can be done with \nthe `--rate` option.\n\nFor example, to limit the speed to 1 packet per 5 seconds:\n\n```\ncat arp.cache | sx tcp --rate 1/5s --json -p 22,80,443 192.168.0.171\n```\n\n### Exclude subnets\n\nSometimes you need to exclude some ip addresses and subnets from scanning. This can be done with \nthe `--exclude` option. It specifies a file with IPs or subnets in CIDR notation to exclude, one-per line.\n\nFor instance, to exclude RFC 1918 addresses, create a file `ips.txt` with the following contents:\n\n```\n10.0.0.0/8\n172.16.0.0/16\n192.168.0.0/16\n```\n\nYou can also insert comments and blank lines:\n\n```\n# exclude RFC 1918 addresses\n10.0.0.0/8 # comment 1\n172.16.0.0/12 # comment 2\n192.168.0.0/16 # comment 3\n\n0.0.0.0/8 # used in initialization procedures (RFC 6890)\n\n# exclude RFC 5735 addresses\n127.0.0.0/8 # loopback address\n192.0.0.0/24 # reserved block for IETF protocol assignments\n224.0.0.0/4 # allocated for use in IPv4 multicast address assignments\n240.0.0.0/4 # reserved for future use\n\n# exclude Amazon network\n3.0.0.0/8\n\n# ip addresses are valid as well\n1.1.1.1\n```\n\nand run a scan with `--exclude ips.txt` option.\n\n### Live LAN TCP SYN scanner\n\nAs an example of scan composition, you can combine ARP and TCP SYN scans to create live TCP port scanner that periodically scan whole LAN network.\n\nStart live ARP scan and save results to `arp.cache` file:\n\n```\nsx arp 192.168.0.1/24 --live 10s --json | tee arp.cache\n```\n\nIn another terminal start TCP SYN scan:\n\n```\nwhile true; do sx tcp -p 1-65535 -a arp.cache -f arp.cache; sleep 30; done\n```\n\n### SOCKS5 scan\n\n`sx` can detect live SOCKS5 proxies. To scan, you must specify an IP range or JSONL file with ip/port pairs.\n\nFor example, an IP range scan:\n\n```\nsx socks -p 1080 10.0.0.1/16\n```\n\nscan ip/port pairs from a file with JSON output:\n\n```\nsx socks --json -f ip_ports_file.jsonl \n```\n\nEach line of the input file is a json string, which must contain the **ip** and **port** fields.\n\nsample input file:\n\n```\n{\"ip\":\"10.0.1.1\",\"port\":1080}\n{\"ip\":\"10.0.2.2\",\"port\":1081}\n```\n\nYou can also specify a range of ports to scan:\n\n```\nsx socks -p 1080-4567 -f ips_file.jsonl\n```\n\nIn this case only ip addresses will be taken from the file and the **port** field is no longer necessary.\n\n### Elasticsearch scan\n\nElasticsearch scan retrieves the cluster information and a list of all indexes along with aliases.\n\nFor example, an IP range scan:\n\n```\nsx elastic -p 9200 10.0.0.1/16\n```\n\nBy default the scan uses the http protocol, to use the https protocol specify the `--proto` option:\n\n```\nsx elastic --proto https -p 9200 10.0.0.1/16\n```\n\nscan ip/port pairs from a file with JSON output:\n\n```\nsx elastic --json -f ip_ports_file.jsonl\n```\n\nEach line of the input file is a json string, which must contain the **ip** and **port** fields.\n\nsample input file:\n\n```\n{\"ip\":\"10.0.1.1\",\"port\":9200}\n{\"ip\":\"10.0.2.2\",\"port\":9201}\n```\n\nYou can also specify a range of ports to scan:\n\n```\nsx elastic -p 9200-9267 -f ips_file.jsonl\n```\n\nIn this case only ip addresses will be taken from the file and the **port** field is no longer necessary.\n\n\n## Usage help\n\n```\nsx help\n```\n\n## 📜 References\n\n  * **Network Security Assessment: Know Your Network 1st Edition** by Chris McNab\n  * **ICMP Usage in Scanning - The Complete Know-How** by Ofir Arkin\n  * [Transmission Control Protocol ( rfc793 )](https://tools.ietf.org/rfc/rfc793.txt)\n  * [User Datagram Protocol ( rfc768 )](https://tools.ietf.org/rfc/rfc768.txt)\n  * [Requirements for Internet Hosts -- Communication Layers ( rfc1122 )](https://tools.ietf.org/rfc/rfc1122.txt)\n  * [SOCKS Protocol Version 5 ( rfc1928 )](https://tools.ietf.org/rfc/rfc1928.txt)\n  * [Internet Control Message Protocol ( rfc792 )](https://tools.ietf.org/rfc/rfc792.txt)\n\n## 🤝 Contributing\n\nContributions, issues and feature requests are welcome.\n\n## 💎 Credits\n\nLogo is designed by [mikhailtsoy.com](https://mikhailtsoy.com/)\n\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](https://github.com/v-byte-cpu/sx/blob/master/LICENSE) file for the full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fv-byte-cpu%2Fsx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fv-byte-cpu%2Fsx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fv-byte-cpu%2Fsx/lists"}