Create payload.py

This project, named "arp_sniffer_payload", is a Python script designed to capture and log ARP (Address Resolution Protocol) packets on a local network. The primary purpose of the script is to identify devices on the local network by monitoring their MAC and IP addresses. This type of tool can be useful for network administrators, cybersecurity professionals, or technology enthusiasts who want to gain a clearer view of the devices connected to their network.

Features and Operation:
ARP Packet Capture: Utilizes a raw socket to capture ARP packets, which are used to map network IP addresses to physical MAC addresses on a local network. Capturing these packets allows for the identification of active devices on the network.

Data Filtering and Processing: The script processes the captured ARP packets, extracting crucial information such as the source MAC address and corresponding IP address.

Duplicate Prevention: To avoid repetition of information, the script uses a set to store and check whether a MAC/IP address pair has already been logged. This ensures that only new devices are logged and reported.

Data Logging: The captured information is logged both to the standard output (console) and to a log file, enabling later analysis of the captured data.

Practical Applications:
Network Security: Helps in detecting unauthorized or unknown devices on the network, a crucial aspect of network security management.

Network Diagnostics: Allows network administrators to monitor and diagnose issues related to devices on the network.

Network Auditing: Provides a means to periodically audit the devices present on the network.

Configurations and Customization:
The log file name (LOG_FILE_NAME) and the network interface (INTERFACE) are configurable, allowing users to adapt the script to their specific needs.
Important Considerations:
Permissions: Running the script requires elevated privileges, as it creates a raw socket to capture ARP packets.

Compatibility: Designed to be compatible with Python versions 2.7 and 3.x.

Responsible Use: As a tool that interacts with the network and captures traffic data, it is important to use the arp_sniffer_payload responsibly and ethically, respecting privacy and local laws.

This project is an excellent tool for anyone in need of a simple and effective solution for monitoring and logging ARP network activity, offering valuable insights into the devices present on a local network.

legacy-mk1/payloads/library/recon/arp_sniffer_payload/payload.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+Author: Julio Della Flora
+Title: arp_sniffer_payload
+Description: 
+    This payload captures ARP packets to identify devices on the local network.
+    It logs each unique source MAC and IP address pair to a file.
+
+Target: 
+    Local network interfaces capable of capturing ARP packets.
+
+Dependencies:
+    - Python 2.7 or 3.x
+    - Access to network interface in promiscuous mode.
+
+Configurable Options:
+    LOG_FILE_NAME = 'arp_sniffer.log'  # Name of the log file
+    INTERFACE = 'eth0'                # Interface to sniff on
+"""
+
+import socket
+import struct
+import logging
+
+# Configurable variables
+LOG_FILE_NAME = 'arp_sniffer.log'
+INTERFACE = 'eth0'
+
+def mac_addr(mac_string):
+    """Convert a MAC address string into a readable format."""
+    return ':'.join('%02x' % (ord(b)) for b in mac_string)
+
+def ipv4_addr(addr):
+    """Convert an IPv4 address string into a readable format."""
+    return '.'.join(map(str, struct.unpack('!BBBB', addr)))
+
+def sniff():
+    # Setup logging
+    logging.basicConfig(filename=LOG_FILE_NAME, level=logging.INFO, format='%(asctime)s %(message)s')
+
+    # Create a raw socket to capture ARP packets
+    s = socket.socket(socket.AF_PACKET, socket.SOCK_RAW, socket.ntohs(0x0003))
+
+    # Set to store seen MAC and IP address pairs
+    seen_addresses = set()
+
+    while True:
+        # Receive packet
+        raw_data, addr = s.recvfrom(65535)
+        # Unpack ethernet frame
+        dest_mac, src_mac, eth_proto = struct.unpack('! 6s 6s H', raw_data[:14])
+
+        # Check for ARP packet
+        if eth_proto == 0x0806:
+            # Unpack ARP packet
+            arp_header = raw_data[14:42]
+            arp_data = struct.unpack('! H H 1s 1s 2s 6s 4s 6s 4s', arp_header)
+            
+            # Check if ARP packet is request or reply
+            if arp_data[4] == b'\x00\x01' or arp_data[4] == b'\x00\x02':
+                src_mac_str = mac_addr(src_mac)
+                src_ip_str = ipv4_addr(arp_data[6])
+
+                # Check for new address pair
+                if (src_mac_str, src_ip_str) not in seen_addresses:
+                    seen_addresses.add((src_mac_str, src_ip_str))
+                    log_message = "Source MAC: {}, Source IP: {}".format(src_mac_str, src_ip_str)
+                    print(log_message)
+                    logging.info(log_message)
+
+# Start sniffing
+sniff()