{"id":21229848,"url":"https://github.com/sleleu/ft_malcolm","last_synced_at":"2025-03-15T02:16:14.804Z","repository":{"id":233008669,"uuid":"785735511","full_name":"Sleleu/ft_malcolm","owner":"Sleleu","description":"A project focused on implementing ARP spoofing/poisoning, a fundamental Man-In-The-Middle attack exploiting vulnerabilities in the ARP protocol's behavior within a network.","archived":false,"fork":false,"pushed_at":"2024-09-10T22:11:38.000Z","size":1317,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-21T18:11:25.723Z","etag":null,"topics":["arp","arp-spoofing","cybersecurity","network"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sleleu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-12T14:08:34.000Z","updated_at":"2024-09-10T22:17:47.000Z","dependencies_parsed_at":"2024-11-20T23:30:04.967Z","dependency_job_id":"e8c8148d-f5c7-4478-a814-4d05918253f5","html_url":"https://github.com/Sleleu/ft_malcolm","commit_stats":null,"previous_names":["sleleu/ft_malcolm"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sleleu%2Fft_malcolm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sleleu%2Fft_malcolm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sleleu%2Fft_malcolm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sleleu%2Fft_malcolm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sleleu","download_url":"https://codeload.github.com/Sleleu/ft_malcolm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243672487,"owners_count":20328768,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arp","arp-spoofing","cybersecurity","network"],"created_at":"2024-11-20T23:29:58.029Z","updated_at":"2025-03-15T02:16:14.786Z","avatar_url":"https://github.com/Sleleu.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"## About the project\n\n*DISCLAIMER: This project is for educational purposes only.*\n\nThe goal of this project is to implement an ARP spoofing tool in C. \nThe program intercepts ARP requests from a target and sends a spoofed ARP reply, associating a fake IP address with a specific MAC address. \nThis helps in understanding how the ARP protocol works at the network layer and how it can be exploited for network attacks.\n\n### Understanding the ARP Protocol and its vulnerabilities\n\nThe Address Resolution Protocol (ARP) is a network protocol used to map IP addresses to MAC addresses in local networks, enabling devices to communicate on the same network segment.\n\nAlthough devices are assigned IP addresses for network-level communication, the actual communication on a local network happens through MAC addresses, which are unique identifiers assigned to network interfaces. Since computers communicate at the **Data Link Layer** (Layer 2 of the OSI model) using MAC addresses, ARP plays a role in linking an IP address (used at **Layer 3, the Network Layer**) to a device's MAC address.\n\nIndeed, when a device wants to communicate with another device on the same network, it needs to know the target's MAC address. If it only has the IP address, ARP is used to resolve this by broadcasting a request on the network. The device with the corresponding IP address responds with its MAC address, and this mapping is stored in an ARP cache for future use, allowing devices to directly communicate using their MAC addresses :\n\n![ARP_protocol](https://github.com/user-attachments/assets/3c09a576-407d-4484-bec9-b76a7e10891c)\n*Source: [GeekFlare](https://geekflare.com/fr/address-resolution-protocol/)*\n\nDespite its importance, ARP is inherently vulnerable due to its lack of authentication mechanisms, making it susceptible to attacks such as ARP spoofing or ARP poisoning. These attacks exploit the trust-based nature of the protocol, allowing an attacker to send falsified ARP replies that associate an incorrect MAC address with an IP address. This can lead to **Man-in-the-Middle (MitM)** attacks, where the attacker intercepts or alters network traffic, or **Denial of Service (DoS)** by corrupting the target’s ARP cache.\n\n### Structure of an ARP Packet\n\nARP Packet is consists of **Ethernet Frame Header** and **ARP Header**. The length of the Ethernet Frame Header is 14 bytes, and 28 bytes for ARP Header.\n\n![arp-packet-format-ipcisco](https://github.com/user-attachments/assets/8cadf049-8efb-438c-8042-21e32c9a87c3)\\\n*Source: [IPCisco: Address Resolution Protocol (ARP)](https://ipcisco.com/lesson/address-resolution-protocol-arp/)*\n\n\nHere is the structure I created to send and receive ARP packets for this project:\n\n```C\n/* ARP PACKET */\ntypedef struct __attribute__((packed)) s_arp_packet {\n    /* ETHERNET HEADER */\n\tu_int8_t    h_target[ETH_ALEN];\n\tu_int8_t    h_src[ETH_ALEN];\n\tu_int16_t   h_proto;\n\n    /* ARP HEADER */\n    u_int16_t   hardware_type;\n    u_int16_t   proto_type;\n    u_int8_t hardware_addr_len;\n    u_int8_t proto_addr_len;\n    u_int16_t operation;\n    u_int8_t mac_src[ETH_ALEN];\n    u_int32_t ip_src;\n    u_int8_t mac_target[ETH_ALEN];\n    u_int32_t ip_target;\n} t_arp_packet;\n```\nThe `__attribute__((packed))` is used to ensure there’s no padding in the structure, allowing the ARP packet to be constructed and sent exactly as required by the protocol's specification.\n\n\n## Installation and usage\n\nGit clone and install the repository:\n\n```bash\ngit clone https://github.com/sleleu/ft_malcolm\ncd ft_malcolm\ngit submodule update --init --recursive\nmake -j\n```\n\nTo start the VMs with the Vagrantfile, run the following command:\n\n```bash\nvagrant up\n```\n(Ensure that Vagrant is installed for using the VMs. The provider used in this project is `libvirt`.)\n\nOnce the VMs are up, you can connect to each VM via SSH using the following commands:\n\n- To connect to the sender VM:\n\n```bash\nvagrant ssh sender\n```\n\nTo connect to the target VM:\n\n```bash\nvagrant ssh target\n```\n\nRun the program to perform ARP spoofing by specifying the source and target IP and MAC addresses as follows:\n\n```bash\nsudo ./ft_malcolm \u003cIP-src\u003e \u003cMAC-src\u003e \u003cIP-target\u003e \u003cMAC-target\u003e [OPTION -v -f]\n```\nThe `ft_malcolm` binary can be found directly in the Vagrant VMs within the `/vagrant` folder. This is a directory shared by default between the different virtual machines launched in a Vagrant box.\n\nTo perform ARP spoofing, set :\n- `\u003cIP-src\u003e` to the IP address you want to spoof,\n- `\u003cMAC-src\u003e` to your own MAC address,\n- `\u003cIP-target\u003e` and `\u003cMAC-target\u003e` to the target machine’s IP and MAC address.\n\nHere is the main logic : \n\n```C\nwhile (42) {\n  if (receive_arp_request()) {\n    printf(\"Now sending an ARP reply to the target address with spoofed source, please wait...\\n\");\n    send_arp_packet(\u0026packet, socket_address);\n    if (g_data.verbose)\n      print_packet(packet);\n    printf(\"Sent an ARP reply packet, you may now check the arp table on the target.\\n\");\n  }\n}\n```\n\nThe program will wait for the next ARP request from the target and then send an ARP reply with the spoofed information. This will result in the target’s ARP table being updated with the spoofed MAC address.\n\n\nBy using the flag `-v` (verbose), you can view the detailed content of the ARP packets that are received and sent to the target:\n\n![ARP_REPLY](https://github.com/user-attachments/assets/2365d22c-3ce5-46eb-9b2c-ec5542b1bfb6)\n\n\n## Usefull resources\n\n- ARP protocol : https://man7.org/linux/man-pages/man7/arp.7.html\n- Structure of an ARP packet : \n  - https://stackoverflow.com/questions/41403445/how-to-structure-and-arp-request-packet-in-c\n  - https://stackoverflow.com/questions/16710040/arp-request-and-reply-using-c-socket-programming\n- RFC 826 for ARP: https://datatracker.ietf.org/doc/html/rfc826\n- ARP header: https://fr.wikipedia.org/wiki/Address_Resolution_Protocol\n- Article on how ARP works : https://www.frameip.com/entete-arp/\n- Install Vagrant : https://developer.hashicorp.com/vagrant/install\n- Nice tuto : https://www.youtube.com/watch?v=16VO0wc8HfM\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsleleu%2Fft_malcolm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsleleu%2Fft_malcolm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsleleu%2Fft_malcolm/lists"}