From bee9170c465edc92a4ad88b29d58d6afc6b4d1fe Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Wed, 14 Sep 2022 00:40:38 +0530
Subject: [PATCH 01/39] Add: Initial support for multithreading

---
 modules/crawler.py | 269 ++++++++++++++++++++++++++++-----------------
 torcrawl.py        |  80 +++++++-------
 2 files changed, 204 insertions(+), 145 deletions(-)

diff --git a/modules/crawler.py b/modules/crawler.py
index 333c98d..339bdc7 100644
--- a/modules/crawler.py
+++ b/modules/crawler.py
@@ -1,40 +1,87 @@
 #!/usr/bin/python
-import http.client
 import json
 import os
 import re
 import sys
 import time
-import urllib.request
+import warnings
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from io import TextIOBase
+from threading import Lock
 from urllib.parse import urljoin
 
+import requests
 from bs4 import BeautifulSoup
+from requests.models import Response
+
+warnings.filterwarnings("ignore", category=UserWarning, module="bs4")
+requests.urllib3.disable_warnings()
 
 
 class Crawler:
     """Crawl input link upto depth (c_depth) with a pause of c_pause seconds.
 
     :param website: String: Website to crawl.
+    :param proxies: Dictionary: Dictionary mapping protocol or protocol and host to the URL of the proxy.
     :param c_depth: Integer: Depth of the crawl.
-    :param c_pause: Integer: Pause after every iteration.
+    :param c_pause: Float: Pause after every iteration.
     :param out_path: String: Output path to store extracted links.
     :param external: Boolean: True if external links are to be crawled else False.
+    :param thread: Integer: Number pages to visit (Threads) at the same time.
     :param logs: Boolean: True if logs are to be written else False.
     :param verbose: Boolean: True if crawl details are to be printed else False.
     :param exclusion: re String: Paths that you don't want to include.
     """
 
+    network_file = "network_structure.json"
+    __header = {
+        "Accept-Encoding": "identity",
+        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
+    }
+    __port = 9050
+    __proxies = {
+        "http": f"socks5h://127.0.0.1:{__port}",
+        "https": f"socks5h://127.0.0.1:{__port}",
+    }
+
     def __init__(
-        self, website, c_depth, c_pause, out_path, external, logs, verbose, exclusion
+        self,
+        website,
+        c_depth,
+        c_pause,
+        out_path,
+        external,
+        thread,
+        logs,
+        verbose,
+        exclusion,
     ):
         self.website = website
         self.c_depth = c_depth
         self.c_pause = c_pause
         self.out_path = out_path
-        self.external = rf"{external}"
+        self.external = external
+        self.thread = thread
         self.logs = logs
+        self.log_path = os.path.join(self.out_path, "log.txt")
         self.verbose = verbose
-        self.exclusion = exclusion
+        self.exclusion = rf"{exclusion}" if exclusion else None
+        self.__executor = ThreadPoolExecutor(max_workers=min(32, self.thread))
+        self.__lock = Lock()
+        self.__files = {
+            "extlinks": open(
+                os.path.join(self.out_path, "extlinks.txt"), "w+", encoding="UTF-8"
+            ),
+            "telephones": open(
+                os.path.join(self.out_path, "telephones.txt"), "w+", encoding="UTF-8"
+            ),
+            "mails": open(
+                os.path.join(self.out_path, "mails.txt"), "w+", encoding="UTF-8"
+            ),
+            "log_file": open(self.log_path, "w+", encoding="UTF-8"),
+            "network_structure": os.path.join(self.out_path, self.network_file),
+            "links": os.path.join(self.out_path, "links.txt"),
+        }
 
     def excludes(self, link):
         """Excludes links that are not required.
@@ -55,21 +102,15 @@ def excludes(self, link):
         if link.startswith("http") and not link.startswith(self.website):
             if self.external is True:
                 return False
-            file_path = self.out_path + "/extlinks.txt"
-            with open(file_path, "a+", encoding="UTF-8") as lst_file:
-                lst_file.write(str(link) + "\n")
+            self.__files["extlinks"].write(str(link) + "\n")
             return True
         # Telephone Number
         if link.startswith("tel:"):
-            file_path = self.out_path + "/telephones.txt"
-            with open(file_path, "a+", encoding="UTF-8") as lst_file:
-                lst_file.write(str(link) + "\n")
+            self.__files["telephones"].write(str(link) + "\n")
             return True
         # Mails
         if link.startswith("mailto:"):
-            file_path = self.out_path + "/mails.txt"
-            with open(file_path, "a+", encoding="UTF-8") as lst_file:
-                lst_file.write(str(link) + "\n")
+            self.__files["mails"].write(str(link) + "\n")
             return True
         # Type of files
         if re.search("^.*\\.(pdf|jpg|jpeg|png|gif|doc)$", link, re.IGNORECASE):
@@ -88,6 +129,85 @@ def canonical(self, base, href):
         # For relative paths
         return urljoin(base, href)
 
+    def __get_tor_session(self):
+        session = requests.Session()
+        session.proxies = self.__proxies
+        session.headers.update(self.__header)
+        session.verify = False
+        return session
+
+    def __crawl_link(self, item, session):
+        # Store the crawled link of an item
+        item_data = set()
+        html_page = Response
+
+        try:
+            if item is not None:
+                # html_page = urllib.request.urlopen(item, timeout=10)
+                html_page = session.get(item, allow_redirects=True, timeout=10).text
+        except Exception as error:
+            if self.logs:
+                print(error)
+            return item, item_data
+
+        # Keeps logs for every webpage visited.
+        if self.logs:
+            with self.__lock:
+                self.__files["log_file"].write(f"{str(item)}\n")
+
+        try:
+            soup = BeautifulSoup(html_page, features="html.parser")
+        except Exception as _:
+            if self.logs:
+                print(f"## Soup Error Encountered:: to parse :: {item}")
+            return item, item_data
+
+        # For each <a href=""> tag.
+        for link in soup.findAll("a"):
+            link = link.get("href")
+
+            if self.excludes(link):
+                continue
+
+            ver_link = self.canonical(item, link)
+            if ver_link is not None:
+                item_data.add(ver_link)
+
+        # For each <area> tag.
+        for link in soup.findAll("area"):
+            link = link.get("href")
+
+            if self.excludes(link):
+                continue
+
+            ver_link = self.canonical(item, link)
+            if ver_link is not None:
+                item_data.add(ver_link)
+
+        # For each <script> tag
+        for link in soup.findAll("script"):
+            link = link.get("src")
+
+            if self.excludes(link):
+                continue
+
+            ver_link = self.canonical(item, link)
+            if ver_link is not None:
+                item_data.add(ver_link)
+
+        # For each <link> tag
+        for link in soup.findAll("link"):
+            link = link.get("href")
+
+            if self.excludes(link):
+                continue
+
+            ver_link = self.canonical(item, link)
+            if ver_link is not None:
+                item_data.add(ver_link)
+
+        return item, item_data
+
     def crawl(self):
         """Core of the crawler.
         :return: Dict (json_data) - Dictionary of crawled links.
@@ -95,106 +215,43 @@ def crawl(self):
         ord_lst = set([self.website])
         old_level = [self.website]
         cur_level = set()
-        log_path = self.out_path + "/log.txt"
-        if self.logs is True and os.access(log_path, os.W_OK) is ~os.path.exists(
-            log_path
+
+        if self.logs is True and os.access(self.log_path, os.W_OK) is ~os.path.exists(
+            self.log_path
         ):
-            print(f"## Unable to write to {self.out_path}/log.txt - Exiting")
+            print(f"## Unable to write to {self.log_path} - Exiting")
             sys.exit(2)
 
         print(
-            f"## Crawler started from {self.website} with "
-            f"{str(self.c_depth)} depth crawl, {'' if self.exclusion else 'and '}{str(self.c_pause)} "
-            f"second(s) delay. Excluding {self.exclusion if self.exclusion else 'no'} links."
+            f"## Crawler started from {self.website} with {self.c_depth} depth, "
+            f"{self.c_pause} second{'s'[:int(self.c_pause)^1]} delay and using {self.thread} "
+            f"Thread{'s'[:self.thread^1]}. Excluding '{self.exclusion}' links."
         )
 
         # Json dictionary
         json_data = {}
         # Depth
         for index in range(0, int(self.c_depth)):
-            # For every element of list.
-            for item in old_level:
-                # Don't crawl if already crawled
-                if (item in json_data) or (
-                    item != item.rstrip("/") and item.rstrip("/") in json_data
-                ):
-                    continue
-
-                # Store the crawled link of an item
-                item_data = set()
-                html_page = http.client.HTTPResponse
-                try:
-                    if item is not None:
-                        html_page = urllib.request.urlopen(item, timeout=10)
-                except Exception as error:
-                    print(error)
-                    continue
-                # Keeps logs for every webpage visited.
-                if self.logs:
-                    with open(log_path, "a+", encoding="UTF-8") as log_file:
-                        log_file.write(f"{str(item)}\n")
-
-                try:
-                    soup = BeautifulSoup(html_page, features="html.parser")
-                except Exception as _:
-                    print(f"## Soup Error Encountered:: to parse :: {item}")
-                    continue
-
-                # For each <a href=""> tag.
-                for link in soup.findAll("a"):
-                    link = link.get("href")
-
-                    if self.excludes(link):
-                        continue
-
-                    ver_link = self.canonical(item, link)
-                    if ver_link is not None:
-                        item_data.add(ver_link)
-
-                # For each <area> tag.
-                for link in soup.findAll("area"):
-                    link = link.get("href")
-
-                    if self.excludes(link):
-                        continue
-
-                    ver_link = self.canonical(item, link)
-                    if ver_link is not None:
-                        item_data.add(ver_link)
-
-                # For each <script> tag
-                for link in soup.findAll("script"):
-                    link = link.get("src")
-
-                    if self.excludes(link):
-                        continue
-
-                    ver_link = self.canonical(item, link)
-                    if ver_link is not None:
-                        item_data.add(ver_link)
-
-                # For each <link> tag
-                for link in soup.findAll("link"):
-                    link = link.get("href")
-
-                    if self.excludes(link):
-                        continue
-
-                    ver_link = self.canonical(item, link)
-                    if ver_link is not None:
-                        item_data.add(ver_link)
+            session = self.__get_tor_session()
 
-                if self.verbose:
-                    sys.stdout.write("-- Results: " + str(len(ord_lst)) + "\r")
-                    sys.stdout.flush()
+            futures = [
+                self.__executor.submit(self.__crawl_link, item=item, session=session)
+                for item in old_level
+                if item not in json_data
+            ]
 
-                # Pause time
-                time.sleep(float(self.c_pause))
+            for future in as_completed(futures):
+                item, item_data = future.result()
 
                 # Add item_data to crawled links.
                 cur_level = cur_level.union(item_data)
+
+                if self.verbose:
+                    sys.stdout.write(f"-- Results: {len(cur_level)}\r")
+                    sys.stdout.flush()
+
                 # Adding to json data
-                json_data[item] = list(item_data)
+                json_data[item.rstrip("/")] = list(item_data)
 
             # Get the next level withouth duplicates.
             clean_cur_level = cur_level.difference(ord_lst)
@@ -207,12 +264,20 @@ def crawl(self):
             print(f"## Step {index + 1} completed \n\t with: {len(ord_lst)} result(s)")
 
             # Creating json
-            json_path = self.out_path + "/network_structure.json"
-            with open(json_path, "w", encoding="UTF-8") as lst_file:
+            with open(
+                self.__files["network_structure"], "w", encoding="UTF-8"
+            ) as lst_file:
                 json.dump(json_data, lst_file, indent=2, sort_keys=False)
 
-            with open(self.out_path + "/links.txt", "w+", encoding="UTF-8") as file:
+            with open(self.__files["links"], "w+", encoding="UTF-8") as file:
                 for item in sorted(ord_lst):
                     file.write(f"{item}\n")
 
+            # Pause time
+            time.sleep(self.c_pause)
+
+        for file in self.__files.values():
+            if isinstance(file, TextIOBase):
+                file.close()
+
         return json_data
diff --git a/torcrawl.py b/torcrawl.py
index 60335d2..6e2b012 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -23,21 +23,22 @@
 -i, --input filename    : Input file with URL(s) (seperated by line)
 -o, --output [filename] : Output page(s) to file(s) (for one page)
 -y, --yara              : Yara keyword search page categorisation
-                        read in from /res folder. 0 search whole html object.
-                        1 search only the text.
+                          read in from /res folder. 0 search whole html object.
+                          1 search only the text.
 
 Crawl:
--c, --crawl       : Crawl website (Default output on /links.txt)
--d, --cdepth      : Set depth of crawl's travel (Default: 1)
--z, --exclusions  : Paths that you don't want to include
--m, --simultaneous: How many pages to visit at the same time (TODO)
--p, --pause       : The length of time the crawler will pause
-                    (Default: 0)
--f, --folder	  : The root directory which will contain the
-                    generated files
--l, --log         : Log file with visited URLs and their response code.
--x, --external    : Exclude external links while crawling a webpage
-                    (Default: include all links)
+-c, --crawl               : Crawl website (Default output on /links.txt)
+-d, --cdepth              : Set depth of crawl's travel (Default: 1)
+-z, --exclusions "regexp" : Paths that you don't want to include
+-t, --thread number       : How many pages to visit (Threads) at the same time
+                            (Default: 16)
+-p, --pause               : The length of time the crawler will pause
+                            (Default: 0)
+-f, --folder	          : The root directory which will contain the
+                            generated files
+-l, --log                 : Log file with visited URLs and their response code.
+-x, --external            : Exclude external links while crawling a webpage
+                            (Default: include all links)
 
 GitHub: github.com/MikeMeliz/TorCrawl.py
 License: GNU General Public License v3.0
@@ -83,29 +84,6 @@
     print("## Install Gooey with 'pip install Gooey' or remove '-g/--gui' argument")
     sys.exit(2)
 
-# Set socket and connection with TOR network
-def connect_tor():
-    """Connect to TOR via DNS resolution through a socket.
-    :return: None or HTTPError.
-    """
-    try:
-        port = 9050
-        # Set socks proxy and wrap the urllib module
-        socks.setdefaultproxy(socks.PROXY_TYPE_SOCKS5, "127.0.0.1", port)
-        socket.socket = socks.socksocket
-
-        # Perform DNS resolution through the socket
-        def getaddrinfo(*args):  # noqa
-            return [(socket.AF_INET, socket.SOCK_STREAM, 6, "", (args[0], args[1]))]
-
-        socket.getaddrinfo = getaddrinfo  # noqa
-    except socks.HTTPError as err:
-        error = sys.exc_info()[0]
-        print(
-            f"Error: {error} \n## Cannot establish connection with TOR\n"
-            f"HTTPError: {err}"
-        )
-
 
 def GooeyConditional(flag, **kwargs):
     """Conditional decorator if GUI backend is available or not"""
@@ -206,8 +184,8 @@ def main():
     parser.add_argument(
         "-p",
         "--cpause",
-        type=int,
-        default=1,
+        type=float,
+        default=0,
         help="The length of time the crawler will pause. (Default: 1 second)",
     )
     parser.add_argument(
@@ -216,6 +194,13 @@ def main():
         type=str,
         help="Regex path that is ignored while crawling",
     )
+    parser.add_argument(
+        "-t",
+        "--thread",
+        type=int,
+        default=16,
+        help="How many pages to visit (Threads) at the same time (Default: 1)",
+    )
     parser.add_argument(
         "-l",
         "--log",
@@ -257,10 +242,18 @@ def main():
     if args.yara not in [0, 1]:
         parser.error("argument -y/--yara: expected argument 0 or 1.")
 
+    if args.cdepth < 1:
+        parser.error("argument -d/--cdepth: expected argument greater than 1.")
+
+    if args.cpause < 0:
+        parser.error("argument -p/--cpause: expected argument greater than 0.")
+
+    if args.thread < 1:
+        parser.error("argument -t/--thread: expected argument greater than 1.")
+
     # Connect to TOR
     if args.without is False:
         check_tor(args.verbose)
-        connect_tor()
 
     if args.verbose:
         check_ip()
@@ -284,16 +277,17 @@ def main():
             args.cpause,
             out_path,
             args.external,
+            args.thread,
             args.log,
             args.verbose,
             args.exclusion,
         )
         json_data = crawler.crawl()
-        print(f"## File created on {os.getcwd()}/{out_path}/network_structure.json")
+        print(f"## File created on {os.path.join(out_path, crawler.network_file)}")
 
         if args.visualize:
             obj = Visualization(
-                out_path + "/network_structure.json", out_path, args.verbose
+                os.path.join(out_path, crawler.network_file), out_path, args.verbose
             )
             obj.indegree_plot()
             obj.indegree_bar()
@@ -301,10 +295,10 @@ def main():
             obj.outdegree_bar()
             obj.eigenvector_centrality_bar()
             obj.pagerank_bar()
-            obj.visualize()
+            # obj.visualize()
 
         if args.extract:
-            input_file = out_path + "/links.txt"
+            input_file = os.path.join(out_path, "links.txt")
             extractor(website, args.crawl, args.output, input_file, out_path, args.yara)
     else:
         extractor(

From 91a6262387af1d909ef3a37748577f298718f87d Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Wed, 14 Sep 2022 00:41:02 +0530
Subject: [PATCH 02/39] Fix: Gitignore file

---
 .gitignore | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.gitignore b/.gitignore
index 0012321..b3f181d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -166,3 +166,5 @@ www*/
 assets/Dark*
 assets/*.odt
 assets/*2.pdf
+
+.vscode

From dc102cf01e27a571ca98e11c32e94adbf62bba41 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Wed, 14 Sep 2022 00:41:25 +0530
Subject: [PATCH 03/39] Add: Contributors and working stats SVG

---
 README.md | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 1d196fa..9826151 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@
 DarkSpider is a python script to crawl and extract (regular or onion) webpages through TOR network.
 
 - **Warning:** Crawling is not illegal, but violating copyright is. It’s always best to double check a website’s T&C before crawling them. Some websites set up what’s called robots.txt to tell crawlers not to visit those pages. This crawler will allow you to go around this, but we always recommend respecting robots.txt.
-- **Keep in mind:** Extracting and crawling through TOR network take some time. That's normal behaviour; you can find more information [here](https://www.torproject.org/docs/faq.html.en#WhySlow).
+- **Keep in mind:** Extracting and crawling through TOR network take some time. That's normal behavior; you can find more information [here](https://www.torproject.org/docs/faq.html.en#WhySlow).
 
 ### What makes it simple?
 
@@ -40,7 +40,7 @@ To install this script, you need to clone that repository:
 
 `git clone https://github.com/PROxZIMA/DarkSpider.git`
 
-You'll also need to install dependecies:
+You'll also need to install dependencies:
 
 `pip install -r requirements.txt`
 
@@ -55,20 +55,21 @@ arg | Long | Description
 **General**: | |
 -h  |--help| Help
 -g  |--gui| Open with GUI backend.
--v  |--verbose| Show more informations about the progress
+-v  |--verbose| Show more information about the progress
 -u  |--url *.onion| URL of Webpage to crawl or extract
 -w  |--without| Without the use of Relay TOR
 -f  |--folder| The directory which will contain the generated files ([@guyo13](https://www.github.com/guyo13))
 -s  |--visualize| Visualize the graphs and insights from the crawled data
 **Extract**: | |
 -e  |--extract| Extract page's code to terminal or file. (Default: Terminal)
--i  |--input filename| Input file with URL(s) (seperated by line)
+-i  |--input filename| Input file with URL(s) (separated by line)
 -o  |--output [filename]| Output page(s) to file(s) (for one page)
 -y  |--yara | Perform yara keyword search (0 = search entire html object. 1 = search only text).
 **Crawl**: | |
 -c  |--crawl| Crawl website (Default output on /links.txt)
 -d  |--cdepth| Set depth of crawl's travel (Default: 1)
 -z  |--exclusion "regexp"| Regex path that is ignored while crawling (Default: None)
+-t  |--thread number| How many pages to visit (Threads) at the same time (Default: 16)
 -p  |--pause| The length of time the crawler will pause (Default: 0)
 -l  |--log| Log file with visited URLs and their response code
 -x  |--external| Exclude external links while crawling a webpage (Default: include all links)
@@ -117,7 +118,7 @@ $ python torcrawl.py -i links.txt
 
 ### As Crawler:
 Crawl the links of the webpage without the use of TOR,
-also show verbose output (really helpfull):
+also show verbose output (really helpful):
 
 ```shell
 $ python torcrawl.py -v -w -u http://www.github.com/ -c
@@ -201,18 +202,20 @@ Use ```-y 0``` for raw html searching and ```-y 1``` for text search only.*
 ## TODO:
 - [x] Store links relation in one-to-may json dictionary format
 - [x] Plot the graphical network of the generated json using [`NetworkX`](https://networkx.org/) package.
-- [ ] Crawl images and scripts
+- [x] Crawl images and scripts
 - [x] -z, --exclusions  : Paths that you don't want to include
-- [ ] -m, --simultaneous: How many pages to visit at the same time
+- [ ] -t, --thread: How many pages to visit at the same time
 
 ## Credits
-- [**@MikeMeliz**](https://github.com/MikeMeliz) for intial [`TorCrawl`](https://github.com/MikeMeliz/TorCrawl.py) codebase
+- [**@MikeMeliz**](https://github.com/MikeMeliz) for initial [`TorCrawl`](https://github.com/MikeMeliz/TorCrawl.py) codebase
 - A. Alharbi et al., "[Exploring the Topological Properties of the Tor Dark Web](https://ieeexplore.ieee.org/document/9340182)", IEEE Access, vol. 9, pp. 21746-21758, 2021.
 
 ## Contributors:
 Feel free to contribute on this project! Just fork it, make any change on your fork and add a pull request on current branch! Any advice, help or questions would be appreciated :shipit:
 
-[![Contributors](https://contrib.rocks/image?repo=PROxZIMA/DarkSpider)](https://github.com/PROxZIMA/DarkSpider/graphs/contributors)
+[![Contributors](https://contrib.rocks/image?repo=PROxZIMA/DarkSpider "Contributors")](https://github.com/PROxZIMA/DarkSpider/graphs/contributors)
+
+[![Stats](https://repobeats.axiom.co/api/embed/6bcd62cf68bef8f509296f236f21b39f6af128a6.svg "Repobeats analytics image")](https://github.com/PROxZIMA/DarkSpider/pulse)
 
 ## License:
 “GPL” stands for “General Public License”. Using the GNU GPL will require that all the released improved versions be free software. [source & more](https://www.gnu.org/licenses/gpl-faq.html)

From 3fb73453315441d982d70b24a6868a522a50a6be Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Wed, 14 Sep 2022 00:41:56 +0530
Subject: [PATCH 04/39] Fix: Crawler object initialization

---
 modules/tests/test_crawler.py       | 1 +
 modules/tests/test_visualization.py | 3 ++-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/modules/tests/test_crawler.py b/modules/tests/test_crawler.py
index 8efab82..5411dd4 100644
--- a/modules/tests/test_crawler.py
+++ b/modules/tests/test_crawler.py
@@ -21,6 +21,7 @@ def setUpClass(cls):
             c_pause=1,
             out_path=out_path,
             external=False,
+            thread=1,
             logs=False,
             verbose=False,
             exclusion=None,
diff --git a/modules/tests/test_visualization.py b/modules/tests/test_visualization.py
index 70cc303..512e0ae 100644
--- a/modules/tests/test_visualization.py
+++ b/modules/tests/test_visualization.py
@@ -42,6 +42,7 @@ def setUpClass(cls):
             c_pause=1,
             out_path=out_path,
             external=True,
+            thread=1,
             logs=False,
             verbose=False,
             exclusion=None,
@@ -51,7 +52,7 @@ def setUpClass(cls):
             cls.crawler.crawl()
 
         cls.obj = Visualization(
-            json_file=out_path + "/network_structure.json",
+            json_file=os.path.join(out_path, cls.crawler.network_file),
             out_path=out_path,
             verbose=True,
         )

From 264e300b11d46a6ec708ae4c7a8105f56f995346 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Wed, 14 Sep 2022 01:04:38 +0530
Subject: [PATCH 05/39] Fix: Readme TODO checklist

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 9826151..2861065 100644
--- a/README.md
+++ b/README.md
@@ -204,7 +204,7 @@ Use ```-y 0``` for raw html searching and ```-y 1``` for text search only.*
 - [x] Plot the graphical network of the generated json using [`NetworkX`](https://networkx.org/) package.
 - [x] Crawl images and scripts
 - [x] -z, --exclusions  : Paths that you don't want to include
-- [ ] -t, --thread: How many pages to visit at the same time
+- [x] -t, --thread: How many pages to visit at the same time
 
 ## Credits
 - [**@MikeMeliz**](https://github.com/MikeMeliz) for initial [`TorCrawl`](https://github.com/MikeMeliz/TorCrawl.py) codebase

From 89c4a21d4eeb3288d25140078eb527f442c81509 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Wed, 14 Sep 2022 20:28:46 +0530
Subject: [PATCH 06/39] Update: Fucntion calls and request proxy

---
 modules/checker.py        |  44 ++++++++-------
 modules/crawler.py        | 116 ++++++++++++++++++++------------------
 modules/extractor.py      |  24 +++++---
 modules/helpers/helper.py |  26 +++++++++
 torcrawl.py               |  44 ++++++++++-----
 5 files changed, 156 insertions(+), 98 deletions(-)

diff --git a/modules/checker.py b/modules/checker.py
index 89dba3f..a0faac9 100644
--- a/modules/checker.py
+++ b/modules/checker.py
@@ -4,14 +4,15 @@
 import re
 import subprocess
 import sys
-from json import load
-from urllib.error import HTTPError
 from urllib.parse import urlparse
-from urllib.request import urlopen
+
+import requests
+
+from modules.helpers.helper import get_requests_header, traceback_name
 
 
 def url_canon(website, verbose):
-    """ URL normalisation/canonicalization
+    """URL normalisation/canonicalization
 
     :param website: String - URL of website.
     :param verbose: Boolean - Verbose logging switch.
@@ -29,7 +30,7 @@ def url_canon(website, verbose):
 
 
 def extract_domain(url, remove_http=True):
-    """ Parses the provided 'url' to provide only the netloc or
+    """Parses the provided 'url' to provide only the netloc or
     scheme + netloc parts of the provided url.
 
     :param url: String - Url to parse.
@@ -46,7 +47,7 @@ def extract_domain(url, remove_http=True):
 
 # Create output path
 def folder(website, verbose):
-    """ Creates an output path for the findings.
+    """Creates an output path for the findings.
 
     :param website: String - URL of website to crawl.
     :param verbose: Boolean - Logging level.
@@ -68,30 +69,33 @@ def check_tor(verbose):
     :param verbose: Boolean -'verbose' logging argument.
     :return: None
     """
-    check_for_tor = subprocess.check_output(['ps', '-e'])
+    check_for_tor = subprocess.check_output(["ps", "-e"])
 
     def find_whole_word(word):
-        return re.compile(r'\b({0})\b'.format(word),
-                          flags=re.IGNORECASE).search
+        return re.compile(r"\b({0})\b".format(word), flags=re.IGNORECASE).search
 
-    if find_whole_word('tor')(str(check_for_tor)):
+    if find_whole_word("tor")(str(check_for_tor)):
         if verbose:
             print("## TOR is ready!")
     else:
         print("## TOR is NOT running!")
-        print('## Enable tor with \'service tor start\' or add -w argument')
+        print("## Enable tor with 'service tor start' or add -w argument")
         sys.exit(2)
 
 
-def check_ip():
-    """ Checks users IP from external resource.
+def check_ip(proxies):
+    """Checks users IP from external resource.
     :return: None or HTTPError
     """
-    addr = 'https://api.ipify.org/?format=json'
+    addr = "https://api.ipify.org/?format=json"
+    headers = get_requests_header()
     try:
-        my_ip = load(urlopen(addr))['ip']
-        print(f'## Your IP: {my_ip}')
-    except HTTPError as err:
-        error = sys.exc_info()[0]
-        print(f"Error: {error} \n## IP cannot be obtained. \n## Is {addr} up? "
-              f"\n## HTTPError: {err}")
+        my_ip = requests.get(
+            addr, headers=headers, proxies=proxies, timeout=10, verify=False
+        ).json()["ip"]
+        print(f"## Your IP: {my_ip}")
+    except Exception as err:
+        print(
+            f"Error: {traceback_name(err)} \n## IP cannot be obtained. \n## Is {addr} up? "
+            f"\n## Exception: {err}"
+        )
diff --git a/modules/crawler.py b/modules/crawler.py
index 339bdc7..c9d450d 100644
--- a/modules/crawler.py
+++ b/modules/crawler.py
@@ -1,5 +1,6 @@
 #!/usr/bin/python
 import json
+import logging
 import os
 import re
 import sys
@@ -8,64 +9,65 @@
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from io import TextIOBase
 from threading import Lock
+from typing import Union
 from urllib.parse import urljoin
 
 import requests
 from bs4 import BeautifulSoup
 from requests.models import Response
 
+from modules.helpers.helper import get_requests_header, traceback_name
+
 warnings.filterwarnings("ignore", category=UserWarning, module="bs4")
 requests.urllib3.disable_warnings()
 
 
 class Crawler:
-    """Crawl input link upto depth (c_depth) with a pause of c_pause seconds.
-
-    :param website: String: Website to crawl.
-    :param proxies: Dictionary: Dictionary mapping protocol or protocol and host to the URL of the proxy.
-    :param c_depth: Integer: Depth of the crawl.
-    :param c_pause: Float: Pause after every iteration.
-    :param out_path: String: Output path to store extracted links.
-    :param external: Boolean: True if external links are to be crawled else False.
-    :param thread: Integer: Number pages to visit (Threads) at the same time.
-    :param logs: Boolean: True if logs are to be written else False.
-    :param verbose: Boolean: True if crawl details are to be printed else False.
-    :param exclusion: re String: Paths that you don't want to include.
+    """Crawl input link upto depth (c_depth) with a pause of c_pause seconds using multiple threads.
+
+    :param str website: Website to crawl.
+    :param dict[str, str] proxies: Dictionary mapping protocol or protocol and host to the URL of the proxy.
+    :param dict[str, any] c_params: Dictionary mapping
+                                    {
+                                        int c_depth: Depth of the crawl,
+                                        float c_pause: Pause after every iteration
+                                    }
+    :param str out_path: Output path to store extracted links.
+    :param bool external: True if external links are to be crawled else False.
+    :param re str exclusion: Paths that you don't want to include.
+    :param int thread: Number pages to visit (Threads) at the same time.
+    :param dict[str, bool] logging: Dictionary mapping
+                                    {
+                                        bool logs: True if logs are to be written else False,
+                                        bool verbose: True if crawl details are to be printed else False
+                                    }
     """
 
     network_file = "network_structure.json"
-    __header = {
-        "Accept-Encoding": "identity",
-        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
-    }
-    __port = 9050
-    __proxies = {
-        "http": f"socks5h://127.0.0.1:{__port}",
-        "https": f"socks5h://127.0.0.1:{__port}",
-    }
+    __headers = get_requests_header()
 
     def __init__(
         self,
-        website,
-        c_depth,
-        c_pause,
-        out_path,
-        external,
-        thread,
-        logs,
-        verbose,
-        exclusion,
+        website: str,
+        proxies: dict[str, str],
+        c_params: dict[str, Union[int, float]],
+        out_path: str,
+        external: bool,
+        exclusion: str,
+        thread: int,
+        logging_: dict[str, bool],
     ):
         self.website = website
-        self.c_depth = c_depth
-        self.c_pause = c_pause
+        self.proxies = proxies
+        self.c_depth = c_params["c_depth"]
+        self.c_pause = c_params["c_pause"]
         self.out_path = out_path
         self.external = external
+        self.exclusion = rf"{exclusion}" if exclusion else None
         self.thread = thread
-        self.logs = logs
+        self.logs = logging_["log"]
         self.log_path = os.path.join(self.out_path, "log.txt")
-        self.verbose = verbose
-        self.exclusion = rf"{exclusion}" if exclusion else None
+        self.verbose = logging_["verbose"]
         self.__executor = ThreadPoolExecutor(max_workers=min(32, self.thread))
         self.__lock = Lock()
         self.__files = {
@@ -83,6 +85,13 @@ def __init__(
             "links": os.path.join(self.out_path, "links.txt"),
         }
 
+    def __get_tor_session(self):
+        session = requests.Session()
+        session.proxies = self.proxies
+        session.headers.update(self.__headers)
+        session.verify = False
+        return session
+
     def excludes(self, link):
         """Excludes links that are not required.
 
@@ -129,37 +138,34 @@ def canonical(self, base, href):
         # For relative paths
         return urljoin(base, href)
 
-    def __get_tor_session(self):
-        session = requests.Session()
-        session.proxies = self.__proxies
-        session.headers.update(self.__header)
-        session.verify = False
-        return session
-
-    def __crawl_link(self, item, session):
+    def __crawl_link(self, item, session) -> tuple[str, list[str]]:
         # Store the crawled link of an item
         item_data = set()
         html_page = Response
 
         try:
             if item is not None:
-                # html_page = urllib.request.urlopen(item, timeout=10)
-                html_page = session.get(item, allow_redirects=True, timeout=10).text
+                html_page = session.get(item, allow_redirects=True, timeout=10)
         except Exception as error:
+            print(
+                f"## Request Error :: {item} :: {traceback_name(error)}{' :: ' + error if self.logs else ''}"
+            )
+            # Keeps logs for every webpage visited.
             if self.logs:
-                print(error)
+                with self.__lock:
+                    self.__files["log_file"].write(f"{str(item)}\n")
             return item, item_data
 
-        # Keeps logs for every webpage visited.
-        if self.logs:
-            with self.__lock:
-                self.__files["log_file"].write(f"{str(item)}\n")
-
         try:
-            soup = BeautifulSoup(html_page, features="html.parser")
-        except Exception as _:
+            soup = BeautifulSoup(html_page.text, features="html.parser")
+        except Exception as error:
+            print(
+                f"## Soup Parse Error :: {item} :: {traceback_name(error)}{' :: ' + error if self.logs else ''}"
+            )
+            # Keeps logs for every webpage visited.
             if self.logs:
-                print(f"## Soup Error Encountered:: to parse :: {item}")
+                with self.__lock:
+                    self.__files["log_file"].write(f"{str(item)}\n")
             return item, item_data
 
         # For each <a href=""> tag.
@@ -237,7 +243,7 @@ def crawl(self):
             futures = [
                 self.__executor.submit(self.__crawl_link, item=item, session=session)
                 for item in old_level
-                if item not in json_data
+                if item.rstrip("/") not in json_data
             ]
 
             for future in as_completed(futures):
diff --git a/modules/extractor.py b/modules/extractor.py
index 9995b62..e1ca7ce 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -185,16 +185,24 @@ def termex(website, yara):
         return
 
 
-def extractor(website, crawl, output_file, input_file, out_path, yara):
+def extractor(
+    website: str,
+    proxies: dict[str, str],
+    crawl: bool,
+    output_file: str,
+    input_file: str,
+    out_path: str,
+    yara: int,
+):
     """Extractor - scrapes the resulting website or discovered links.
 
-    :param website: String: URL of website to scrape.
-    :param crawl: Boolean: Cinex trigger.
-        If used iteratively scrape the urls from input_file.
-    :param output_file: String: Filename of resulting output from scrape.
-    :param input_file: String: Filename of crawled/discovered URLs
-    :param out_path: String: Dir path for output files.
-    :param yara: Integer: keyword search option.
+    :param str website: URL of website to scrape.
+    :param dict[str, str] proxies: Dictionary mapping protocol or protocol and host to the URL of the proxy.
+    :param bool crawl: Cinex trigger. If used iteratively scrape the urls from input_file.
+    :param str output_file: Filename of resulting output from scrape.
+    :param str input_file: Filename of crawled/discovered URLs
+    :param str out_path: Dir path for output files.
+    :param int yara: keyword search option.
     :return: None
     """
     # TODO: Return output to torcrawl.py
diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index 25c18c5..a0928c5 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -45,3 +45,29 @@ def wrapper(*args, **kwargs):
     wrapper.__doc__ = func.__doc__
     wrapper.__name__ = func.__name__
     return wrapper
+
+
+def get_requests_header():
+    """Get requests header"""
+    return {
+        "Accept-Encoding": "identity",
+        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
+    }
+
+
+def get_tor_proxies(without, port=9050):
+    """Get Tor proxies"""
+    if without:
+        return None
+    return {
+        "http": f"socks5h://127.0.0.1:{port}",
+        "https": f"socks5h://127.0.0.1:{port}",
+    }
+
+
+def traceback_name(error):
+    """Get traceback name"""
+    module = error.__class__.__module__
+    if module is None or module == str.__class__.__module__:
+        return error.__class__.__name__
+    return module + "." + error.__class__.__name__
diff --git a/torcrawl.py b/torcrawl.py
index 6e2b012..2a9bdb3 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -47,10 +47,9 @@
 
 import argparse
 import os
-import socket
 import sys
 
-import socks  # noqa - pysocks
+from modules.helpers.helper import get_tor_proxies
 
 try:
     from gooey import Gooey, GooeyParser
@@ -199,7 +198,7 @@ def main():
         "--thread",
         type=int,
         default=16,
-        help="How many pages to visit (Threads) at the same time (Default: 1)",
+        help="How many pages to visit (Threads) at the same time (Default: 16)",
     )
     parser.add_argument(
         "-l",
@@ -255,8 +254,10 @@ def main():
     if args.without is False:
         check_tor(args.verbose)
 
+    proxies = get_tor_proxies(without=args.without)
+
     if args.verbose:
-        check_ip()
+        check_ip(proxies=proxies)
         print(("## URL: " + args.url))
 
     website = ""
@@ -272,15 +273,14 @@ def main():
 
     if args.crawl:
         crawler = Crawler(
-            website,
-            args.cdepth,
-            args.cpause,
-            out_path,
-            args.external,
-            args.thread,
-            args.log,
-            args.verbose,
-            args.exclusion,
+            website=website,
+            proxies=proxies,
+            c_params={"c_depth": args.cdepth, "c_pause": args.cpause},
+            out_path=out_path,
+            external=args.external,
+            exclusion=args.exclusion,
+            thread=args.thread,
+            logging_={"log": args.log, "verbose": args.verbose},
         )
         json_data = crawler.crawl()
         print(f"## File created on {os.path.join(out_path, crawler.network_file)}")
@@ -299,10 +299,24 @@ def main():
 
         if args.extract:
             input_file = os.path.join(out_path, "links.txt")
-            extractor(website, args.crawl, args.output, input_file, out_path, args.yara)
+            extractor(
+                website,
+                proxies,
+                args.crawl,
+                args.output,
+                input_file,
+                out_path,
+                args.yara,
+            )
     else:
         extractor(
-            website, args.crawl, args.output, args.input or "", out_path, args.yara
+            website,
+            proxies,
+            args.crawl,
+            args.output,
+            args.input or "",
+            out_path,
+            args.yara,
         )
 
 

From fe446633354c324adcb8792513e7e0d4d4ebe301 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Wed, 14 Sep 2022 22:13:47 +0530
Subject: [PATCH 07/39] Refactor: Extractor converted to a class

---
 modules/extractor.py | 416 +++++++++++++++++++++++--------------------
 torcrawl.py          |  36 ++--
 2 files changed, 241 insertions(+), 211 deletions(-)

diff --git a/modules/extractor.py b/modules/extractor.py
index e1ca7ce..02db38b 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -1,221 +1,249 @@
 #!/usr/bin/python
-import io
 import os
 import urllib.error
 import urllib.parse
 import urllib.request
 from http.client import IncompleteRead, InvalidURL
+from io import TextIOWrapper
 from urllib.error import HTTPError, URLError
 
+import requests
 import yara as _yara
 from bs4 import BeautifulSoup
 
+from modules.helpers.helper import get_requests_header, traceback_name
 
-def text(response=None):
-    """Removes all the garbage from the HTML and takes only text elements
-    from the page.
 
-    :param response: HTTP Response.
-    :return: String: Text only stripped response.
-    """
-    soup = BeautifulSoup(response, features="lxml")
-    for s in soup(["script", "style"]):
-        s.decompose()
-
-    return " ".join(soup.stripped_strings)
-
-
-def check_yara(raw=None, yara=0):
-    """Validates Yara Rule to categorize the site and check for keywords.
-
-    :param raw: HTTP Response body.
-    :param yara:  Integer: Keyword search argument.
-    :return matches: List of yara rule matches.
-    """
-
-    file_path = os.path.join("res/keywords.yar")
-
-    if raw is not None:
-        if yara == 1:
-            raw = text(response=raw).lower()
-
-        file = os.path.join(file_path)
-        rules = _yara.compile(file)
-        matches = rules.match(data=raw)
-        if len(matches) != 0:
-            print("found a match!")
-        return matches
-    return None
-
-
-def cinex(input_file, out_path, yara=None):
-    """Ingests the crawled links from the input_file,
-    scrapes the contents of the resulting web pages and writes the contents to
-    the into out_path/{url_address}.
+class Extractor:
+    """Extractor - scrapes the resulting website or discovered links.
 
-    :param input_file: String: Filename of the crawled Urls.
-    :param out_path: String: Pathname of results.
-    :param yara: Integer: Keyword search argument.
-    :return: None
+    :param str website: URL of website to scrape.
+    :param dict[str, str] proxies: Dictionary mapping protocol or protocol and host to the URL of the proxy.
+    :param bool crawl: Cinex trigger. If used iteratively scrape the urls from input_file.
+    :param str output_file: Filename of resulting output from scrape.
+    :param str input_file: Filename of crawled/discovered URLs
+    :param str out_path: Dir path for output files.
+    :param int yara: keyword search option.
     """
-    file = io.TextIOWrapper
-    try:
-        file = open(input_file, "r", encoding="UTF-8")
-    except IOError as err:
-        print(f"Error: {err}\n## Can't open: {input_file}")
-
-    for line in file.read().splitlines():
 
-        # Generate the name for every file.
+    __headers = get_requests_header()
+
+    def __init__(
+        self,
+        website: str,
+        proxies: dict[str, str],
+        crawl: bool,
+        output_file: str,
+        input_file: str,
+        out_path: str,
+        yara: int,
+    ):
+        self.website = website
+        self.proxies = proxies
+        self.crawl = crawl
+        self.output_file = output_file
+        self.input_file = input_file
+
+        self.out_path = os.path.join(out_path, "extracted")
+        if not os.path.exists(self.out_path):
+            os.mkdir(self.out_path)
+
+        self.yara = yara
+        self.__session = self.__get_tor_session()
+
+    def __get_tor_session(self):
+        session = requests.Session()
+        # session.proxies = self.proxies
+        # session.headers.update(self.__headers)
+        # session.verify = False
+        return session
+
+    def __text(self, response=None):
+        """Removes all the garbage from the HTML and takes only text elements
+        from the page.
+
+        :param response: HTTP Response.
+        :return: String: Text only stripped response.
+        """
+        soup = BeautifulSoup(response, features="lxml")
+        for s in soup(["script", "style"]):
+            s.decompose()
+
+        return " ".join(soup.stripped_strings)
+
+    def __check_yara(self, raw=None, yara=0):
+        """Validates Yara Rule to categorize the site and check for keywords.
+
+        :param raw: HTTP Response body.
+        :param yara:  Integer: Keyword search argument.
+        :return matches: List of yara rule matches.
+        """
+
+        file_path = os.path.join("res/keywords.yar")
+
+        if raw is not None:
+            if yara == 1:
+                raw = self.__text(response=raw).lower()
+
+            file = os.path.join(file_path)
+            rules = _yara.compile(file)
+            matches = rules.match(data=raw)
+            if len(matches) != 0:
+                print("found a match!")
+            return matches
+        return None
+
+    def __cinex(self, input_file, out_path, yara=None):
+        """Ingests the crawled links from the input_file,
+        scrapes the contents of the resulting web pages and writes the contents to
+        the into out_path/{url_address}.
+
+        :param input_file: String: Filename of the crawled Urls.
+        :param out_path: String: Pathname of results.
+        :param yara: Integer: Keyword search argument.
+        :return: None
+        """
+        file = TextIOWrapper
         try:
-            page_name = line.rsplit("/", 1)
-            cl_page_name = str(page_name[1])
-            cl_page_name = cl_page_name[:-1]
-            if len(cl_page_name) == 0:
-                output_file = "index.htm"
-            else:
-                output_file = cl_page_name
-        except IndexError as error:
-            print(f"Error: {error}")
-            continue
+            file = open(input_file, "r", encoding="UTF-8")
+        except IOError as err:
+            print(f"Error: {err}\n## Can't open: {input_file}")
+
+        for line in file.read().splitlines():
+
+            # Generate the name for every file.
+            try:
+                page_name = line.rsplit("/", 1)
+                cl_page_name = str(page_name[1])
+                if len(cl_page_name) == 0:
+                    output_file = "index.html"
+                else:
+                    output_file = cl_page_name
+            except IndexError as error:
+                print(f"Error: {error}")
+                continue
+
+            # Extract page to file.
+            try:
+                content = self.__session.get(
+                    line, allow_redirects=True, timeout=10
+                ).text
 
-        # Extract page to file.
+                if yara is not None:
+                    full_match_keywords = self.__check_yara(content, yara)
+
+                    if len(full_match_keywords) == 0:
+                        print("No matches found.")
+                        continue
+
+                with open(
+                    os.path.join(out_path, output_file), "w+", encoding="UTF-8"
+                ) as results:
+                    results.write(content)
+                print(f"# File created on: {os.path.join(out_path, output_file)}")
+            except HTTPError as err:
+                print(f"Cinex Error: {err.code}, cannot access: {err.url}")
+                continue
+            except InvalidURL as _:
+                print(f"Invalid URL: {line} \n Skipping...")
+                continue
+            except IncompleteRead as _:
+                print(f"IncompleteRead on {line}")
+                continue
+            except IOError as err:
+                print(f"Error: {err}\nCan't write on file: {output_file}")
+        file.close()
+
+    def __intermex(self, input_file, yara):
+        """Input links from file and extract them into terminal.
+
+        :param input_file: String: File name of links file.
+        :param yara: Integer: Keyword search argument.
+        :return: None
+        """
         try:
-            content = urllib.request.urlopen(line, timeout=10).read()
+            with open(input_file, "r", encoding="UTF-8") as file:
+                for line in file.read().splitlines():
+                    content = self.__session.get(
+                        line, allow_redirects=True, timeout=10
+                    ).text
+                    if yara is not None:
+                        full_match_keywords = self.__check_yara(raw=content, yara=yara)
+
+                        if full_match_keywords is None or len(full_match_keywords) == 0:
+                            print(f"No matches in: {line}")
+                    print(content)
+        except (HTTPError, URLError, InvalidURL) as err:
+            print(f"Request Error: {err}")
+        except IOError as err:
+            print(f"Error: {err}\n## Not valid file")
+        except Exception as err:
+            print(f"Error: {err}")
+
+    def __outex(self, website, output_file, out_path, yara):
+        """Scrapes the contents of the provided web address and outputs the
+        contents to file.
+
+        :param website: String: Url of web address to scrape.
+        :param output_file: String: Filename of the results.
+        :param out_path: String: Folder name of the output findings.
+        :param yara: Integer: Keyword search argument.
+        :return: None
+        """
+        # Extract page to file
+        try:
+            output_file = os.path.join(out_path, output_file)
+            content = self.__session.get(website, allow_redirects=True, timeout=10).text
 
             if yara is not None:
-                full_match_keywords = check_yara(content, yara)
+                full_match_keywords = self.__check_yara(raw=content, yara=yara)
 
                 if len(full_match_keywords) == 0:
-                    print("No matches found.")
-                    continue
-
-            with open(out_path + "/" + output_file, "wb") as results:
-                results.write(content)
-            print(f"# File created on: {os.getcwd()}/{out_path}/{output_file}")
-        except HTTPError as err:
-            print(f"Cinex Error: {err.code}, cannot access: {err.url}")
-            continue
-        except InvalidURL as _:
-            print(f"Invalid URL: {line} \n Skipping...")
-            continue
-        except IncompleteRead as _:
-            print(f"IncompleteRead on {line}")
-            continue
-        except IOError as err:
-            print(f"Error: {err}\nCan't write on file: {output_file}")
-    file.close()
+                    print(f"No matches in: {website}")
 
+            with open(output_file, "w+", encoding="UTF-8") as file:
+                file.write(content)
+            print(f"## File created on: {output_file}")
+        except (HTTPError, URLError, InvalidURL) as err:
+            print(f"HTTPError: {err}")
+        except IOError as err:
+            print(f"Error: {err}\n Can't write on file: {output_file}")
 
-def intermex(input_file, yara):
-    """Input links from file and extract them into terminal.
-
-    :param input_file: String: File name of links file.
-    :param yara: Integer: Keyword search argument.
-    :return: None
-    """
-    try:
-        with open(input_file, "r", encoding="UTF-8") as file:
-            for line in file.read().splitlines():
-                content = urllib.request.urlopen(line).read()
-                if yara is not None:
-                    full_match_keywords = check_yara(raw=content, yara=yara)
-
-                    if full_match_keywords is None or len(full_match_keywords) == 0:
-                        print(f"No matches in: {line}")
-                print(content)
-    except (HTTPError, URLError, InvalidURL) as err:
-        print(f"Request Error: {err}")
-    except IOError as err:
-        print(f"Error: {err}\n## Not valid file")
-    except Exception as err:
-        print(f"Error: {err}")
-
-
-def outex(website, output_file, out_path, yara):
-    """Scrapes the contents of the provided web address and outputs the
-    contents to file.
-
-    :param website: String: Url of web address to scrape.
-    :param output_file: String: Filename of the results.
-    :param out_path: String: Folder name of the output findings.
-    :param yara: Integer: Keyword search argument.
-    :return: None
-    """
-    # Extract page to file
-    try:
-        output_file = out_path + "/" + output_file
-        content = urllib.request.urlopen(website).read()
-
-        if yara is not None:
-            full_match_keywords = check_yara(raw=content, yara=yara)
-
-            if len(full_match_keywords) == 0:
-                print(f"No matches in: {website}")
-
-        with open(output_file, "wb") as file:
-            file.write(content)
-        print(f"## File created on: {os.getcwd()}/{output_file}")
-    except (HTTPError, URLError, InvalidURL) as err:
-        print(f"HTTPError: {err}")
-    except IOError as err:
-        print(f"Error: {err}\n Can't write on file: {output_file}")
-
-
-def termex(website, yara):
-    """Scrapes provided web address and prints the results to the terminal.
-
-    :param website: String: URL of website to scrape.
-    :param yara: Integer: Keyword search argument.
-    :return: None
-    """
-    try:
-        content = urllib.request.urlopen(website).read()
-        if yara is not None:
-            full_match_keywords = check_yara(content, yara)
-
-            if full_match_keywords is None or len(full_match_keywords) == 0:
-                # No match.
-                print(f"No matches in: {website}")
-                return
-
-        print(content)
-    except (HTTPError, URLError, InvalidURL) as err:
-        print(f"Error: ({err}) {website}")
-        return
-
-
-def extractor(
-    website: str,
-    proxies: dict[str, str],
-    crawl: bool,
-    output_file: str,
-    input_file: str,
-    out_path: str,
-    yara: int,
-):
-    """Extractor - scrapes the resulting website or discovered links.
+    def __termex(self, website, yara):
+        """Scrapes provided web address and prints the results to the terminal.
 
-    :param str website: URL of website to scrape.
-    :param dict[str, str] proxies: Dictionary mapping protocol or protocol and host to the URL of the proxy.
-    :param bool crawl: Cinex trigger. If used iteratively scrape the urls from input_file.
-    :param str output_file: Filename of resulting output from scrape.
-    :param str input_file: Filename of crawled/discovered URLs
-    :param str out_path: Dir path for output files.
-    :param int yara: keyword search option.
-    :return: None
-    """
-    # TODO: Return output to torcrawl.py
-    if len(input_file) > 0:
-        if crawl:
-            cinex(input_file, out_path, yara)
-        # TODO: Extract from list into a folder
-        # elif len(output_file) > 0:
-        # 	inoutex(website, input_ile, output_file)
-        else:
-            intermex(input_file, yara)
-    else:
-        if len(output_file) > 0:
-            outex(website, output_file, out_path, yara)
+        :param website: String: URL of website to scrape.
+        :param yara: Integer: Keyword search argument.
+        :return: None
+        """
+        try:
+            content = self.__session.get(website, allow_redirects=True, timeout=10).text
+            if yara is not None:
+                full_match_keywords = self.__check_yara(content, yara)
+
+                if full_match_keywords is None or len(full_match_keywords) == 0:
+                    # No match.
+                    print(f"No matches in: {website}")
+                    return
+
+            print(content)
+        except (HTTPError, URLError, InvalidURL) as err:
+            print(f"Error: ({err}) {website}")
+            return
+
+    def extract(self):
+        """Extracts the contents of the input file into the outputs folder/file"""
+        # TODO: Return output to torcrawl.py
+        if len(self.input_file) > 0:
+            if self.crawl:
+                self.__cinex(self.input_file, self.out_path, self.yara)
+            # TODO: Extract from list into a folder
+            # elif len(output_file) > 0:
+            # 	inoutex(website, input_ile, output_file)
+            else:
+                self.__intermex(self.input_file, self.yara)
         else:
-            termex(website, yara)
+            if len(self.output_file) > 0:
+                self.__outex(self.website, self.output_file, self.out_path, self.yara)
+            else:
+                self.__termex(self.website, self.yara)
diff --git a/torcrawl.py b/torcrawl.py
index 2a9bdb3..d4c0490 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -62,7 +62,7 @@
 
 # DarkSpider Modules
 from modules.crawler import Crawler
-from modules.extractor import extractor
+from modules.extractor import Extractor
 from modules.visualization import Visualization
 
 IGNORE_COMMAND = "--ignore-gooey"
@@ -299,25 +299,27 @@ def main():
 
         if args.extract:
             input_file = os.path.join(out_path, "links.txt")
-            extractor(
-                website,
-                proxies,
-                args.crawl,
-                args.output,
-                input_file,
-                out_path,
-                args.yara,
+            extractor = Extractor(
+                website=website,
+                proxies=proxies,
+                crawl=args.crawl,
+                output_file=args.output,
+                input_file=input_file,
+                out_path=out_path,
+                yara=args.yara,
             )
+            extractor.extract()
     else:
-        extractor(
-            website,
-            proxies,
-            args.crawl,
-            args.output,
-            args.input or "",
-            out_path,
-            args.yara,
+        extractor = Extractor(
+            website=website,
+            proxies=proxies,
+            crawl=args.crawl,
+            output_file=args.output,
+            input_file=input_file or "",
+            out_path=out_path,
+            yara=args.yara,
         )
+        extractor.extract()
 
 
 # Stub to call main method.

From 1a06069a4e67c8a8cc8de2ba805cbc4d22836158 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Fri, 16 Sep 2022 18:19:06 +0530
Subject: [PATCH 08/39] Fix: Input file argument and yara search

---
 README.md            |  4 +--
 modules/extractor.py | 67 ++++++++++++++++++++------------------------
 torcrawl.py          |  4 +--
 3 files changed, 35 insertions(+), 40 deletions(-)

diff --git a/README.md b/README.md
index 2861065..8b527e0 100644
--- a/README.md
+++ b/README.md
@@ -64,7 +64,7 @@ arg | Long | Description
 -e  |--extract| Extract page's code to terminal or file. (Default: Terminal)
 -i  |--input filename| Input file with URL(s) (separated by line)
 -o  |--output [filename]| Output page(s) to file(s) (for one page)
--y  |--yara | Perform yara keyword search (0 = search entire html object. 1 = search only text).
+-y  |--yara 0\|1 | Perform yara keyword search (0 = search entire html object. 1 = search only text).
 **Crawl**: | |
 -c  |--crawl| Crawl website (Default output on /links.txt)
 -d  |--cdepth| Set depth of crawl's travel (Default: 1)
@@ -86,7 +86,7 @@ $ python torcrawl.py -u http://www.github.com
 </html>
 ```
 
-Extract into a file (github.htm) without the use of TOR:
+Extract into a file (github.html) without the use of TOR:
 
 ```shell
 $ python torcrawl.py -w -u http://www.github.com -o github.htm
diff --git a/modules/extractor.py b/modules/extractor.py
index 02db38b..2e47998 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -27,6 +27,7 @@ class Extractor:
     """
 
     __headers = get_requests_header()
+    __yara_rules = _yara.compile("res/keywords.yar")
 
     def __init__(
         self,
@@ -53,9 +54,9 @@ def __init__(
 
     def __get_tor_session(self):
         session = requests.Session()
-        # session.proxies = self.proxies
-        # session.headers.update(self.__headers)
-        # session.verify = False
+        session.proxies = self.proxies
+        session.headers.update(self.__headers)
+        session.verify = False
         return session
 
     def __text(self, response=None):
@@ -74,26 +75,24 @@ def __text(self, response=None):
     def __check_yara(self, raw=None, yara=0):
         """Validates Yara Rule to categorize the site and check for keywords.
 
-        :param raw: HTTP Response body.
         :param yara:  Integer: Keyword search argument.
+        :param raw:   HTTP Response body.
         :return matches: List of yara rule matches.
         """
+        if raw is None:
+            return None
 
-        file_path = os.path.join("res/keywords.yar")
+        if yara == 1:
+            raw = self.__text(response=raw).lower()
 
-        if raw is not None:
-            if yara == 1:
-                raw = self.__text(response=raw).lower()
+        matches = self.__yara_rules.match(data=raw)
 
-            file = os.path.join(file_path)
-            rules = _yara.compile(file)
-            matches = rules.match(data=raw)
-            if len(matches) != 0:
-                print("found a match!")
-            return matches
-        return None
+        if len(matches) != 0:
+            print("found a match!")
 
-    def __cinex(self, input_file, out_path, yara=None):
+        return matches
+
+    def __cinex(self, input_file, out_path, yara):
         """Ingests the crawled links from the input_file,
         scrapes the contents of the resulting web pages and writes the contents to
         the into out_path/{url_address}.
@@ -129,12 +128,11 @@ def __cinex(self, input_file, out_path, yara=None):
                     line, allow_redirects=True, timeout=10
                 ).text
 
-                if yara is not None:
-                    full_match_keywords = self.__check_yara(content, yara)
+                full_match_keywords = self.__check_yara(content, yara)
 
-                    if len(full_match_keywords) == 0:
-                        print("No matches found.")
-                        continue
+                if len(full_match_keywords) == 0:
+                    print("No matches found.")
+                    continue
 
                 with open(
                     os.path.join(out_path, output_file), "w+", encoding="UTF-8"
@@ -167,11 +165,10 @@ def __intermex(self, input_file, yara):
                     content = self.__session.get(
                         line, allow_redirects=True, timeout=10
                     ).text
-                    if yara is not None:
-                        full_match_keywords = self.__check_yara(raw=content, yara=yara)
+                    full_match_keywords = self.__check_yara(raw=content, yara=yara)
 
-                        if full_match_keywords is None or len(full_match_keywords) == 0:
-                            print(f"No matches in: {line}")
+                    if full_match_keywords is None or len(full_match_keywords) == 0:
+                        print(f"No matches in: {line}")
                     print(content)
         except (HTTPError, URLError, InvalidURL) as err:
             print(f"Request Error: {err}")
@@ -195,11 +192,10 @@ def __outex(self, website, output_file, out_path, yara):
             output_file = os.path.join(out_path, output_file)
             content = self.__session.get(website, allow_redirects=True, timeout=10).text
 
-            if yara is not None:
-                full_match_keywords = self.__check_yara(raw=content, yara=yara)
+            full_match_keywords = self.__check_yara(raw=content, yara=yara)
 
-                if len(full_match_keywords) == 0:
-                    print(f"No matches in: {website}")
+            if len(full_match_keywords) == 0:
+                print(f"No matches in: {website}")
 
             with open(output_file, "w+", encoding="UTF-8") as file:
                 file.write(content)
@@ -218,13 +214,12 @@ def __termex(self, website, yara):
         """
         try:
             content = self.__session.get(website, allow_redirects=True, timeout=10).text
-            if yara is not None:
-                full_match_keywords = self.__check_yara(content, yara)
+            full_match_keywords = self.__check_yara(content, yara)
 
-                if full_match_keywords is None or len(full_match_keywords) == 0:
-                    # No match.
-                    print(f"No matches in: {website}")
-                    return
+            if full_match_keywords is None or len(full_match_keywords) == 0:
+                # No match.
+                print(f"No matches in: {website}")
+                return
 
             print(content)
         except (HTTPError, URLError, InvalidURL) as err:
@@ -232,7 +227,7 @@ def __termex(self, website, yara):
             return
 
     def extract(self):
-        """Extracts the contents of the input file into the outputs folder/file"""
+        """Extracts the contents of the input file/single URL into the outputs folder/file/terminal."""
         # TODO: Return output to torcrawl.py
         if len(self.input_file) > 0:
             if self.crawl:
diff --git a/torcrawl.py b/torcrawl.py
index d4c0490..1197f31 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -22,7 +22,7 @@
                           (Defualt: terminal)
 -i, --input filename    : Input file with URL(s) (seperated by line)
 -o, --output [filename] : Output page(s) to file(s) (for one page)
--y, --yara              : Yara keyword search page categorisation
+-y, --yara 0|1          : Yara keyword search page categorisation
                           read in from /res folder. 0 search whole html object.
                           1 search only the text.
 
@@ -315,7 +315,7 @@ def main():
             proxies=proxies,
             crawl=args.crawl,
             output_file=args.output,
-            input_file=input_file or "",
+            input_file=args.input or "",
             out_path=out_path,
             yara=args.yara,
         )

From 89fc2f004e4b013b8d685fb82509fd6d14077e47 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Fri, 16 Sep 2022 23:17:44 +0530
Subject: [PATCH 09/39] Fix: Cross platform tor service check

---
 modules/checker.py        | 60 +++++++++++++++++++++++++--------------
 modules/helpers/helper.py | 11 ++++---
 torcrawl.py               | 11 +++----
 3 files changed, 52 insertions(+), 30 deletions(-)

diff --git a/modules/checker.py b/modules/checker.py
index a0faac9..c95f1c5 100644
--- a/modules/checker.py
+++ b/modules/checker.py
@@ -1,14 +1,17 @@
 #!/usr/bin/python
 
 import os
-import re
-import subprocess
 import sys
 from urllib.parse import urlparse
 
+import psutil
 import requests
 
-from modules.helpers.helper import get_requests_header, traceback_name
+from modules.helpers.helper import (
+    TorProxyException,
+    get_requests_header,
+    traceback_name,
+)
 
 
 def url_canon(website, verbose):
@@ -69,33 +72,48 @@ def check_tor(verbose):
     :param verbose: Boolean -'verbose' logging argument.
     :return: None
     """
-    check_for_tor = subprocess.check_output(["ps", "-e"])
-
-    def find_whole_word(word):
-        return re.compile(r"\b({0})\b".format(word), flags=re.IGNORECASE).search
-
-    if find_whole_word("tor")(str(check_for_tor)):
-        if verbose:
-            print("## TOR is ready!")
+    for i in psutil.process_iter():
+        if "tor" == i.name().lower().rstrip(".exe"):
+            if verbose:
+                print("## TOR is ready!")
+            break
     else:
         print("## TOR is NOT running!")
         print("## Enable tor with 'service tor start' or add -w argument")
         sys.exit(2)
 
 
-def check_ip(proxies):
+def check_ip(proxies, url, verbose, without_tor):
     """Checks users IP from external resource.
-    :return: None or HTTPError
+    :return: None
     """
-    addr = "https://api.ipify.org/?format=json"
+    addr = "https://check.torproject.org/api/ip"
     headers = get_requests_header()
     try:
-        my_ip = requests.get(
+        # https://tor.stackexchange.com/a/13079
+        # Double check to tackle false positives
+        check1 = requests.get(
             addr, headers=headers, proxies=proxies, timeout=10, verify=False
-        ).json()["ip"]
-        print(f"## Your IP: {my_ip}")
+        ).json()
+
+        check2 = requests.get(
+            addr, headers=headers, proxies=proxies, timeout=10, verify=False
+        ).json()
+
+        if verbose:
+            print(
+                f"## Your IP: {check2['IP']} :: Tor Connection: {check1['IsTor'] or check2['IsTor']}"
+            )
+            print(f"## URL: {url}")
+
+        if (
+            check1["IsTor"] is False
+            and check2["IsTor"] is False
+            and without_tor is False
+        ):
+            raise TorProxyException(
+                "Tor proxy is NOT running! More info: https://support.torproject.org/connecting/#connecting-4"
+            )
     except Exception as err:
-        print(
-            f"Error: {traceback_name(err)} \n## IP cannot be obtained. \n## Is {addr} up? "
-            f"\n## Exception: {err}"
-        )
+        print(f"## Exception: {traceback_name(err)} \n## Error: {err}")
+        sys.exit(2)
diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index a0928c5..9fcb677 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -55,10 +55,8 @@ def get_requests_header():
     }
 
 
-def get_tor_proxies(without, port=9050):
-    """Get Tor proxies"""
-    if without:
-        return None
+def get_tor_proxies(port=9050):
+    """Get Tor socks proxies"""
     return {
         "http": f"socks5h://127.0.0.1:{port}",
         "https": f"socks5h://127.0.0.1:{port}",
@@ -71,3 +69,8 @@ def traceback_name(error):
     if module is None or module == str.__class__.__module__:
         return error.__class__.__name__
     return module + "." + error.__class__.__name__
+
+
+class TorProxyException(Exception):
+    "Exception raised for errors in the Tor proxy. This might happen if the Tor is running but the application is using a different port."
+    pass
diff --git a/torcrawl.py b/torcrawl.py
index 1197f31..60fc3f9 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -250,15 +250,16 @@ def main():
     if args.thread < 1:
         parser.error("argument -t/--thread: expected argument greater than 1.")
 
+    proxies = None
+
     # Connect to TOR
     if args.without is False:
         check_tor(args.verbose)
+        proxies = get_tor_proxies()
 
-    proxies = get_tor_proxies(without=args.without)
-
-    if args.verbose:
-        check_ip(proxies=proxies)
-        print(("## URL: " + args.url))
+    check_ip(
+        proxies=proxies, url=args.url, verbose=args.verbose, without_tor=args.without
+    )
 
     website = ""
     out_path = ""

From 77074203a2f1a1275130f84f1c7eae1ff24f3147 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sat, 17 Sep 2022 00:29:50 +0530
Subject: [PATCH 10/39] Add: Tor Socks Proxy port argument and catch base
 exceptions

---
 README.md                 |  7 ++---
 modules/extractor.py      | 33 +++++++++++++----------
 modules/helpers/helper.py |  2 +-
 torcrawl.py               | 55 +++++++++++++++++++++++----------------
 4 files changed, 57 insertions(+), 40 deletions(-)

diff --git a/README.md b/README.md
index 8b527e0..57dd2ae 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
 <!--
   Title: DarkSpider
   Description: a python script to crawl and extract (regular or onion) webpages through TOR network.
-  Author: MikeMeliz
+  Author: PROxZIMA
   -->
 # DarkSpider
 
@@ -58,17 +58,18 @@ arg | Long | Description
 -v  |--verbose| Show more information about the progress
 -u  |--url *.onion| URL of Webpage to crawl or extract
 -w  |--without| Without the use of Relay TOR
+-n  |--port number| Port number of TOR Socks Proxy (default: 9050)
 -f  |--folder| The directory which will contain the generated files ([@guyo13](https://www.github.com/guyo13))
 -s  |--visualize| Visualize the graphs and insights from the crawled data
 **Extract**: | |
 -e  |--extract| Extract page's code to terminal or file. (Default: Terminal)
 -i  |--input filename| Input file with URL(s) (separated by line)
--o  |--output [filename]| Output page(s) to file(s) (for one page)
+-o  |--output filename| Output page(s) to file(s) (for one page)
 -y  |--yara 0\|1 | Perform yara keyword search (0 = search entire html object. 1 = search only text).
 **Crawl**: | |
 -c  |--crawl| Crawl website (Default output on /links.txt)
 -d  |--cdepth| Set depth of crawl's travel (Default: 1)
--z  |--exclusion "regexp"| Regex path that is ignored while crawling (Default: None)
+-z  |--exclusion regexp| Regex path that is ignored while crawling (Default: None)
 -t  |--thread number| How many pages to visit (Threads) at the same time (Default: 16)
 -p  |--pause| The length of time the crawler will pause (Default: 0)
 -l  |--log| Log file with visited URLs and their response code
diff --git a/modules/extractor.py b/modules/extractor.py
index 2e47998..4a749b8 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -150,6 +150,8 @@ def __cinex(self, input_file, out_path, yara):
                 continue
             except IOError as err:
                 print(f"Error: {err}\nCan't write on file: {output_file}")
+            except Exception as err:
+                print(f"Error: ({err}) {line}")
         file.close()
 
     def __intermex(self, input_file, yara):
@@ -161,21 +163,22 @@ def __intermex(self, input_file, yara):
         """
         try:
             with open(input_file, "r", encoding="UTF-8") as file:
-                for line in file.read().splitlines():
-                    content = self.__session.get(
-                        line, allow_redirects=True, timeout=10
-                    ).text
-                    full_match_keywords = self.__check_yara(raw=content, yara=yara)
-
-                    if full_match_keywords is None or len(full_match_keywords) == 0:
-                        print(f"No matches in: {line}")
-                    print(content)
-        except (HTTPError, URLError, InvalidURL) as err:
-            print(f"Request Error: {err}")
+                try:
+                    for line in file.read().splitlines():
+                        content = self.__session.get(
+                            line, allow_redirects=True, timeout=10
+                        ).text
+                        full_match_keywords = self.__check_yara(raw=content, yara=yara)
+
+                        if full_match_keywords is None or len(full_match_keywords) == 0:
+                            print(f"No matches in: {line}")
+                        print(content)
+                except (HTTPError, URLError, InvalidURL) as err:
+                    print(f"Request Error: ({err}) {line}")
+                except Exception as err:
+                    print(f"Error: ({err}) {line}")
         except IOError as err:
             print(f"Error: {err}\n## Not valid file")
-        except Exception as err:
-            print(f"Error: {err}")
 
     def __outex(self, website, output_file, out_path, yara):
         """Scrapes the contents of the provided web address and outputs the
@@ -204,6 +207,8 @@ def __outex(self, website, output_file, out_path, yara):
             print(f"HTTPError: {err}")
         except IOError as err:
             print(f"Error: {err}\n Can't write on file: {output_file}")
+        except Exception as err:
+            print(f"Error: ({err}) {website}")
 
     def __termex(self, website, yara):
         """Scrapes provided web address and prints the results to the terminal.
@@ -222,7 +227,7 @@ def __termex(self, website, yara):
                 return
 
             print(content)
-        except (HTTPError, URLError, InvalidURL) as err:
+        except (HTTPError, URLError, InvalidURL, Exception) as err:
             print(f"Error: ({err}) {website}")
             return
 
diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index 9fcb677..7f4553d 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -55,7 +55,7 @@ def get_requests_header():
     }
 
 
-def get_tor_proxies(port=9050):
+def get_tor_proxies(port):
     """Get Tor socks proxies"""
     return {
         "http": f"socks5h://127.0.0.1:{port}",
diff --git a/torcrawl.py b/torcrawl.py
index 60fc3f9..33f6b71 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -14,33 +14,34 @@
 -g, --gui          : Open with GUI backend.
 -v, --verbose      : Show more informations about the progress
 -u, --url *.onion  : URL of Webpage to crawl or extract
+-n, --port number  : Port number of TOR Proxy (default: 9050)
 -w, --without      : Without the use of Relay TOR
 -s, --visualize    : Visualize the graphs and insights from the crawled data
 
 Extract:
--e, --extract           : Extract page's code to terminal or file.
-                          (Defualt: terminal)
--i, --input filename    : Input file with URL(s) (seperated by line)
--o, --output [filename] : Output page(s) to file(s) (for one page)
--y, --yara 0|1          : Yara keyword search page categorisation
-                          read in from /res folder. 0 search whole html object.
-                          1 search only the text.
+-e, --extract         : Extract page's code to terminal or file.
+                        (Defualt: terminal)
+-i, --input filename  : Input file with URL(s) (seperated by line)
+-o, --output filename : Output page(s) to file(s) (for one page)
+-y, --yara 0|1        : Yara keyword search page categorisation
+                        read in from /res folder. 0 search whole html object.
+                        1 search only the text.
 
 Crawl:
--c, --crawl               : Crawl website (Default output on /links.txt)
--d, --cdepth              : Set depth of crawl's travel (Default: 1)
--z, --exclusions "regexp" : Paths that you don't want to include
--t, --thread number       : How many pages to visit (Threads) at the same time
-                            (Default: 16)
--p, --pause               : The length of time the crawler will pause
-                            (Default: 0)
--f, --folder	          : The root directory which will contain the
-                            generated files
--l, --log                 : Log file with visited URLs and their response code.
--x, --external            : Exclude external links while crawling a webpage
-                            (Default: include all links)
-
-GitHub: github.com/MikeMeliz/TorCrawl.py
+-c, --crawl             : Crawl website (Default output on /links.txt)
+-d, --cdepth            : Set depth of crawl's travel (Default: 1)
+-z, --exclusions regexp : Paths that you don't want to include
+-t, --thread number     : How many pages to visit (Threads) at the same time
+                          (Default: 16)
+-p, --pause             : The length of time the crawler will pause
+                          (Default: 0)
+-f, --folder	        : The root directory which will contain the
+                          generated files
+-l, --log               : Log file with visited URLs and their response code.
+-x, --external          : Exclude external links while crawling a webpage
+                          (Default: include all links)
+
+GitHub: github.com/PROxZIMA/DarkSpider.py
 License: GNU General Public License v3.0
 
 """
@@ -141,6 +142,13 @@ def main():
     parser.add_argument(
         "-u", "--url", type=str, help="URL of webpage to crawl or extract"
     )
+    parser.add_argument(
+        "-n",
+        "--port",
+        type=int,
+        default=9050,
+        help="Port number of TOR Proxy (default: 9050)",
+    )
     parser.add_argument(
         "-w", "--without", action="store_true", help="Without the use of Relay TOR"
     )
@@ -238,6 +246,9 @@ def main():
     if args.url is None and args.input is None:
         parser.error("either argument -u/--url or -i/--input is required to proceed.")
 
+    if args.port < 1 or 65535 < args.port:
+        parser.error("argument -n/--port: expected argument in between 1 to 65535.")
+
     if args.yara not in [0, 1]:
         parser.error("argument -y/--yara: expected argument 0 or 1.")
 
@@ -255,7 +266,7 @@ def main():
     # Connect to TOR
     if args.without is False:
         check_tor(args.verbose)
-        proxies = get_tor_proxies()
+        proxies = get_tor_proxies(port=args.port)
 
     check_ip(
         proxies=proxies, url=args.url, verbose=args.verbose, without_tor=args.without

From cfef59ac36868879c3e6a98c52882ea011d95d48 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 00:38:23 +0530
Subject: [PATCH 11/39] Add: Logging functionality throughout the code

---
 modules/checker.py        |  49 +++-----
 modules/crawler.py        |  76 ++++--------
 modules/extractor.py      | 252 +++++++++++++++++++++-----------------
 modules/helpers/helper.py |  31 +++++
 modules/visualization.py  |   5 +-
 torcrawl.py               |  60 ++++++---
 6 files changed, 257 insertions(+), 216 deletions(-)

diff --git a/modules/checker.py b/modules/checker.py
index c95f1c5..7a3d8d1 100644
--- a/modules/checker.py
+++ b/modules/checker.py
@@ -7,29 +7,22 @@
 import psutil
 import requests
 
-from modules.helpers.helper import (
-    TorProxyException,
-    get_requests_header,
-    traceback_name,
-)
+from modules.helpers.helper import TorProxyException, get_requests_header
 
 
-def url_canon(website, verbose):
+def url_canon(website):
     """URL normalisation/canonicalization
 
     :param website: String - URL of website.
-    :param verbose: Boolean - Verbose logging switch.
     :return: String 'website' - normalised result.
     """
+    canon = False
     if not website.startswith("http"):
         if not website.startswith("www."):
             website = "www." + website
-            if verbose:
-                print(("## URL fixed: " + website))
         website = "http://" + website
-        if verbose:
-            print(("## URL fixed: " + website))
-    return website
+        canon = True
+    return canon, website
 
 
 def extract_domain(url, remove_http=True):
@@ -49,41 +42,36 @@ def extract_domain(url, remove_http=True):
 
 
 # Create output path
-def folder(website, verbose):
+def folder(out_path):
     """Creates an output path for the findings.
 
-    :param website: String - URL of website to crawl.
-    :param verbose: Boolean - Logging level.
+    :param out_path: String - Output path in which all extracted data is stored.
     :return: String 'out_path' - Path of the output folder.
     """
-    out_path = website
     if not os.path.exists(out_path):
         os.makedirs(out_path)
-    if verbose:
-        print(f"## Folder created: {out_path}")
     return out_path
 
 
-def check_tor(verbose):
+def check_tor(logger):
     """Checks to see if TOR service is running on device.
     Will exit if (-w) with argument is provided on application startup and TOR
     service is not found to be running on the device.
 
-    :param verbose: Boolean -'verbose' logging argument.
+    :param Logger logger: A logger object to log the output.
     :return: None
     """
     for i in psutil.process_iter():
         if "tor" == i.name().lower().rstrip(".exe"):
-            if verbose:
-                print("## TOR is ready!")
+            logger.debug("TOR is ready!")
             break
     else:
-        print("## TOR is NOT running!")
-        print("## Enable tor with 'service tor start' or add -w argument")
+        logger.critical("TOR is NOT running!")
+        logger.critical("Enable tor with 'service tor start' or add -w argument")
         sys.exit(2)
 
 
-def check_ip(proxies, url, verbose, without_tor):
+def check_ip(proxies, url, logger, without_tor):
     """Checks users IP from external resource.
     :return: None
     """
@@ -100,11 +88,10 @@ def check_ip(proxies, url, verbose, without_tor):
             addr, headers=headers, proxies=proxies, timeout=10, verify=False
         ).json()
 
-        if verbose:
-            print(
-                f"## Your IP: {check2['IP']} :: Tor Connection: {check1['IsTor'] or check2['IsTor']}"
-            )
-            print(f"## URL: {url}")
+        logger.debug(
+            f"Your IP: {check2['IP']} :: Tor Connection: {check1['IsTor'] or check2['IsTor']}"
+        )
+        logger.debug(f"URL: {url}")
 
         if (
             check1["IsTor"] is False
@@ -115,5 +102,5 @@ def check_ip(proxies, url, verbose, without_tor):
                 "Tor proxy is NOT running! More info: https://support.torproject.org/connecting/#connecting-4"
             )
     except Exception as err:
-        print(f"## Exception: {traceback_name(err)} \n## Error: {err}")
+        logger.exception(err)
         sys.exit(2)
diff --git a/modules/crawler.py b/modules/crawler.py
index c9d450d..5a157d8 100644
--- a/modules/crawler.py
+++ b/modules/crawler.py
@@ -1,14 +1,11 @@
 #!/usr/bin/python
 import json
-import logging
 import os
 import re
-import sys
 import time
-import warnings
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from io import TextIOBase
-from threading import Lock
+from logging import Logger
 from typing import Union
 from urllib.parse import urljoin
 
@@ -16,10 +13,7 @@
 from bs4 import BeautifulSoup
 from requests.models import Response
 
-from modules.helpers.helper import get_requests_header, traceback_name
-
-warnings.filterwarnings("ignore", category=UserWarning, module="bs4")
-requests.urllib3.disable_warnings()
+from modules.helpers.helper import get_requests_header
 
 
 class Crawler:
@@ -36,11 +30,7 @@ class Crawler:
     :param bool external: True if external links are to be crawled else False.
     :param re str exclusion: Paths that you don't want to include.
     :param int thread: Number pages to visit (Threads) at the same time.
-    :param dict[str, bool] logging: Dictionary mapping
-                                    {
-                                        bool logs: True if logs are to be written else False,
-                                        bool verbose: True if crawl details are to be printed else False
-                                    }
+    :param Logger logger: A logger object to log the output.
     """
 
     network_file = "network_structure.json"
@@ -55,7 +45,7 @@ def __init__(
         external: bool,
         exclusion: str,
         thread: int,
-        logging_: dict[str, bool],
+        logger: Logger,
     ):
         self.website = website
         self.proxies = proxies
@@ -65,11 +55,9 @@ def __init__(
         self.external = external
         self.exclusion = rf"{exclusion}" if exclusion else None
         self.thread = thread
-        self.logs = logging_["log"]
-        self.log_path = os.path.join(self.out_path, "log.txt")
-        self.verbose = logging_["verbose"]
+        self.logger = logger
+
         self.__executor = ThreadPoolExecutor(max_workers=min(32, self.thread))
-        self.__lock = Lock()
         self.__files = {
             "extlinks": open(
                 os.path.join(self.out_path, "extlinks.txt"), "w+", encoding="UTF-8"
@@ -80,7 +68,6 @@ def __init__(
             "mails": open(
                 os.path.join(self.out_path, "mails.txt"), "w+", encoding="UTF-8"
             ),
-            "log_file": open(self.log_path, "w+", encoding="UTF-8"),
             "network_structure": os.path.join(self.out_path, self.network_file),
             "links": os.path.join(self.out_path, "links.txt"),
         }
@@ -138,35 +125,25 @@ def canonical(self, base, href):
         # For relative paths
         return urljoin(base, href)
 
-    def __crawl_link(self, item, session) -> tuple[str, list[str]]:
+    def __crawl_link(self, item, session) -> tuple[str, set[str], int]:
         # Store the crawled link of an item
         item_data = set()
         html_page = Response
+        response_code = 0
 
         try:
             if item is not None:
                 html_page = session.get(item, allow_redirects=True, timeout=10)
-        except Exception as error:
-            print(
-                f"## Request Error :: {item} :: {traceback_name(error)}{' :: ' + error if self.logs else ''}"
-            )
-            # Keeps logs for every webpage visited.
-            if self.logs:
-                with self.__lock:
-                    self.__files["log_file"].write(f"{str(item)}\n")
-            return item, item_data
+                response_code = html_page.status_code
+        except Exception as _:
+            self.logger.debug(f"Request Error :: {item}", exc_info=True)
+            return item, item_data, 0
 
         try:
             soup = BeautifulSoup(html_page.text, features="html.parser")
-        except Exception as error:
-            print(
-                f"## Soup Parse Error :: {item} :: {traceback_name(error)}{' :: ' + error if self.logs else ''}"
-            )
-            # Keeps logs for every webpage visited.
-            if self.logs:
-                with self.__lock:
-                    self.__files["log_file"].write(f"{str(item)}\n")
-            return item, item_data
+        except Exception as _:
+            self.logger.debug(f"Soup Parse Error :: {item}", exc_info=True)
+            return item, item_data, 0
 
         # For each <a href=""> tag.
         for link in soup.findAll("a"):
@@ -212,7 +189,7 @@ def __crawl_link(self, item, session) -> tuple[str, list[str]]:
             if ver_link is not None:
                 item_data.add(ver_link)
 
-        return item, item_data
+        return item, item_data, response_code
 
     def crawl(self):
         """Core of the crawler.
@@ -222,14 +199,8 @@ def crawl(self):
         old_level = [self.website]
         cur_level = set()
 
-        if self.logs is True and os.access(self.log_path, os.W_OK) is ~os.path.exists(
-            self.log_path
-        ):
-            print(f"## Unable to write to {self.log_path} - Exiting")
-            sys.exit(2)
-
-        print(
-            f"## Crawler started from {self.website} with {self.c_depth} depth, "
+        self.logger.info(
+            f"Crawler started from {self.website} with {self.c_depth} depth, "
             f"{self.c_pause} second{'s'[:int(self.c_pause)^1]} delay and using {self.thread} "
             f"Thread{'s'[:self.thread^1]}. Excluding '{self.exclusion}' links."
         )
@@ -247,14 +218,13 @@ def crawl(self):
             ]
 
             for future in as_completed(futures):
-                item, item_data = future.result()
+                item, item_data, response_code = future.result()
+                self.logger.debug(f"{item} :: {response_code}")
 
                 # Add item_data to crawled links.
                 cur_level = cur_level.union(item_data)
 
-                if self.verbose:
-                    sys.stdout.write(f"-- Results: {len(cur_level)}\r")
-                    sys.stdout.flush()
+                print(f"-- Results: {len(cur_level)}\r", end="", flush=True)
 
                 # Adding to json data
                 json_data[item.rstrip("/")] = list(item_data)
@@ -267,7 +237,9 @@ def crawl(self):
             old_level = list(clean_cur_level)
             # Reset cur_level
             cur_level = set()
-            print(f"## Step {index + 1} completed \n\t with: {len(ord_lst)} result(s)")
+            self.logger.info(
+                f"Step {index + 1} completed with: {len(ord_lst)} result(s)"
+            )
 
             # Creating json
             with open(
diff --git a/modules/extractor.py b/modules/extractor.py
index 4a749b8..3850b61 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -1,17 +1,16 @@
 #!/usr/bin/python
 import os
-import urllib.error
-import urllib.parse
-import urllib.request
 from http.client import IncompleteRead, InvalidURL
 from io import TextIOWrapper
+from logging import Logger
 from urllib.error import HTTPError, URLError
 
 import requests
 import yara as _yara
 from bs4 import BeautifulSoup
 
-from modules.helpers.helper import get_requests_header, traceback_name
+from modules.checker import folder
+from modules.helpers.helper import get_requests_header
 
 
 class Extractor:
@@ -24,10 +23,12 @@ class Extractor:
     :param str input_file: Filename of crawled/discovered URLs
     :param str out_path: Dir path for output files.
     :param int yara: keyword search option.
+    :param Logger logger: A logger object to log the output.
     """
 
     __headers = get_requests_header()
     __yara_rules = _yara.compile("res/keywords.yar")
+    __extract_folder = "extracted"
 
     def __init__(
         self,
@@ -38,6 +39,7 @@ def __init__(
         input_file: str,
         out_path: str,
         yara: int,
+        logger: Logger,
     ):
         self.website = website
         self.proxies = proxies
@@ -45,13 +47,28 @@ def __init__(
         self.output_file = output_file
         self.input_file = input_file
 
-        self.out_path = os.path.join(out_path, "extracted")
-        if not os.path.exists(self.out_path):
-            os.mkdir(self.out_path)
+        self.out_path = out_path
+        if self.crawl:
+            self.out_path = folder(os.path.join(out_path, self.__extract_folder))
 
         self.yara = yara
+        self.logger = logger
         self.__session = self.__get_tor_session()
 
+    def extract(self):
+        """Extracts the contents of the input file/single URL into the outputs folder/file/terminal."""
+        # TODO: Return output to torcrawl.py
+        if len(self.input_file) > 0:
+            if self.crawl or self.out_path:
+                self.__cinex(self.input_file, self.out_path, self.yara)
+            else:
+                self.__intermex(self.input_file, self.yara)
+        else:
+            if len(self.output_file) > 0:
+                self.__outex(self.website, self.output_file, self.out_path, self.yara)
+            else:
+                self.__termex(self.website, self.yara)
+
     def __get_tor_session(self):
         session = requests.Session()
         session.proxies = self.proxies
@@ -72,9 +89,10 @@ def __text(self, response=None):
 
         return " ".join(soup.stripped_strings)
 
-    def __check_yara(self, raw=None, yara=0):
+    def __check_yara(self, type_, raw=None, yara=0):
         """Validates Yara Rule to categorize the site and check for keywords.
 
+        :param type_: String: "Cinex" or "Intermex" or "Outex" or "Termex".
         :param yara:  Integer: Keyword search argument.
         :param raw:   HTTP Response body.
         :return matches: List of yara rule matches.
@@ -87,40 +105,45 @@ def __check_yara(self, raw=None, yara=0):
 
         matches = self.__yara_rules.match(data=raw)
 
-        if len(matches) != 0:
-            print("found a match!")
+        # if len(matches) != 0:
+        #     self.logger.debug(f"{type_} :: Yara match found!")
 
         return matches
 
-    def __cinex(self, input_file, out_path, yara):
+    def __inex(self, type_, input_file, yara, out_path=None):
         """Ingests the crawled links from the input_file,
-        scrapes the contents of the resulting web pages and writes the contents to
-        the into out_path/{url_address}.
+        scrapes the contents of the resulting web pages and writes the contents
+        into the terminal if out_path is None else out_path/{url_address}.
 
+        :param type_: String: Either "Cinex" or "Intermex".
         :param input_file: String: Filename of the crawled Urls.
-        :param out_path: String: Pathname of results.
+        :param out_path: String|None : Pathname of results.
         :param yara: Integer: Keyword search argument.
         :return: None
         """
         file = TextIOWrapper
         try:
             file = open(input_file, "r", encoding="UTF-8")
-        except IOError as err:
-            print(f"Error: {err}\n## Can't open: {input_file}")
+        except IOError as _:
+            self.logger.exception(f"{type_} Read Error :: {input_file}")
+            return
 
         for line in file.read().splitlines():
 
             # Generate the name for every file.
-            try:
-                page_name = line.rsplit("/", 1)
-                cl_page_name = str(page_name[1])
-                if len(cl_page_name) == 0:
-                    output_file = "index.html"
-                else:
-                    output_file = cl_page_name
-            except IndexError as error:
-                print(f"Error: {error}")
-                continue
+            if out_path is not None:
+                try:
+                    page_name = line.rsplit("/", 1)
+                    cl_page_name = str(page_name[1])
+                    if len(cl_page_name) == 0:
+                        output_file = "index.html"
+                    else:
+                        output_file = cl_page_name
+                except Exception as _:
+                    self.logger.debug(
+                        f"{type_} Output File Error :: {line}", exc_info=True
+                    )
+                    continue
 
             # Extract page to file.
             try:
@@ -128,32 +151,57 @@ def __cinex(self, input_file, out_path, yara):
                     line, allow_redirects=True, timeout=10
                 ).text
 
-                full_match_keywords = self.__check_yara(content, yara)
-
-                if len(full_match_keywords) == 0:
-                    print("No matches found.")
-                    continue
-
-                with open(
-                    os.path.join(out_path, output_file), "w+", encoding="UTF-8"
-                ) as results:
-                    results.write(content)
-                print(f"# File created on: {os.path.join(out_path, output_file)}")
-            except HTTPError as err:
-                print(f"Cinex Error: {err.code}, cannot access: {err.url}")
+                full_match_keywords = self.__check_yara(
+                    type_=type_, raw=content, yara=yara
+                )
+
+                self.logger.debug(
+                    f"{type_} :: {line} :: {'Yara' if len(full_match_keywords) else 'No yara'} match found!"
+                )
+
+                # if len(full_match_keywords) == 0:
+                #     self.logger.debug(f"{type_} :: No yara matches found.")
+                #     Don't write to file if no matches found.
+                #     if out_path is not None:
+                #         continue
+
+                if out_path is not None:
+                    with open(
+                        os.path.join(out_path, output_file), "w+", encoding="UTF-8"
+                    ) as results:
+                        results.write(content)
+                    self.logger.debug(
+                        f"{type_} File created :: {os.path.join(out_path, output_file)}"
+                    )
+                else:
+                    self.logger.info(f"{line} :: {content}")
+            except HTTPError as _:
+                self.logger.debug(f"{type_} Request Error :: {line}", exc_info=True)
                 continue
-            except InvalidURL as _:
-                print(f"Invalid URL: {line} \n Skipping...")
+            except (InvalidURL, URLError) as _:
+                self.logger.debug(f"{type_} Invalid URL Error :: {line} :: Skipping...")
                 continue
             except IncompleteRead as _:
-                print(f"IncompleteRead on {line}")
+                self.logger.debug(f"{type_} Incomplete Read Error :: {line}")
                 continue
-            except IOError as err:
-                print(f"Error: {err}\nCan't write on file: {output_file}")
-            except Exception as err:
-                print(f"Error: ({err}) {line}")
+            except IOError as _:
+                self.logger.debug(f"{type_} IOError Error :: {line}", exc_info=True)
+            except Exception as _:
+                self.logger.debug(f"{type_} Error :: {line}", exc_info=True)
         file.close()
 
+    def __cinex(self, input_file, out_path, yara):
+        """Ingests the crawled links from the input_file,
+        scrapes the contents of the resulting web pages and writes the contents to
+        the into out_path/{url_address}.
+
+        :param input_file: String: Filename of the crawled Urls.
+        :param out_path: String: Pathname of results.
+        :param yara: Integer: Keyword search argument.
+        :return: None
+        """
+        self.__inex(type_="Cinex", input_file=input_file, yara=yara, out_path=out_path)
+
     def __intermex(self, input_file, yara):
         """Input links from file and extract them into terminal.
 
@@ -161,54 +209,65 @@ def __intermex(self, input_file, yara):
         :param yara: Integer: Keyword search argument.
         :return: None
         """
-        try:
-            with open(input_file, "r", encoding="UTF-8") as file:
-                try:
-                    for line in file.read().splitlines():
-                        content = self.__session.get(
-                            line, allow_redirects=True, timeout=10
-                        ).text
-                        full_match_keywords = self.__check_yara(raw=content, yara=yara)
-
-                        if full_match_keywords is None or len(full_match_keywords) == 0:
-                            print(f"No matches in: {line}")
-                        print(content)
-                except (HTTPError, URLError, InvalidURL) as err:
-                    print(f"Request Error: ({err}) {line}")
-                except Exception as err:
-                    print(f"Error: ({err}) {line}")
-        except IOError as err:
-            print(f"Error: {err}\n## Not valid file")
+        self.__inex(type_="Intermex", input_file=input_file, yara=yara)
 
-    def __outex(self, website, output_file, out_path, yara):
+    def __ex(self, type_, website, yara, output_file=None, out_path=None):
         """Scrapes the contents of the provided web address and outputs the
-        contents to file.
+        contents to file or terminal.
 
+        :param type: String: Either "Outex" or "Termex".
         :param website: String: Url of web address to scrape.
-        :param output_file: String: Filename of the results.
-        :param out_path: String: Folder name of the output findings.
         :param yara: Integer: Keyword search argument.
+        :param output_file: String|None: Filename of the results.
+        :param out_path: String|None: Folder name of the output findings.
         :return: None
         """
         # Extract page to file
         try:
-            output_file = os.path.join(out_path, output_file)
+            if out_path is not None:
+                output_file = os.path.join(out_path, output_file)
             content = self.__session.get(website, allow_redirects=True, timeout=10).text
 
-            full_match_keywords = self.__check_yara(raw=content, yara=yara)
+            full_match_keywords = self.__check_yara(type_=type_, raw=content, yara=yara)
 
-            if len(full_match_keywords) == 0:
-                print(f"No matches in: {website}")
+            self.logger.debug(
+                f"{type_} :: {website} :: {'Yara' if len(full_match_keywords) else 'No yara'} match found!"
+            )
 
-            with open(output_file, "w+", encoding="UTF-8") as file:
-                file.write(content)
-            print(f"## File created on: {output_file}")
-        except (HTTPError, URLError, InvalidURL) as err:
-            print(f"HTTPError: {err}")
-        except IOError as err:
-            print(f"Error: {err}\n Can't write on file: {output_file}")
-        except Exception as err:
-            print(f"Error: ({err}) {website}")
+            if out_path is not None:
+                with open(output_file, "w+", encoding="UTF-8") as file:
+                    file.write(content)
+                self.logger.debug(f"{type_} File created :: {output_file}")
+            else:
+                self.logger.info(f"{website} :: {content}")
+        except HTTPError as _:
+            self.logger.debug(f"{type_} Request Error :: {website}", exc_info=True)
+        except (InvalidURL, URLError) as _:
+            self.logger.debug(f"{type_} Invalid URL Error :: {website} :: Skipping...")
+        except IncompleteRead as _:
+            self.logger.debug(f"{type_} Incomplete Read Error :: {website}")
+        except IOError as _:
+            self.logger.debug(f"{type_} IOError Error :: {website}", exc_info=True)
+        except Exception as _:
+            self.logger.debug(f"{type_} Error :: {website}", exc_info=True)
+
+    def __outex(self, website, output_file, out_path, yara):
+        """Scrapes the contents of the provided web address and outputs the
+        contents to file.
+
+        :param website: String: Url of web address to scrape.
+        :param output_file: String: Filename of the results.
+        :param out_path: String: Folder name of the output findings.
+        :param yara: Integer: Keyword search argument.
+        :return: None
+        """
+        self.__ex(
+            type_="Outex",
+            website=website,
+            yara=yara,
+            output_file=output_file,
+            out_path=out_path,
+        )
 
     def __termex(self, website, yara):
         """Scrapes provided web address and prints the results to the terminal.
@@ -217,33 +276,4 @@ def __termex(self, website, yara):
         :param yara: Integer: Keyword search argument.
         :return: None
         """
-        try:
-            content = self.__session.get(website, allow_redirects=True, timeout=10).text
-            full_match_keywords = self.__check_yara(content, yara)
-
-            if full_match_keywords is None or len(full_match_keywords) == 0:
-                # No match.
-                print(f"No matches in: {website}")
-                return
-
-            print(content)
-        except (HTTPError, URLError, InvalidURL, Exception) as err:
-            print(f"Error: ({err}) {website}")
-            return
-
-    def extract(self):
-        """Extracts the contents of the input file/single URL into the outputs folder/file/terminal."""
-        # TODO: Return output to torcrawl.py
-        if len(self.input_file) > 0:
-            if self.crawl:
-                self.__cinex(self.input_file, self.out_path, self.yara)
-            # TODO: Extract from list into a folder
-            # elif len(output_file) > 0:
-            # 	inoutex(website, input_ile, output_file)
-            else:
-                self.__intermex(self.input_file, self.yara)
-        else:
-            if len(self.output_file) > 0:
-                self.__outex(self.website, self.output_file, self.out_path, self.yara)
-            else:
-                self.__termex(self.website, self.yara)
+        self.__ex(type_="Termex", website=website, yara=yara)
diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index 7f4553d..69dd541 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -1,3 +1,4 @@
+import logging
 import os
 import sys
 from io import StringIO
@@ -47,6 +48,36 @@ def wrapper(*args, **kwargs):
     return wrapper
 
 
+def setup_custom_logger(name, verbose_, filelog, filename):
+    """Setup custom logger with stream and file handlers"""
+    formatter = logging.Formatter(
+        fmt="{asctime} [{levelname:^7s}] [{filename}:{lineno}] {message}",
+        style="{",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.DEBUG)
+    logger.handlers.clear()
+
+    screen_handler = logging.StreamHandler(stream=sys.stdout)
+    screen_handler.setFormatter(formatter)
+    screen_handler.setLevel(logging.DEBUG)
+
+    if verbose_ is False:
+        screen_handler.setLevel(logging.INFO)
+
+    logger.addHandler(screen_handler)
+
+    if filelog:
+        file_handler = logging.FileHandler(filename=filename, mode="w")
+        file_handler.setFormatter(formatter)
+        file_handler.setLevel(logging.DEBUG)
+        logger.addHandler(file_handler)
+
+    return logger
+
+
 def get_requests_header():
     """Get requests header"""
     return {
diff --git a/modules/visualization.py b/modules/visualization.py
index db99e83..e428135 100644
--- a/modules/visualization.py
+++ b/modules/visualization.py
@@ -8,6 +8,7 @@
 import seaborn as sns
 from matplotlib.ticker import MultipleLocator
 
+from modules.checker import folder
 from modules.helpers.helper import verbose
 
 
@@ -23,9 +24,7 @@ def __init__(self, json_file, out_path, verbose):
         self.json_file = json_file
         self.verbose = verbose
 
-        self.out_path = os.path.join(out_path, "visualization")
-        if not os.path.exists(self.out_path):
-            os.mkdir(self.out_path)
+        self.out_path = folder(os.path.join(out_path, "visualization"))
 
         with open(self.json_file, "r", encoding="UTF-8") as f:
             self.data = json.load(f)
diff --git a/torcrawl.py b/torcrawl.py
index 33f6b71..6ad0fb7 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -47,10 +47,14 @@
 """
 
 import argparse
+import logging
 import os
 import sys
+import warnings
 
-from modules.helpers.helper import get_tor_proxies
+import requests
+
+from modules.helpers.helper import get_tor_proxies, setup_custom_logger
 
 try:
     from gooey import Gooey, GooeyParser
@@ -66,6 +70,10 @@
 from modules.extractor import Extractor
 from modules.visualization import Visualization
 
+warnings.filterwarnings("ignore", category=UserWarning, module="bs4")
+logging.getLogger("urllib3").setLevel(logging.ERROR)
+requests.urllib3.disable_warnings()
+
 IGNORE_COMMAND = "--ignore-gooey"
 
 # Remove IGNORE_COMMAND if present in arguments.
@@ -262,28 +270,37 @@ def main():
         parser.error("argument -t/--thread: expected argument greater than 1.")
 
     proxies = None
+    out_path = ""
+    canon, website = False, ""
+
+    # Canonicalization of web url and create path for output.
+    if args.url:
+        canon, website = url_canon(args.url)
+        out_path = folder(extract_domain(website))
+    elif args.folder:
+        out_path = folder(args.folder)
+
+    # Logger setup
+    crawlog = setup_custom_logger(
+        name="crawlog",
+        verbose_=args.verbose,
+        filelog=args.log,
+        filename=os.path.join(out_path, "crawl.log"),
+    )
 
     # Connect to TOR
     if args.without is False:
-        check_tor(args.verbose)
+        check_tor(logger=crawlog)
         proxies = get_tor_proxies(port=args.port)
 
-    check_ip(
-        proxies=proxies, url=args.url, verbose=args.verbose, without_tor=args.without
-    )
+    check_ip(proxies=proxies, url=args.url, logger=crawlog, without_tor=args.without)
 
-    website = ""
-    out_path = ""
+    if canon:
+        crawlog.debug("URL fixed: %s", website)
+    if out_path:
+        crawlog.debug("Folder created: %s", out_path)
 
-    # Canonicalization of web url and create path for output.
-    if args.url:
-        website = url_canon(args.url, args.verbose)
-        if args.folder is not None:
-            out_path = folder(args.folder, args.verbose)
-        else:
-            out_path = folder(extract_domain(website), args.verbose)
-
-    if args.crawl:
+    if args.crawl and website:
         crawler = Crawler(
             website=website,
             proxies=proxies,
@@ -292,10 +309,13 @@ def main():
             external=args.external,
             exclusion=args.exclusion,
             thread=args.thread,
-            logging_={"log": args.log, "verbose": args.verbose},
+            logger=crawlog,
         )
         json_data = crawler.crawl()
-        print(f"## File created on {os.path.join(out_path, crawler.network_file)}")
+        crawlog.info(
+            "Network Structure created :: %s",
+            os.path.join(out_path, crawler.network_file),
+        )
 
         if args.visualize:
             obj = Visualization(
@@ -319,9 +339,10 @@ def main():
                 input_file=input_file,
                 out_path=out_path,
                 yara=args.yara,
+                logger=crawlog,
             )
             extractor.extract()
-    else:
+    elif args.input or website:
         extractor = Extractor(
             website=website,
             proxies=proxies,
@@ -330,6 +351,7 @@ def main():
             input_file=args.input or "",
             out_path=out_path,
             yara=args.yara,
+            logger=crawlog,
         )
         extractor.extract()
 

From 35745a59357df683fbf470bf722153ac2d8d2186 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 01:03:31 +0530
Subject: [PATCH 12/39] Fix: Visualization module logging

---
 modules/helpers/helper.py | 3 +--
 modules/visualization.py  | 4 ++--
 torcrawl.py               | 9 +++++++--
 3 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index 69dd541..e67a637 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -32,8 +32,7 @@ def verbose(func):
     """Verbose decorator"""
 
     def wrapper(*args, **kwargs):
-        if args[0].verbose:
-            print(f"## {func.__doc__}...")
+        args[0].logger.info(f"Generating :: {func.__doc__}..")
         plt.cla()
         plt.figure(figsize=(12, 6))
         plt.grid()
diff --git a/modules/visualization.py b/modules/visualization.py
index e428135..8bb202e 100644
--- a/modules/visualization.py
+++ b/modules/visualization.py
@@ -20,9 +20,9 @@ class Visualization:
     :param verbose: Whether to print the output or not
     """
 
-    def __init__(self, json_file, out_path, verbose):
+    def __init__(self, json_file, out_path, logger):
         self.json_file = json_file
-        self.verbose = verbose
+        self.logger = logger
 
         self.out_path = folder(os.path.join(out_path, "visualization"))
 
diff --git a/torcrawl.py b/torcrawl.py
index 6ad0fb7..87cfa45 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -293,7 +293,10 @@ def main():
         check_tor(logger=crawlog)
         proxies = get_tor_proxies(port=args.port)
 
-    check_ip(proxies=proxies, url=args.url, logger=crawlog, without_tor=args.without)
+    if args.verbose:
+        check_ip(
+            proxies=proxies, url=args.url, logger=crawlog, without_tor=args.without
+        )
 
     if canon:
         crawlog.debug("URL fixed: %s", website)
@@ -319,7 +322,9 @@ def main():
 
         if args.visualize:
             obj = Visualization(
-                os.path.join(out_path, crawler.network_file), out_path, args.verbose
+                json_file=os.path.join(out_path, crawler.network_file),
+                out_path=out_path,
+                logger=crawlog,
             )
             obj.indegree_plot()
             obj.indegree_bar()

From 61a5cb7f560414abe63a3c76f62888eed7e08ea6 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 01:23:03 +0530
Subject: [PATCH 13/39] Fix: Crawler crawl error and response code synced

---
 modules/crawler.py | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/modules/crawler.py b/modules/crawler.py
index 5a157d8..8f27421 100644
--- a/modules/crawler.py
+++ b/modules/crawler.py
@@ -125,7 +125,9 @@ def canonical(self, base, href):
         # For relative paths
         return urljoin(base, href)
 
-    def __crawl_link(self, item, session) -> tuple[str, set[str], int]:
+    def __crawl_link(
+        self, item, session
+    ) -> tuple[str, set[str], Union[int, tuple[str, Exception]]]:
         # Store the crawled link of an item
         item_data = set()
         html_page = Response
@@ -135,15 +137,13 @@ def __crawl_link(self, item, session) -> tuple[str, set[str], int]:
             if item is not None:
                 html_page = session.get(item, allow_redirects=True, timeout=10)
                 response_code = html_page.status_code
-        except Exception as _:
-            self.logger.debug(f"Request Error :: {item}", exc_info=True)
-            return item, item_data, 0
+        except Exception as err:
+            return item, item_data, ("Request", err)
 
         try:
             soup = BeautifulSoup(html_page.text, features="html.parser")
-        except Exception as _:
-            self.logger.debug(f"Soup Parse Error :: {item}", exc_info=True)
-            return item, item_data, 0
+        except Exception as err:
+            return item, item_data, ("Soup Parse", err)
 
         # For each <a href=""> tag.
         for link in soup.findAll("a"):
@@ -219,7 +219,11 @@ def crawl(self):
 
             for future in as_completed(futures):
                 item, item_data, response_code = future.result()
-                self.logger.debug(f"{item} :: {response_code}")
+                if isinstance(response_code, int):
+                    self.logger.debug(f"{item} :: {response_code}")
+                else:
+                    error, exception = response_code
+                    self.logger.debug(f"{error} Error :: {item}", exc_info=exception)
 
                 # Add item_data to crawled links.
                 cur_level = cur_level.union(item_data)
@@ -237,9 +241,7 @@ def crawl(self):
             old_level = list(clean_cur_level)
             # Reset cur_level
             cur_level = set()
-            self.logger.info(
-                f"Step {index + 1} completed with: {len(ord_lst)} result(s)"
-            )
+            self.logger.info(f"Step {index + 1} completed :: {len(ord_lst)} result(s)")
 
             # Creating json
             with open(

From 4727fd352677590c012fff33893e3dbd89d83c0f Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 09:32:59 +0530
Subject: [PATCH 14/39] Refactor: Non-verbose screen log is much cleaner

---
 modules/helpers/helper.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index e67a637..d4b564e 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -64,6 +64,13 @@ def setup_custom_logger(name, verbose_, filelog, filename):
     screen_handler.setLevel(logging.DEBUG)
 
     if verbose_ is False:
+        screen_handler.setFormatter(
+            logging.Formatter(
+                fmt="## {message}",
+                style="{",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+        )
         screen_handler.setLevel(logging.INFO)
 
     logger.addHandler(screen_handler)

From 90944e54213484f8c4245d80d734deaf043d9e3b Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 09:34:10 +0530
Subject: [PATCH 15/39] Fix: Lazy logger message string evaluation

---
 modules/checker.py        |  6 +++--
 modules/crawler.py        |  8 ++++---
 modules/extractor.py      | 49 ++++++++++++++++++++++-----------------
 modules/helpers/helper.py |  2 +-
 torcrawl.py               |  4 ++--
 5 files changed, 40 insertions(+), 29 deletions(-)

diff --git a/modules/checker.py b/modules/checker.py
index 7a3d8d1..c96ffe2 100644
--- a/modules/checker.py
+++ b/modules/checker.py
@@ -89,9 +89,11 @@ def check_ip(proxies, url, logger, without_tor):
         ).json()
 
         logger.debug(
-            f"Your IP: {check2['IP']} :: Tor Connection: {check1['IsTor'] or check2['IsTor']}"
+            "Your IP: %s :: Tor Connection: %s",
+            check2["IP"],
+            check1["IsTor"] or check2["IsTor"],
         )
-        logger.debug(f"URL: {url}")
+        logger.debug("URL :: %s", url)
 
         if (
             check1["IsTor"] is False
diff --git a/modules/crawler.py b/modules/crawler.py
index 8f27421..d65bdcb 100644
--- a/modules/crawler.py
+++ b/modules/crawler.py
@@ -220,10 +220,10 @@ def crawl(self):
             for future in as_completed(futures):
                 item, item_data, response_code = future.result()
                 if isinstance(response_code, int):
-                    self.logger.debug(f"{item} :: {response_code}")
+                    self.logger.debug("%s :: %d", item, response_code)
                 else:
                     error, exception = response_code
-                    self.logger.debug(f"{error} Error :: {item}", exc_info=exception)
+                    self.logger.debug("%s Error :: %s", error, item, exc_info=exception)
 
                 # Add item_data to crawled links.
                 cur_level = cur_level.union(item_data)
@@ -241,7 +241,9 @@ def crawl(self):
             old_level = list(clean_cur_level)
             # Reset cur_level
             cur_level = set()
-            self.logger.info(f"Step {index + 1} completed :: {len(ord_lst)} result(s)")
+            self.logger.info(
+                "Step %d completed :: %d result(s)", index + 1, len(ord_lst)
+            )
 
             # Creating json
             with open(
diff --git a/modules/extractor.py b/modules/extractor.py
index 3850b61..11a4b85 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -121,11 +121,14 @@ def __inex(self, type_, input_file, yara, out_path=None):
         :param yara: Integer: Keyword search argument.
         :return: None
         """
+        self.logger.info(
+            "%s :: Extracting from %s to %s", type_, input_file, out_path or "terminal"
+        )
         file = TextIOWrapper
         try:
             file = open(input_file, "r", encoding="UTF-8")
         except IOError as _:
-            self.logger.exception(f"{type_} Read Error :: {input_file}")
+            self.logger.exception("Read Error :: %s", input_file)
             return
 
         for line in file.read().splitlines():
@@ -140,9 +143,7 @@ def __inex(self, type_, input_file, yara, out_path=None):
                     else:
                         output_file = cl_page_name
                 except Exception as _:
-                    self.logger.debug(
-                        f"{type_} Output File Error :: {line}", exc_info=True
-                    )
+                    self.logger.debug("Output File Error :: %s", line, exc_info=True)
                     continue
 
             # Extract page to file.
@@ -156,7 +157,9 @@ def __inex(self, type_, input_file, yara, out_path=None):
                 )
 
                 self.logger.debug(
-                    f"{type_} :: {line} :: {'Yara' if len(full_match_keywords) else 'No yara'} match found!"
+                    "%s :: %s match found!",
+                    line,
+                    "Yara" if len(full_match_keywords) else "No yara",
                 )
 
                 # if len(full_match_keywords) == 0:
@@ -171,23 +174,23 @@ def __inex(self, type_, input_file, yara, out_path=None):
                     ) as results:
                         results.write(content)
                     self.logger.debug(
-                        f"{type_} File created :: {os.path.join(out_path, output_file)}"
+                        "File created :: %s", os.path.join(out_path, output_file)
                     )
                 else:
-                    self.logger.info(f"{line} :: {content}")
+                    self.logger.info("%s :: %s", line, content)
             except HTTPError as _:
-                self.logger.debug(f"{type_} Request Error :: {line}", exc_info=True)
+                self.logger.debug("Request Error :: %s", line, exc_info=True)
                 continue
             except (InvalidURL, URLError) as _:
-                self.logger.debug(f"{type_} Invalid URL Error :: {line} :: Skipping...")
+                self.logger.debug("Invalid URL Error :: %s :: Skipping...", line)
                 continue
             except IncompleteRead as _:
-                self.logger.debug(f"{type_} Incomplete Read Error :: {line}")
+                self.logger.debug("Incomplete Read Error :: %s", line)
                 continue
             except IOError as _:
-                self.logger.debug(f"{type_} IOError Error :: {line}", exc_info=True)
+                self.logger.debug("IOError Error :: %s", line, exc_info=True)
             except Exception as _:
-                self.logger.debug(f"{type_} Error :: {line}", exc_info=True)
+                self.logger.debug("Error :: %s", line, exc_info=True)
         file.close()
 
     def __cinex(self, input_file, out_path, yara):
@@ -222,34 +225,38 @@ def __ex(self, type_, website, yara, output_file=None, out_path=None):
         :param out_path: String|None: Folder name of the output findings.
         :return: None
         """
-        # Extract page to file
         try:
             if out_path is not None:
                 output_file = os.path.join(out_path, output_file)
+            self.logger.info(
+                "%s :: Extracting %s to %s", type_, website, output_file or "terminal"
+            )
             content = self.__session.get(website, allow_redirects=True, timeout=10).text
 
             full_match_keywords = self.__check_yara(type_=type_, raw=content, yara=yara)
 
             self.logger.debug(
-                f"{type_} :: {website} :: {'Yara' if len(full_match_keywords) else 'No yara'} match found!"
+                "%s :: %s match found!",
+                website,
+                "Yara" if len(full_match_keywords) else "No yara",
             )
 
             if out_path is not None:
                 with open(output_file, "w+", encoding="UTF-8") as file:
                     file.write(content)
-                self.logger.debug(f"{type_} File created :: {output_file}")
+                self.logger.debug("File created :: %s", output_file)
             else:
-                self.logger.info(f"{website} :: {content}")
+                self.logger.info("%s :: %s", website, content)
         except HTTPError as _:
-            self.logger.debug(f"{type_} Request Error :: {website}", exc_info=True)
+            self.logger.debug("Request Error :: %s", website, exc_info=True)
         except (InvalidURL, URLError) as _:
-            self.logger.debug(f"{type_} Invalid URL Error :: {website} :: Skipping...")
+            self.logger.debug("Invalid URL Error :: %s :: Skipping...", website)
         except IncompleteRead as _:
-            self.logger.debug(f"{type_} Incomplete Read Error :: {website}")
+            self.logger.debug("Incomplete Read Error :: %s", website)
         except IOError as _:
-            self.logger.debug(f"{type_} IOError Error :: {website}", exc_info=True)
+            self.logger.debug("IOError Error :: %s", website, exc_info=True)
         except Exception as _:
-            self.logger.debug(f"{type_} Error :: {website}", exc_info=True)
+            self.logger.debug("Error :: %s", website, exc_info=True)
 
     def __outex(self, website, output_file, out_path, yara):
         """Scrapes the contents of the provided web address and outputs the
diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index d4b564e..06b21e1 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -32,7 +32,7 @@ def verbose(func):
     """Verbose decorator"""
 
     def wrapper(*args, **kwargs):
-        args[0].logger.info(f"Generating :: {func.__doc__}..")
+        args[0].logger.info("Generating :: %s..", func.__doc__)
         plt.cla()
         plt.figure(figsize=(12, 6))
         plt.grid()
diff --git a/torcrawl.py b/torcrawl.py
index 87cfa45..77925af 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -299,9 +299,9 @@ def main():
         )
 
     if canon:
-        crawlog.debug("URL fixed: %s", website)
+        crawlog.debug("URL fixed :: %s", website)
     if out_path:
-        crawlog.debug("Folder created: %s", out_path)
+        crawlog.debug("Folder created :: %s", out_path)
 
     if args.crawl and website:
         crawler = Crawler(

From 4c458ae6d0070e1d4c2bc53f405cd2e191a31b75 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 10:18:16 +0530
Subject: [PATCH 16/39] Fix: Exclude JS, CSS files from script/link tags

---
 modules/crawler.py | 26 ++------------------------
 1 file changed, 2 insertions(+), 24 deletions(-)

diff --git a/modules/crawler.py b/modules/crawler.py
index d65bdcb..ddde147 100644
--- a/modules/crawler.py
+++ b/modules/crawler.py
@@ -109,7 +109,7 @@ def excludes(self, link):
             self.__files["mails"].write(str(link) + "\n")
             return True
         # Type of files
-        if re.search("^.*\\.(pdf|jpg|jpeg|png|gif|doc)$", link, re.IGNORECASE):
+        if re.search("^.*\\.(pdf|jpg|jpeg|png|gif|doc|js|css)$", link, re.IGNORECASE):
             return True
 
     def canonical(self, base, href):
@@ -156,7 +156,7 @@ def __crawl_link(
             if ver_link is not None:
                 item_data.add(ver_link)
 
-        # For each <area> tag.
+        # For each <area href=""> tag.
         for link in soup.findAll("area"):
             link = link.get("href")
 
@@ -167,28 +167,6 @@ def __crawl_link(
             if ver_link is not None:
                 item_data.add(ver_link)
 
-        # For each <script> tag
-        for link in soup.findAll("script"):
-            link = link.get("src")
-
-            if self.excludes(link):
-                continue
-
-            ver_link = self.canonical(item, link)
-            if ver_link is not None:
-                item_data.add(ver_link)
-
-        # For each <link> tag
-        for link in soup.findAll("link"):
-            link = link.get("href")
-
-            if self.excludes(link):
-                continue
-
-            ver_link = self.canonical(item, link)
-            if ver_link is not None:
-                item_data.add(ver_link)
-
         return item, item_data, response_code
 
     def crawl(self):

From 025ff1760ef77757edcf39086537a95b587714af Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 12:25:57 +0530
Subject: [PATCH 17/39] Fix: Trailing / in urls with or without path

---
 modules/checker.py | 14 +++++++++++---
 modules/crawler.py |  9 +++++----
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/modules/checker.py b/modules/checker.py
index c96ffe2..f5d6a31 100644
--- a/modules/checker.py
+++ b/modules/checker.py
@@ -10,18 +10,26 @@
 from modules.helpers.helper import TorProxyException, get_requests_header
 
 
-def url_canon(website):
+def url_canon(website, www=False):
     """URL normalisation/canonicalization
 
     :param website: String - URL of website.
-    :return: String 'website' - normalised result.
+    :param www: Boolean - True if www is to be included else False.
+    :return: [Boolean, String] 'canon, website' - Bool indicating if normalised, normalised result.
     """
     canon = False
     if not website.startswith("http"):
-        if not website.startswith("www."):
+        if www and not website.startswith("www."):
             website = "www." + website
         website = "http://" + website
         canon = True
+
+    # Remove trailing slash if website is just a hostname
+    uri = urlparse(website)
+    if uri.path == "/":
+        website = website.rstrip("/")
+        canon = True
+
     return canon, website
 
 
diff --git a/modules/crawler.py b/modules/crawler.py
index ddde147..84dac4a 100644
--- a/modules/crawler.py
+++ b/modules/crawler.py
@@ -13,6 +13,7 @@
 from bs4 import BeautifulSoup
 from requests.models import Response
 
+from modules.checker import url_canon
 from modules.helpers.helper import get_requests_header
 
 
@@ -154,7 +155,7 @@ def __crawl_link(
 
             ver_link = self.canonical(item, link)
             if ver_link is not None:
-                item_data.add(ver_link)
+                item_data.add(url_canon(ver_link)[1])
 
         # For each <area href=""> tag.
         for link in soup.findAll("area"):
@@ -165,7 +166,7 @@ def __crawl_link(
 
             ver_link = self.canonical(item, link)
             if ver_link is not None:
-                item_data.add(ver_link)
+                item_data.add(url_canon(ver_link)[1])
 
         return item, item_data, response_code
 
@@ -192,7 +193,7 @@ def crawl(self):
             futures = [
                 self.__executor.submit(self.__crawl_link, item=item, session=session)
                 for item in old_level
-                if item.rstrip("/") not in json_data
+                if item not in json_data
             ]
 
             for future in as_completed(futures):
@@ -209,7 +210,7 @@ def crawl(self):
                 print(f"-- Results: {len(cur_level)}\r", end="", flush=True)
 
                 # Adding to json data
-                json_data[item.rstrip("/")] = list(item_data)
+                json_data[item] = list(item_data)
 
             # Get the next level withouth duplicates.
             clean_cur_level = cur_level.difference(ord_lst)

From 388236970927cc60665d8d6daf0238357fb6961e Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 17:20:47 +0530
Subject: [PATCH 18/39] Add: Custom RotatingFileHandler for infinite logging of
 10MB each

---
 modules/helpers/helper.py | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index 06b21e1..fded706 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -2,6 +2,7 @@
 import os
 import sys
 from io import StringIO
+from logging.handlers import RotatingFileHandler
 
 import matplotlib.pyplot as plt
 
@@ -37,9 +38,7 @@ def wrapper(*args, **kwargs):
         plt.figure(figsize=(12, 6))
         plt.grid()
         ret = func(*args, **kwargs)
-        plt.savefig(
-            os.path.join(args[0].out_path, f"{func.__name__}.png"), bbox_inches="tight"
-        )
+        plt.savefig(os.path.join(args[0].out_path, f"{func.__name__}.png"), bbox_inches="tight")
         return ret
 
     wrapper.__doc__ = func.__doc__
@@ -47,6 +46,24 @@ def wrapper(*args, **kwargs):
     return wrapper
 
 
+class RollingFileHandler(RotatingFileHandler):
+    def __init__(self, filename, mode="w", maxBytes=0, backupCount=0, encoding=None, delay=False):
+        self.last_backup_cnt = 0
+        super(RollingFileHandler, self).__init__(
+            filename=filename, mode=mode, maxBytes=maxBytes, backupCount=backupCount, encoding=encoding, delay=delay
+        )
+
+    def doRollover(self):
+        if self.stream:
+            self.stream.close()
+            self.stream = None
+        self.last_backup_cnt += 1
+        next_name = "{0}.{2}{1}".format(*os.path.splitext(self.baseFilename), self.last_backup_cnt)
+        self.rotate(self.baseFilename, next_name)
+        if not self.delay:
+            self.stream = self._open()
+
+
 def setup_custom_logger(name, verbose_, filelog, filename):
     """Setup custom logger with stream and file handlers"""
     formatter = logging.Formatter(
@@ -76,7 +93,7 @@ def setup_custom_logger(name, verbose_, filelog, filename):
     logger.addHandler(screen_handler)
 
     if filelog:
-        file_handler = logging.FileHandler(filename=filename, mode="w")
+        file_handler = RollingFileHandler(filename=filename, mode="w", maxBytes=10 * 1024 * 1024)
         file_handler.setFormatter(formatter)
         file_handler.setLevel(logging.DEBUG)
         logger.addHandler(file_handler)

From 0a76cc79f2810f2c2fe2759ea3b453a7ca415057 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 17:22:25 +0530
Subject: [PATCH 19/39] Add: checker.folder can create folder if file argument
 is passed

---
 modules/checker.py | 20 ++++++--------------
 1 file changed, 6 insertions(+), 14 deletions(-)

diff --git a/modules/checker.py b/modules/checker.py
index f5d6a31..9af747d 100644
--- a/modules/checker.py
+++ b/modules/checker.py
@@ -50,14 +50,14 @@ def extract_domain(url, remove_http=True):
 
 
 # Create output path
-def folder(out_path):
+def folder(out_path, is_file=False):
     """Creates an output path for the findings.
 
     :param out_path: String - Output path in which all extracted data is stored.
+    :param is_file: String - True if output path is a file else False.
     :return: String 'out_path' - Path of the output folder.
     """
-    if not os.path.exists(out_path):
-        os.makedirs(out_path)
+    os.makedirs(os.path.dirname(out_path) if is_file else out_path, exist_ok=True)
     return out_path
 
 
@@ -88,13 +88,9 @@ def check_ip(proxies, url, logger, without_tor):
     try:
         # https://tor.stackexchange.com/a/13079
         # Double check to tackle false positives
-        check1 = requests.get(
-            addr, headers=headers, proxies=proxies, timeout=10, verify=False
-        ).json()
+        check1 = requests.get(addr, headers=headers, proxies=proxies, timeout=10, verify=False).json()
 
-        check2 = requests.get(
-            addr, headers=headers, proxies=proxies, timeout=10, verify=False
-        ).json()
+        check2 = requests.get(addr, headers=headers, proxies=proxies, timeout=10, verify=False).json()
 
         logger.debug(
             "Your IP: %s :: Tor Connection: %s",
@@ -103,11 +99,7 @@ def check_ip(proxies, url, logger, without_tor):
         )
         logger.debug("URL :: %s", url)
 
-        if (
-            check1["IsTor"] is False
-            and check2["IsTor"] is False
-            and without_tor is False
-        ):
+        if check1["IsTor"] is False and check2["IsTor"] is False and without_tor is False:
             raise TorProxyException(
                 "Tor proxy is NOT running! More info: https://support.torproject.org/connecting/#connecting-4"
             )

From a60fdfe2c3b5159cad4cd40e4693cb81f11fc750 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 17:23:30 +0530
Subject: [PATCH 20/39] Add: Multithreading support in extractor

---
 modules/extractor.py      | 209 +++++++++++++++++---------------------
 modules/helpers/helper.py |   2 +
 torcrawl.py               |  20 ++--
 3 files changed, 104 insertions(+), 127 deletions(-)

diff --git a/modules/extractor.py b/modules/extractor.py
index 11a4b85..a728e6e 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -1,9 +1,15 @@
 #!/usr/bin/python
+import logging
 import os
+import re
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from http.client import IncompleteRead, InvalidURL
 from io import TextIOWrapper
 from logging import Logger
+from typing import Union
+from unittest import result
 from urllib.error import HTTPError, URLError
+from urllib.parse import urlparse
 
 import requests
 import yara as _yara
@@ -22,6 +28,7 @@ class Extractor:
     :param str output_file: Filename of resulting output from scrape.
     :param str input_file: Filename of crawled/discovered URLs
     :param str out_path: Dir path for output files.
+    :param int thread: Number pages to extract (Threads) at the same time.
     :param int yara: keyword search option.
     :param Logger logger: A logger object to log the output.
     """
@@ -38,6 +45,7 @@ def __init__(
         output_file: str,
         input_file: str,
         out_path: str,
+        thread: int,
         yara: int,
         logger: Logger,
     ):
@@ -51,6 +59,8 @@ def __init__(
         if self.crawl:
             self.out_path = folder(os.path.join(out_path, self.__extract_folder))
 
+        self.thread = thread
+        self.__executor = ThreadPoolExecutor(max_workers=min(32, self.thread))
         self.yara = yara
         self.logger = logger
         self.__session = self.__get_tor_session()
@@ -60,14 +70,19 @@ def extract(self):
         # TODO: Return output to torcrawl.py
         if len(self.input_file) > 0:
             if self.crawl or self.out_path:
-                self.__cinex(self.input_file, self.out_path, self.yara)
+                self.__cinex(self.input_file, self.yara, self.out_path)
             else:
-                self.__intermex(self.input_file, self.yara)
+                self.__terminex(self.input_file, self.yara)
         else:
+            results = []
             if len(self.output_file) > 0:
-                self.__outex(self.website, self.output_file, self.out_path, self.yara)
+                self.output_file = os.path.join(self.out_path, self.output_file)
+                results = self.__outex(self.website, self.yara, self.output_file)
             else:
-                self.__termex(self.website, self.yara)
+                results = self.__termex(self.website, self.yara)
+
+            for level, args, exception in results:
+                self.logger.log(level, *args, exc_info=exception)
 
     def __get_tor_session(self):
         session = requests.Session()
@@ -89,10 +104,9 @@ def __text(self, response=None):
 
         return " ".join(soup.stripped_strings)
 
-    def __check_yara(self, type_, raw=None, yara=0):
+    def __check_yara(self, raw=None, yara=0):
         """Validates Yara Rule to categorize the site and check for keywords.
 
-        :param type_: String: "Cinex" or "Intermex" or "Outex" or "Termex".
         :param yara:  Integer: Keyword search argument.
         :param raw:   HTTP Response body.
         :return matches: List of yara rule matches.
@@ -105,25 +119,39 @@ def __check_yara(self, type_, raw=None, yara=0):
 
         matches = self.__yara_rules.match(data=raw)
 
-        # if len(matches) != 0:
-        #     self.logger.debug(f"{type_} :: Yara match found!")
-
         return matches
 
-    def __inex(self, type_, input_file, yara, out_path=None):
+    def __generate_file_extract(self, url, yara, out_path) -> list[tuple[int, tuple[str], Union[Exception, bool]]]:
+        output_file = None
+        if out_path is not None:
+            try:
+                uri = urlparse(url)
+                output_file = os.path.join(
+                    out_path,
+                    os.path.join(uri.netloc, *uri.path.split("/")) + re.sub(r"[^\w_.)( -]", "", uri.query) + "_.html",
+                )
+                folder(output_file, is_file=True)
+            except Exception as err:
+                return [
+                    (
+                        logging.DEBUG,
+                        ("Output File Error :: %s", url),
+                        err,
+                    )
+                ]
+
+        return self.__ex(website=url, yara=yara, output_file=output_file)
+
+    def __inex(self, input_file, yara, out_path=None):
         """Ingests the crawled links from the input_file,
         scrapes the contents of the resulting web pages and writes the contents
         into the terminal if out_path is None else out_path/{url_address}.
 
-        :param type_: String: Either "Cinex" or "Intermex".
         :param input_file: String: Filename of the crawled Urls.
         :param out_path: String|None : Pathname of results.
         :param yara: Integer: Keyword search argument.
         :return: None
         """
-        self.logger.info(
-            "%s :: Extracting from %s to %s", type_, input_file, out_path or "terminal"
-        )
         file = TextIOWrapper
         try:
             file = open(input_file, "r", encoding="UTF-8")
@@ -131,90 +159,41 @@ def __inex(self, type_, input_file, yara, out_path=None):
             self.logger.exception("Read Error :: %s", input_file)
             return
 
-        for line in file.read().splitlines():
-
-            # Generate the name for every file.
-            if out_path is not None:
-                try:
-                    page_name = line.rsplit("/", 1)
-                    cl_page_name = str(page_name[1])
-                    if len(cl_page_name) == 0:
-                        output_file = "index.html"
-                    else:
-                        output_file = cl_page_name
-                except Exception as _:
-                    self.logger.debug("Output File Error :: %s", line, exc_info=True)
-                    continue
-
-            # Extract page to file.
-            try:
-                content = self.__session.get(
-                    line, allow_redirects=True, timeout=10
-                ).text
+        futures = [
+            self.__executor.submit(self.__generate_file_extract, url=url, yara=yara, out_path=out_path)
+            for url in file.read().splitlines()
+        ]
 
-                full_match_keywords = self.__check_yara(
-                    type_=type_, raw=content, yara=yara
-                )
-
-                self.logger.debug(
-                    "%s :: %s match found!",
-                    line,
-                    "Yara" if len(full_match_keywords) else "No yara",
-                )
+        for future in as_completed(futures):
+            for level, args, exception in future.result():
+                self.logger.log(level, *args, exc_info=exception)
 
-                # if len(full_match_keywords) == 0:
-                #     self.logger.debug(f"{type_} :: No yara matches found.")
-                #     Don't write to file if no matches found.
-                #     if out_path is not None:
-                #         continue
-
-                if out_path is not None:
-                    with open(
-                        os.path.join(out_path, output_file), "w+", encoding="UTF-8"
-                    ) as results:
-                        results.write(content)
-                    self.logger.debug(
-                        "File created :: %s", os.path.join(out_path, output_file)
-                    )
-                else:
-                    self.logger.info("%s :: %s", line, content)
-            except HTTPError as _:
-                self.logger.debug("Request Error :: %s", line, exc_info=True)
-                continue
-            except (InvalidURL, URLError) as _:
-                self.logger.debug("Invalid URL Error :: %s :: Skipping...", line)
-                continue
-            except IncompleteRead as _:
-                self.logger.debug("Incomplete Read Error :: %s", line)
-                continue
-            except IOError as _:
-                self.logger.debug("IOError Error :: %s", line, exc_info=True)
-            except Exception as _:
-                self.logger.debug("Error :: %s", line, exc_info=True)
         file.close()
 
-    def __cinex(self, input_file, out_path, yara):
+    def __cinex(self, input_file, yara, out_path):
         """Ingests the crawled links from the input_file,
         scrapes the contents of the resulting web pages and writes the contents to
         the into out_path/{url_address}.
 
         :param input_file: String: Filename of the crawled Urls.
-        :param out_path: String: Pathname of results.
         :param yara: Integer: Keyword search argument.
+        :param out_path: String: Pathname of results.
         :return: None
         """
-        self.__inex(type_="Cinex", input_file=input_file, yara=yara, out_path=out_path)
+        self.logger.info("Cinex :: Extracting from %s to %s", input_file, out_path)
+        self.__inex(input_file=input_file, yara=yara, out_path=out_path)
 
-    def __intermex(self, input_file, yara):
+    def __terminex(self, input_file, yara):
         """Input links from file and extract them into terminal.
 
         :param input_file: String: File name of links file.
         :param yara: Integer: Keyword search argument.
         :return: None
         """
-        self.__inex(type_="Intermex", input_file=input_file, yara=yara)
+        self.logger.info("Terminex :: Extracting from %s to terminal", input_file)
+        self.__inex(input_file=input_file, yara=yara)
 
-    def __ex(self, type_, website, yara, output_file=None, out_path=None):
+    def __ex(self, website, yara, output_file=None) -> list[tuple[int, tuple[str], Union[Exception, bool]]]:
         """Scrapes the contents of the provided web address and outputs the
         contents to file or terminal.
 
@@ -222,59 +201,60 @@ def __ex(self, type_, website, yara, output_file=None, out_path=None):
         :param website: String: Url of web address to scrape.
         :param yara: Integer: Keyword search argument.
         :param output_file: String|None: Filename of the results.
-        :param out_path: String|None: Folder name of the output findings.
         :return: None
         """
+        result = []
         try:
-            if out_path is not None:
-                output_file = os.path.join(out_path, output_file)
-            self.logger.info(
-                "%s :: Extracting %s to %s", type_, website, output_file or "terminal"
-            )
             content = self.__session.get(website, allow_redirects=True, timeout=10).text
 
-            full_match_keywords = self.__check_yara(type_=type_, raw=content, yara=yara)
-
-            self.logger.debug(
-                "%s :: %s match found!",
-                website,
-                "Yara" if len(full_match_keywords) else "No yara",
+            full_match_keywords = self.__check_yara(raw=content, yara=yara)
+
+            result.append(
+                (
+                    logging.DEBUG,
+                    (
+                        "%s :: %s match found!",
+                        website,
+                        "Yara" if len(full_match_keywords) else "No yara",
+                    ),
+                    False,
+                )
             )
 
-            if out_path is not None:
-                with open(output_file, "w+", encoding="UTF-8") as file:
+            # if len(full_match_keywords) == 0:
+            #     # Don't write to file if no matches found.
+            #     if output_file is not None:
+            #         return result
+
+            if output_file is not None:
+                with open(output_file, "w", encoding="UTF-8") as file:
                     file.write(content)
-                self.logger.debug("File created :: %s", output_file)
+                result.append((logging.DEBUG, ("File created :: %s", output_file), False))
             else:
-                self.logger.info("%s :: %s", website, content)
-        except HTTPError as _:
-            self.logger.debug("Request Error :: %s", website, exc_info=True)
+                result.append((logging.INFO, ("%s :: %s", website, content), False))
+        except HTTPError as err:
+            result.append((logging.DEBUG, ("Request Error :: %s", website), err))
         except (InvalidURL, URLError) as _:
-            self.logger.debug("Invalid URL Error :: %s :: Skipping...", website)
+            result.append((logging.DEBUG, ("Invalid URL Error :: %s :: Skipping...", website), False))
         except IncompleteRead as _:
-            self.logger.debug("Incomplete Read Error :: %s", website)
-        except IOError as _:
-            self.logger.debug("IOError Error :: %s", website, exc_info=True)
-        except Exception as _:
-            self.logger.debug("Error :: %s", website, exc_info=True)
-
-    def __outex(self, website, output_file, out_path, yara):
+            result.append((logging.DEBUG, ("Incomplete Read Error :: %s", website), False))
+        except IOError as err:
+            result.append((logging.DEBUG, ("IOError Error :: %s", website), err))
+        except Exception as err:
+            result.append((logging.DEBUG, ("Error :: %s", website), err))
+        return result
+
+    def __outex(self, website, yara, output_file):
         """Scrapes the contents of the provided web address and outputs the
         contents to file.
 
         :param website: String: Url of web address to scrape.
-        :param output_file: String: Filename of the results.
-        :param out_path: String: Folder name of the output findings.
         :param yara: Integer: Keyword search argument.
+        :param output_file: String: Filename of the results.
         :return: None
         """
-        self.__ex(
-            type_="Outex",
-            website=website,
-            yara=yara,
-            output_file=output_file,
-            out_path=out_path,
-        )
+        self.logger.info("Outex :: Extracting %s to %s", website, output_file)
+        return self.__ex(website=website, yara=yara, output_file=output_file)
 
     def __termex(self, website, yara):
         """Scrapes provided web address and prints the results to the terminal.
@@ -283,4 +263,5 @@ def __termex(self, website, yara):
         :param yara: Integer: Keyword search argument.
         :return: None
         """
-        self.__ex(type_="Termex", website=website, yara=yara)
+        self.logger.info("Termex :: Extracting %s to terminal", website)
+        return self.__ex(website=website, yara=yara)
diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index fded706..f188190 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -47,6 +47,8 @@ def wrapper(*args, **kwargs):
 
 
 class RollingFileHandler(RotatingFileHandler):
+    """Custom RotatingFileHandler for incremental infinite logging"""
+
     def __init__(self, filename, mode="w", maxBytes=0, backupCount=0, encoding=None, delay=False):
         self.last_backup_cnt = 0
         super(RollingFileHandler, self).__init__(
diff --git a/torcrawl.py b/torcrawl.py
index 77925af..b8f40bb 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -112,8 +112,7 @@ def main():
 
     # Get arguments with GooeyParser if available else argparse.
     description = (
-        "DarkSpider.py is a python script to crawl and extract "
-        + "(regular or onion) webpages through TOR network."
+        "DarkSpider.py is a python script to crawl and extract " + "(regular or onion) webpages through TOR network."
     )
     if GOOEY_AVAILABLE:
         parser = GooeyParser(description=description)
@@ -147,9 +146,7 @@ def main():
         action="store_true",
         help="Visualize the graphs and insights from the crawled data",
     )
-    parser.add_argument(
-        "-u", "--url", type=str, help="URL of webpage to crawl or extract"
-    )
+    parser.add_argument("-u", "--url", type=str, help="URL of webpage to crawl or extract")
     parser.add_argument(
         "-n",
         "--port",
@@ -157,9 +154,7 @@ def main():
         default=9050,
         help="Port number of TOR Proxy (default: 9050)",
     )
-    parser.add_argument(
-        "-w", "--without", action="store_true", help="Without the use of Relay TOR"
-    )
+    parser.add_argument("-w", "--without", action="store_true", help="Without the use of Relay TOR")
 
     # Extract
     parser.add_argument(
@@ -220,8 +215,7 @@ def main():
         "-l",
         "--log",
         action="store_true",
-        help="A save log will let you see which URLs were visited and their "
-        "response code",
+        help="A save log will let you see which URLs were visited and their " "response code",
     )
     parser.add_argument(
         "-f",
@@ -294,9 +288,7 @@ def main():
         proxies = get_tor_proxies(port=args.port)
 
     if args.verbose:
-        check_ip(
-            proxies=proxies, url=args.url, logger=crawlog, without_tor=args.without
-        )
+        check_ip(proxies=proxies, url=args.url, logger=crawlog, without_tor=args.without)
 
     if canon:
         crawlog.debug("URL fixed :: %s", website)
@@ -343,6 +335,7 @@ def main():
                 output_file=args.output,
                 input_file=input_file,
                 out_path=out_path,
+                thread=args.thread,
                 yara=args.yara,
                 logger=crawlog,
             )
@@ -355,6 +348,7 @@ def main():
             output_file=args.output,
             input_file=args.input or "",
             out_path=out_path,
+            thread=args.thread,
             yara=args.yara,
             logger=crawlog,
         )

From 055498db0dae5c1212ce9b165dbf3e7c641a64e8 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 17:53:46 +0530
Subject: [PATCH 21/39] Update: Logging enabled by default

---
 torcrawl.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/torcrawl.py b/torcrawl.py
index b8f40bb..a0f6c4e 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -214,7 +214,8 @@ def main():
     parser.add_argument(
         "-l",
         "--log",
-        action="store_true",
+        action="store_false",
+        default=True,
         help="A save log will let you see which URLs were visited and their " "response code",
     )
     parser.add_argument(

From a3035230f7d36e424c6a68914c6e583842c3106e Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 19:42:35 +0530
Subject: [PATCH 22/39] Fix: Yara support, skip file if empty search result

---
 modules/extractor.py | 233 +++++++++++++++++++++++--------------------
 torcrawl.py          |   9 +-
 2 files changed, 130 insertions(+), 112 deletions(-)

diff --git a/modules/extractor.py b/modules/extractor.py
index a728e6e..f0892a8 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -1,4 +1,3 @@
-#!/usr/bin/python
 import logging
 import os
 import re
@@ -7,17 +6,25 @@
 from io import TextIOWrapper
 from logging import Logger
 from typing import Union
-from unittest import result
 from urllib.error import HTTPError, URLError
 from urllib.parse import urlparse
 
 import requests
 import yara as _yara
 from bs4 import BeautifulSoup
+from requests import Session
 
 from modules.checker import folder
 from modules.helpers.helper import get_requests_header
 
+# Type hinting aliases
+ExcInfo = Union[Exception, bool]
+LogMsg = tuple[str]
+LogLevel = int
+Log = tuple[LogLevel, LogMsg, ExcInfo]
+Single_res = list[Log]
+Results = list[Single_res]
+
 
 class Extractor:
     """Extractor - scrapes the resulting website or discovered links.
@@ -29,7 +36,7 @@ class Extractor:
     :param str input_file: Filename of crawled/discovered URLs
     :param str out_path: Dir path for output files.
     :param int thread: Number pages to extract (Threads) at the same time.
-    :param int yara: keyword search option.
+    :param int|None yara: keyword search option.
     :param Logger logger: A logger object to log the output.
     """
 
@@ -46,7 +53,7 @@ def __init__(
         input_file: str,
         out_path: str,
         thread: int,
-        yara: int,
+        yara: Union[int, None],
         logger: Logger,
     ):
         self.website = website
@@ -67,82 +74,78 @@ def __init__(
 
     def extract(self):
         """Extracts the contents of the input file/single URL into the outputs folder/file/terminal."""
-        # TODO: Return output to torcrawl.py
+        results: Results = []
         if len(self.input_file) > 0:
             if self.crawl or self.out_path:
-                self.__cinex(self.input_file, self.yara, self.out_path)
+                results = self.__cinex(self.input_file, self.yara, self.out_path)
             else:
-                self.__terminex(self.input_file, self.yara)
+                results = self.__terminex(self.input_file, self.yara)
         else:
-            results = []
             if len(self.output_file) > 0:
                 self.output_file = os.path.join(self.out_path, self.output_file)
-                results = self.__outex(self.website, self.yara, self.output_file)
+                single_res = self.__outex(self.website, self.yara, self.output_file)
             else:
-                results = self.__termex(self.website, self.yara)
+                single_res = self.__termex(self.website, self.yara)
 
-            for level, args, exception in results:
+            for level, args, exception in single_res:
                 self.logger.log(level, *args, exc_info=exception)
 
-    def __get_tor_session(self):
+            results.append(single_res)
+        return results
+
+    def __get_tor_session(self) -> Session:
         session = requests.Session()
         session.proxies = self.proxies
         session.headers.update(self.__headers)
         session.verify = False
         return session
 
-    def __text(self, response=None):
-        """Removes all the garbage from the HTML and takes only text elements
-        from the page.
+    def __cinex(self, input_file: str, yara: Union[int, None], out_path: str) -> Results:
+        """Ingests the crawled links from the input_file,
+        scrapes the contents of the resulting web pages and writes the contents to
+        the into out_path/{url_address}.
 
-        :param response: HTTP Response.
-        :return: String: Text only stripped response.
+        :param input_file: String: Filename of the crawled Urls.
+        :param yara: Integer: Keyword search argument.
+        :param out_path: String: Pathname of results.
+        :return: None
         """
-        soup = BeautifulSoup(response, features="lxml")
-        for s in soup(["script", "style"]):
-            s.decompose()
-
-        return " ".join(soup.stripped_strings)
+        self.logger.info("Cinex :: Extracting from %s to %s", input_file, out_path)
+        return self.__inex(input_file=input_file, yara=yara, out_path=out_path)
 
-    def __check_yara(self, raw=None, yara=0):
-        """Validates Yara Rule to categorize the site and check for keywords.
+    def __terminex(self, input_file: str, yara: Union[int, None]) -> Results:
+        """Input links from file and extract them into terminal.
 
-        :param yara:  Integer: Keyword search argument.
-        :param raw:   HTTP Response body.
-        :return matches: List of yara rule matches.
+        :param input_file: String: File name of links file.
+        :param yara: Integer: Keyword search argument.
+        :return: None
         """
-        if raw is None:
-            return None
-
-        if yara == 1:
-            raw = self.__text(response=raw).lower()
+        self.logger.info("Terminex :: Extracting from %s to terminal", input_file)
+        return self.__inex(input_file=input_file, yara=yara)
 
-        matches = self.__yara_rules.match(data=raw)
+    def __outex(self, website: str, yara: Union[int, None], output_file: str) -> Single_res:
+        """Scrapes the contents of the provided web address and outputs the
+        contents to file.
 
-        return matches
+        :param website: String: Url of web address to scrape.
+        :param yara: Integer: Keyword search argument.
+        :param output_file: String: Filename of the results.
+        :return: None
+        """
+        self.logger.info("Outex :: Extracting %s to %s", website, output_file)
+        return self.__ex(website=website, yara=yara, output_file=output_file)
 
-    def __generate_file_extract(self, url, yara, out_path) -> list[tuple[int, tuple[str], Union[Exception, bool]]]:
-        output_file = None
-        if out_path is not None:
-            try:
-                uri = urlparse(url)
-                output_file = os.path.join(
-                    out_path,
-                    os.path.join(uri.netloc, *uri.path.split("/")) + re.sub(r"[^\w_.)( -]", "", uri.query) + "_.html",
-                )
-                folder(output_file, is_file=True)
-            except Exception as err:
-                return [
-                    (
-                        logging.DEBUG,
-                        ("Output File Error :: %s", url),
-                        err,
-                    )
-                ]
+    def __termex(self, website: str, yara: Union[int, None]) -> Single_res:
+        """Scrapes provided web address and prints the results to the terminal.
 
-        return self.__ex(website=url, yara=yara, output_file=output_file)
+        :param website: String: URL of website to scrape.
+        :param yara: Integer: Keyword search argument.
+        :return: None
+        """
+        self.logger.info("Termex :: Extracting %s to terminal", website)
+        return self.__ex(website=website, yara=yara)
 
-    def __inex(self, input_file, yara, out_path=None):
+    def __inex(self, input_file: str, yara: Union[int, None], out_path: str = None) -> Results:
         """Ingests the crawled links from the input_file,
         scrapes the contents of the resulting web pages and writes the contents
         into the terminal if out_path is None else out_path/{url_address}.
@@ -160,40 +163,45 @@ def __inex(self, input_file, yara, out_path=None):
             return
 
         futures = [
-            self.__executor.submit(self.__generate_file_extract, url=url, yara=yara, out_path=out_path)
+            self.__executor.submit(self.__generate_file, url=url, yara=yara, out_path=out_path)
             for url in file.read().splitlines()
         ]
 
+        results: Results = []
+
         for future in as_completed(futures):
-            for level, args, exception in future.result():
+            single_res = future.result()
+            results.append(single_res)
+
+            for level, args, exception in single_res:
                 self.logger.log(level, *args, exc_info=exception)
 
         file.close()
 
-    def __cinex(self, input_file, yara, out_path):
-        """Ingests the crawled links from the input_file,
-        scrapes the contents of the resulting web pages and writes the contents to
-        the into out_path/{url_address}.
+        return results
 
-        :param input_file: String: Filename of the crawled Urls.
-        :param yara: Integer: Keyword search argument.
-        :param out_path: String: Pathname of results.
-        :return: None
-        """
-        self.logger.info("Cinex :: Extracting from %s to %s", input_file, out_path)
-        self.__inex(input_file=input_file, yara=yara, out_path=out_path)
-
-    def __terminex(self, input_file, yara):
-        """Input links from file and extract them into terminal.
+    def __generate_file(self, url: str, yara: Union[int, None], out_path: Union[str, None]) -> Single_res:
+        output_file = None
+        if out_path is not None:
+            try:
+                uri = urlparse(url)
+                output_file = os.path.join(
+                    out_path,
+                    os.path.join(uri.netloc, *uri.path.split("/")) + re.sub(r"[^\w_.)( -]", "", uri.query) + "_.html",
+                )
+                folder(output_file, is_file=True)
+            except Exception as err:
+                return [
+                    (
+                        logging.DEBUG,
+                        ("Output File Error :: %s", url),
+                        err,
+                    )
+                ]
 
-        :param input_file: String: File name of links file.
-        :param yara: Integer: Keyword search argument.
-        :return: None
-        """
-        self.logger.info("Terminex :: Extracting from %s to terminal", input_file)
-        self.__inex(input_file=input_file, yara=yara)
+        return self.__ex(website=url, yara=yara, output_file=output_file)
 
-    def __ex(self, website, yara, output_file=None) -> list[tuple[int, tuple[str], Union[Exception, bool]]]:
+    def __ex(self, website: str, yara: Union[int, None], output_file: str = None) -> Single_res:
         """Scrapes the contents of the provided web address and outputs the
         contents to file or terminal.
 
@@ -206,25 +214,25 @@ def __ex(self, website, yara, output_file=None) -> list[tuple[int, tuple[str], U
         result = []
         try:
             content = self.__session.get(website, allow_redirects=True, timeout=10).text
+            if yara:
+                full_match_keywords = self.__check_yara(raw=content, yara=yara)
 
-            full_match_keywords = self.__check_yara(raw=content, yara=yara)
-
-            result.append(
-                (
-                    logging.DEBUG,
+                result.append(
                     (
-                        "%s :: %s match found!",
-                        website,
-                        "Yara" if len(full_match_keywords) else "No yara",
-                    ),
-                    False,
+                        logging.DEBUG,
+                        (
+                            "%s :: %s match found!",
+                            website,
+                            "Yara" if len(full_match_keywords) else "No yara",
+                        ),
+                        False,
+                    )
                 )
-            )
 
-            # if len(full_match_keywords) == 0:
-            #     # Don't write to file if no matches found.
-            #     if output_file is not None:
-            #         return result
+                if len(full_match_keywords) == 0:
+                    # Don't write to file/terminal if no matches found.
+                    if output_file is not None:
+                        return result
 
             if output_file is not None:
                 with open(output_file, "w", encoding="UTF-8") as file:
@@ -242,26 +250,35 @@ def __ex(self, website, yara, output_file=None) -> list[tuple[int, tuple[str], U
             result.append((logging.DEBUG, ("IOError Error :: %s", website), err))
         except Exception as err:
             result.append((logging.DEBUG, ("Error :: %s", website), err))
+
         return result
 
-    def __outex(self, website, yara, output_file):
-        """Scrapes the contents of the provided web address and outputs the
-        contents to file.
+    def __check_yara(self, raw: str = None, yara: int = 0) -> dict:
+        """Validates Yara Rule to categorize the site and check for keywords.
 
-        :param website: String: Url of web address to scrape.
-        :param yara: Integer: Keyword search argument.
-        :param output_file: String: Filename of the results.
-        :return: None
+        :param yara:  Integer: Keyword search argument.
+        :param raw:   HTTP Response body.
+        :return matches: List of yara rule matches.
         """
-        self.logger.info("Outex :: Extracting %s to %s", website, output_file)
-        return self.__ex(website=website, yara=yara, output_file=output_file)
+        if raw is None:
+            return None
 
-    def __termex(self, website, yara):
-        """Scrapes provided web address and prints the results to the terminal.
+        if yara == 1:
+            raw = self.__text(response=raw).lower()
 
-        :param website: String: URL of website to scrape.
-        :param yara: Integer: Keyword search argument.
-        :return: None
+        matches = self.__yara_rules.match(data=raw)
+
+        return matches
+
+    def __text(self, response: str = None) -> str:
+        """Removes all the garbage from the HTML and takes only text elements
+        from the page.
+
+        :param response: HTTP Response.
+        :return: String: Text only stripped response.
         """
-        self.logger.info("Termex :: Extracting %s to terminal", website)
-        return self.__ex(website=website, yara=yara)
+        soup = BeautifulSoup(response, features="lxml")
+        for s in soup(["script", "style"]):
+            s.decompose()
+
+        return " ".join(soup.stripped_strings)
diff --git a/torcrawl.py b/torcrawl.py
index a0f6c4e..8a1d52e 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -1,4 +1,5 @@
-#!/usr/bin/python
+#!/usr/bin/env python3
+
 """
 DarkSpider is a python script to crawl and extract (regular or onion)
 webpages through TOR network.
@@ -235,9 +236,9 @@ def main():
         "-y",
         "--yara",
         type=int,
-        default=0,
+        default=None,
         help="Check for keywords and only scrape documents that contain a "
-        "match. 0 search whole html object. 1 search only the text. (Default: 0)",
+        "match. 0 search whole html object. 1 search only the text. (Default: None)",
     )
 
     if len(sys.argv) == 1:
@@ -252,7 +253,7 @@ def main():
     if args.port < 1 or 65535 < args.port:
         parser.error("argument -n/--port: expected argument in between 1 to 65535.")
 
-    if args.yara not in [0, 1]:
+    if args.yara and args.yara not in [0, 1]:
         parser.error("argument -y/--yara: expected argument 0 or 1.")
 
     if args.cdepth < 1:

From 5397e1613d5ba9ef4c96e327e8d8da16f089f200 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 23:57:13 +0530
Subject: [PATCH 23/39] Refactor: Modules documentation improved

---
 modules/checker.py        |  73 +++++++++-----
 modules/crawler.py        | 161 ++++++++++++++++++-------------
 modules/extractor.py      | 198 +++++++++++++++++++++++++++-----------
 modules/helpers/helper.py |  55 +++++++++--
 torcrawl.py               |  13 ++-
 5 files changed, 337 insertions(+), 163 deletions(-)

diff --git a/modules/checker.py b/modules/checker.py
index 9af747d..5570039 100644
--- a/modules/checker.py
+++ b/modules/checker.py
@@ -1,7 +1,7 @@
-#!/usr/bin/python
-
 import os
 import sys
+from logging import Logger
+from typing import Optional
 from urllib.parse import urlparse
 
 import psutil
@@ -10,12 +10,15 @@
 from modules.helpers.helper import TorProxyException, get_requests_header
 
 
-def url_canon(website, www=False):
+def url_canon(website: str, www: bool = False) -> tuple[bool, str]:
     """URL normalisation/canonicalization
 
-    :param website: String - URL of website.
-    :param www: Boolean - True if www is to be included else False.
-    :return: [Boolean, String] 'canon, website' - Bool indicating if normalised, normalised result.
+    Args:
+        website: URL of website.
+        www: True if www is to be included else False.
+
+    Returns:
+        A tuple of a boolean indicating whether ``website`` is normalised, normalised ``website``.
     """
     canon = False
     if not website.startswith("http"):
@@ -33,13 +36,16 @@ def url_canon(website, www=False):
     return canon, website
 
 
-def extract_domain(url, remove_http=True):
+def extract_domain(url: str, remove_http: bool = True) -> str:
     """Parses the provided 'url' to provide only the netloc or
     scheme + netloc parts of the provided url.
 
-    :param url: String - Url to parse.
-    :param remove_http: Boolean
-    :return: String 'domain_name' - Resulting parsed Url
+    Args:
+        url: Url to parse.
+        remove_http: True if http/https is to be removed else False.
+
+    Returns:
+        Resulting parsed Url.
     """
     uri = urlparse(url)
     if remove_http:
@@ -49,25 +55,30 @@ def extract_domain(url, remove_http=True):
     return domain_name
 
 
-# Create output path
-def folder(out_path, is_file=False):
+def folder(out_path: str, is_file: bool = False) -> str:
     """Creates an output path for the findings.
 
-    :param out_path: String - Output path in which all extracted data is stored.
-    :param is_file: String - True if output path is a file else False.
-    :return: String 'out_path' - Path of the output folder.
+    Args:
+        out_path: Output path in which all extracted data is stored.
+        is_file: True if output path is a file else False.
+
+    Returns:
+        Path of the output folder.
     """
     os.makedirs(os.path.dirname(out_path) if is_file else out_path, exist_ok=True)
     return out_path
 
 
-def check_tor(logger):
+def check_tor(logger: Logger) -> Optional[bool]:
     """Checks to see if TOR service is running on device.
     Will exit if (-w) with argument is provided on application startup and TOR
     service is not found to be running on the device.
 
-    :param Logger logger: A logger object to log the output.
-    :return: None
+    Args:
+        Logger: A logger object to log the output.
+
+    Returns:
+        True if TOR service is running.
     """
     for i in psutil.process_iter():
         if "tor" == i.name().lower().rstrip(".exe"):
@@ -78,10 +89,25 @@ def check_tor(logger):
         logger.critical("Enable tor with 'service tor start' or add -w argument")
         sys.exit(2)
 
+    return True
 
-def check_ip(proxies, url, logger, without_tor):
-    """Checks users IP from external resource.
-    :return: None
+
+def check_ip(
+    proxies: Optional[dict[str, str]], url: str, logger: Logger, without_tor: bool = False
+) -> Optional[dict[str, str | bool]]:
+    """Checks users IP and Tor proxy connection from external resource.
+
+    Args:
+        proxies: Dictionary mapping protocol or protocol and host to the URL of the proxy.
+        url: Url to debug.
+        logger: A logger object to log the output.
+        without_tor: True if not using Tor for crawling/extraction else False.
+
+    Returns:
+        Dictionary containing the IP address and the Tor proxy flag.
+
+        {"IsTor":True,
+        "IP":"185.165.171.46"}
     """
     addr = "https://check.torproject.org/api/ip"
     headers = get_requests_header()
@@ -99,10 +125,13 @@ def check_ip(proxies, url, logger, without_tor):
         )
         logger.debug("URL :: %s", url)
 
-        if check1["IsTor"] is False and check2["IsTor"] is False and without_tor is False:
+        # If both checks are false, then Tor proxy is not working
+        if not (check1["IsTor"] or check2["IsTor"] or without_tor):
             raise TorProxyException(
                 "Tor proxy is NOT running! More info: https://support.torproject.org/connecting/#connecting-4"
             )
+
+        return check2
     except Exception as err:
         logger.exception(err)
         sys.exit(2)
diff --git a/modules/crawler.py b/modules/crawler.py
index 84dac4a..fa8e3fb 100644
--- a/modules/crawler.py
+++ b/modules/crawler.py
@@ -1,4 +1,3 @@
-#!/usr/bin/python
 import json
 import os
 import re
@@ -6,7 +5,7 @@
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from io import TextIOBase
 from logging import Logger
-from typing import Union
+from typing import Optional
 from urllib.parse import urljoin
 
 import requests
@@ -20,18 +19,16 @@
 class Crawler:
     """Crawl input link upto depth (c_depth) with a pause of c_pause seconds using multiple threads.
 
-    :param str website: Website to crawl.
-    :param dict[str, str] proxies: Dictionary mapping protocol or protocol and host to the URL of the proxy.
-    :param dict[str, any] c_params: Dictionary mapping
-                                    {
-                                        int c_depth: Depth of the crawl,
-                                        float c_pause: Pause after every iteration
-                                    }
-    :param str out_path: Output path to store extracted links.
-    :param bool external: True if external links are to be crawled else False.
-    :param re str exclusion: Paths that you don't want to include.
-    :param int thread: Number pages to visit (Threads) at the same time.
-    :param Logger logger: A logger object to log the output.
+    Attributes:
+        website: Website to crawl.
+        proxies: Dictionary mapping protocol or protocol and host to the URL of the proxy.
+        c_depth: Depth of the crawl.
+        c_pause: Pause after every depth iteration.
+        out_path: Output path to store extracted links.
+        external: True if external links are to be crawled else False.
+        exclusion: Paths that you don't want to include.
+        thread: Number pages to visit (Threads) at the same time.
+        logger: A logger object to log the output.
     """
 
     network_file = "network_structure.json"
@@ -41,7 +38,8 @@ def __init__(
         self,
         website: str,
         proxies: dict[str, str],
-        c_params: dict[str, Union[int, float]],
+        c_depth: int,
+        c_pause: float,
         out_path: str,
         external: bool,
         exclusion: str,
@@ -50,8 +48,8 @@ def __init__(
     ):
         self.website = website
         self.proxies = proxies
-        self.c_depth = c_params["c_depth"]
-        self.c_pause = c_params["c_pause"]
+        self.c_depth = c_depth
+        self.c_pause = c_pause
         self.out_path = out_path
         self.external = external
         self.exclusion = rf"{exclusion}" if exclusion else None
@@ -60,33 +58,34 @@ def __init__(
 
         self.__executor = ThreadPoolExecutor(max_workers=min(32, self.thread))
         self.__files = {
-            "extlinks": open(
-                os.path.join(self.out_path, "extlinks.txt"), "w+", encoding="UTF-8"
-            ),
-            "telephones": open(
-                os.path.join(self.out_path, "telephones.txt"), "w+", encoding="UTF-8"
-            ),
-            "mails": open(
-                os.path.join(self.out_path, "mails.txt"), "w+", encoding="UTF-8"
-            ),
+            "extlinks": open(os.path.join(self.out_path, "extlinks.txt"), "w+", encoding="UTF-8"),
+            "telephones": open(os.path.join(self.out_path, "telephones.txt"), "w+", encoding="UTF-8"),
+            "mails": open(os.path.join(self.out_path, "mails.txt"), "w+", encoding="UTF-8"),
             "network_structure": os.path.join(self.out_path, self.network_file),
             "links": os.path.join(self.out_path, "links.txt"),
         }
 
-    def __get_tor_session(self):
+    def __get_tor_session(self) -> requests.Session:
+        """Get a new session with Tor proxies.
+
+        Returns:
+            Session object to make requests.
+        """
         session = requests.Session()
         session.proxies = self.proxies
         session.headers.update(self.__headers)
         session.verify = False
         return session
 
-    def excludes(self, link):
+    def excludes(self, link: str) -> bool:
         """Excludes links that are not required.
 
-        :param link: String
-        :return: Boolean
+        Args:
+            link: Link to check for exclusion.
+
+        Returns:
+            True if link is to be excluded else False.
         """
-        # BUG: For NoneType Exceptions, got to find a solution here
         if link is None:
             return True
         # Excludes links that matches the regex path.
@@ -97,7 +96,7 @@ def excludes(self, link):
             return True
         # External links
         if link.startswith("http") and not link.startswith(self.website):
-            if self.external is True:
+            if self.external:
                 return False
             self.__files["extlinks"].write(str(link) + "\n")
             return True
@@ -113,11 +112,15 @@ def excludes(self, link):
         if re.search("^.*\\.(pdf|jpg|jpeg|png|gif|doc|js|css)$", link, re.IGNORECASE):
             return True
 
-    def canonical(self, base, href):
+    def canonical(self, base: str, href: str) -> str:
         """Canonization of the link.
 
-        :param link: String
-        :return: String 'final_link': parsed canonical url.
+        Args:
+            base: Base URL.
+            href: Hyperlink present in the base URL page.
+
+        Returns:
+            parsed canonical url.
         """
         # Already formatted
         if href.startswith("http"):
@@ -126,25 +129,36 @@ def canonical(self, base, href):
         # For relative paths
         return urljoin(base, href)
 
-    def __crawl_link(
-        self, item, session
-    ) -> tuple[str, set[str], Union[int, tuple[str, Exception]]]:
-        # Store the crawled link of an item
-        item_data = set()
+    def __crawl_link(self, url: str, session: requests.Session) -> tuple[str, set[str], int | tuple[str, Exception]]:
+        """
+        Extracts all the hyperlinks from the given url and returns a tuple of
+        the url, set of hyperlinks and either status code or raised Exception.
+
+        Args:
+            url: URL to crawl.
+            session: Session object to make requests.
+
+        Returns:
+            A tuple of the url, set of hyperlinks and either status code or raised Exception.
+
+            (`https://example.com`, {`https://example.com/1`, `https://example.com/2`}, `200`)
+            (`https://error.com`, {}, `Exception()`)
+        """
+        url_data = set()
         html_page = Response
         response_code = 0
 
         try:
-            if item is not None:
-                html_page = session.get(item, allow_redirects=True, timeout=10)
+            if url is not None:
+                html_page = session.get(url, allow_redirects=True, timeout=10)
                 response_code = html_page.status_code
         except Exception as err:
-            return item, item_data, ("Request", err)
+            return url, url_data, ("Request", err)
 
         try:
             soup = BeautifulSoup(html_page.text, features="html.parser")
         except Exception as err:
-            return item, item_data, ("Soup Parse", err)
+            return url, url_data, ("Soup Parse", err)
 
         # For each <a href=""> tag.
         for link in soup.findAll("a"):
@@ -153,9 +167,9 @@ def __crawl_link(
             if self.excludes(link):
                 continue
 
-            ver_link = self.canonical(item, link)
+            ver_link = self.canonical(url, link)
             if ver_link is not None:
-                item_data.add(url_canon(ver_link)[1])
+                url_data.add(url_canon(ver_link)[1])
 
         # For each <area href=""> tag.
         for link in soup.findAll("area"):
@@ -164,15 +178,24 @@ def __crawl_link(
             if self.excludes(link):
                 continue
 
-            ver_link = self.canonical(item, link)
+            ver_link = self.canonical(url, link)
             if ver_link is not None:
-                item_data.add(url_canon(ver_link)[1])
+                url_data.add(url_canon(ver_link)[1])
 
-        return item, item_data, response_code
+        return url, url_data, response_code
 
-    def crawl(self):
+    def crawl(self) -> dict[str, list[str]]:
         """Core of the crawler.
-        :return: Dict (json_data) - Dictionary of crawled links.
+
+        Returns:
+            Dictionary of crawled links.
+
+            {
+                "link1": [ "link2", "link3", "link4" ],
+                "link2": [ "link5", "link6", "link4" ],
+                "link3": [ "link7", "link2", "link9" ],
+                "link4": [ "link1" ]
+            }
         """
         ord_lst = set([self.website])
         old_level = [self.website]
@@ -190,27 +213,29 @@ def crawl(self):
         for index in range(0, int(self.c_depth)):
             session = self.__get_tor_session()
 
+            # Sumbit all the links to the thread pool
             futures = [
-                self.__executor.submit(self.__crawl_link, item=item, session=session)
-                for item in old_level
-                if item not in json_data
+                self.__executor.submit(self.__crawl_link, url=url, session=session)
+                for url in old_level
+                if url not in json_data
             ]
 
+            # Get the results from list of futures and update the json_data
             for future in as_completed(futures):
-                item, item_data, response_code = future.result()
+                url, url_data, response_code = future.result()
                 if isinstance(response_code, int):
-                    self.logger.debug("%s :: %d", item, response_code)
+                    self.logger.debug("%s :: %d", url, response_code)
                 else:
                     error, exception = response_code
-                    self.logger.debug("%s Error :: %s", error, item, exc_info=exception)
+                    self.logger.debug("%s Error :: %s", error, url, exc_info=exception)
 
-                # Add item_data to crawled links.
-                cur_level = cur_level.union(item_data)
+                # Add url_data to crawled links.
+                cur_level = cur_level.union(url_data)
 
                 print(f"-- Results: {len(cur_level)}\r", end="", flush=True)
 
                 # Adding to json data
-                json_data[item] = list(item_data)
+                json_data[url] = list(url_data)
 
             # Get the next level withouth duplicates.
             clean_cur_level = cur_level.difference(ord_lst)
@@ -220,23 +245,23 @@ def crawl(self):
             old_level = list(clean_cur_level)
             # Reset cur_level
             cur_level = set()
-            self.logger.info(
-                "Step %d completed :: %d result(s)", index + 1, len(ord_lst)
-            )
+            self.logger.info("Step %d completed :: %d result(s)", index + 1, len(ord_lst))
 
             # Creating json
-            with open(
-                self.__files["network_structure"], "w", encoding="UTF-8"
-            ) as lst_file:
+            with open(self.__files["network_structure"], "w", encoding="UTF-8") as lst_file:
                 json.dump(json_data, lst_file, indent=2, sort_keys=False)
 
             with open(self.__files["links"], "w+", encoding="UTF-8") as file:
-                for item in sorted(ord_lst):
-                    file.write(f"{item}\n")
+                for url in sorted(ord_lst):
+                    file.write(f"{url}\n")
 
             # Pause time
             time.sleep(self.c_pause)
 
+        # Close the executor, don't wait for all threads to finish
+        self.__executor.shutdown(wait=False)
+
+        # Close the output files and return the json_data
         for file in self.__files.values():
             if isinstance(file, TextIOBase):
                 file.close()
diff --git a/modules/extractor.py b/modules/extractor.py
index f0892a8..9ba68df 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -5,20 +5,19 @@
 from http.client import IncompleteRead, InvalidURL
 from io import TextIOWrapper
 from logging import Logger
-from typing import Union
+from typing import Optional
 from urllib.error import HTTPError, URLError
 from urllib.parse import urlparse
 
 import requests
 import yara as _yara
 from bs4 import BeautifulSoup
-from requests import Session
 
 from modules.checker import folder
 from modules.helpers.helper import get_requests_header
 
 # Type hinting aliases
-ExcInfo = Union[Exception, bool]
+ExcInfo = Exception | bool
 LogMsg = tuple[str]
 LogLevel = int
 Log = tuple[LogLevel, LogMsg, ExcInfo]
@@ -29,15 +28,16 @@
 class Extractor:
     """Extractor - scrapes the resulting website or discovered links.
 
-    :param str website: URL of website to scrape.
-    :param dict[str, str] proxies: Dictionary mapping protocol or protocol and host to the URL of the proxy.
-    :param bool crawl: Cinex trigger. If used iteratively scrape the urls from input_file.
-    :param str output_file: Filename of resulting output from scrape.
-    :param str input_file: Filename of crawled/discovered URLs
-    :param str out_path: Dir path for output files.
-    :param int thread: Number pages to extract (Threads) at the same time.
-    :param int|None yara: keyword search option.
-    :param Logger logger: A logger object to log the output.
+    Attributes:
+        website: URL of website to scrape.
+        proxies: Dictionary mapping protocol or protocol and host to the URL of the proxy.
+        crawl: Cinex trigger. If used, iteratively scrape the urls from input_file.
+        output_file: Filename of resulting output from scrape.
+        input_file: Filename of crawled/discovered URLs.
+        out_path: Dir path for output files.
+        thread: Number pages to extract (Threads) at the same time.
+        yara: keyword search option.
+        logger: A logger object to log the output.
     """
 
     __headers = get_requests_header()
@@ -53,7 +53,7 @@ def __init__(
         input_file: str,
         out_path: str,
         thread: int,
-        yara: Union[int, None],
+        yara: Optional[int],
         logger: Logger,
     ):
         self.website = website
@@ -67,24 +67,62 @@ def __init__(
             self.out_path = folder(os.path.join(out_path, self.__extract_folder))
 
         self.thread = thread
-        self.__executor = ThreadPoolExecutor(max_workers=min(32, self.thread))
         self.yara = yara
         self.logger = logger
+
+        self.__executor = ThreadPoolExecutor(max_workers=min(32, self.thread))
         self.__session = self.__get_tor_session()
 
-    def extract(self):
-        """Extracts the contents of the input file/single URL into the outputs folder/file/terminal."""
+    def extract(self) -> Results:
+        """Extracts the contents of the input file/single URL into the outputs folder/file/terminal.
+
+        Note:
+            `Log` represents either Yara or an Exception output.
+
+            If Yara search is True then content is written to file/terminal.
+
+            If Yara search is False then content is ignored.
+
+        A `Log` is a tuple of `LogLevel`, `LogMsg` and `ExcInfo` with the following format:
+            (`LogLevel`, (`msg`, `*args`), `Exception()` or `False`)
+
+        `Single_res` of an url is a list of `Log` with the following format:
+            [
+                (10, ("%s :: %s match found!", "`http://example.com/file.html`", "Yara"), False),
+
+                (10, ("IOError Error :: %s", "`http://example.com/file.html`"), IOError()),
+            ]
+
+        Returns:
+            `Results` of an input which is a List of `Single_res` with the following format:
+
+            [[
+                (10, ("%s :: %s match found!", "`http://example.com`", "Yara"), False),
+
+                (10, ("File created :: %s", "example.com/extracted/example.com/_.html"), False),
+            ], [
+                (10, ("%s :: %s match found!", "`http://example.com/main.html`", "No yara"), False)
+            ], [
+                (10, ("%s :: %s match found!", "`http://example.com/file.html`", "Yara"), False),
+
+                (10, ("IOError Error :: %s", "`http://example.com/file.html`"), IOError()),
+            ]]
+        """
         results: Results = []
         if len(self.input_file) > 0:
             if self.crawl or self.out_path:
-                results = self.__cinex(self.input_file, self.yara, self.out_path)
+                # Crawl(output folder) | INput file | EXtract
+                results = self.__cinex(self.input_file, self.out_path, self.yara)
             else:
+                # TERMinal | INput file | EXtract
                 results = self.__terminex(self.input_file, self.yara)
         else:
             if len(self.output_file) > 0:
+                # OUTput file | EXtract
                 self.output_file = os.path.join(self.out_path, self.output_file)
-                single_res = self.__outex(self.website, self.yara, self.output_file)
+                single_res = self.__outex(self.website, self.output_file, self.yara)
             else:
+                # TERMinal | EXtract
                 single_res = self.__termex(self.website, self.yara)
 
             for level, args, exception in single_res:
@@ -93,67 +131,87 @@ def extract(self):
             results.append(single_res)
         return results
 
-    def __get_tor_session(self) -> Session:
+    def __get_tor_session(self) -> requests.Session:
+        """Get a new session with Tor proxies.
+
+        Returns:
+            Session object to make requests.
+        """
         session = requests.Session()
         session.proxies = self.proxies
         session.headers.update(self.__headers)
         session.verify = False
         return session
 
-    def __cinex(self, input_file: str, yara: Union[int, None], out_path: str) -> Results:
+    def __cinex(self, input_file: str, out_path: str, yara: Optional[int]) -> Results:
         """Ingests the crawled links from the input_file,
         scrapes the contents of the resulting web pages and writes the contents to
         the into out_path/{url_address}.
 
-        :param input_file: String: Filename of the crawled Urls.
-        :param yara: Integer: Keyword search argument.
-        :param out_path: String: Pathname of results.
-        :return: None
+        Args:
+            input_file: Filename of the crawled Urls.
+            out_path: Dir path for results.
+            yara: Keyword search argument.
+
+        Returns:
+            List of `Single_res` for each url in input.
         """
         self.logger.info("Cinex :: Extracting from %s to %s", input_file, out_path)
         return self.__inex(input_file=input_file, yara=yara, out_path=out_path)
 
-    def __terminex(self, input_file: str, yara: Union[int, None]) -> Results:
+    def __terminex(self, input_file: str, yara: Optional[int]) -> Results:
         """Input links from file and extract them into terminal.
 
-        :param input_file: String: File name of links file.
-        :param yara: Integer: Keyword search argument.
-        :return: None
+        Args:
+            input_file: Filename of the crawled Urls.
+            yara: Keyword search argument.
+
+        Returns:
+            List of `Single_res` for each url in input.
         """
         self.logger.info("Terminex :: Extracting from %s to terminal", input_file)
         return self.__inex(input_file=input_file, yara=yara)
 
-    def __outex(self, website: str, yara: Union[int, None], output_file: str) -> Single_res:
+    def __outex(self, website: str, output_file: str, yara: Optional[int]) -> Single_res:
         """Scrapes the contents of the provided web address and outputs the
         contents to file.
 
-        :param website: String: Url of web address to scrape.
-        :param yara: Integer: Keyword search argument.
-        :param output_file: String: Filename of the results.
-        :return: None
+        Args:
+            website: Url of web address to scrape.
+            output_file: Filename to write the contents to.
+            yara: Keyword search argument.
+
+        Returns:
+            List of `Log` for given website.
         """
         self.logger.info("Outex :: Extracting %s to %s", website, output_file)
         return self.__ex(website=website, yara=yara, output_file=output_file)
 
-    def __termex(self, website: str, yara: Union[int, None]) -> Single_res:
+    def __termex(self, website: str, yara: Optional[int]) -> Single_res:
         """Scrapes provided web address and prints the results to the terminal.
 
-        :param website: String: URL of website to scrape.
-        :param yara: Integer: Keyword search argument.
-        :return: None
+        Args:
+            website: Url of web address to scrape.
+            yara: Keyword search argument.
+
+        Returns:
+            List of `Log` for given website.
         """
         self.logger.info("Termex :: Extracting %s to terminal", website)
         return self.__ex(website=website, yara=yara)
 
-    def __inex(self, input_file: str, yara: Union[int, None], out_path: str = None) -> Results:
+    def __inex(self, input_file: str, out_path: Optional[str] = None, yara: Optional[int] = None) -> Results:
         """Ingests the crawled links from the input_file,
         scrapes the contents of the resulting web pages and writes the contents
         into the terminal if out_path is None else out_path/{url_address}.
 
-        :param input_file: String: Filename of the crawled Urls.
-        :param out_path: String|None : Pathname of results.
-        :param yara: Integer: Keyword search argument.
-        :return: None
+        Args:
+            input_file: Filename of the crawled Urls.
+            out_path: Dir path for results.
+            yara: Keyword search argument.
+
+        Returns:
+            List of `Single_res` [`Results`] for each url in input.
         """
         file = TextIOWrapper
         try:
@@ -162,6 +220,7 @@ def __inex(self, input_file: str, yara: Union[int, None], out_path: str = None)
             self.logger.exception("Read Error :: %s", input_file)
             return
 
+        # Sumbit all the links to the thread pool
         futures = [
             self.__executor.submit(self.__generate_file, url=url, yara=yara, out_path=out_path)
             for url in file.read().splitlines()
@@ -169,6 +228,7 @@ def __inex(self, input_file: str, yara: Union[int, None], out_path: str = None)
 
         results: Results = []
 
+        # Get the results from list of futures and append them to results
         for future in as_completed(futures):
             single_res = future.result()
             results.append(single_res)
@@ -176,19 +236,33 @@ def __inex(self, input_file: str, yara: Union[int, None], out_path: str = None)
             for level, args, exception in single_res:
                 self.logger.log(level, *args, exc_info=exception)
 
+        # Close the executor, don't wait for all threads to finish
+        self.__executor.shutdown(wait=False)
         file.close()
 
         return results
 
-    def __generate_file(self, url: str, yara: Union[int, None], out_path: Union[str, None]) -> Single_res:
+    def __generate_file(self, url: str, out_path: Optional[str], yara: Optional[int]) -> Single_res:
+        """Generate output file from url and send it to extractor.
+
+        Args:
+            url: Url of web address to scrape.
+            output_file: Filename to write the contents to.
+            yara: Keyword search argument.
+
+        Returns:
+            List of `Log` [`Single_res`] for given url.
+        """
         output_file = None
         if out_path is not None:
             try:
+                # http://a.com/b.ext?x=&y=$%z2 -> a.com/b.extxyz2_.html
                 uri = urlparse(url)
                 output_file = os.path.join(
                     out_path,
                     os.path.join(uri.netloc, *uri.path.split("/")) + re.sub(r"[^\w_.)( -]", "", uri.query) + "_.html",
                 )
+                # Create the directory if it doesn't exist
                 folder(output_file, is_file=True)
             except Exception as err:
                 return [
@@ -201,20 +275,22 @@ def __generate_file(self, url: str, yara: Union[int, None], out_path: Union[str,
 
         return self.__ex(website=url, yara=yara, output_file=output_file)
 
-    def __ex(self, website: str, yara: Union[int, None], output_file: str = None) -> Single_res:
+    def __ex(self, website: str, output_file: str = None, yara: Optional[int] = None) -> Single_res:
         """Scrapes the contents of the provided web address and outputs the
         contents to file or terminal.
 
-        :param type: String: Either "Outex" or "Termex".
-        :param website: String: Url of web address to scrape.
-        :param yara: Integer: Keyword search argument.
-        :param output_file: String|None: Filename of the results.
-        :return: None
+        Args:
+            website: Url of web address to scrape.
+            output_file: Filename to write the contents to.
+            yara: Keyword search argument.
+
+        Returns:
+            List of `Log` [`Single_res`] for given website.
         """
         result = []
         try:
             content = self.__session.get(website, allow_redirects=True, timeout=10).text
-            if yara:
+            if yara is not None:
                 full_match_keywords = self.__check_yara(raw=content, yara=yara)
 
                 result.append(
@@ -253,12 +329,17 @@ def __ex(self, website: str, yara: Union[int, None], output_file: str = None) ->
 
         return result
 
-    def __check_yara(self, raw: str = None, yara: int = 0) -> dict:
+    def __check_yara(self, raw: str, yara: int = 0) -> dict[str, list]:
         """Validates Yara Rule to categorize the site and check for keywords.
 
-        :param yara:  Integer: Keyword search argument.
-        :param raw:   HTTP Response body.
-        :return matches: List of yara rule matches.
+        Args:
+            yara: Keyword search argument.
+            raw: HTTP Response body.
+
+        Returns:
+            Dictionary of yara rule matches.
+
+            {"namespace":[match1,match2,...]}
         """
         if raw is None:
             return None
@@ -270,12 +351,15 @@ def __check_yara(self, raw: str = None, yara: int = 0) -> dict:
 
         return matches
 
-    def __text(self, response: str = None) -> str:
+    def __text(self, response: str) -> str:
         """Removes all the garbage from the HTML and takes only text elements
         from the page.
 
-        :param response: HTTP Response.
-        :return: String: Text only stripped response.
+        Args:
+            response: HTTP Response.
+
+        Returns:
+        Text only stripped response.
         """
         soup = BeautifulSoup(response, features="lxml")
         for s in soup(["script", "style"]):
diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index f188190..56e50d3 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -66,8 +66,20 @@ def doRollover(self):
             self.stream = self._open()
 
 
-def setup_custom_logger(name, verbose_, filelog, filename):
-    """Setup custom logger with stream and file handlers"""
+def setup_custom_logger(
+    name: str, filename: str = "log.log", verbose_: bool = False, filelog: bool = True
+) -> logging.Logger:
+    """Setup custom logger with stream and file handlers
+
+    Args:
+        name: Name of the logger.
+        filename: Name of the log file.
+        verbose_: Simple formatter for stream if False.
+        filelog: Add FileHandler to logger if True.
+
+    Returns:
+        Logger object with custom handlers and formatters.
+    """
     formatter = logging.Formatter(
         fmt="{asctime} [{levelname:^7s}] [{filename}:{lineno}] {message}",
         style="{",
@@ -82,7 +94,8 @@ def setup_custom_logger(name, verbose_, filelog, filename):
     screen_handler.setFormatter(formatter)
     screen_handler.setLevel(logging.DEBUG)
 
-    if verbose_ is False:
+    # Set simple formatter for file non-verbose logging
+    if not verbose_:
         screen_handler.setFormatter(
             logging.Formatter(
                 fmt="## {message}",
@@ -103,24 +116,48 @@ def setup_custom_logger(name, verbose_, filelog, filename):
     return logger
 
 
-def get_requests_header():
-    """Get requests header"""
+def get_requests_header() -> dict[str, str]:
+    """Get requests header
+
+    Returns:
+        Header dictioanry with Accept-Encoding and User-Agent.
+
+        {"Accept-Encoding": "identity",
+        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36"}
+    """
     return {
         "Accept-Encoding": "identity",
         "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
     }
 
 
-def get_tor_proxies(port):
-    """Get Tor socks proxies"""
+def get_tor_proxies(port: int = 9050) -> dict[str, str]:
+    """Get Tor socks proxies
+
+    Args:
+        port: Port number of the Tor socks proxy.
+
+    Returns:
+        Dictioanry with socks5h based http and https proxies.
+
+        {"http": f"socks5h://127.0.0.1:9050",
+        "https": f"socks5h://127.0.0.1:9050"}
+    """
     return {
         "http": f"socks5h://127.0.0.1:{port}",
         "https": f"socks5h://127.0.0.1:{port}",
     }
 
 
-def traceback_name(error):
-    """Get traceback name"""
+def traceback_name(error: Exception) -> str:
+    """Get traceback class names from an exception
+
+    Args:
+        error: Exception object.
+
+    Returns:
+        Exception traceback class names.
+    """
     module = error.__class__.__module__
     if module is None or module == str.__class__.__module__:
         return error.__class__.__name__
diff --git a/torcrawl.py b/torcrawl.py
index 8a1d52e..65f5f83 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -107,8 +107,6 @@ def decorate(function):
 def main():
     """Main method of DarkSpider application. Collects and parses arguments and
     instructs the rest of the application on how to run.
-
-    :return: None
     """
 
     # Get arguments with GooeyParser if available else argparse.
@@ -279,13 +277,13 @@ def main():
     # Logger setup
     crawlog = setup_custom_logger(
         name="crawlog",
+        filename=os.path.join(out_path, "crawl.log"),
         verbose_=args.verbose,
         filelog=args.log,
-        filename=os.path.join(out_path, "crawl.log"),
     )
 
     # Connect to TOR
-    if args.without is False:
+    if not args.without:
         check_tor(logger=crawlog)
         proxies = get_tor_proxies(port=args.port)
 
@@ -301,7 +299,8 @@ def main():
         crawler = Crawler(
             website=website,
             proxies=proxies,
-            c_params={"c_depth": args.cdepth, "c_pause": args.cpause},
+            c_depth=args.cdepth,
+            c_pause=args.cpause,
             out_path=out_path,
             external=args.external,
             exclusion=args.exclusion,
@@ -341,7 +340,7 @@ def main():
                 yara=args.yara,
                 logger=crawlog,
             )
-            extractor.extract()
+            extract = extractor.extract()
     elif args.input or website:
         extractor = Extractor(
             website=website,
@@ -354,7 +353,7 @@ def main():
             yara=args.yara,
             logger=crawlog,
         )
-        extractor.extract()
+        extract = extractor.extract()
 
 
 # Stub to call main method.

From c757e2aa1d1c0a1aeaefa0f19fa64b14c3a339bf Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Sun, 18 Sep 2022 23:57:45 +0530
Subject: [PATCH 24/39] Update: Project requirements

---
 requirements.txt | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/requirements.txt b/requirements.txt
index ba3db99..2bb7163 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,8 +1,9 @@
 beautifulsoup4>=4.7.1
 Gooey>=1.0.7
-matplotlib>=3.5.0
-networkx>=2.8
+matplotlib>=3.5.2
+networkx>=2.8.5
+psutil>=5.9.0
+requests>=2.25.1
 seaborn>=0.11.1
-pysocks>=1.7.1
 yara==1.7.7
 lxml

From 9390c0ba059acc3eb6f04c6da5302533bbae512c Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Mon, 19 Sep 2022 20:26:00 +0530
Subject: [PATCH 25/39] Fix: Incremental log file generation with timestamp

---
 modules/helpers/helper.py | 21 +++++++++++++++------
 1 file changed, 15 insertions(+), 6 deletions(-)

diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index 56e50d3..21097d1 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -1,6 +1,7 @@
 import logging
 import os
 import sys
+import time
 from io import StringIO
 from logging.handlers import RotatingFileHandler
 
@@ -49,10 +50,17 @@ def wrapper(*args, **kwargs):
 class RollingFileHandler(RotatingFileHandler):
     """Custom RotatingFileHandler for incremental infinite logging"""
 
-    def __init__(self, filename, mode="w", maxBytes=0, backupCount=0, encoding=None, delay=False):
-        self.last_backup_cnt = 0
+    def __init__(self, filename, mode="a", maxBytes=0, backupCount=0, encoding=None, delay=False, errors=None):
+        self.last_backup_cnt = int(time.time())
+        self.filename = filename
         super(RollingFileHandler, self).__init__(
-            filename=filename, mode=mode, maxBytes=maxBytes, backupCount=backupCount, encoding=encoding, delay=delay
+            filename="{0}.{2}.init{1}".format(*os.path.splitext(self.filename), self.last_backup_cnt),
+            mode=mode,
+            maxBytes=maxBytes,
+            backupCount=backupCount,
+            encoding=encoding,
+            delay=delay,
+            errors=errors,
         )
 
     def doRollover(self):
@@ -60,8 +68,9 @@ def doRollover(self):
             self.stream.close()
             self.stream = None
         self.last_backup_cnt += 1
-        next_name = "{0}.{2}{1}".format(*os.path.splitext(self.baseFilename), self.last_backup_cnt)
-        self.rotate(self.baseFilename, next_name)
+        next_name = "{0}.{2}{1}".format(*os.path.splitext(self.filename), self.last_backup_cnt)
+        self.baseFilename = next_name
+        # self.rotate(self.baseFilename, next_name)
         if not self.delay:
             self.stream = self._open()
 
@@ -108,7 +117,7 @@ def setup_custom_logger(
     logger.addHandler(screen_handler)
 
     if filelog:
-        file_handler = RollingFileHandler(filename=filename, mode="w", maxBytes=10 * 1024 * 1024)
+        file_handler = RollingFileHandler(filename=filename, mode="w", maxBytes=1024 * 1024 * 10)
         file_handler.setFormatter(formatter)
         file_handler.setLevel(logging.DEBUG)
         logger.addHandler(file_handler)

From f2a342207b2085cd96e7c691af9e81bba005448f Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Mon, 19 Sep 2022 23:19:21 +0530
Subject: [PATCH 26/39] Refactor: Single_res variable name changes to camel
 case

---
 modules/extractor.py | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/modules/extractor.py b/modules/extractor.py
index 9ba68df..339fc6b 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -21,8 +21,8 @@
 LogMsg = tuple[str]
 LogLevel = int
 Log = tuple[LogLevel, LogMsg, ExcInfo]
-Single_res = list[Log]
-Results = list[Single_res]
+SingleRes = list[Log]
+Results = list[SingleRes]
 
 
 class Extractor:
@@ -86,7 +86,7 @@ def extract(self) -> Results:
         A `Log` is a tuple of `LogLevel`, `LogMsg` and `ExcInfo` with the following format:
             (`LogLevel`, (`msg`, `*args`), `Exception()` or `False`)
 
-        `Single_res` of an url is a list of `Log` with the following format:
+        `SingleRes` of an url is a list of `Log` with the following format:
             [
                 (10, ("%s :: %s match found!", "`http://example.com/file.html`", "Yara"), False),
 
@@ -94,7 +94,7 @@ def extract(self) -> Results:
             ]
 
         Returns:
-            `Results` of an input which is a List of `Single_res` with the following format:
+            `Results` of an input which is a List of `SingleRes` with the following format:
 
             [[
                 (10, ("%s :: %s match found!", "`http://example.com`", "Yara"), False),
@@ -154,7 +154,7 @@ def __cinex(self, input_file: str, out_path: str, yara: Optional[int]) -> Result
             yara: Keyword search argument.
 
         Returns:
-            List of `Single_res` for each url in input.
+            List of `SingleRes` for each url in input.
         """
         self.logger.info("Cinex :: Extracting from %s to %s", input_file, out_path)
         return self.__inex(input_file=input_file, yara=yara, out_path=out_path)
@@ -167,12 +167,12 @@ def __terminex(self, input_file: str, yara: Optional[int]) -> Results:
             yara: Keyword search argument.
 
         Returns:
-            List of `Single_res` for each url in input.
+            List of `SingleRes` for each url in input.
         """
         self.logger.info("Terminex :: Extracting from %s to terminal", input_file)
         return self.__inex(input_file=input_file, yara=yara)
 
-    def __outex(self, website: str, output_file: str, yara: Optional[int]) -> Single_res:
+    def __outex(self, website: str, output_file: str, yara: Optional[int]) -> SingleRes:
         """Scrapes the contents of the provided web address and outputs the
         contents to file.
 
@@ -187,7 +187,7 @@ def __outex(self, website: str, output_file: str, yara: Optional[int]) -> Single
         self.logger.info("Outex :: Extracting %s to %s", website, output_file)
         return self.__ex(website=website, yara=yara, output_file=output_file)
 
-    def __termex(self, website: str, yara: Optional[int]) -> Single_res:
+    def __termex(self, website: str, yara: Optional[int]) -> SingleRes:
         """Scrapes provided web address and prints the results to the terminal.
 
         Args:
@@ -211,7 +211,7 @@ def __inex(self, input_file: str, out_path: Optional[str] = None, yara: Optional
             yara: Keyword search argument.
 
         Returns:
-            List of `Single_res` [`Results`] for each url in input.
+            List of `SingleRes` [`Results`] for each url in input.
         """
         file = TextIOWrapper
         try:
@@ -242,7 +242,7 @@ def __inex(self, input_file: str, out_path: Optional[str] = None, yara: Optional
 
         return results
 
-    def __generate_file(self, url: str, out_path: Optional[str], yara: Optional[int]) -> Single_res:
+    def __generate_file(self, url: str, out_path: Optional[str], yara: Optional[int]) -> SingleRes:
         """Generate output file from url and send it to extractor.
 
         Args:
@@ -251,7 +251,7 @@ def __generate_file(self, url: str, out_path: Optional[str], yara: Optional[int]
             yara: Keyword search argument.
 
         Returns:
-            List of `Log` [`Single_res`] for given url.
+            List of `Log` [`SingleRes`] for given url.
         """
         output_file = None
         if out_path is not None:
@@ -275,7 +275,7 @@ def __generate_file(self, url: str, out_path: Optional[str], yara: Optional[int]
 
         return self.__ex(website=url, yara=yara, output_file=output_file)
 
-    def __ex(self, website: str, output_file: str = None, yara: Optional[int] = None) -> Single_res:
+    def __ex(self, website: str, output_file: str = None, yara: Optional[int] = None) -> SingleRes:
         """Scrapes the contents of the provided web address and outputs the
         contents to file or terminal.
 
@@ -285,7 +285,7 @@ def __ex(self, website: str, output_file: str = None, yara: Optional[int] = None
             yara: Keyword search argument.
 
         Returns:
-            List of `Log` [`Single_res`] for given website.
+            List of `Log` [`SingleRes`] for given website.
         """
         result = []
         try:

From 64784a406e11cab771ab5300445885994800bd94 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Mon, 19 Sep 2022 23:19:50 +0530
Subject: [PATCH 27/39] Refactor: Visualization modules documentation improved

---
 modules/visualization.py | 21 ++++++++-------------
 1 file changed, 8 insertions(+), 13 deletions(-)

diff --git a/modules/visualization.py b/modules/visualization.py
index 8bb202e..fb9c2bb 100644
--- a/modules/visualization.py
+++ b/modules/visualization.py
@@ -13,11 +13,12 @@
 
 
 class Visualization:
-    """Visualize the graphs and insights from the crawled data
+    """Visualize the graphs and insights from the crawled data.
 
-    :param json_file: The json file containing the crawled data
-    :param out_path: The path to the output directory
-    :param verbose: Whether to print the output or not
+    Attributes:
+        json_file: The json file containing the crawled data.
+        out_path: The path to the output directory.
+        logger: A logger object to log the output.
     """
 
     def __init__(self, json_file, out_path, logger):
@@ -84,9 +85,7 @@ def indegree_bar(self):
 
         ax = sns.barplot(x=indegree_keys, y=indegree_percent, color="cornflowerblue")
         ax.set_xlim(-1, min(50, len(indegree_keys)))
-        ax.xaxis.set_major_locator(
-            MultipleLocator(base=min(50, max(len(indegree_keys), 5)) // 5)
-        )
+        ax.xaxis.set_major_locator(MultipleLocator(base=min(50, max(len(indegree_keys), 5)) // 5))
         plt.ylabel("Percentage of Nodes")
         plt.xlabel("Indegree")
         plt.title("Indegree of the graph")
@@ -118,9 +117,7 @@ def outdegree_bar(self):
 
         ax = sns.barplot(x=outdegree_keys, y=outdegree_percent, color="cornflowerblue")
         ax.set_xlim(-1, min(50, len(outdegree_keys)) + 1)
-        ax.xaxis.set_major_locator(
-            MultipleLocator(base=min(50, max(len(outdegree_keys), 5)) // 5)
-        )
+        ax.xaxis.set_major_locator(MultipleLocator(base=min(50, max(len(outdegree_keys), 5)) // 5))
         plt.ylabel("Percentage of Nodes")
         plt.xlabel("Outdegree")
         plt.title("Outdegree of the graph")
@@ -158,9 +155,7 @@ def pagerank_bar(self):
 
         ax = sns.barplot(x=pagerank_keys, y=pagerank_percent, color="cornflowerblue")
         ax.set_xticklabels(map(lambda x: f"{x:.2E}", pagerank_keys))
-        ax.xaxis.set_major_locator(
-            MultipleLocator(base=max(len(pagerank_keys), 5) // 5)
-        )
+        ax.xaxis.set_major_locator(MultipleLocator(base=max(len(pagerank_keys), 5) // 5))
         plt.ylabel("Percentage of Nodes")
         plt.xlabel("PageRank")
         plt.title("PageRank of the graph")

From f2bb809d6e66402ba81aa159788a9f5830bc8bb4 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Tue, 20 Sep 2022 00:18:28 +0530
Subject: [PATCH 28/39] Fix: 'url_canon' return false canon flag for removing
 trailing slash

---
 modules/checker.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/modules/checker.py b/modules/checker.py
index 5570039..54b3b09 100644
--- a/modules/checker.py
+++ b/modules/checker.py
@@ -31,7 +31,6 @@ def url_canon(website: str, www: bool = False) -> tuple[bool, str]:
     uri = urlparse(website)
     if uri.path == "/":
         website = website.rstrip("/")
-        canon = True
 
     return canon, website
 

From 4b169d4a652547baa69a915f162611a69f7fd799 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Tue, 20 Sep 2022 00:18:56 +0530
Subject: [PATCH 29/39] Update: Readme documentation

---
 README.md          | 275 +++++++++++++++++++++++++++------------------
 assets/logging.png | Bin 0 -> 99291 bytes
 2 files changed, 167 insertions(+), 108 deletions(-)
 create mode 100644 assets/logging.png

diff --git a/README.md b/README.md
index 57dd2ae..f861dd1 100644
--- a/README.md
+++ b/README.md
@@ -5,34 +5,40 @@
   -->
 # DarkSpider
 
-[![Version](https://img.shields.io/badge/version-1.2-green.svg?style=plastic)]() [![Python](https://img.shields.io/badge/python-v3-blue.svg?style=plastic)]() [![license](https://img.shields.io/github/license/PROxZIMA/DarkSpider.svg?style=plastic)]()
+[![Version](https://img.shields.io/badge/version-2.0.0-green.svg?style=plastic)]() [![Python](https://img.shields.io/badge/python-v3-blue.svg?style=plastic)]() [![license](https://img.shields.io/github/license/PROxZIMA/DarkSpider.svg?style=plastic)]()
 
 ## Basic Information:
 DarkSpider is a python script to crawl and extract (regular or onion) webpages through TOR network.
 
-- **Warning:** Crawling is not illegal, but violating copyright is. It’s always best to double check a website’s T&C before crawling them. Some websites set up what’s called robots.txt to tell crawlers not to visit those pages. This crawler will allow you to go around this, but we always recommend respecting robots.txt.
-- **Keep in mind:** Extracting and crawling through TOR network take some time. That's normal behavior; you can find more information [here](https://www.torproject.org/docs/faq.html.en#WhySlow).
+> **Warning**
+>
+> Crawling is not illegal, but violating copyright is. It’s always best to double check a website’s T&C before crawling them. Some websites set up what’s called `robots.txt` to tell crawlers not to visit those pages. This crawler will allow you to go around this, but we always recommend respecting `robots.txt`.
+
+> **Keep in mind**
+>
+> Extracting and crawling through TOR network take some time. That's normal behaviour; you can find more information [here](https://support.torproject.org/relay-operators/why-is-my-relay-slow/).
 
 ### What makes it simple?
 
 With a single argument you can read an .onion webpage or a regular one through TOR Network and using pipes you can pass the output at any other tool you prefer.
 
 ```shell
-$ torcrawl -u http://www.github.com/ | grep 'google-analytics'
-    <meta-name="google-analytics" content="UA-XXXXXX- ">
+$ python torcrawl.py -u http://github.com/ | grep 'google-site-verification'
+    <meta name="google-site-verification" content="xxxx">
 ```
 
-If you want to crawl the links of a webpage use the `-c` and you got on a file all the inside links. You can even use `-d` to crawl them and so on. As far, there is also the necessary argument `-p` to wait some seconds before the next crawl.
+If you want to crawl the links of a webpage use the `-c` and you will get a folder all the extracted links. You can even use `-d` to crawl them and so on. As far, there is also the necessary argument `-p` to wait some seconds before the next crawl.
 
 ```shell
-$ torcrawl -v -u http://www.github.com/ -c -d 2 -p 2
-# TOR is ready!
-# URL: http://www.github.com/
-# Your IP: XXX.XXX.XXX.XXX
-# Crawler started from http://www.github.com/ with 2 depth crawl and 2 second(s) delay:
-# Step 1 completed with: 11 results
-# Step 2 completed with: 112 results
-# File created on /path/to/project/links.txt
+$ python torcrawl.py -v -u http://github.com/ -c -d 2 -p 2
+[ DEBUG ] TOR is ready!
+[ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: True
+[ DEBUG ] URL :: http://github.com
+[ DEBUG ] Folder created :: github.com
+[ INFO  ] Crawler started from http://github.com with 2 depth, 2.0 seconds delay and using 16 Threads. Excluding 'None' links.
+[ INFO  ] Step 1 completed :: 87 result(s)
+[ INFO  ] Step 2 completed :: 4228 result(s)
+[ INFO  ] Network Structure created :: github.com/network_structure.json
 ```
 
 ## Installation:
@@ -50,162 +56,191 @@ Debian/Ubuntu: `apt-get install tor`
 [(for more distros and instructions)](https://www.torproject.org/docs/)
 
 ## Arguments:
-arg | Long | Description
+Args | Long | Description
 ----|------|------------
 **General**: | |
--h  |--help| Help
--g  |--gui| Open with GUI backend.
--v  |--verbose| Show more information about the progress
--u  |--url *.onion| URL of Webpage to crawl or extract
--w  |--without| Without the use of Relay TOR
--n  |--port number| Port number of TOR Socks Proxy (default: 9050)
--f  |--folder| The directory which will contain the generated files ([@guyo13](https://www.github.com/guyo13))
--s  |--visualize| Visualize the graphs and insights from the crawled data
+`-h` |`--help`| Help
+`-g` |`--gui`| Open with GUI backend.
+`-v` |`--verbose`| Show more information about the progress
+`-u` |`--url *.onion`| URL of Webpage to crawl or extract
+`-w` |`--without`| Without the use of Relay TOR
+`-n` |`--port number`| Port number of TOR Socks Proxy (default: 9050)
+`-f` |`--folder`| The directory which will contain the generated files
+`-s` |`--visualize`| Visualize the graphs and insights from the crawled data
 **Extract**: | |
--e  |--extract| Extract page's code to terminal or file. (Default: Terminal)
--i  |--input filename| Input file with URL(s) (separated by line)
--o  |--output filename| Output page(s) to file(s) (for one page)
--y  |--yara 0\|1 | Perform yara keyword search (0 = search entire html object. 1 = search only text).
+`-e` |`--extract`| Extract page's code to terminal or file. (Default: Terminal)
+`-i` |`--input filename`| Input file with URL(s) (separated by line)
+`-o` |`--output filename`| Output page(s) to file(s) (for one page)
+`-y` |`--yara 0\|1`| Perform yara keyword search (0 = search entire html object. 1 = search only text).
 **Crawl**: | |
--c  |--crawl| Crawl website (Default output on /links.txt)
--d  |--cdepth| Set depth of crawl's travel (Default: 1)
--z  |--exclusion regexp| Regex path that is ignored while crawling (Default: None)
--t  |--thread number| How many pages to visit (Threads) at the same time (Default: 16)
--p  |--pause| The length of time the crawler will pause (Default: 0)
--l  |--log| Log file with visited URLs and their response code
--x  |--external| Exclude external links while crawling a webpage (Default: include all links)
+`-c` |`--crawl`| Crawl website (Default output on /links.txt)
+`-d` |`--cdepth`| Set depth of crawl's travel (Default: 1)
+`-z` |`--exclusion regexp`| Regex path that is ignored while crawling (Default: None)
+`-t` |`--thread number`| How many pages to visit (Threads) at the same time (Default: 16)
+`-p` |`--pause`| The length of time the crawler will pause (Default: 0)
+`-l` |`--log`| Log file with visited URLs and their response code
+`-x` |`--external`| Exclude external links while crawling a webpage (Default: include all links)
 
 ## Usage:
 
 ### As Extractor:
-To just extract a single webpage to terminal:
+
+> **Note**
+>
+> Extractor takes maximum file name length under consideration and creates sub-directories based on the url.
+>
+> `http://a.com/b.ext?x=&y=$%z2` -> `a.com/b.extxyz2_.html` (`a.com` folder with `b.extxyz2_.html` file in it)
+
+- To just extract a single webpage to terminal:
 
 ```shell
-$ python torcrawl.py -u http://www.github.com
+$ python torcrawl.py -u http://github.com/
+## Termex :: Extracting http://github.com to terminal
+## http://github.com ::
 <!DOCTYPE html>
 ...
 </html>
 ```
 
-Extract into a file (github.html) without the use of TOR:
+- Extract into a file (github.html) without the use of TOR:
 
 ```shell
-$ python torcrawl.py -w -u http://www.github.com -o github.htm
-## File created on /script/path/github.htm
+$ python torcrawl.py -w -u http://github.com -o github.html
+## Outex :: Extracting http://github.com to github.com/github.html
 ```
 
-Extract to terminal and find only the line with google-analytics:
+- Extract to terminal and find only the line with google-site-verification:
 
 ```shell
-$ python torcrawl.py -u http://www.github.com | grep 'google-analytics'
-    <meta name="google-analytics" content="UA-*******-*">
+$ python torcrawl.py -u http://github.com/ | grep 'google-site-verification'
+    <meta name="google-site-verification" content="xxxx">
 ```
 
-Extract to file and find only the line with google-analytics using yara:
+- Extract to file and find only the line with google-site-verification using `yara`:
+
 ```shell
 $ python torcrawl.py -v -w -u https://github.com -e -y 0
 ...
 ```
-**_Note:_** update res/keyword.yar to search for other keywords.
-Use ```-y 0``` for raw html searching and ```-y 1``` for text search only.
 
-Extract a set of webpages (imported from file) to terminal:
+> **Note**
+>
+> Update `res/keyword.yar` to search for other keywords.
+> Use `-y 0` for raw html searching and `-y 1` for text search only.
+
+- Extract a set of webpages (imported from file) to a folder:
 
 ```shell
-$ python torcrawl.py -i links.txt
+$ python torcrawl.py -i links.txt -f links_output
 ...
 ```
 
-
 ### As Crawler:
-Crawl the links of the webpage without the use of TOR,
-also show verbose output (really helpful):
+- Crawl the links of the webpage without the use of TOR, also show verbose output (really helpful):
 
 ```shell
-$ python torcrawl.py -v -w -u http://www.github.com/ -c
-## URL: http://www.github.com/
-## Your IP: *.*.*.*
-## Crawler Started from http://www.github.com/ with step 1 and wait 0
-## Step 1 completed with: 11 results
-## File created on /script/path/links.txt
+$ python torcrawl.py -v -w -u http://github.com/ -c
+[ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: False
+[ DEBUG ] URL :: http://github.com/
+[ DEBUG ] Folder created :: github.com
+[ INFO  ] Crawler started from http://github.com with 1 depth, 0 seconds delay and using 16 Threads. Excluding 'None' links.
+[ INFO  ] Step 1 completed :: 87 result(s)
+[ INFO  ] Network Structure created :: github.com/network_structure.json
 ```
 
-Crawl the webpage with depth 2 (2 clicks) and 5 seconds waiting before crawl the next page:
+- Crawl the webpage with depth 2 (2 clicks) and 5 seconds waiting before crawl the next page:
 
 ```shell
-$ python torcrawl.py -v -u http://www.github.com/ -c -d 2 -p 5
-## TOR is ready!
-## URL: http://www.github.com/
-## Your IP: *.*.*.*
-## Crawler Started from http://www.github.com with step 2 and wait 5
-## Step 1 completed with: 11 results
-## Step 2 completed with: 112 results
-## File created on /script/path/links.txt
+$ python torcrawl.py -v -u http://github.com/ -c -d 2 -p 5
+[ DEBUG ] TOR is ready!
+[ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: True
+[ DEBUG ] URL :: http://github.com
+[ DEBUG ] Folder created :: github.com
+[ INFO  ] Crawler started from http://github.com with 2 depth, 5.0 seconds delay and using 16 Threads. Excluding 'None' links.
+[ INFO  ] Step 1 completed :: 87 result(s)
+[ INFO  ] Step 2 completed :: 4228 result(s)
+[ INFO  ] Network Structure created :: github.com/network_structure.json
 ```
 
 Crawl the webpage with depth 1 (1 clicks), 1 seconds pause and exclude links that match `.*\.blog`:
 
 ```shell
-$ python torcrawl.py -v -u http://www.github.com/ -c -d 1 -p 1 -z ".*\.blog"
-## TOR is ready!
-## URL: http://www.github.com/
-## Your IP: *.*.*.*
-## Crawler Started from http://www.github.com with step 1 and wait 1. Excluding .*\.blog links.
-## Step 1 completed with: 9 results
-## File created on /script/path/links.txt
+$ python torcrawl.py -v -u http://github.com/ -c -d 1 -p 1 -z ".*\.blog"
+[ DEBUG ] TOR is ready!
+[ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: True
+[ DEBUG ] URL :: http://github.com/
+[ DEBUG ] Folder created :: github.com
+[ INFO  ] Crawler started from http://github.com with 1 depth, 1.0 second delay and using 16 Threads. Excluding '.*\.blog' links.
+[ INFO  ] Step 1 completed :: 85 result(s)
+[ INFO  ] Network Structure created :: github.com/network_structure.json
 ```
-### As Both:
+
+### As Crawler + Extractor:
 You can crawl a page and also extract the webpages into a folder with a single command:
 
 ```shell
-$ python torcrawl.py -v -u http://www.github.com/ -c -d 2 -p 5 -e
-## TOR is ready!
-## URL: http://www.github.com/
-## Your IP: *.*.*.*
-## Crawler Started from http://www.github.com with step 1 and wait 5
-## Step 1 completed with: 11 results
-## File created on /script/path/FolderName/index.htm
-## File created on /script/path/FolderName/projects.html
-## ...
+$ python torcrawl.py -v -u http://github.com/ -c -d 1 -p 1 -e
+[ DEBUG ] TOR is ready!
+[ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: True
+[ DEBUG ] URL :: http://github.com/
+[ DEBUG ] Folder created :: github.com
+[ INFO  ] Crawler started from http://github.com with 1 depth, 1.0 second delay and using 16 Threads. Excluding 'None' links.
+[ INFO  ] Step 1 completed :: 87 result(s)
+[ INFO  ] Network Structure created :: github.com/network_structure.json
+[ INFO  ] Cinex :: Extracting from github.com/links.txt to github.com/extracted
+[ DEBUG ] File created :: github.com/extracted/github.com/collections_.html
+...
+[ DEBUG ] File created :: github.com/extracted/github.community/_.html
 ```
-***Note:*** *The default (and only for now) file for crawler's links is the `links.txt` document. Also, to extract right after the crawl you have to give `-e` argument*
+
+> **Note**
+>
+> The default (and only for now) file for crawler's links is the `links.txt` document.
+> To extract along with crawl `-e` argument is required.
 
 Following the same logic; you can parse all these pages to grep (for example) and search for specific text:
 
 ```shell
-$ python torcrawl.py -u http://www.github.com/ -c -e | grep '</html>'
+$ python torcrawl.py -u http://github.com/ -c -e | grep '</html>'
 </html>
 </html>
 ...
 ```
 
-### As Both + Keyword Search:
+### As Crawler + Extractor + Keyword Search:
 You can crawl a page, perform a keyword search and extract the webpages that match the findings into a folder with a single command:
 
 ```shell
-$ python torcrawl.py -v -u http://www.github.com/ -c -d 2 -p 5 -e -y 0
-## TOR is ready!
-## URL: http://www.github.com/
-## Your IP: *.*.*.*
-## Crawler Started from http://www.github.com with step 1 and wait 5
-## Step 1 completed with: 11 results
-## File created on /script/path/FolderName/index.htm
-## File created on /script/path/FolderName/projects.html
-## ...
+$ python torcrawl.py -v -u http://github.com/ -o github.html -y 0
+[ DEBUG ] TOR is ready!
+[ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: True
+[ DEBUG ] URL :: http://github.com/
+[ DEBUG ] Folder created :: github.com
+[ INFO  ] Outex :: Extracting http://github.com to github.com/github.html
+[ DEBUG ] http://github.com :: Yara match found!
 ```
 
-***Note:*** *Update res/keyword.yar to search for other keywords.
-Use ```-y 0``` for raw html searching and ```-y 1``` for text search only.*
+### Visualization of the Network Structure:
+Provide `-s` argument to create graphs to gain [insights](https://github.com/PROxZIMA/DarkSpider/pull/13) from the generated data,
 
-## Demo:
-![peek 2018-12-08 16-11](https://user-images.githubusercontent.com/9204902/49687660-f72f8280-fb0e-11e8-981e-1bbeeac398cc.gif)
+```shell
+$ python torcrawl.py -u "http://github.com/" -c -d 2 -p 1 -t 32 -s
+## Crawler started from http://github.com with 2 depth, 1.0 second delay and using 32 Threads. Excluding 'None' links.
+## Step 1 completed :: 87 result(s)
+## Step 2 completed :: 4508 result(s)
+## Network Structure created :: github.com/network_structure.json
+## Generating :: Scatter Plot of the indegree vs nodes of the graph...
+## Generating :: Bar Graph of the indegree vs percentage of nodes of the graph...
+## Generating :: Scatter Plot of the outdegree vs nodes of the graph...
+## Generating :: Bar Graph of the outdegree vs percentage of nodes of the graph...
+## Generating :: Bar Graph of the eigenvector centrality vs percentage of nodes of the graph...
+## Generating :: Bar Graph of the pagerank vs percentage of nodes of the graph...
+## Generating :: Visualization of the graph...
+```
 
-## TODO:
-- [x] Store links relation in one-to-may json dictionary format
-- [x] Plot the graphical network of the generated json using [`NetworkX`](https://networkx.org/) package.
-- [x] Crawl images and scripts
-- [x] -z, --exclusions  : Paths that you don't want to include
-- [x] -t, --thread: How many pages to visit at the same time
+> **Note**
+>
+> Output in Readme is trimmed for better readability. General [verbose output](./assets/logging.png) is much detailed.
 
 ## Credits
 - [**@MikeMeliz**](https://github.com/MikeMeliz) for initial [`TorCrawl`](https://github.com/MikeMeliz/TorCrawl.py) codebase
@@ -221,8 +256,32 @@ Feel free to contribute on this project! Just fork it, make any change on your f
 ## License:
 “GPL” stands for “General Public License”. Using the GNU GPL will require that all the released improved versions be free software. [source & more](https://www.gnu.org/licenses/gpl-faq.html)
 
+
 ## Changelog:
-```
-v1:
-    * Initial project setup
-```
+
+    v2.0.0:
+### What's Changed
+* Add: Project IEEE citation by @PROxZIMA in https://github.com/PROxZIMA/DarkSpider/pull/8
+* Fix: Ignore Gooey installation by default by @PROxZIMA in https://github.com/PROxZIMA/DarkSpider/pull/9
+* Add: CLI command to include/exclude external links by @PROxZIMA in https://github.com/PROxZIMA/DarkSpider/pull/11
+* Fixed Issue related to Graphical Analysis by @knightster0804 in https://github.com/PROxZIMA/DarkSpider/pull/10
+* Revert "Fixed Issue related to Graphical Analysis" by @PROxZIMA in https://github.com/PROxZIMA/DarkSpider/pull/12
+* Creating json by @r0nl in https://github.com/PROxZIMA/DarkSpider/pull/14
+* Added 'exclusion' Argument by @r0nl in https://github.com/PROxZIMA/DarkSpider/pull/16
+* Added required functionalities and Images by @knightster0804 in https://github.com/PROxZIMA/DarkSpider/pull/13
+* White box unit test cases for modules by @PROxZIMA in https://github.com/PROxZIMA/DarkSpider/pull/7
+* New graphical visualization using `seaborn` library by @PROxZIMA in https://github.com/PROxZIMA/DarkSpider/pull/17
+* Added image and script crawler by @ytatiya3 in https://github.com/PROxZIMA/DarkSpider/pull/15
+
+### New Contributors
+* @PROxZIMA made their first contribution in https://github.com/PROxZIMA/DarkSpider/pull/8
+* @knightster0804 made their first contribution in https://github.com/PROxZIMA/DarkSpider/pull/10
+* @r0nl made their first contribution in https://github.com/PROxZIMA/DarkSpider/pull/14
+* @ytatiya3 made their first contribution in https://github.com/PROxZIMA/DarkSpider/pull/15
+
+**Full Changelog**: https://github.com/PROxZIMA/DarkSpider/compare/1.0.0...21
+
+    v1.0.0:
+* Initial project setup
+
+**Full Changelog**: https://github.com/PROxZIMA/DarkSpider/commits/1.0.0
diff --git a/assets/logging.png b/assets/logging.png
new file mode 100644
index 0000000000000000000000000000000000000000..887bedc84f553ee7d5ee1f1a981c6224f1b9f6ad
GIT binary patch
literal 99291
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

literal 0
HcmV?d00001


From addfa798744a6c3f47096f514f2aad58bce0390b Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Tue, 20 Sep 2022 19:01:18 +0530
Subject: [PATCH 30/39] Refactor: Simple logging format for StreamHandler

---
 modules/helpers/helper.py | 50 ++++++++++++++++++++++-----------------
 torcrawl.py               |  1 +
 2 files changed, 29 insertions(+), 22 deletions(-)

diff --git a/modules/helpers/helper.py b/modules/helpers/helper.py
index 21097d1..9092586 100644
--- a/modules/helpers/helper.py
+++ b/modules/helpers/helper.py
@@ -76,7 +76,7 @@ def doRollover(self):
 
 
 def setup_custom_logger(
-    name: str, filename: str = "log.log", verbose_: bool = False, filelog: bool = True
+    name: str, filename: str = "log.log", verbose_: bool = False, filelog: bool = True, argv: list[str] = None
 ) -> logging.Logger:
     """Setup custom logger with stream and file handlers
 
@@ -89,38 +89,44 @@ def setup_custom_logger(
     Returns:
         Logger object with custom handlers and formatters.
     """
-    formatter = logging.Formatter(
-        fmt="{asctime} [{levelname:^7s}] [{filename}:{lineno}] {message}",
-        style="{",
-        datefmt="%Y-%m-%d %H:%M:%S",
-    )
-
     logger = logging.getLogger(name)
     logger.setLevel(logging.DEBUG)
-    logger.handlers.clear()
+    logger.handlers.clear()  # Clear all handlers
 
-    screen_handler = logging.StreamHandler(stream=sys.stdout)
-    screen_handler.setFormatter(formatter)
-    screen_handler.setLevel(logging.DEBUG)
+    # Create file handler if filelog is True
+    if filelog:
+        file_handler = RollingFileHandler(filename=filename, mode="w", maxBytes=1024 * 1024 * 10)
+        file_handler.setFormatter(None)
+        file_handler.setLevel(logging.DEBUG)
+        logger.addHandler(file_handler)
 
-    # Set simple formatter for file non-verbose logging
-    if not verbose_:
-        screen_handler.setFormatter(
+        # Add a single non-formatted terminal command to the log file only
+        if argv:
+            logger.info("$ python %s \n", " ".join(argv))
+
+        # Update the formatter for the file handler
+        logger.handlers[0].setFormatter(
             logging.Formatter(
-                fmt="## {message}",
+                fmt="{asctime} |{levelname:^7s}| {filename}:{lineno} | {message}",
                 style="{",
                 datefmt="%Y-%m-%d %H:%M:%S",
             )
         )
-        screen_handler.setLevel(logging.INFO)
 
-    logger.addHandler(screen_handler)
+    # Simple formatter for non-verbose logging
+    fmt, level = ("[{levelname:^7s}] {message}", logging.DEBUG) if verbose_ else ("## {message}", logging.INFO)
 
-    if filelog:
-        file_handler = RollingFileHandler(filename=filename, mode="w", maxBytes=1024 * 1024 * 10)
-        file_handler.setFormatter(formatter)
-        file_handler.setLevel(logging.DEBUG)
-        logger.addHandler(file_handler)
+    # Add screen handler with custom formatter
+    screen_handler = logging.StreamHandler(stream=sys.stdout)
+    screen_handler.setFormatter(
+        logging.Formatter(
+            fmt=fmt,
+            style="{",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+    )
+    screen_handler.setLevel(level)
+    logger.addHandler(screen_handler)
 
     return logger
 
diff --git a/torcrawl.py b/torcrawl.py
index 65f5f83..e35d2be 100755
--- a/torcrawl.py
+++ b/torcrawl.py
@@ -280,6 +280,7 @@ def main():
         filename=os.path.join(out_path, "crawl.log"),
         verbose_=args.verbose,
         filelog=args.log,
+        argv=sys.argv,
     )
 
     # Connect to TOR

From c50a3ccdb12c4b87c3c0a617b8b121b6e43800af Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Tue, 20 Sep 2022 19:31:34 +0530
Subject: [PATCH 31/39] Refactor: Script name torcrawl -> darkspider

---
 README.md                    | 28 ++++++++++++++--------------
 torcrawl.py => darkspider.py | 10 +++++-----
 2 files changed, 19 insertions(+), 19 deletions(-)
 rename torcrawl.py => darkspider.py (97%)

diff --git a/README.md b/README.md
index f861dd1..e1573d7 100644
--- a/README.md
+++ b/README.md
@@ -23,14 +23,14 @@ DarkSpider is a python script to crawl and extract (regular or onion) webpages t
 With a single argument you can read an .onion webpage or a regular one through TOR Network and using pipes you can pass the output at any other tool you prefer.
 
 ```shell
-$ python torcrawl.py -u http://github.com/ | grep 'google-site-verification'
+$ python darkspider.py -u http://github.com/ | grep 'google-site-verification'
     <meta name="google-site-verification" content="xxxx">
 ```
 
 If you want to crawl the links of a webpage use the `-c` and you will get a folder all the extracted links. You can even use `-d` to crawl them and so on. As far, there is also the necessary argument `-p` to wait some seconds before the next crawl.
 
 ```shell
-$ python torcrawl.py -v -u http://github.com/ -c -d 2 -p 2
+$ python darkspider.py -v -u http://github.com/ -c -d 2 -p 2
 [ DEBUG ] TOR is ready!
 [ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: True
 [ DEBUG ] URL :: http://github.com
@@ -94,7 +94,7 @@ Args | Long | Description
 - To just extract a single webpage to terminal:
 
 ```shell
-$ python torcrawl.py -u http://github.com/
+$ python darkspider.py -u http://github.com/
 ## Termex :: Extracting http://github.com to terminal
 ## http://github.com ::
 <!DOCTYPE html>
@@ -105,21 +105,21 @@ $ python torcrawl.py -u http://github.com/
 - Extract into a file (github.html) without the use of TOR:
 
 ```shell
-$ python torcrawl.py -w -u http://github.com -o github.html
+$ python darkspider.py -w -u http://github.com -o github.html
 ## Outex :: Extracting http://github.com to github.com/github.html
 ```
 
 - Extract to terminal and find only the line with google-site-verification:
 
 ```shell
-$ python torcrawl.py -u http://github.com/ | grep 'google-site-verification'
+$ python darkspider.py -u http://github.com/ | grep 'google-site-verification'
     <meta name="google-site-verification" content="xxxx">
 ```
 
 - Extract to file and find only the line with google-site-verification using `yara`:
 
 ```shell
-$ python torcrawl.py -v -w -u https://github.com -e -y 0
+$ python darkspider.py -v -w -u https://github.com -e -y 0
 ...
 ```
 
@@ -131,7 +131,7 @@ $ python torcrawl.py -v -w -u https://github.com -e -y 0
 - Extract a set of webpages (imported from file) to a folder:
 
 ```shell
-$ python torcrawl.py -i links.txt -f links_output
+$ python darkspider.py -i links.txt -f links_output
 ...
 ```
 
@@ -139,7 +139,7 @@ $ python torcrawl.py -i links.txt -f links_output
 - Crawl the links of the webpage without the use of TOR, also show verbose output (really helpful):
 
 ```shell
-$ python torcrawl.py -v -w -u http://github.com/ -c
+$ python darkspider.py -v -w -u http://github.com/ -c
 [ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: False
 [ DEBUG ] URL :: http://github.com/
 [ DEBUG ] Folder created :: github.com
@@ -151,7 +151,7 @@ $ python torcrawl.py -v -w -u http://github.com/ -c
 - Crawl the webpage with depth 2 (2 clicks) and 5 seconds waiting before crawl the next page:
 
 ```shell
-$ python torcrawl.py -v -u http://github.com/ -c -d 2 -p 5
+$ python darkspider.py -v -u http://github.com/ -c -d 2 -p 5
 [ DEBUG ] TOR is ready!
 [ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: True
 [ DEBUG ] URL :: http://github.com
@@ -165,7 +165,7 @@ $ python torcrawl.py -v -u http://github.com/ -c -d 2 -p 5
 Crawl the webpage with depth 1 (1 clicks), 1 seconds pause and exclude links that match `.*\.blog`:
 
 ```shell
-$ python torcrawl.py -v -u http://github.com/ -c -d 1 -p 1 -z ".*\.blog"
+$ python darkspider.py -v -u http://github.com/ -c -d 1 -p 1 -z ".*\.blog"
 [ DEBUG ] TOR is ready!
 [ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: True
 [ DEBUG ] URL :: http://github.com/
@@ -179,7 +179,7 @@ $ python torcrawl.py -v -u http://github.com/ -c -d 1 -p 1 -z ".*\.blog"
 You can crawl a page and also extract the webpages into a folder with a single command:
 
 ```shell
-$ python torcrawl.py -v -u http://github.com/ -c -d 1 -p 1 -e
+$ python darkspider.py -v -u http://github.com/ -c -d 1 -p 1 -e
 [ DEBUG ] TOR is ready!
 [ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: True
 [ DEBUG ] URL :: http://github.com/
@@ -201,7 +201,7 @@ $ python torcrawl.py -v -u http://github.com/ -c -d 1 -p 1 -e
 Following the same logic; you can parse all these pages to grep (for example) and search for specific text:
 
 ```shell
-$ python torcrawl.py -u http://github.com/ -c -e | grep '</html>'
+$ python darkspider.py -u http://github.com/ -c -e | grep '</html>'
 </html>
 </html>
 ...
@@ -211,7 +211,7 @@ $ python torcrawl.py -u http://github.com/ -c -e | grep '</html>'
 You can crawl a page, perform a keyword search and extract the webpages that match the findings into a folder with a single command:
 
 ```shell
-$ python torcrawl.py -v -u http://github.com/ -o github.html -y 0
+$ python darkspider.py -v -u http://github.com/ -o github.html -y 0
 [ DEBUG ] TOR is ready!
 [ DEBUG ] Your IP: XXX.XXX.XXX.XXX :: Tor Connection: True
 [ DEBUG ] URL :: http://github.com/
@@ -224,7 +224,7 @@ $ python torcrawl.py -v -u http://github.com/ -o github.html -y 0
 Provide `-s` argument to create graphs to gain [insights](https://github.com/PROxZIMA/DarkSpider/pull/13) from the generated data,
 
 ```shell
-$ python torcrawl.py -u "http://github.com/" -c -d 2 -p 1 -t 32 -s
+$ python darkspider.py -u "http://github.com/" -c -d 2 -p 1 -t 32 -s
 ## Crawler started from http://github.com with 2 depth, 1.0 second delay and using 32 Threads. Excluding 'None' links.
 ## Step 1 completed :: 87 result(s)
 ## Step 2 completed :: 4508 result(s)
diff --git a/torcrawl.py b/darkspider.py
similarity index 97%
rename from torcrawl.py
rename to darkspider.py
index e35d2be..00d405e 100755
--- a/torcrawl.py
+++ b/darkspider.py
@@ -4,11 +4,11 @@
 DarkSpider is a python script to crawl and extract (regular or onion)
 webpages through TOR network.
 
-usage: python torcrawl.py [options]
-python torcrawl.py -u l0r3m1p5umD0lorS1t4m3t.onion
-python torcrawl.py -v -w -u http://www.github.com -o github.htm
-python torcrawl.py -v -u l0r3m1p5umD0lorS1t4m3t.onion -c -d 2 -p 5
-python torcrawl.py -v -w -u http://www.github.com -c -d 2 -p 5 -e -f GitHub
+usage: python darkspider.py [options]
+python darkspider.py -u l0r3m1p5umD0lorS1t4m3t.onion
+python darkspider.py -v -w -u http://www.github.com -o github.htm
+python darkspider.py -v -u l0r3m1p5umD0lorS1t4m3t.onion -c -d 2 -p 5
+python darkspider.py -v -w -u http://www.github.com -c -d 2 -p 5 -e -f GitHub
 
 General:
 -h, --help         : Help

From 91a08958782b48780253fbd164a03ef4c672d54e Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Tue, 20 Sep 2022 21:33:10 +0530
Subject: [PATCH 32/39] Refactor: Moved module classes to modules/ root

---
 darkspider.py                         | 7 +++----
 modules/__init__.py                   | 3 +++
 modules/checker.py                    | 4 ++--
 modules/crawler.py                    | 2 +-
 modules/extractor.py                  | 2 +-
 modules/helper/__init__.py            | 1 +
 modules/{helpers => helper}/helper.py | 2 +-
 modules/helpers/__init__.py           | 0
 modules/visualization.py              | 2 +-
 9 files changed, 13 insertions(+), 10 deletions(-)
 create mode 100644 modules/helper/__init__.py
 rename modules/{helpers => helper}/helper.py (99%)
 delete mode 100644 modules/helpers/__init__.py

diff --git a/darkspider.py b/darkspider.py
index 00d405e..074ecee 100755
--- a/darkspider.py
+++ b/darkspider.py
@@ -55,7 +55,7 @@
 
 import requests
 
-from modules.helpers.helper import get_tor_proxies, setup_custom_logger
+from modules.helper import get_tor_proxies, setup_custom_logger
 
 try:
     from gooey import Gooey, GooeyParser
@@ -64,10 +64,9 @@
 except ModuleNotFoundError:
     GOOEY_AVAILABLE = False
 
-from modules.checker import check_ip, check_tor, extract_domain, folder, url_canon
-
 # DarkSpider Modules
-from modules.crawler import Crawler
+from modules import Crawler
+from modules.checker import check_ip, check_tor, extract_domain, folder, url_canon
 from modules.extractor import Extractor
 from modules.visualization import Visualization
 
diff --git a/modules/__init__.py b/modules/__init__.py
index e69de29..d21d012 100644
--- a/modules/__init__.py
+++ b/modules/__init__.py
@@ -0,0 +1,3 @@
+from modules.crawler import Crawler
+from modules.extractor import Extractor
+from modules.visualization import Visualization
diff --git a/modules/checker.py b/modules/checker.py
index 54b3b09..0a03168 100644
--- a/modules/checker.py
+++ b/modules/checker.py
@@ -7,7 +7,7 @@
 import psutil
 import requests
 
-from modules.helpers.helper import TorProxyException, get_requests_header
+from modules.helper import TorProxyException, get_requests_header
 
 
 def url_canon(website: str, www: bool = False) -> tuple[bool, str]:
@@ -133,4 +133,4 @@ def check_ip(
         return check2
     except Exception as err:
         logger.exception(err)
-        sys.exit(2)
+        raise
diff --git a/modules/crawler.py b/modules/crawler.py
index fa8e3fb..df29e3f 100644
--- a/modules/crawler.py
+++ b/modules/crawler.py
@@ -13,7 +13,7 @@
 from requests.models import Response
 
 from modules.checker import url_canon
-from modules.helpers.helper import get_requests_header
+from modules.helper import get_requests_header
 
 
 class Crawler:
diff --git a/modules/extractor.py b/modules/extractor.py
index 339fc6b..fe1054a 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -14,7 +14,7 @@
 from bs4 import BeautifulSoup
 
 from modules.checker import folder
-from modules.helpers.helper import get_requests_header
+from modules.helper import get_requests_header
 
 # Type hinting aliases
 ExcInfo = Exception | bool
diff --git a/modules/helper/__init__.py b/modules/helper/__init__.py
new file mode 100644
index 0000000..ffbec22
--- /dev/null
+++ b/modules/helper/__init__.py
@@ -0,0 +1 @@
+from .helper import *
diff --git a/modules/helpers/helper.py b/modules/helper/helper.py
similarity index 99%
rename from modules/helpers/helper.py
rename to modules/helper/helper.py
index 9092586..abab7ff 100644
--- a/modules/helpers/helper.py
+++ b/modules/helper/helper.py
@@ -181,4 +181,4 @@ def traceback_name(error: Exception) -> str:
 
 class TorProxyException(Exception):
     "Exception raised for errors in the Tor proxy. This might happen if the Tor is running but the application is using a different port."
-    pass
+    error_code = 69
diff --git a/modules/helpers/__init__.py b/modules/helpers/__init__.py
deleted file mode 100644
index e69de29..0000000
diff --git a/modules/visualization.py b/modules/visualization.py
index fb9c2bb..6014555 100644
--- a/modules/visualization.py
+++ b/modules/visualization.py
@@ -9,7 +9,7 @@
 from matplotlib.ticker import MultipleLocator
 
 from modules.checker import folder
-from modules.helpers.helper import verbose
+from modules.helper import verbose
 
 
 class Visualization:

From 3e9ec558c9d1614b05fe1167e19e422513b6a9e5 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Tue, 20 Sep 2022 22:37:49 +0530
Subject: [PATCH 33/39] Update: Now raise critical error instead of sys.exit

---
 modules/checker.py       | 35 ++++++++++++++++++++++++-----------
 modules/helper/helper.py |  7 ++++++-
 2 files changed, 30 insertions(+), 12 deletions(-)

diff --git a/modules/checker.py b/modules/checker.py
index 0a03168..4790836 100644
--- a/modules/checker.py
+++ b/modules/checker.py
@@ -8,6 +8,7 @@
 import requests
 
 from modules.helper import TorProxyException, get_requests_header
+from modules.helper.helper import TorServiceException
 
 
 def url_canon(website: str, www: bool = False) -> tuple[bool, str]:
@@ -78,17 +79,24 @@ def check_tor(logger: Logger) -> Optional[bool]:
 
     Returns:
         True if TOR service is running.
-    """
-    for i in psutil.process_iter():
-        if "tor" == i.name().lower().rstrip(".exe"):
-            logger.debug("TOR is ready!")
-            break
-    else:
-        logger.critical("TOR is NOT running!")
-        logger.critical("Enable tor with 'service tor start' or add -w argument")
-        sys.exit(2)
 
-    return True
+    Raises:
+        TorServiceException: If Tor Service is not working.
+    """
+    try:
+        tor = "tor"
+        for i in psutil.process_iter():
+            if tor == i.name().lower().rstrip(".exe"):
+                logger.debug("TOR is ready!")
+                break
+        else:
+            raise TorServiceException("TOR is NOT running! Enable tor with 'service tor start' or add -w argument")
+        return True
+    except Exception as err:
+        # We could've logged the TorServiceException where it was raised and could've avoided try/catch block
+        # but we want to log unexpected errors too and raise all the exception
+        logger.critical(err)
+        raise
 
 
 def check_ip(
@@ -107,6 +115,9 @@ def check_ip(
 
         {"IsTor":True,
         "IP":"185.165.171.46"}
+
+    Raises:
+        TorProxyException: If Tor proxy is not working.
     """
     addr = "https://check.torproject.org/api/ip"
     headers = get_requests_header()
@@ -132,5 +143,7 @@ def check_ip(
 
         return check2
     except Exception as err:
-        logger.exception(err)
+        # We could've logged the TorProxyException where it was raised and could've avoided try/catch block
+        # but we want to log unexpected errors too and raise all the exception
+        logger.critical(err)
         raise
diff --git a/modules/helper/helper.py b/modules/helper/helper.py
index abab7ff..f3320dd 100644
--- a/modules/helper/helper.py
+++ b/modules/helper/helper.py
@@ -180,5 +180,10 @@ def traceback_name(error: Exception) -> str:
 
 
 class TorProxyException(Exception):
-    "Exception raised for errors in the Tor proxy. This might happen if the Tor is running but the application is using a different port."
+    "Exception raised for errors in the Tor proxy. This might happen if the Tor Service is running but the application is using a different port."
     error_code = 69
+
+
+class TorServiceException(Exception):
+    "Exception raised for errors in the Tor Service. This error is raised if the Tor Service is not running."
+    error_code = 96

From 456e37164db5ffb1763eae9a237762afad7306a2 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Tue, 20 Sep 2022 22:38:20 +0530
Subject: [PATCH 34/39] Update: Checker module test cases

---
 modules/tests/test_checker.py | 208 ++++++++++++++++++++++------------
 1 file changed, 136 insertions(+), 72 deletions(-)

diff --git a/modules/tests/test_checker.py b/modules/tests/test_checker.py
index 2df5290..92a8ff8 100644
--- a/modules/tests/test_checker.py
+++ b/modules/tests/test_checker.py
@@ -2,9 +2,41 @@
 import re
 import shutil
 import unittest
+from typing import Iterator
+from unittest import mock
 
 from modules.checker import check_ip, check_tor, extract_domain, folder, url_canon
-from modules.helpers.helper import Capturing
+from modules.helper import TorProxyException, get_tor_proxies, setup_custom_logger
+from modules.helper.helper import TorServiceException
+
+
+class MockedPsutilProcess:
+    """Custom class for mock testing psutil process"""
+
+    def __init__(self, _name: str):
+        self._name = _name
+
+    def name(self) -> str:
+        """Returns the name of the process"""
+        return self._name
+
+
+def mocked_psutil_process_iter(has_tor: bool = True) -> list[Iterator[MockedPsutilProcess]]:
+    """Custom sideeffect for mock testing psutil process
+
+    Args:
+        has_tor: True if tor is to be included else False.
+
+    Returns:
+        List of processes.
+    """
+
+    response = [MockedPsutilProcess("firefox"), MockedPsutilProcess("chrome")]
+
+    if has_tor:
+        response.append(MockedPsutilProcess("tor"))
+
+    return [iter(response)]
 
 
 class TestCheckerFunctions(unittest.TestCase):
@@ -13,94 +45,126 @@ class TestCheckerFunctions(unittest.TestCase):
     @classmethod
     def setUpClass(cls) -> None:
         """Test Suite Setup."""
-        pass
+        cls.logger = setup_custom_logger(
+            name="testlog",
+            filename=None,
+            verbose_=False,
+            filelog=False,
+            argv=None,
+        )
 
     @classmethod
     def tearDownClass(cls):
         """Test Suite Teardown."""
         # Remove test folder.
-        shutil.rmtree("torcrawl", ignore_errors=True)
+        shutil.rmtree("darkspider", ignore_errors=True)
 
     def test_url_canon_001(self):
-        """url_canon unit test.
-        Returns true if the function successfully performs URL normalisation.
-        """
-        url = "torcrawl.com"
-        expected = "http://www.torcrawl.com"
-        result = url_canon(url, verbose=False)
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        """url_canon unit test."""
+        url = "www.darkspider.com"
+        expected = (True, "http://www.darkspider.com")
+        result = url_canon(url, www=False)
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
     def test_url_canon_002(self):
-        """url_canon unit test.
-        Returns true if the function successfully performs URL normalisation.
-        """
-        url = "www.torcrawl.com"
-        expected = "http://www.torcrawl.com"
-        result = url_canon(url, verbose=False)
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        """url_canon unit test."""
+        url = "www.darkspider.com"
+        expected = (True, "http://www.darkspider.com")
+        result = url_canon(url, www=True)
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
+
+    def test_url_canon_003(self):
+        """url_canon unit test."""
+        url = "darkspider.com"
+        expected = (True, "http://www.darkspider.com")
+        result = url_canon(url, www=True)
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
+
+    def test_url_canon_004(self):
+        """url_canon unit test."""
+        url = "http://darkspider.com/"
+        expected = (False, "http://darkspider.com")
+        result = url_canon(url, www=False)
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
     def test_extract_domain_001(self):
-        """extract_domain test.
-        Returns true if correct domain is returned.
-        """
-        url = "http://www.torcrawl.com/test/domain-extract/api?id=001"
-        expected = "www.torcrawl.com"
+        """extract_domain test."""
+        url = "http://darkspider.com/test/domain-extract/api?id=001"
+        expected = "darkspider.com"
         result = extract_domain(url, remove_http=True)
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
     def test_extract_domain_002(self):
-        """extract_domain test.
-        Returns true if correct domain is returned.
-        """
-        url = "http://www.torcrawl.com/test/domain-extract/api?id=002"
-        expected = "http://www.torcrawl.com"
+        """extract_domain test."""
+        url = "http://darkspider.com/test/domain-extract/api?id=002"
+        expected = "http://darkspider.com"
         result = extract_domain(url, remove_http=False)
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    def test_folder_creation(self):
-        """folder creation test.
-        Returns true if folder is successfully created.
-        """
-        _input = "torcrawl"
+    def test_folder_creation_001(self):
+        """folder creation test."""
+        _input = "darkspider"
         result = folder(_input, False)
+        self.assertTrue(os.path.exists(result), f"Test Fail:: could not find folder {_input}")
+
+    def test_folder_creation_002(self):
+        """folder creation test."""
+        _input = "darkspider/deep/folder/file.txt"
+        result = folder(_input, True)
+        self.assertTrue(os.path.exists(os.path.dirname(result)), f"Test Fail:: could not find directory of {_input}")
+
+    def test_check_ip_001(self):
+        """check_ip test."""
+
+        with self.assertRaises(Exception) as error:
+            # `None proxy` and `with tor` will raise exception.
+            check_ip(proxies=None, url=None, logger=self.logger, without_tor=False)
+
+        self.assertEqual(error.exception.error_code, TorProxyException.error_code)
+
+    def test_check_ip_002(self):
+        """check_ip test."""
+        expected_ip = r"^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$"
+
+        response = check_ip(proxies=None, url=None, logger=self.logger, without_tor=True)
+
+        self.assertTrue(
+            bool(re.match(expected_ip, response["IP"])),
+            f"Test Fail:: expected = {expected_ip}, got {response['IP']}",
+        )
+        self.assertFalse(
+            response["IsTor"],
+            f"Test Fail:: Tor proxy flag must be False, got {response['IsTor']}",
+        )
+
+    def test_check_ip_003(self):
+        """check_ip test."""
+        expected_ip = r"^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$"
+
+        response = check_ip(proxies=get_tor_proxies(), url=None, logger=self.logger, without_tor=True)
+
+        self.assertTrue(
+            bool(re.match(expected_ip, response["IP"])),
+            f"Test Fail:: expected = {expected_ip}, got {response['IP']}",
+        )
         self.assertTrue(
-            os.path.exists(result), f"Test Fail:: could not find folder {_input}"
+            response["IsTor"],
+            f"Test Fail:: Tor proxy flag must be True, got {response['IsTor']}",
         )
 
-    def test_check_tor(self):
-        """folder creation test.
-        Returns true if folder is successfully created.
-        """
-        expected_ip = r"^## Your IP: (?:[0-9]{1,3}\.){3}[0-9]{1,3}$"
-        expected_error = [
-            "Error: <class 'urllib.error.HTTPError'> ",
-            "## IP cannot be obtained. ",
-            "## Is https://api.ipify.org/?format=json up? ",
-            "## HTTPError: HTTP Error 404: Not Found",
-        ]
-
-        with Capturing() as result:
-            check_ip()
-
-        if result[0].startswith("## Your IP:"):
-            self.assertEqual(
-                re.findall(expected_ip, result[0]),
-                result,
-                f"Test Fail:: expected = {expected_ip}, got {result}",
-            )
-        else:
-            self.assertEqual(
-                expected_error,
-                result,
-                f"Test Fail:: expected = {expected_ip}, got {result}",
-            )
-
-    # TODO: Implement check_tor tests.
+    @mock.patch("psutil.process_iter", side_effect=mocked_psutil_process_iter(has_tor=True))
+    def test_check_tor_001(self, _):
+        """check_tor test."""
+        self.assertTrue(
+            check_tor(self.logger),
+            "Test Fail:: Tor Service must be running",
+        )
+
+    @mock.patch("psutil.process_iter", side_effect=mocked_psutil_process_iter(has_tor=False))
+    def test_check_tor_002(self, _):
+        """check_tor test."""
+        with self.assertRaises(Exception) as error:
+            # `None proxy` and `with tor` will raise exception.
+            check_tor(self.logger)
+
+        self.assertEqual(error.exception.error_code, TorServiceException.error_code)

From b1c3375331867dcd1044d7c9fc9fb84e79b5575e Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Tue, 20 Sep 2022 23:19:34 +0530
Subject: [PATCH 35/39] Update: Crawler module test cases

---
 modules/tests/test_crawler.py | 76 +++++++++++++++++++++--------------
 1 file changed, 46 insertions(+), 30 deletions(-)

diff --git a/modules/tests/test_crawler.py b/modules/tests/test_crawler.py
index 5411dd4..68d9ada 100644
--- a/modules/tests/test_crawler.py
+++ b/modules/tests/test_crawler.py
@@ -1,10 +1,12 @@
 import shutil
 import unittest
-from copy import copy
 
+from modules import Crawler
 from modules.checker import extract_domain, folder
-from modules.crawler import Crawler
-from modules.helpers.helper import Capturing
+from modules.helper import setup_custom_logger
+
+# Disable sorted test case loading
+unittest.TestLoader.sortTestMethodsUsing = lambda *args: -1
 
 
 class TestCrawlerFunctions(unittest.TestCase):
@@ -15,21 +17,36 @@ def setUpClass(cls):
         """Test Suite Setup."""
         cls._website = "http://info.cern.ch/"
         cls.out_path = out_path = folder(extract_domain(cls._website), False)
+        cls.logger = setup_custom_logger(
+            name="testlog",
+            filename=None,
+            verbose_=False,
+            filelog=False,
+            argv=None,
+        )
         cls.crawler = Crawler(
             website=cls._website,
+            proxies=None,
             c_depth=1,
             c_pause=1,
             out_path=out_path,
             external=False,
-            thread=1,
-            logs=False,
-            verbose=False,
             exclusion=None,
+            thread=1,
+            logger=cls.logger,
         )
-        cls.crawler_ex = copy(cls.crawler)
-        cls.crawler_ex.external = True
         # Exclude links with subdomain='home.web'
-        cls.crawler_ex.exclusion = ".*//home\.web.*"
+        cls.crawler_ex = Crawler(
+            website=cls._website,
+            proxies=None,
+            c_depth=1,
+            c_pause=1,
+            out_path=out_path,
+            external=True,
+            exclusion=".*//home\.web.*",
+            thread=1,
+            logger=cls.logger,
+        )
 
     @classmethod
     def tearDownClass(cls):
@@ -38,17 +55,14 @@ def tearDownClass(cls):
         shutil.rmtree(cls.out_path)
 
     def test_excludes(self):
-        """Test crawler.excludes function.
-        Return True if the function successfully excludes the the provided
-        failing links.
-        """
+        """Test crawler.excludes function."""
         _uri = self._website
         failing_links = [
             None,
             "#",
             "http://home.web.cern.ch/topics",
             "tel:012-013-104-5",
-            "mailto:test@torcrawl.com",
+            "mailto:test@darkspider.com",
             f"{_uri}/res/test.pdf",
             f"{_uri}/res/test.jpg",
             f"{_uri}/res/test.jpeg",
@@ -73,10 +87,7 @@ def test_excludes(self):
         )
 
     def test_canonical(self):
-        """Test crawler.canonical function.
-        Return True if the function successfully normalizes the provided
-        failing links.
-        """
+        """Test crawler.canonical function."""
         _uri = self._website
         links = [
             [f"{_uri}sundance", f"{_uri}sundance"],
@@ -94,15 +105,12 @@ def test_canonical(self):
                 f"Test Fail:: Canon returned = {result}, expected {link[1]}",
             )
 
-    def test_crawl(self):
-        """Test Crawlwer.crawl functionality
-
-        Return: List (ord_lst) - List of crawled links."""
+    def test_crawl_001(self):
+        """Test Crawler.crawl functionality"""
         _uri = self._website
 
-        with Capturing() as _:
-            result = self.crawler.crawl()
-            result_ex = self.crawler_ex.crawl()
+        # with Capturing() as _:
+        result = self.crawler.crawl()
 
         expected = {
             _uri: [
@@ -110,6 +118,19 @@ def test_crawl(self):
             ]
         }
 
+        self.assertCountEqual(
+            expected,
+            result,
+            f"Test Fail:: Crawler returned = {result}, expected {expected}",
+        )
+
+    def test_crawl_002(self):
+        """Test Crawler.crawl functionality"""
+        _uri = self._website
+
+        # with Capturing() as _:
+        result_ex = self.crawler_ex.crawl()
+
         # Following links are excluded as they match the exclusion pattern
         # http://home.web.cern.ch/topics/birth-web
         # http://home.web.cern.ch/about
@@ -120,11 +141,6 @@ def test_crawl(self):
             ]
         }
 
-        self.assertCountEqual(
-            expected,
-            result,
-            f"Test Fail:: Crawler returned = {result}, expected {expected}",
-        )
         self.assertCountEqual(
             expected_ex,
             result_ex,

From 4088847e6c6613f02c2d3b9b35a0388caf88eb92 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Tue, 20 Sep 2022 23:29:14 +0530
Subject: [PATCH 36/39] Update: Visualization module test cases

---
 modules/tests/test_visualization.py | 62 +++++++++++------------------
 1 file changed, 23 insertions(+), 39 deletions(-)

diff --git a/modules/tests/test_visualization.py b/modules/tests/test_visualization.py
index 512e0ae..90c781d 100644
--- a/modules/tests/test_visualization.py
+++ b/modules/tests/test_visualization.py
@@ -2,23 +2,15 @@
 import shutil
 import unittest
 
+from modules import Crawler
 from modules.checker import extract_domain, folder
-from modules.crawler import Crawler
-from modules.helpers.helper import Capturing
+from modules.helper import setup_custom_logger
 from modules.visualization import Visualization
 
 
 def test_plots(self, _func):
     """Base test function for all the plots."""
-    with Capturing() as result:
-        _func()
-
-    expected = [f"## {_func.__doc__}..."]
-    self.assertEqual(
-        expected,
-        result,
-        f"Test Fail:: {_func.__name__} returned = {result}, expected {expected}",
-    )
+    _func()
 
     output = os.path.join(self.obj.out_path, f"{_func.__name__}.png")
     self.assertTrue(
@@ -35,26 +27,32 @@ def setUpClass(cls):
         """Test Suite Setup."""
         cls._website = "http://info.cern.ch/"
         cls.out_path = out_path = folder(extract_domain(cls._website), False)
+        cls.logger = setup_custom_logger(
+            name="testlog",
+            filename=None,
+            verbose_=False,
+            filelog=False,
+            argv=None,
+        )
 
         cls.crawler = Crawler(
             website=cls._website,
-            c_depth=2,
+            proxies=None,
+            c_depth=1,
             c_pause=1,
             out_path=out_path,
             external=True,
-            thread=1,
-            logs=False,
-            verbose=False,
             exclusion=None,
+            thread=1,
+            logger=cls.logger,
         )
 
-        with Capturing() as _:
-            cls.crawler.crawl()
+        cls.crawler.crawl()
 
         cls.obj = Visualization(
             json_file=os.path.join(out_path, cls.crawler.network_file),
             out_path=out_path,
-            verbose=True,
+            logger=cls.logger,
         )
 
     @classmethod
@@ -64,43 +62,29 @@ def tearDownClass(cls):
         shutil.rmtree(cls.out_path)
 
     def test_indegree_plot(self):
-        """Test visualization.indegree_plot function.
-        Scatter Plot of the indegree vs nodes of the graph.
-        """
+        """Test visualization.indegree_plot function."""
         test_plots(self, self.obj.indegree_plot)
 
     def test_indegree_bar(self):
-        """Test visualization.indegree_bar function.
-        Bar Graph of the indegree vs percentage of nodes of the graph.
-        """
+        """Test visualization.indegree_bar function."""
         test_plots(self, self.obj.indegree_bar)
 
     def test_outdegree_plot(self):
-        """Test visualization.outdegree_plot function.
-        Scatter Plot of the outdegree vs nodes of the graph.
-        """
+        """Test visualization.outdegree_plot function."""
         test_plots(self, self.obj.outdegree_plot)
 
     def test_outdegree_bar(self):
-        """Test visualization.outdegree_bar function.
-        Bar Graph of the outdegree vs percentage of nodes of the graph.
-        """
+        """Test visualization.outdegree_bar function."""
         test_plots(self, self.obj.outdegree_bar)
 
     def test_eigenvector_centrality_bar(self):
-        """Test visualization.eigenvector_centrality_bar function.
-        Bar Graph of the eigenvector centrality vs percentage of nodes of the graph.
-        """
+        """Test visualization.eigenvector_centrality_bar function."""
         test_plots(self, self.obj.eigenvector_centrality_bar)
 
     def test_pagerank_bar(self):
-        """Test visualization.pagerank_bar function.
-        Bar Graph of the pagerank vs percentage of nodes of the graph.
-        """
+        """Test visualization.pagerank_bar function."""
         test_plots(self, self.obj.pagerank_bar)
 
     def test_visualize(self):
-        """Test visualization.visualize function.
-        Visualization of the graph.
-        """
+        """Test visualization.visualize function."""
         test_plots(self, self.obj.visualize)

From c3fcc257003719f1f0c84a7900a8dbca327fd8b7 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Wed, 21 Sep 2022 23:34:35 +0530
Subject: [PATCH 37/39] Fix: Full ignore content if yara match not found

---
 modules/extractor.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/modules/extractor.py b/modules/extractor.py
index fe1054a..4f0590f 100644
--- a/modules/extractor.py
+++ b/modules/extractor.py
@@ -305,10 +305,9 @@ def __ex(self, website: str, output_file: str = None, yara: Optional[int] = None
                     )
                 )
 
+                # Don't write to file/terminal if no matches found.
                 if len(full_match_keywords) == 0:
-                    # Don't write to file/terminal if no matches found.
-                    if output_file is not None:
-                        return result
+                    return result
 
             if output_file is not None:
                 with open(output_file, "w", encoding="UTF-8") as file:

From 5c6bfea1e00a31db7c2f084893524762d6e53e25 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Wed, 21 Sep 2022 23:35:14 +0530
Subject: [PATCH 38/39] Refactor: Redundant module import

---
 modules/checker.py            | 4 +---
 modules/tests/test_checker.py | 3 +--
 2 files changed, 2 insertions(+), 5 deletions(-)

diff --git a/modules/checker.py b/modules/checker.py
index 4790836..fe8e8a9 100644
--- a/modules/checker.py
+++ b/modules/checker.py
@@ -1,5 +1,4 @@
 import os
-import sys
 from logging import Logger
 from typing import Optional
 from urllib.parse import urlparse
@@ -7,8 +6,7 @@
 import psutil
 import requests
 
-from modules.helper import TorProxyException, get_requests_header
-from modules.helper.helper import TorServiceException
+from modules.helper import TorProxyException, TorServiceException, get_requests_header
 
 
 def url_canon(website: str, www: bool = False) -> tuple[bool, str]:
diff --git a/modules/tests/test_checker.py b/modules/tests/test_checker.py
index 92a8ff8..a8bc1d4 100644
--- a/modules/tests/test_checker.py
+++ b/modules/tests/test_checker.py
@@ -6,8 +6,7 @@
 from unittest import mock
 
 from modules.checker import check_ip, check_tor, extract_domain, folder, url_canon
-from modules.helper import TorProxyException, get_tor_proxies, setup_custom_logger
-from modules.helper.helper import TorServiceException
+from modules.helper import TorProxyException, TorServiceException, get_tor_proxies, setup_custom_logger
 
 
 class MockedPsutilProcess:

From bed95bccf019c7d010db50f2efed1bb483eed759 Mon Sep 17 00:00:00 2001
From: PROxZIMA <pratikbpingale9075@gmail.com>
Date: Wed, 21 Sep 2022 23:38:49 +0530
Subject: [PATCH 39/39] Update: Extractor module test cases

---
 README.md                       |  18 +-
 modules/tests/test_extractor.py | 570 ++++++++++----------------------
 2 files changed, 196 insertions(+), 392 deletions(-)

diff --git a/README.md b/README.md
index e1573d7..81d0465 100644
--- a/README.md
+++ b/README.md
@@ -238,15 +238,29 @@ $ python darkspider.py -u "http://github.com/" -c -d 2 -p 1 -t 32 -s
 ## Generating :: Visualization of the graph...
 ```
 
+## Testing:
+Test cases must be updated as we don't want any unexpected exception to pop-up in-between long runs.
+
+Before creating a PR make sure to run all the test cases.
+
+```bash
+$ python3 -m unittest -b
+```
+or a module specific test cases using
+
+```bash
+$ python3 -m unittest modules.tests.test_crawler -b
+```
+---
 > **Note**
 >
 > Output in Readme is trimmed for better readability. General [verbose output](./assets/logging.png) is much detailed.
 
-## Credits
+## Credits:
 - [**@MikeMeliz**](https://github.com/MikeMeliz) for initial [`TorCrawl`](https://github.com/MikeMeliz/TorCrawl.py) codebase
 - A. Alharbi et al., "[Exploring the Topological Properties of the Tor Dark Web](https://ieeexplore.ieee.org/document/9340182)", IEEE Access, vol. 9, pp. 21746-21758, 2021.
 
-## Contributors:
+## Contributing:
 Feel free to contribute on this project! Just fork it, make any change on your fork and add a pull request on current branch! Any advice, help or questions would be appreciated :shipit:
 
 [![Contributors](https://contrib.rocks/image?repo=PROxZIMA/DarkSpider "Contributors")](https://github.com/PROxZIMA/DarkSpider/graphs/contributors)
diff --git a/modules/tests/test_extractor.py b/modules/tests/test_extractor.py
index e983e6c..0aa0976 100644
--- a/modules/tests/test_extractor.py
+++ b/modules/tests/test_extractor.py
@@ -1,92 +1,104 @@
 import os.path
 import shutil
 import unittest
-import urllib.request
-from ast import literal_eval
 from collections import defaultdict
-from pathlib import Path
+from copy import copy
 from unittest import mock
 
 from modules.checker import folder
-from modules.extractor import (
-    check_yara,
-    cinex,
-    extractor,
-    intermex,
-    outex,
-    termex,
-    text,
-)
-from modules.helpers.helper import Capturing
+from modules.extractor import Extractor
+from modules.helper import setup_custom_logger
 
 URL_1 = "http://info.cern.ch/"
 URL_2 = "http://info.cern.ch/hypertext/WWW/TheProject.html"
 URL_3 = "unknown_path"
 
 
-def mocked_urllib_open(*args, **kwargs):
+def mocked_requests_Session_get(*args, **kwargs):
     """Custom sideeffect for mock testing network urls"""
 
     class MockResponse:
         """Custom mock response"""
 
         def __init__(self, response_data):
-            self.response_data = response_data
+            self.text = response_data
 
-        def read(self):
-            """Read method for urllib.request.urlopen"""
-            return self.response_data
-
-    responses = defaultdict(lambda: None)
+    responses = defaultdict(lambda: "")
 
     responses[
         URL_1
-    ] = b'<html><head></head><body><header>\n<title>http://info.cern.ch</title>\n</header>\n\n<h1>http://info.cern.ch - home of the first website</h1>\n<p>From here you can:</p>\n<ul>\n<li><a href="http://info.cern.ch/hypertext/WWW/TheProject.html">Browse the first website</a></li>\n<li><a href="http://line-mode.cern.ch/www/hypertext/WWW/TheProject.html">Browse the first website using the line-mode browser simulator</a></li>\n<li><a href="http://home.web.cern.ch/topics/birth-web">Learn about the birth of the web</a></li>\n<li><a href="http://home.web.cern.ch/about">Learn about CERN, the physics laboratory where the web was born</a></li>\n</ul>\n</body></html>\n'
+    ] = '<html><head></head><body><header>\n<title>http://info.cern.ch</title>\n</header>\n\n<h1>http://info.cern.ch - home of the first website</h1>\n<p>From here you can:</p>\n<ul>\n<li><a href="http://info.cern.ch/hypertext/WWW/TheProject.html">Browse the first website</a></li>\n<li><a href="http://line-mode.cern.ch/www/hypertext/WWW/TheProject.html">Browse the first website using the line-mode browser simulator</a></li>\n<li><a href="http://home.web.cern.ch/topics/birth-web">Learn about the birth of the web</a></li>\n<li><a href="http://home.web.cern.ch/about">Learn about CERN, the physics laboratory where the web was born</a></li>\n</ul>\n</body></html>\n'
 
     responses[
         URL_2
-    ] = b'<HEADER>\n<TITLE>The World Wide Web project</TITLE>\n<NEXTID N="55">\n</HEADER>\n<BODY>\n<H1>World Wide Web</H1>The WorldWideWeb (W3) is a wide-area<A\nNAME=0 HREF="WhatIs.html">\nhypermedia</A> information retrieval\ninitiative aiming to give universal\naccess to a large universe of documents.<P>\nEverything there is online about\nW3 is linked directly or indirectly\nto this document, including an <A\nNAME=24 HREF="Summary.html">executive\nsummary</A> of the project, <A\nNAME=29 HREF="Administration/Mailing/Overview.html">Mailing lists</A>\n, <A\nNAME=30 HREF="Policy.html">Policy</A> , November\'s  <A\nNAME=34 HREF="News/9211.html">W3  news</A> ,\n<A\nNAME=41 HREF="FAQ/List.html">Frequently Asked Questions</A> .\n<DL>\n<DT><A\nNAME=44 HREF="../DataSources/Top.html">What\'s out there?</A>\n<DD> Pointers to the\nworld\'s online information,<A\nNAME=45 HREF="../DataSources/bySubject/Overview.html"> subjects</A>\n, <A\nNAME=z54 HREF="../DataSources/WWW/Servers.html">W3 servers</A>, etc.\n<DT><A\nNAME=46 HREF="Help.html">Help</A>\n<DD> on the browser you are using\n<DT><A\nNAME=13 HREF="Status.html">Software Products</A>\n<DD> A list of W3 project\ncomponents and their current state.\n(e.g. <A\nNAME=27 HREF="LineMode/Browser.html">Line Mode</A> ,X11 <A\nNAME=35 HREF="Status.html#35">Viola</A> ,  <A\nNAME=26 HREF="NeXT/WorldWideWeb.html">NeXTStep</A>\n, <A\nNAME=25 HREF="Daemon/Overview.html">Servers</A> , <A\nNAME=51 HREF="Tools/Overview.html">Tools</A> ,<A\nNAME=53 HREF="MailRobot/Overview.html"> Mail robot</A> ,<A\nNAME=52 HREF="Status.html#57">\nLibrary</A> )\n<DT><A\nNAME=47 HREF="Technical.html">Technical</A>\n<DD> Details of protocols, formats,\nprogram internals etc\n<DT><A\nNAME=40 HREF="Bibliography.html">Bibliography</A>\n<DD> Paper documentation\non  W3 and references.\n<DT><A\nNAME=14 HREF="People.html">People</A>\n<DD> A list of some people involved\nin the project.\n<DT><A\nNAME=15 HREF="History.html">History</A>\n<DD> A summary of the history\nof the project.\n<DT><A\nNAME=37 HREF="Helping.html">How can I help</A> ?\n<DD> If you would like\nto support the web..\n<DT><A\nNAME=48 HREF="../README.html">Getting code</A>\n<DD> Getting the code by<A\nNAME=49 HREF="LineMode/Defaults/Distribution.html">\nanonymous FTP</A> , etc.</A>\n</DL>\n</BODY>\n'
+    ] = '<HEADER>\n<TITLE>The World Wide Web project</TITLE>\n<NEXTID N="55">\n</HEADER>\n<BODY>\n<H1>World Wide Web</H1>The WorldWideWeb (W3) is a wide-area<A\nNAME=0 HREF="WhatIs.html">\nhypermedia</A> information retrieval\ninitiative aiming to give universal\naccess to a large universe of documents.<P>\nEverything there is online about\nW3 is linked directly or indirectly\nto this document, including an <A\nNAME=24 HREF="Summary.html">executive\nsummary</A> of the project, <A\nNAME=29 HREF="Administration/Mailing/Overview.html">Mailing lists</A>\n, <A\nNAME=30 HREF="Policy.html">Policy</A> , November\'s  <A\nNAME=34 HREF="News/9211.html">W3  news</A> ,\n<A\nNAME=41 HREF="FAQ/List.html">Frequently Asked Questions</A> .\n<DL>\n<DT><A\nNAME=44 HREF="../DataSources/Top.html">What\'s out there?</A>\n<DD> Pointers to the\nworld\'s online information,<A\nNAME=45 HREF="../DataSources/bySubject/Overview.html"> subjects</A>\n, <A\nNAME=z54 HREF="../DataSources/WWW/Servers.html">W3 servers</A>, etc.\n<DT><A\nNAME=46 HREF="Help.html">Help</A>\n<DD> on the browser you are using\n<DT><A\nNAME=13 HREF="Status.html">Software Products</A>\n<DD> A list of W3 project\ncomponents and their current state.\n(e.g. <A\nNAME=27 HREF="LineMode/Browser.html">Line Mode</A> ,X11 <A\nNAME=35 HREF="Status.html#35">Viola</A> ,  <A\nNAME=26 HREF="NeXT/WorldWideWeb.html">NeXTStep</A>\n, <A\nNAME=25 HREF="Daemon/Overview.html">Servers</A> , <A\nNAME=51 HREF="Tools/Overview.html">Tools</A> ,<A\nNAME=53 HREF="MailRobot/Overview.html"> Mail robot</A> ,<A\nNAME=52 HREF="Status.html#57">\nLibrary</A> )\n<DT><A\nNAME=47 HREF="Technical.html">Technical</A>\n<DD> Details of protocols, formats,\nprogram internals etc\n<DT><A\nNAME=40 HREF="Bibliography.html">Bibliography</A>\n<DD> Paper documentation\non  W3 and references.\n<DT><A\nNAME=14 HREF="People.html">People</A>\n<DD> A list of some people involved\nin the project.\n<DT><A\nNAME=15 HREF="History.html">History</A>\n<DD> A summary of the history\nof the project.\n<DT><A\nNAME=37 HREF="Helping.html">How can I help</A> ?\n<DD> If you would like\nto support the web..\n<DT><A\nNAME=48 HREF="../README.html">Getting code</A>\n<DD> Getting the code by<A\nNAME=49 HREF="LineMode/Defaults/Distribution.html">\nanonymous FTP</A> , etc.</A>\n</DL>\n</BODY>\n'
 
     return MockResponse(responses[args[0]])
 
 
+@mock.patch("requests.Session.get", side_effect=mocked_requests_Session_get)
 class TestCheckerFunctions(unittest.TestCase):
     """Unit test for Extractor module."""
 
+    @classmethod
+    def setUpClass(cls) -> None:
+        """Test Suite Setup."""
+        cls.out_path = "darkspider"
+        cls.out_file = os.path.join(cls.out_path, "index.html")
+        cls.inp_file = os.path.join(cls.out_path, "links.txt")
+        cls.logger = setup_custom_logger(
+            name="testlog",
+            filename=None,
+            verbose_=False,
+            filelog=False,
+            argv=None,
+        )
+        cls.extractor_1 = Extractor(
+            website=URL_1,
+            proxies=None,
+            crawl=False,
+            output_file=cls.out_file,
+            input_file=cls.inp_file,
+            out_path=cls.out_path,
+            thread=1,
+            yara=True,
+            logger=cls.logger,
+        )
+
     def setUp(self):
         """Test Case Setup."""
-        self.out_path = folder("torcrawl", False)
-        self.inp_path = "links.txt"
+        folder(self.out_path, False)
 
-        with open(self.inp_path, "w", encoding="utf-8") as f:
+        with open(self.inp_file, "w", encoding="utf-8") as f:
             f.write(f"{URL_1}\n")
             f.write(f"{URL_2}\n")
             f.write(URL_3)
 
     def tearDown(self):
         """Test Case Teardown."""
-        # Remove input file.
-        os.remove(self.inp_path)
         # Remove test folder.
         shutil.rmtree(self.out_path, ignore_errors=True)
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_text(self, _):
-        """text unit test.
-        Removes all the garbage from the HTML and takes only text elements from the page.
+    def get_response_text(self, url: str) -> str:
+        """Get patched response text.
+
+        Args:
+            url: URL to get response text.
+
+        Returns:
+            Response text.
         """
+        return self.extractor_1._Extractor__session.get(url, allow_redirects=True, timeout=10).text
+
+    def test_text(self, _):
+        """text unit test."""
         expected = """http://info.cern.ch http://info.cern.ch - home of the first website From here you can: Browse the first website Browse the first website using the line-mode browser simulator Learn about the birth of the web Learn about CERN, the physics laboratory where the web was born"""
-        content = urllib.request.urlopen(URL_1, timeout=10).read()
-        result = text(response=content)
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        content = self.get_response_text(URL_1)
+        result = self.extractor_1._Extractor__text(response=content)
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
     def test_check_yara_001(self, _):
-        """check_yara unit test.
-        Validates Yara Rule to categorize the site and check for keywords.
-        """
+        """check_yara unit test."""
         expected = {
             "main": [
                 {
@@ -154,14 +166,10 @@ def test_check_yara_001(self, _):
             ]
         }
 
-        content = urllib.request.urlopen(URL_1, timeout=10).read()
-        with Capturing() as _:
-            result = check_yara(raw=content, yara=0)
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        content = self.get_response_text(URL_1)
+        result = self.extractor_1._Extractor__check_yara(raw=content, yara=0)
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
     def test_check_yara_002(self, _):
         """check_yara unit test.
         Validates Yara Rule to categorize the site and check for keywords.
@@ -221,407 +229,189 @@ def test_check_yara_002(self, _):
             ]
         }
 
-        content = urllib.request.urlopen(URL_1, timeout=10).read()
-        with Capturing() as _:
-            result = check_yara(raw=content, yara=1)
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
-
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_check_yara_003(self, _):
-        """check_yara unit test.
-        Validates Yara Rule to categorize the site and check for keywords.
-        """
-        expected = {}
-
-        content = urllib.request.urlopen(URL_2, timeout=10).read()
-        result = check_yara(raw=content, yara=0)
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        content = self.get_response_text(URL_1)
+        result = self.extractor_1._Extractor__check_yara(raw=content, yara=1)
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_check_yara_004(self, _):
-        """check_yara unit test.
-        Validates Yara Rule to categorize the site and check for keywords.
-        """
-        expected = {}
-
-        content = urllib.request.urlopen(URL_2, timeout=10).read()
-        result = check_yara(raw=content, yara=1)
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
-
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_check_yara_005(self, _):
-        """check_yara unit test.
-        Validates Yara Rule to categorize the site and check for keywords.
-        """
-        expected = None
-
-        content = urllib.request.urlopen(URL_3, timeout=10).read()
-        result = check_yara(raw=content, yara=1)
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
-
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_cinex_001(self, _):
-        """cinex unit test.
-        Ingests the crawled links from the input_file,
-        scrapes the contents of the resulting web pages and writes the contents to
-        the into out_path/{url_address}.
-        """
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_cinex_001(self, _, __):
+        """cinex unit test."""
         expected = [
-            f"# File created on: {Path(__file__).parent.parent.parent}/{self.out_path}/index.htm",
-            f"# File created on: {Path(__file__).parent.parent.parent}/{self.out_path}/TheProject.htm",
-            "Error: list index out of range",
+            [
+                (10, ("%s :: %s match found!", "http://info.cern.ch/", "Yara"), False),
+                (10, ("File created :: %s", f"{self.out_path}/info.cern.ch/_.html"), False),
+            ],
+            [(10, ("%s :: %s match found!", "http://info.cern.ch/hypertext/WWW/TheProject.html", "No yara"), False)],
+            [(10, ("%s :: %s match found!", "unknown_path", "No yara"), False)],
         ]
 
-        with Capturing() as result:
-            cinex(self.inp_path, self.out_path)
+        result = self.extractor_1._Extractor__cinex(self.inp_file, self.out_path, 0)
 
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        self.assertCountEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-        # We can't simply compare the contents of the files in `self.out_path`
-        # because the order of the files is not guaranteed.
-        link_1 = os.path.join(self.out_path, "index.htm")
-        link_2 = os.path.join(self.out_path, "TheProject.htm")
-
-        with open(link_1, "rb") as f:
-            expected = mocked_urllib_open(URL_1).read()
-            result = f.read()
-            self.assertEqual(
-                expected, result, f"Test Fail:: expected = {expected}, got {result}"
-            )
-
-        with open(link_2, "rb") as f:
-            expected = mocked_urllib_open(URL_2).read()
-            result = f.read()
-            self.assertEqual(
-                expected, result, f"Test Fail:: expected = {expected}, got {result}"
-            )
-
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_cinex_002(self, _):
-        """cinex unit test.
-        Ingests the crawled links from the input_file,
-        scrapes the contents of the resulting web pages and writes the contents to
-        the into out_path/{url_address}.
-        """
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_cinex_002(self, _, __):
+        """cinex unit test."""
         expected = [
-            "found a match!",
-            f"# File created on: {Path(__file__).parent.parent.parent}/{self.out_path}/index.htm",
-            "No matches found.",
-            "Error: list index out of range",
+            [(10, ("File created :: %s", "darkspider/info.cern.ch/_.html"), False)],
+            [(10, ("File created :: %s", "darkspider/info.cern.ch/hypertext/WWW/TheProject.html_.html"), False)],
+            [(10, ("File created :: %s", "darkspider/unknown_path_.html"), False)],
         ]
 
-        with Capturing() as result:
-            cinex(self.inp_path, self.out_path, yara=1)
+        result = self.extractor_1._Extractor__cinex(self.inp_file, self.out_path, None)
 
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
-
-        link = os.path.join(self.out_path, "index.htm")
-
-        with open(link, "rb") as f:
-            expected = mocked_urllib_open(URL_1).read()
-            result = f.read()
-            self.assertEqual(
-                expected, result, f"Test Fail:: expected = {expected}, got {result}"
-            )
+        self.assertCountEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_intermex_001(self, _):
-        """intermex unit test.
-        Input links from file and extract them into terminal.
-        """
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_terminex_001(self, _, __):
+        """intermex unit test."""
         expected = [
-            mocked_urllib_open(URL_1).read(),
-            mocked_urllib_open(URL_2).read(),
-            "None",
+            [
+                (10, ("%s :: %s match found!", "http://info.cern.ch/", "Yara"), False),
+                (20, ("%s :: %s", "http://info.cern.ch/", mocked_requests_Session_get(URL_1).text), False),
+            ],
+            [(10, ("%s :: %s match found!", "http://info.cern.ch/hypertext/WWW/TheProject.html", "No yara"), False)],
+            [(10, ("%s :: %s match found!", "unknown_path", "No yara"), False)],
         ]
 
-        with Capturing() as result:
-            intermex(self.inp_path, None)
+        result = self.extractor_1._Extractor__terminex(self.inp_file, 1)
 
-        result = [
-            literal_eval(x) if x.startswith("b'") and x.endswith("'") else x
-            for x in result
-        ]
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        self.assertCountEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_intermex_002(self, _):
-        """intermex unit test.
-        Input links from file and extract them into terminal.
-        """
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_terminex_002(self, _, __):
+        """intermex unit test."""
         expected = [
-            "found a match!",
-            mocked_urllib_open(URL_1).read(),
-            f"No matches in: {URL_2}",
-            mocked_urllib_open(URL_2).read(),
-            f"No matches in: {URL_3}",
-            "None",
+            [
+                (20, ("%s :: %s", "http://info.cern.ch/", mocked_requests_Session_get(URL_1).text), False),
+            ],
+            [
+                (
+                    20,
+                    (
+                        "%s :: %s",
+                        "http://info.cern.ch/hypertext/WWW/TheProject.html",
+                        mocked_requests_Session_get(URL_2).text,
+                    ),
+                    False,
+                ),
+            ],
+            [
+                (20, ("%s :: %s", "unknown_path", mocked_requests_Session_get(URL_3).text), False),
+            ],
         ]
 
-        with Capturing() as result:
-            intermex(self.inp_path, 1)
+        result = self.extractor_1._Extractor__terminex(self.inp_file, None)
 
-        result = [
-            literal_eval(x) if x.startswith("b'") and x.endswith("'") else x
-            for x in result
-        ]
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        self.assertCountEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_intermex_003(self, _):
-        """intermex unit test.
-        Input links from file and extract them into terminal.
-        """
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_outex_001(self, _, __):
+        """outex unit test."""
         expected = [
-            "Error: [Errno 2] No such file or directory: 'unknown_path'",
-            "## Not valid file",
+            (10, ("%s :: %s match found!", "http://info.cern.ch/", "Yara"), False),
+            (10, ("File created :: %s", f"{self.out_path}/index.html"), False),
         ]
 
-        with Capturing() as result:
-            intermex("unknown_path", None)
+        result = self.extractor_1._Extractor__outex(URL_1, self.out_file, 0)
 
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_outex_001(self, _):
-        """outex unit test.
-        Scrapes the contents of the provided web address and outputs the
-        contents to file.
-        """
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_outex_002(self, _, __):
+        """outex unit test."""
         expected = [
-            f"## File created on: {Path(__file__).parent.parent.parent}/{self.out_path}/index.htm"
+            (10, ("File created :: %s", f"{self.out_path}/index.html"), False),
         ]
 
-        with Capturing() as result:
-            outex(URL_1, "index.htm", self.out_path, None)
-
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
-
-        link = os.path.join(self.out_path, "index.htm")
+        result = self.extractor_1._Extractor__outex(URL_1, self.out_file, None)
 
-        with open(link, "rb") as f:
-            expected = mocked_urllib_open(URL_1).read()
-            result = f.read()
-            self.assertEqual(
-                expected, result, f"Test Fail:: expected = {expected}, got {result}"
-            )
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_outex_002(self, _):
-        """outex unit test.
-        Scrapes the contents of the provided web address and outputs the
-        contents to file.
-        """
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_termex_001(self, _, __):
+        """termex unit test."""
         expected = [
-            "found a match!",
-            f"## File created on: {Path(__file__).parent.parent.parent}/{self.out_path}/index.htm",
+            (10, ("%s :: %s match found!", "http://info.cern.ch/", "Yara"), False),
+            (20, ("%s :: %s", "http://info.cern.ch/", mocked_requests_Session_get(URL_1).text), False),
         ]
 
-        with Capturing() as result:
-            outex(URL_1, "index.htm", self.out_path, 1)
-
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
-
-        link = os.path.join(self.out_path, "index.htm")
+        result = self.extractor_1._Extractor__termex(URL_1, 1)
 
-        with open(link, "rb") as f:
-            expected = mocked_urllib_open(URL_1).read()
-            result = f.read()
-            self.assertEqual(
-                expected, result, f"Test Fail:: expected = {expected}, got {result}"
-            )
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_outex_003(self, _):
-        """outex unit test.
-        Scrapes the contents of the provided web address and outputs the
-        contents to file.
-        """
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_termex_002(self, _, __):
+        """termex unit test."""
         expected = [
-            "found a match!",
-            f"Error: [Errno 21] Is a directory: '{self.out_path}/'",
-            f" Can't write on file: {self.out_path}/",
+            (20, ("%s :: %s", "http://info.cern.ch/", mocked_requests_Session_get(URL_1).text), False),
         ]
 
-        with Capturing() as result:
-            outex(URL_1, "", self.out_path, 1)
+        result = self.extractor_1._Extractor__termex(URL_1, None)
 
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_outex_004(self, _):
-        """outex unit test.
-        Scrapes the contents of the provided web address and outputs the
-        contents to file.
-        """
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_extractor_001(self, _, __):
+        """extractor unit test."""
         expected = [
-            f"Error: [Errno 21] Is a directory: '{self.out_path}/'",
-            f" Can't write on file: {self.out_path}/",
+            [
+                (10, ("%s :: %s match found!", "http://info.cern.ch/", "Yara"), False),
+                (10, ("File created :: %s", f"{self.out_path}/info.cern.ch/_.html"), False),
+            ],
+            [(10, ("%s :: %s match found!", "http://info.cern.ch/hypertext/WWW/TheProject.html", "No yara"), False)],
+            [(10, ("%s :: %s match found!", "unknown_path", "No yara"), False)],
         ]
 
-        with Capturing() as result:
-            outex(URL_1, "", self.out_path, None)
+        result = self.extractor_1.extract()
 
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_termex_001(self, _):
-        """termex unit test.
-        Scrapes provided web address and prints the results to the terminal
-        """
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_extractor_002(self, _, __):
+        """extractor unit test."""
         expected = [
-            mocked_urllib_open(URL_1).read(),
+            [
+                (10, ("%s :: %s match found!", "http://info.cern.ch/", "Yara"), False),
+                (20, ("%s :: %s", "http://info.cern.ch/", mocked_requests_Session_get(URL_1).text), False),
+            ],
+            [(10, ("%s :: %s match found!", "http://info.cern.ch/hypertext/WWW/TheProject.html", "No yara"), False)],
+            [(10, ("%s :: %s match found!", "unknown_path", "No yara"), False)],
         ]
 
-        with Capturing() as result:
-            termex(URL_1, None)
-
-        result = [literal_eval(*result)]
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
-
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_termex_002(self, _):
-        """termex unit test.
-        Scrapes provided web address and prints the results to the terminal
-        """
-        expected = [f"No matches in: {URL_2}"]
-
-        with Capturing() as result:
-            termex(URL_2, 1)
+        extractor_2 = copy(self.extractor_1)
+        extractor_2.out_path = None
 
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
-
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_termex_003(self, _):
-        """termex unit test.
-        Scrapes provided web address and prints the results to the terminal
-        """
-        expected = ["None"]
+        result = extractor_2.extract()
 
-        with Capturing() as result:
-            termex("unknown_path", None)
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
-
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_termex_004(self, _):
-        """termex unit test.
-        Scrapes provided web address and prints the results to the terminal
-        """
-        expected = [f"No matches in: {URL_3}"]
-
-        with Capturing() as result:
-            termex("unknown_path", 1)
-
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
-
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_extractor_001(self, _):
-        """extractor unit test.
-        Extractor - scrapes the resulting website or discovered links
-        """
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_extractor_003(self, _, __):
+        """extractor unit test."""
         expected = [
-            f"# File created on: {Path(__file__).parent.parent.parent}/{self.out_path}/index.htm",
-            f"# File created on: {Path(__file__).parent.parent.parent}/{self.out_path}/TheProject.htm",
-            "Error: list index out of range",
+            [(10, ("%s :: %s match found!", "http://info.cern.ch/hypertext/WWW/TheProject.html", "No yara"), False)]
         ]
 
-        with Capturing() as result:
-            # Cinex
-            extractor(URL_1, True, "index.htm", self.inp_path, self.out_path, None)
+        extractor_3 = copy(self.extractor_1)
+        extractor_3.website = URL_2
+        extractor_3.input_file = ""
+        extractor_3.output_file = "index.html"
 
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        result = extractor_3.extract()
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_extractor_002(self, _):
-        """extractor unit test.
-        Extractor - scrapes the resulting website or discovered links
-        """
-        expected = [
-            mocked_urllib_open(URL_1).read(),
-            mocked_urllib_open(URL_2).read(),
-            "None",
-        ]
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")
 
-        with Capturing() as result:
-            # Intermex
-            extractor(URL_1, False, "index.htm", self.inp_path, self.out_path, None)
+    @mock.patch("concurrent.futures.ThreadPoolExecutor.shutdown", side_effect=[lambda wait: None])
+    def test_extractor_004(self, _, __):
+        """extractor unit test."""
+        expected = [[(10, ("%s :: %s match found!", "unknown_path", "No yara"), False)]]
 
-        result = [
-            literal_eval(x) if x.startswith("b'") and x.endswith("'") else x
-            for x in result
-        ]
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        extractor_4 = copy(self.extractor_1)
+        extractor_4.website = URL_3
+        extractor_4.input_file = ""
+        extractor_4.output_file = ""
 
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_extractor_003(self, _):
-        """extractor unit test.
-        Extractor - scrapes the resulting website or discovered links
-        """
-        expected = [
-            f"## File created on: {Path(__file__).parent.parent.parent}/{self.out_path}/index.htm"
-        ]
-
-        with Capturing() as result:
-            # Outex
-            extractor(URL_1, True, "index.htm", "", self.out_path, None)
+        result = extractor_4.extract()
 
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
-
-    @mock.patch("urllib.request.urlopen", side_effect=mocked_urllib_open)
-    def test_extractor_004(self, _):
-        """extractor unit test.
-        Extractor - scrapes the resulting website or discovered links
-        """
-        expected = [
-            mocked_urllib_open(URL_1).read(),
-        ]
-
-        with Capturing() as result:
-            # Termex
-            extractor(URL_1, True, "", "", self.out_path, None)
-
-        result = [literal_eval(*result)]
-        self.assertEqual(
-            expected, result, f"Test Fail:: expected = {expected}, got {result}"
-        )
+        self.assertEqual(expected, result, f"Test Fail:: expected = {expected}, got {result}")