Added Comments (#340)

* Added Comments

* updated changes

* removed comma

tanner/emulators/php_object_injection.py

@@ -12,6 +12,11 @@ def __init__(self, loop=None):
         self.helper = PHPSandboxHelper(self._loop)
 
     async def get_injection_result(self, code):
+        """
+        Injects the code from attacker to vulnerable code and get emulation results from php sandbox.
+        :param code (str): Input payload from attacker
+        :return: object_injection_result (dict): file_md5 (md5 hash), stdout (injection result) as keys.
+        """
 
         vul_code = "<?php " \
                    "class ObjectInjection { " \
@@ -31,12 +36,25 @@ async def get_injection_result(self, code):
         return object_injection_result
 
     def scan(self, value):
+        """
+        Scans the input payload to detect attack using regex
+        :param value (str): code from attacker
+        :return: detection (dict): name (attack name), order (attack order) as keys
+        """
+
         detection = None
         if patterns.PHP_OBJECT_INJECTION.match(value):
             detection = dict(name='php_object_injection', order=3)
         return detection
 
     async def handle(self, attack_params):
+        """
+        Handler of emulator
+        :param attack_params (list): contains dicts as elements with id and value (payload from attacker) as keys
+        :return: (dict): value (result of emulator), page (if set to true the payload will be injected to index.html
+        itself) as keys.
+        """
+
         result = await self.get_injection_result(attack_params[0]['value'])
         if not result or 'stdout' not in result:
             return dict(status_code=504)

tanner/emulators/xxe_injection.py

@@ -13,6 +13,11 @@ def __init__(self, loop=None):
         self.helper = PHPSandboxHelper(self._loop)
 
     async def get_injection_result(self, code):
+        """
+        Injects the code from attacker to vulnerable code and get emulation results from php sandbox.
+        :param code (str): Input payload from attacker
+        :return: object_injection_result (dict): file_md5 (md5 hash), stdout (injection result) as keys.
+        """
 
         vul_code = '''<?php
                         libxml_disable_entity_loader (false);
@@ -29,12 +34,25 @@ async def get_injection_result(self, code):
         return xxe_injection_result
 
     def scan(self, value):
+        """
+        Scans the input payload to detect attack using regex
+        :param value (str): code from attacker
+        :return: detection (dict): name (attack name), order (attack order) as keys
+        """
+
         detection = None
         if patterns.XXE_INJECTION.match(value):
             detection = dict(name='xxe_injection', order=3)
         return detection
 
     async def handle(self, attack_params):
+        """
+        Handler of emulator
+        :param attack_params (list): contains dicts as elements with id and value (payload from attacker) as keys
+        :return: (dict): value (result of emulator), page (if set to true the payload will be injected to index.html
+        itself) as keys.
+        """
+
         result = await self.get_injection_result(attack_params[0]['value'])
         if not result or 'stdout' not in result:
             return dict(status_code=504)

tanner/utils/mysql_db_helper.py

@@ -15,15 +15,23 @@ def __init__(self):
         self.logger = logging.getLogger('tanner.db_helper.MySQLDBHelper')
 
     async def connect_to_db(self):
+        """
+        Creates a aiomysql connection
+        :return: connection object
+        """
+
         conn = await aiomysql.connect(host=TannerConfig.get('SQLI', 'host'),
                                       user=TannerConfig.get('SQLI', 'user'),
                                       password=TannerConfig.get('SQLI', 'password')
                                       )
         return conn
 
-    async def check_db_exists(self, db_name, ):
-
-        # Checks if DB exists or not, Returns 0 if no such database exists else 1
+    async def check_db_exists(self, db_name):
+        """
+        Checks if DB exists or not
+        :param db_name (str): mysql db name
+        :return: result (int): 0 if no such database exists else 1
+        """
 
         conn = await self.connect_to_db()
         cursor = await conn.cursor()
@@ -34,8 +42,10 @@ async def check_db_exists(self, db_name, ):
         return len(result)
 
     async def setup_db_from_config(self, name=None):
-
-        # Helper function to setup DB from db_config.json and inserts dummy data in the created DB.
+        """
+        Helper function to setup DB from db_config.json and inserts dummy data in the created DB.
+        :param name (str): database name
+        """
 
         config = self.read_config()
         if name is not None:
@@ -58,6 +68,11 @@ async def setup_db_from_config(self, name=None):
         conn.close()
 
     async def delete_db(self, db):
+        """
+        Deletes the database
+        :param db (str): db name to be deleted
+        """
+
         conn = await self.connect_to_db()
         cursor = await conn.cursor()
         delete_db_query = 'DROP DATABASE {db_name}'
@@ -66,6 +81,13 @@ async def delete_db(self, db):
         conn.close()
 
     async def copy_db(self, user_db, attacker_db):
+        """
+        Copies the user database to new attacker database
+        :param user_db (str): existing user db
+        :param attacker_db (str): new db to be created
+        :return: new created db (str)
+        """
+
         db_exists = await self.check_db_exists(attacker_db)
         if db_exists:
             self.logger.info('Attacker db already exists')
@@ -99,8 +121,12 @@ async def copy_db(self, user_db, attacker_db):
         return attacker_db
 
     async def insert_dummy_data(self, table_name, data_tokens, cursor):
-
-        # Inserts dummy data in the table based on input data tokens for ex: 'I,L'
+        """
+        Inserts dummy data in the table based on input data tokens for ex: 'I,L'
+        :param table_name (str): table in which data to be inserted
+        :param data_tokens (str): input data format tokens
+        :param cursor (object): current db cursor
+        """
 
         inserted_data, token_list = self.generate_dummy_data(data_tokens)
 
@@ -114,8 +140,11 @@ async def insert_dummy_data(self, table_name, data_tokens, cursor):
                                  inserted_string_patt + ")", inserted_data)
 
     async def create_query_map(self, db_name):
-
-        # Returns a query map (type `dict`) of the tables and its columns present in the database
+        """
+        Returns a query map of the tables and its columns present in the database
+        :param db_name (str): current database
+        :return: query_map (dict): Created Query Map
+        """
 
         query_map = {}
         tables = []