From b6973f487e6e6d87b2b611a2893884a3d606cb98 Mon Sep 17 00:00:00 2001 From: HectorTa1989 <31132150+HectorTa1989@users.noreply.github.com> Date: Mon, 25 Oct 2021 15:07:16 +0800 Subject: [PATCH] Update README.md --- README.md | 125 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 124 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f67ba45..a2823fe 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,125 @@ # HecPy3-Packet-Sniffer -A network packet sniffing tool written in Python 3 +A network packet sniffing tool is written in Python 3. Packets are disassembled +as they arrive at a given network interface controller and their information +is displayed on the screen. + +This application maintains no dependencies on third-party modules and can be +run by any Python 3.x interpreter. + +## Installation + +### GNU / Linux + +Simply clone this repository with `git clone` and execute the `packet_sniffer.py` +file as described in the following [Usage](#usage) section. + +``` +user@host:~/DIR$ git clone https://github.com/HectorTa1989/HecPy3-Packet-Sniffer.git +``` + +### Other Systems + +This project is dependent on `PF_PACKET` - a stateful packet filter not +found on Windows or Mac OS X. For demonstration purposes, you can try out this +package in a Docker container. Although it will not have full access to +localhost on your machine, you can still sniff on the Docker subnet and at +least get the module running. + +Use this command to build and run from the project directory: + +``` +docker build -t sniff . && docker run --network host sniff +``` + +Note that the entry command is simply `python packet_sniffer.py`, so feel +free to use the full functionality of the module by overriding the default +command. Remember that we tagged the container with the name "sniff" +before, so we can pass command-line arguments to the sniffer in the +following manner: + +``` +docker run --network host sniff [your command goes here] +echo "Now let's print help" +docker run --network host sniff python packet_sniffer.py --help +``` + +Usage of `--network host` is not supported on OS X or Windows +so this container won't be fully functional - but you will see packets +traveling within the docker subnet. + +## Usage + +``` +packet_sniffer.py [-h] [-i INTERFACE] [-d] + +A pure-Python network packet sniffer. + +optional arguments: + -h, --help show this help message and exit + -i INTERFACE, --interface INTERFACE + Interface from which packets will be captured (captures + from all available interfaces by default). + -d, --displaydata Output packet data during capture. +``` + +## Running the Application + + + + + + + + + + + + + + + + +
ObjectiveInitiate the capture of packets on all available interfaces
Executionsudo python3 packet_sniffer.py
OutcomeRefer to sample output below
+ +- Sample output: + +``` +[>] Packet #476 at 17:45:13: + [+] MAC ......ae:45:39:30:8f:5a -> dc:d9:ae:71:c8:b9 + [+] IPv4 ..........192.168.1.65 -> 140.82.113.3 | PROTO: TCP TTL: 64 + [+] TCP ..................40820 -> 443 | Flags: 0x010 > ACK +[>] Packet #477 at 17:45:14: + [+] MAC ......dc:d9:ae:71:c8:b9 -> ae:45:39:30:8f:5a + [+] IPv4 ..........140.82.113.3 -> 192.168.1.65 | PROTO: TCP TTL: 49 + [+] TCP ....................443 -> 40820 | Flags: 0x010 > ACK +[>] Packet #478 at 17:45:18: + [+] MAC ......dc:d9:ae:71:c8:b9 -> ae:45:39:30:8f:5a + [+] ARP Who has 192.168.1.65 ? -> Tell 192.168.1.254 +[>] Packet #479 at 17:45:18: + [+] MAC ......ae:45:39:30:8f:5a -> dc:d9:ae:71:c8:b9 + [+] ARP ...........192.168.1.65 -> Is at ae:45:39:30:8f:5a +``` + +## Legal Disclaimer + +The use of code contained in this repository, either in part or in its totality, +for engaging targets without prior mutual consent is illegal. **It is +the end user's responsibility to obey all applicable local, state and +federal laws.** + +Developers assume **no liability** and are not +responsible for misuses or damages caused by any code contained +in this repository in any event that, accidentally or otherwise, it comes to +be utilized by a threat agent or unauthorized entity as a means to compromise +the security, privacy, confidentiality, integrity, and/or availability of +systems and their associated resources by leveraging the exploitation of known +or unknown vulnerabilities present in said systems, including, but not limited +to, the implementation of security controls, human- or electronically-enabled. + +The use of this code is **only** endorsed by the developers in those +circumstances directly related to **educational environments** or +**authorized penetration testing engagements** whose declared purpose is that +of finding and mitigating vulnerabilities in systems, limiting their exposure +to compromises and exploits employed by malicious agents as defined in their +respective threat models. +