tcpscan is a Python command-line tool that leverages the core functionalities of tcpdump and Scapy to provide clear, concise output for TCP/IP packet analysis. It captures TCP packets, displaying source/destination IPs, MSS (Maximum Segment Size), Window Size, and ACK status—making it ideal for efficient network testing and debugging.
Designed for macOS and Linux, it supports interactive interface selection, command-line arguments, and automatic interface activation (e.g., enabling Wi-Fi on macOS).
- Capture TCP SYN packets (for MSS) or all TCP packets
- Clear output of packet details:
- Source/Destination IPs
- MSS
- Window Size
- ACK status
- Debug TCP options if MSS is not present
- Activate inactive interfaces (e.g., enable Wi-Fi, prompt for Ethernet cable)
- Command-line arguments for:
- Interface
- Packet count
- Timeout
- Packet type
- Compatible with macOS and Linux
Python 3.6+
python3 --versionpip3
python3 -m ensurepip --upgradelibpcap (required by Scapy for packet capture)
macOS: Usually preinstalled
Linux:
sudo apt-get install libpcap-devRoot Privileges:
Use sudo when running the script.
Active Network Interface:
macOS: en0, en1, lo0
Linux: eth0, wlan0, lo
git clone https://github.com/FranzFelini/tcpscan.git
cd tcpscanpip3 install -r requirements.txtpython3 -m venv venv
source venv/bin/activate
pip install -r requirements.txtIf pip3 requires root:
sudo pip3 install -r requirements.txtsudo mv tcpscan /usr/local/bin/tcpscan
sudo chmod +x /usr/local/bin/tcpscanRun interactively (prompts for interface):
sudo tcpscanSpecify interface:
sudo tcpscan -i en0Capture 20 packets with a 30-second timeout:
sudo tcpscan -i en0 -c 20 -t 30Capture all TCP packets (not just SYN):
sudo tcpscan -i en0 --all-tcpTo generate SYN packets (which include MSS), start a new connection:
curl http://google.comOr open a browser and visit:
https://example.com
TCP Packet Fingerprint Tool
Capturing up to 10 TCP SYN packets on interface en0 (timeout: 10 seconds)...
172.16.4.47 -> 104.18.29.234, MSS: 1460, Window: 65535, ACK: No
Debug: TCP options for 172.16.4.47 -> 104.18.29.234: [('MSS', 1460), ('WScale', 7), ('SAckOK', ''), ('Timestamp', (123456, 0))]
Captured 3 TCP SYN packets.
- MSS is only present in TCP SYN packets. Use
--all-tcpto capture all TCP traffic (MSS will not be present in non-SYN packets). - macOS interfaces:
en0= Wi-Fien1= Ethernetlo0= loopback
- Linux interfaces:
eth0,wlan0,lo
- The script can:
- Enable Wi-Fi on macOS
- Prompt to plug in Ethernet cable
- Debug output shows full TCP options if MSS is not present
- Generate new connections during capture for best results
Ensure traffic:
curl http://example.comVerify interface:
ifconfig en0 # macOS
ip link # LinuxTest with tcpdump:
sudo tcpdump -i en0 -nn 'tcp[tcpflags] & tcp-syn != 0'Ensure pip is installed:
python3 -m ensurepip --upgradeInstall libpcap (Linux):
sudo apt-get install libpcap-devRun as root:
sudo tcpscanVerify Scapy:
python3 -c "import scapy; print(scapy.__version__)"Check debug output. In rare cases, MSS may be stripped by:
- Firewalls
- Middleboxes
- Network filtering gear
MIT License. See the LICENSE file.