- Notifications
You must be signed in to change notification settings - Fork43
📦 The fastest and simplest packet manipulation lib for Python
License
mike01/pypacker
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Please note: This respository has become staled due to relocation to GitLab. Visithttps://gitlab.com/mike01/pypacker for up-to-date versions.
This is Pypacker: The fastest and simplest packet manipulation lib for Python.It lets you create packets manually by defining every aspect of all header data,dissect packets by parsing raw packet bytes, sending/receiving packets on different layers and intercepting packets.
Create Packets giving specific values or take the defaults:
frompypacker.layer3.ipimportIPfrompypacker.layer3.icmpimportICMPip=IP(src_s="127.0.0.1",dst_s="192.168.0.1",p=1)+\ICMP(type=8)+\ICMP.Echo(id=123,seq=1,body_bytes=b"foobar")# output packetprint("%s"%ip)IP(v_hl=45,tos=0,len=2A,id=0,off=0,ttl=40,p=1,sum=3B29,src=b'\x7f\x00\x00\x01',dst=b'\xc0\xa8\x00\x01',opts=[],handler=icmp)ICMP(type=8,code=0,sum=C03F,handler=echo)Echo(id=7B,seq=1,ts=0,bytes=b'foobar')
Read packets from file (pcap/tcpdump format), analyze it and write them back:
frompypackerimportppcapfrompypacker.layer12importethernetfrompypacker.layer3importipfrompypacker.layer4importtcppreader=ppcap.Reader(filename="packets_ether.pcap")pwriter=ppcap.Writer(filename="packets_ether_new.pcap",linktype=ppcap.DLT_EN10MB)forts,bufinpreader:eth=ethernet.Ethernet(buf)ifeth[ethernet.Ethernet,ip.IP,tcp.TCP]isnotNone:print("%d: %s:%s -> %s:%s"% (ts,eth[ip.IP].src_s,eth[tcp.TCP].sport,eth[ip.IP].dst_s,eth[tcp.TCP].dport))pwriter.write(eth.bin())pwriter.close()
Intercept (and modificate) Packets eg for MITM:
# Add iptables rule:# iptables -I INPUT 1 -p icmp -j NFQUEUE --queue-balance 0:2importtimefrompypackerimportinterceptorfrompypacker.layer3importip,icmp# ICMP Echo request interceptingdefverdict_cb(ll_data,ll_proto_id,data,ctx):ip1=ip.IP(data)icmp1=ip1[icmp.ICMP]ificmp1isNoneoricmp1.type!=icmp.ICMP_TYPE_ECHO_REQ:returndata,interceptor.NF_ACCEPTecho1=icmp1[icmp.ICMP.Echo]ifecho1isNone:returndata,interceptor.NF_ACCEPTpp_bts=b"PYPACKER"print("changing ICMP echo request packet")echo1.body_bytes=echo1.body_bytes[:-len(pp_bts)]+pp_btsreturnip1.bin(),interceptor.NF_ACCEPTictor=interceptor.Interceptor()ictor.start(verdict_cb,queue_ids=[0,1,2])print("now sind a ICMP echo request to localhost: ping 127.0.0.1")time.sleep(999)ictor.stop()
Send and receive packets:
# send/receive raw bytesfrompypackerimportpsocketfrompypacker.layer12importethernetfrompypacker.layer3importippsock=psocket.SocketHndl(mode=psocket.SocketHndl.MODE_LAYER_2,timeout=10)forraw_bytesinpsock:eth=ethernet.Ethernet(raw_bytes)print("Got packet: %r"%eth)eth.reverse_address()eth.ip.reverse_address()psock.send(eth.bin())# stop on first packetbreakpsock.close()
# send/receive using filterfrompypackerimportpsocketfrompypacker.layer3importipfrompypacker.layer4importtcppacket_ip=ip.IP(src_s="127.0.0.1",dst_s="127.0.0.1")+tcp.TCP(dport=80)psock=psocket.SocketHndl(mode=psocket.SocketHndl.MODE_LAYER_3,timeout=10)deffilter_pkt(pkt):returnpkt.ip.tcp.sport==80psock.send(packet_ip.bin(),dst=packet_ip.dst_s)pkts=psock.recvp(filter_match_recv=filter_pkt)forpktinpkts:print("got answer: %r"%pkt)psock.close()
# Send/receive based on source/destination datafrompypackerimportpsocketfrompypacker.layer3importipfrompypacker.layer4importtcppacket_ip=ip.IP(src_s="127.0.0.1",dst_s="127.0.0.1")+tcp.TCP(dport=80)psock=psocket.SocketHndl(mode=psocket.SocketHndl.MODE_LAYER_3,timeout=10)packets=psock.sr(packet_ip,max_packets_recv=1)forpinpackets:print("got layer 3 packet: %s"%p)psock.close()
- Create network packets on different OSI layers using keywords like MyPacket(value=123) or raw bytes MyPacket(b"value")
- Concatination of layers via "+" like packet = layer1 + layer2
- Fast access to layers via packet[tcp.TCP] or packet.sublayerXYZ.tcp notation
- Readable packet structure using print(packet) or similar statements
- Read/store packets via Pcap/tcpdump file reader/writer
- Live packet reading/writing using a wrapped socket API
- Auto Checksum calculation capabilities
- Intercept Packets using NFQUEUE targets
- Easily create new protocols (see FAQ below)
- Python 3.x (CPython, Pypy, Jython or whatever Interpreter)
- Optional (for interceptor):
- CPython
- Linux based system
- iptables
- NFQUEUE target support in kernel for packet intercepting
- libnetfilter_queue library (seehttp://www.netfilter.org/projects/libnetfilter_queue)
Some examples:
- Download/clone pypacker -> python setup.py install (newest version)
- pip install pypacker (synched to master on major version changes)
See examples/ and tests/test_pypacker.py.
Tests are executed as follows:
- Add Pypacker directory to the PYTHONPATH.
- cd pypacker
- export PYTHONPATH=$PYTHONPATH:$(pwd)
- execute tests
- python tests/test_pypacker.py
Performance test results: pypacker
orC = Intel Core2 Duo CPU @ 1,866 GHz, 2GB RAM, CPython v3.6orP = Intel Core2 Duo CPU @ 1,866 GHz, 2GB RAM, Pypy 5.10.1rounds per test: 10000=====================================>>> parsing (IP + ICMP)orC = 86064 p/sorP = 208346 p/s>>> creating/direct assigning (IP only header)orC = 41623 p/sorP = 59370 p/s>>> bin() without change (IP)orC = 170356 p/sorP = 292133 p/s>>> output with change/checksum recalculation (IP)orC = 10104 p/sorP = 23851 p/s>>> basic/first layer parsing (Ethernet + IP + TCP + HTTP)orC = 62748 p/sorP = 241047 p/s>>> changing Triggerlist element value (Ethernet + IP + TCP + HTTP)orC = 101552 p/sorP = 201994 p/s>>> changing Triggerlist/text based proto (Ethernet + IP + TCP + HTTP)orC = 37249 p/sorP = 272972 p/s>>> direct assigning and concatination (Ethernet + IP + TCP + HTTP)orC = 7428 p/sorP = 14315 p/s>>> full packet parsing (Ethernet + IP + TCP + HTTP)orC = 6886 p/sorP = 17040 p/sPerformance test results: pypacker vs. dpkt vs. scapy
Comparing pypacker, dpkt and scapy performance (parsing Ethernet + IP + TCP + HTTP)orC = Intel Core2 Duo CPU @ 1,866 GHz, 2GB RAM, CPython v3.6orC2 = Intel Core2 Duo CPU @ 1,866 GHz, 2GB RAM, CPython v2.7rounds per test: 10000=====================================>>> testing pypacker parsing speedorC = 17938 p/s>>> testing dpkt parsing speedorC = 12431 p/s>>> testing scapy parsing speedorC2 = 726 p/sQ:Where should I start learn to use Pypacker?
A:If you allready know Scapy starting by reading the examples should be OK. Otherwise thereis a general introduction to pypacker included at the doc's which shows the usage and conceptsof pypacker.
Q:How fast is pypacker?
A:See results above. For detailed results on your machine execute tests.
Q:Is there any documentation?
A:Pypacker is based on code of dpkt, which in turn didn't have any official and very littleinternal code documentation. This made understanding of the internal behaviour tricky.After all the code documentation was pretty much extended for Pypacker. Documentation canbe found in these directories and files:
- examples/ (many examples showing the usage of Pypacker)
- wiki (general intro into pypacker)
- pypacker.py (general Packet structure)
Protocols itself (see layerXYZ) generally don't have much documentation because those are documentedby their respective RFCs/official standards.
Q:Which protocols are supported?
A:Currently minimum supported protocols are:Ethernet, Radiotap, IEEE80211, ARP, DNS, STP, PPP, OSPF, VRRP, DTP, IP, ICMP, PIM, IGMP, IPX,TCP, UDP, SCTP, HTTP, NTP, RTP, DHCP, RIP, SIP, Telnet, HSRP, Diameter, SSL, TPKT, Pmap, Radius, BGP
Q:How are protocols added?
A: Short answer: Extend Packet class and add the class variable__hdr__ to define header fields.Long answer: See examples/examples_new_protocol.py for a very complete example.
Q: How can I contribute to this project?
A: Please use the Github bug-tracker for bugs/feature request. Please read the bugtracker foralready known bugs before filing a new one. Patches can be send via pull request.
Q:Under which license Pypacker is issued?
A:It's the GPLv2 License (see LICENSE file for more information).
Q:Are there any plans to support [protocol xyz]?
A:Support for particular protocols is added to Pypacker as a result of people contributingthat support - no formal plans for adding support for particular protocols in particularfuture releases exist.
Q:There is problem xyz with Pypacker using Windows 3.11/XP/7/8/mobile etc. Can you fix that?
A:The basic features should work with any OS. Optional ones may make trouble (eg interceptor)and there will be no support for that. Why? Because quality matters and I won't give support forinferior systems. Think twice before chosing an operating system and deal with the consequences;don't blame others for your decision. Alternatively: give me monetary compensation and I'll seewhat I can do (;
- For maxmimum performance start accessing attributes at lowest level e.g. for filtering:
# This will lazy parse only needed layers behind the scenesif ether.src == "...": ...elif ip.src == "...": ...elif tcp.sport == "...": ...- Avoid to convert packets using the "%s" or "%r" format as it triggers parsing behind the scene:
pkt = Ethernet() + IP() + TCP()# This parses ALL layerspacket_print = "%s" % pkt- Avoid searching for a layer using single-value index-notation via pkt[L] as it parses all layers until L is found or highest layer is reached:
packet_found = pkt[Telnet]# Alternative: Use multi-value index-notation. This will stop parsing at any non-matching layer:packet_found = pkt[Ethernet,IP,TCP,Telnet]- For even more performance disable auto fields (affects calling bin(...)):
pkt = ip.IP(src_s="1.2.3.4", dst_s="1.2.3.5") + tcp.TCP()# Disable checksum calculation (and any other update) for IP and TCP (only THIS packet instance)pkt.sum_au_active = Falsepkt.tcp.sum_au_active = Falsebts = pkt.bin(update_auto_fields=False)- Enlarge receive/send buffers to get max performance. This can be done using the following commands(taken from:http://www.cyberciti.biz/faq/linux-tcp-tuning/):
sysctl -w net.core.rmem_max=12582912sysctl -w net.core.rmem_default=12582912sysctl -w net.core.wmem_max=12582912sysctl -w net.core.wmem_default=12582912sysctl -w net.core.optmem_max=2048000sysctl -w net.core.netdev_max_backlog=5000sysctl -w net.unix.max_dgram_qlen=1000sysctl -w net.ipv4.tcp_rmem="10240 87380 12582912"sysctl -w net.ipv4.tcp_wmem="10240 87380 12582912"sysctl -w net.ipv4.tcp_mem="21228 87380 12582912"sysctl -w net.ipv4.udp_mem="21228 87380 12582912"sysctl -w net.ipv4.tcp_window_scaling=1sysctl -w net.ipv4.tcp_timestamps=1sysctl -w net.ipv4.tcp_sack=1- Assemblation of TCP/UDP streams can be done by tshark using pipeswith "-i -" and "-z follow,prot,mode,filter[,range]"
About
📦 The fastest and simplest packet manipulation lib for Python