Feature: Cross-Platform Support (Scapy), IPv6 Dissection, and Stateful Ping Flood IDS

.gitignore

@@ -1 +1,2 @@
-.idea/
+/venv/
+__pycache__

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 julio finatto e buckyroberts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,3 +1,58 @@
-## To Do
+# Multiplatform Python Packet Sniffer & Ping Flood Detector
 
-- Interpret HTTP data (tcp.dest_port will be 80)
+Este projeto é um sniffer de rede multiplataforma escrito em Python. Ele atua interceptando o tráfego de rede da interface hospedeira e realizando o unpacking contínuo de protocolos (Ethernet, IPv4, TCP, UDP, ICMP, HTTP). 
+
+Como diferencial de segurança, possui um Módulo Ativo de Detecção de Ping Flood, que interpreta os cabeçalhos IPv4 e ICMP para alertar sobre anomalias e negação de serviço na rede local.
+
+##  Tecnologias e Bibliotecas
+- Python 3.x
+- [Scapy](https://scapy.net/) (Motor de captura multiplataforma e filtros BPF)
+- Estrutura base inspirada no repositório didático de buckyroberts.
+
+## Instalação
+1. Clone este repositório:
+   `git clone https://github.com/Jfinatto/Python-Packet-Sniffer-com-detector-de-ping-flood.git`
+2. Instale as dependências necessárias:
+   `pip install scapy`
+   *(Nota para usuários Windows: Certifique-se de possuir o driver Npcap instalado, comumente incluído com o Wireshark).*
+
+##  Como Executar
+O sniffer precisa de acesso direto à interface de rede, logo, deve ser executado com privilégios de administrador.
+
+**No Windows (Abra o CMD como Administrador):**
+```bash
+python main.py
+
+**no linux/MacOS:**
+sudo python3 main.py
+
+
+🇺🇸 English Version
+This project is a Multiplatform Network Packet Sniffer written in Python. It intercepts network traffic from the host interface and performs continuous, real-time unpacking of multiple protocols across the link, network, and transport layers (Ethernet, IPv4, IPv6, TCP, UDP, ICMP, ICMPv6, and HTTP).
+
+As a security highlight, the system includes an Active Ping Flood Detection Module, which dynamically interprets network headers to issue real-time alerts regarding anomalies and potential Denial of Service (DoS) attacks on the local network.
+
+🌟 Key Features
+Multiplatform Capture: Powered by the Scapy library, ensuring native compatibility across Windows, Linux, and macOS.
+
+IPv4 and IPv6 Support: Full decoding of IPv4 packets and support for dynamic traversal of IPv6 Extension Headers in accordance with IANA specifications.
+
+Ping Flood Detection (Time Window): An algorithm based on time-bounded queues that detects rapid bursts of echo requests (Pings) originating from the same IP address within a configurable time window.
+
+Intelligent Memory Management: An internal Garbage Collection mechanism that automatically expires and clears inactive IP history to prevent RAM overflow during long-term captures.
+
+Structured Log Export (JSONL): Security alerts are automatically appended to a JSON Lines file (security_alerts.jsonl), allowing seamless ingestion into data pipelines, SIEMs, and analytical dashboards.
+
+PCAP Capture Saving: Intercepted traffic is natively written into a standard PCAP file format for subsequent analysis in tools like Wireshark.
+
+🗂️ Project File Structure
+sniffer.py / main.py: The main entry point script that initializes the sniffer, processes captured packets, manages memory cleanups, and triggers anomaly checks.
+
+ipv6.py: A specialized module for decoding the IPv6 header and implementing the dynamic header traversal algorithm to locate the actual transport protocol past any extension headers.
+
+general.py: Utility functions for visual data formatting, multi-line hex/string representation, and parsing raw bytes into readable MAC addresses.
+
+🛠️ Technologies and Libraries
+Python 3.x
+
+Scapy (Packet capture engine and BPF filter support)

networking/ipv6.py

@@ -0,0 +1,51 @@
+import socket
+
+class IPv6:
+    def __init__(self, raw_data):
+        # O cabeçalho base do IPv6 possui 40 bytes.
+        # The base IPv6 header has 40 bytes.
+        self.version = raw_data[0] >> 4
+        self.next_header = raw_data[6]
+        self.src = socket.inet_ntop(socket.AF_INET6, raw_data[8:24])
+        self.target = socket.inet_ntop(socket.AF_INET6, raw_data[24:40])
+
+        # O payload começa imediatamente após o cabeçalho base (byte 40)
+        # The payload starts immediately after the base header (byte 40
+        offset = 40
+        current_header = self.next_header
+
+        # Códigos oficiais da IANA para Extension Headers comuns no IPv6
+        # Official IANA codes for common IPv6 Extension Headers
+        # 0: Hop-by-Hop, 43: Routing, 44: Fragment, 50: ESP, 51: AH, 60: Dest Options
+        extension_headers = {0, 43, 44, 50, 51, 60}
+
+        # Algoritmo de Travessia Dinâmica de Cabeçalhos de Extensão
+        # Dynamic Extension Header Traversal Algorithm
+        while current_header in extension_headers and offset < len(raw_data):
+            # O primeiro byte da extensão sempre indica qual é o próximo cabeçalho da cadeia
+            # The first byte of the extension always indicates what the next header in the chain is
+            next_hdr = raw_data[offset]
+
+            # O Fragment Header (44) é uma exceção e tem tamanho estrito de 8 bytes
+            # The Fragment Header (44) is an exception and has a strict length of 8 bytes
+            if current_header == 44:
+                ext_len = 8
+            else:
+                # Para as outras extensões, o segundo byte indica o comprimento.
+                # For other extensions, the second byte indicates the length.
+                # A fórmula do protocolo é: (Comprimento + 1) * 8 bytes
+                # The protocol formula is: (Length + 1) * 8 bytes
+                hdr_ext_len = raw_data[offset + 1]
+                ext_len = (hdr_ext_len + 1) * 8
+
+            # Salta o bloco de memória correspondente ao cabeçalho lido
+            # Skips the memory block corresponding to the read header
+            offset += ext_len
+            current_header = next_hdr
+
+        # Após a travessia do while, current_header conterá o protocolo de transporte real (ex: 58 para ICMPv6)
+        # After traversing the while loop, current_header will contain the actual transport protocol (e.g., 58 for ICMPv6)
+        self.next_header = current_header
+        # Isola os dados reais após descartar todo o encadeamento de rede
+        # Isolates the real data after discarding all network chaining
+        self.data = raw_data[offset:]