Informações gerais

Este é o Pypacker: a biblioteca de manipulação de pacotes de baixo nível mais rápida e simples para Python. Veja abaixo exemplos do que você pode fazer com ela.

Se você quiser apoiar este projeto, você pode via PayPal.

O que você pode fazer com o Pypacker

• Crie pacotes personalizados via palavras-chave ou a partir de bytes brutos e leia/altere seus dados via Python: examples/create_packets.py
• Leia/escreva pacotes de/para arquivo pcap (Suporte apenas para o formato pcap do Wireshark/tcpdump): examples/pcap_read_write.py
• Mescle vários arquivos pcap em um único arquivo. Tenta ler arquivos pcap corrompidos e permite filtragem por callback: examples/pcap_merge.py
• Envie/receba pacotes de camada 2: examples/send_receive_l2.py
• Intercepte (e modifique) pacotes, ex. para MITM: examples/interceptor3.py

Pré-requisitos

• Python 3.x (CPython, Pypy, Jython ou qualquer interpretador)
• Opcional: netifaces >=0.10.6 (para utils)
• Opcional (para interceptor):
  • CPython
  • Sistema baseado em Linux com suporte do kernel para o alvo NFQUEUE. A opção de configuração do kernel está em:
    • Networking Options -> Network packet filtering -> Core Netfilter -> NFQUEUE target
  • iptables (alternativamente nftables)
    • Regras relacionadas a NFQUEUE podem ser adicionadas, ex. "iptables -I INPUT 1 -j NFQUEUE --queue-num 0"
  • biblioteca libnetfilter_queue (veja http://www.netfilter.org/projects/libnetfilter_queue)

Instalação

Alguns exemplos:

• Clone a versão mais recente
  • git clone https://gitlab.com/mike01/pypacker.git
  • cd pypacker
  • python setup.py install

pip/pypi não é mais suportado por causa do seu complicado mecanismo de autenticação, desculpe.

Exemplos de uso e documentação

Veja:

• Exemplos acima
• Exemplos no diretório ./examples
• Gitlab Wiki: https://gitlab.com/mike01/pypacker/-/wikis/home

Os próprios protocolos (veja layerXYZ) geralmente não têm muita documentação porque são documentados por suas respectivas RFCs/padrões oficiais.

Testes

Os testes são executados da seguinte forma:

1. Adicione o diretório Pypacker ao PYTHONPATH.

• cd pypacker
• export PYTHONPATH=$(pwd):$PYTHONPATH

2. Execute os testes

• python tests/test_pypacker.py

Resultados dos testes de desempenho:

Hardware: Intel CPU, 4 Cores @ 3.2 GHz
Python: CPython v3.10

nr = new results on this machine
Rounds per test: 10000
=====================================
>>> Packet parsing (Ethernet + IP + UDP + DNS): Search UDP port
Time diff: 0.1409761905670166s
nr = 70933 p/s
>>> Packet parsing (Ethernet + IP + TCP + HTTP): Search TCP port
Time diff: 0.3157649040222168s
nr = 31669 p/s
>>> Packet parsing (Ethernet + IP + TCP + HTTP): Reading all header
Time diff: 0.5989120006561279s
nr = 16696 p/s
>>> Parsing first layer (IP + ICMP)
Time diff: 0.014587163925170898s
nr = 685534 p/s
>>> Creating/direct assigning (IP only header)
Time diff: 0.02884364128112793s
nr = 346696 p/s
>>> bin() without change (IP)
Time diff: 0.013646364212036133s
nr = 732795 p/s
>>> Output with change/checksum recalculation (IP)
Time diff: 0.07719659805297852s
nr = 129539 p/s
>>> Basic/first layer parsing (Ethernet + IP + TCP + HTTP)
Time diff: 0.019113540649414062s
nr = 523189 p/s
>>> Changing Triggerlist element value (Ethernet + IP + TCP + HTTP)
Time diff: 0.017654895782470703s
nr = 566415 p/s
>>> Changing dynamic field (Ethernet + IP + TCP + HTTP)
Time diff: 0.006037473678588867s
nr = 1656321 p/s
>>> Direct assigning and concatination (Ethernet + IP + TCP + HTTP)
Time diff: 0.2050457000732422s
nr = 48769 p/s
.>>> Performance test pypacker vs. dpkt vs. scapy
Comparing pypacker, dpkt and scapy performance (parsing Ethernet + IP + TCP + HTTP)
nr = new results on this machine
Rounds per test: 10000
>> Testing pypacker parsing speed
nr = 194382 p/s
>> Testing dpkt parsing speed
Could not execute dpkt tests: ModuleNotFoundError("No module named 'dpkt'")
>> Testing scapy parsing speed
nr = 2775 p/s

FAQ

Para qualquer dúvida restante, por favor registre um bug (será marcado como "questions").

Q: Quão rápido é o pypacker?

A: Veja os resultados acima. Para resultados detalhados na sua máquina, execute os testes: python tests/test_pypacker.py PerfTestCase

Q: Quais protocolos são suportados?

A: Atualmente, os protocolos mínimos suportados são: 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: Existem planos para suportar [xyz]?

A: Novos recursos são adicionados ao Pypacker como resultado de eu precisar deles ou de pessoas contribuindo com eles - não existem planos formais para adicionar suporte a recursos específicos em futuras versões. Uma diretriz geral para contribuição pode ser encontrada no arquivo HACKING.

Q: Como posso contribuir para este projeto?

A: Por favor, use o rastreador de bugs do Gitlab para bugs/solicitações de recursos. Por favor, leia o rastreador de bugs para bugs já conhecidos antes de abrir um novo. Patches podem ser enviados via pull request.

Q: Há um problema xyz com o Pypacker usando Windows 3.11/XP/7/8/mobile etc. Você pode consertar isso?

A: Os recursos básicos devem funcionar com qualquer SO. Os opcionais podem causar problemas (ex. interceptor).

Q: Sob qual licença o Pypacker é distribuído?

A: É a Licença GPLv2 (veja o arquivo LICENSE para mais informações).

Q: Chamar copy.deepcopy(some_packet) levanta uma exceção "TypeError: can't pickle Struct objects".

A: Tente a seguinte alternativa para conseguir fazer pickle de objetos Struct:

import struct, copyreg
def pickle_struct(s):
	return struct.Struct, (s.format,)

copyreg.pickle(struct.Struct, pickle_struct)

Dicas de uso

Relacionado a desempenho

• Para obter o máximo desempenho, comece a acessar atributos no nível mais baixo usando a seguinte notação de índice. Isso fará o parse preguiçoso apenas das camadas necessárias nos bastidores:

pkt_eth, pkt_ip, pkt_tcp, pkt_http = pkt[
 	None,
	(None, lambda b: b.__class__ in [ip.IP, ip6.IP6]),
	(tcp.TCP, lambda c: c.dport==80),
	http.HTTP
]
...

• Evite converter pacotes usando o formato "%s" ou "%r", pois isso aciona o parsing nos bastidores:

pkt = Ethernet() + IP() + TCP()
# This parses ALL layers
packet_print = "%s" % pkt

• Evite procurar uma camada usando a notação de índice de valor único via pkt[L], pois isso analisa todas as camadas até que L seja encontrado ou a camada mais alta seja alcançada:

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]

• Use pypy (~3x mais rápido que CPython em relação ao parsing completo de pacotes)