secator 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

secator/utils.py

@@ -26,7 +26,7 @@ import ifaddr
 import yaml
 
 from secator.definitions import (DEBUG_COMPONENT, VERSION, DEV_PACKAGE)
-from secator.config import CONFIG, ROOT_FOLDER, LIB_FOLDER
+from secator.config import CONFIG, ROOT_FOLDER, LIB_FOLDER, download_file
 from secator.rich import console
 
 logger = logging.getLogger(__name__)
@@ -308,11 +308,21 @@ def pluralize(word):
 	"""
 	if word.endswith('y'):
 		return word.rstrip('y') + 'ies'
-	else:
-		return f'{word}s'
+	return f'{word}s'
 
 
 def load_fixture(name, fixtures_dir, ext=None, only_path=False):
+	"""Load fixture a fixture dir. Optionally load it's content if it's JSON / YAML.
+
+	Args:
+		name (str): Fixture name.
+		fixtures_dir (str): Fixture parent directory.
+		ext (str, Optional): Extension to load.
+		only_path (bool, Optional): Return fixture path instead of fixture content.
+
+	Returns:
+		str: Fixture path or content.
+	"""
 	fixture_path = f'{fixtures_dir}/{name}'
 	exts = ['.json', '.txt', '.xml', '.rc']
 	if ext:
@@ -331,10 +341,19 @@ def load_fixture(name, fixtures_dir, ext=None, only_path=False):
 
 
 def get_file_timestamp():
+	"""Get current timestamp into a formatted string."""
 	return datetime.now().strftime("%Y_%m_%d-%I_%M_%S_%f_%p")
 
 
 def detect_host(interface=None):
+	"""Detect hostname from ethernet adapters.
+
+	Args:
+		interface (str): Interface name to get hostname from.
+
+	Returns:
+		str | None: hostname or ip address, or None if not found.
+	"""
 	adapters = ifaddr.get_adapters()
 	for adapter in adapters:
 		iface = adapter.name
@@ -345,7 +364,14 @@ def detect_host(interface=None):
 
 
 def rich_to_ansi(text):
-	"""Convert text formatted with rich markup to standard string."""
+	"""Convert text formatted with rich markup to standard string.
+
+	Args:
+		text (str): Text.
+
+	Returns:
+		str: Converted text (ANSI).
+	"""
 	from rich.console import Console
 	tmp_console = Console(file=None, highlight=False, color_system='truecolor')
 	with tmp_console.capture() as capture:
@@ -353,43 +379,65 @@ def rich_to_ansi(text):
 	return capture.get()
 
 
+def rich_escape(obj):
+	"""Escape object for rich printing.
+
+	Args:
+		obj (any): Input object.
+
+	Returns:
+		any: Initial object, or escaped Rich string.
+	"""
+	if isinstance(obj, str):
+		return obj.replace('[', r'\[').replace(']', r'\]')
+	return obj
+
+
 def format_object(obj, obj_breaklines=False):
-    """Format the debug object for printing."""
-    sep = '\n ' if obj_breaklines else ', '
-    if isinstance(obj, dict):
-        return sep.join(f'[dim cyan]{k}[/] [dim yellow]->[/] [dim green]{v}[/]' for k, v in obj.items() if v is not None)  # noqa: E501
-    elif isinstance(obj, list):
-        return f'[dim green]{sep.join(obj)}[/]'
-    return ''
+	"""Format the debug object for printing.
+
+	Args:
+		obj (dict | list): Input object.
+		obj_breaklines (bool): Split output with newlines for each item in input object.
+
+	Returns:
+		str: Rich-formatted string.
+	"""
+	sep = '\n ' if obj_breaklines else ', '
+	if isinstance(obj, dict):
+		return sep.join(f'[dim cyan]{k}[/] [dim yellow]->[/] [dim green]{v}[/]' for k, v in obj.items() if v is not None)  # noqa: E501
+	elif isinstance(obj, list):
+		return f'[dim green]{sep.join(obj)}[/]'
+	return ''
 
 
 def debug(msg, sub='', id='', obj=None, lazy=None, obj_after=True, obj_breaklines=False, verbose=False):
-    """Print debug log if DEBUG >= level."""
-    if not DEBUG_COMPONENT or DEBUG_COMPONENT == [""]:
-        return
+	"""Print debug log if DEBUG >= level."""
+	if not DEBUG_COMPONENT or DEBUG_COMPONENT == [""]:
+		return
 
-    if sub:
-        if verbose and sub not in DEBUG_COMPONENT:
-            sub = f'debug.{sub}'
-        if not any(sub.startswith(s) for s in DEBUG_COMPONENT):
-            return
+	if sub:
+		if verbose and sub not in DEBUG_COMPONENT:
+			sub = f'debug.{sub}'
+		if not any(sub.startswith(s) for s in DEBUG_COMPONENT):
+			return
 
-    if lazy:
-        msg = lazy(msg)
+	if lazy:
+		msg = lazy(msg)
 
-    formatted_msg = f'[dim yellow4]{sub:13s}[/] ' if sub else ''
-    obj_str = format_object(obj, obj_breaklines) if obj else ''
+	formatted_msg = f'[yellow4]{sub:13s}[/] ' if sub else ''
+	obj_str = format_object(obj, obj_breaklines) if obj else ''
 
-    # Constructing the message string based on object position
-    if obj_str and not obj_after:
-        formatted_msg += f'{obj_str} '
-    formatted_msg += f'[dim yellow]{msg}[/]'
-    if obj_str and obj_after:
-        formatted_msg += f': {obj_str}'
-    if id:
-        formatted_msg += f' [italic dim gray11]\[{id}][/]'
+	# Constructing the message string based on object position
+	if obj_str and not obj_after:
+		formatted_msg += f'{obj_str} '
+	formatted_msg += f'[yellow]{msg}[/]'
+	if obj_str and obj_after:
+		formatted_msg += f': {obj_str}'
+	if id:
+		formatted_msg += rf' [italic gray11]\[{id}][/]'
 
-    console.print(f'[dim red]🐛 {formatted_msg}[/]', style='red')
+	console.print(rf'[dim]\[[magenta4]DBG[/]] {formatted_msg}[/]')
 
 
 def escape_mongodb_url(url):
@@ -414,7 +462,7 @@ def print_version():
 	"""Print secator version information."""
 	from secator.installer import get_version_info
 	console.print(f'[bold gold3]Current version[/]: {VERSION}', highlight=False, end='')
-	info = get_version_info('secator', github_handle='freelabz/secator', version=VERSION)
+	info = get_version_info('secator', install_github_handle='freelabz/secator', version=VERSION)
 	latest_version = info['latest_version']
 	status = info['status']
 	location = info['location']
@@ -528,16 +576,15 @@ def get_file_date(file_path):
 
 
 def trim_string(s, max_length=30):
-	"""
-	Trims a long string to include the beginning and the end, with an ellipsis in the middle.
-	The output string will not exceed the specified maximum length.
+	"""Trims a long string to include the beginning and the end, with an ellipsis in the middle. The output string will
+	not exceed the specified maximum length.
 
 	Args:
 		s (str): The string to be trimmed.
 		max_length (int): The maximum allowed length of the trimmed string.
 
 	Returns:
-	str: The trimmed string.
+		str: The trimmed string.
 	"""
 	if len(s) <= max_length:
 		return s  # Return the original string if it's short enough
@@ -627,6 +674,14 @@ def list_reports(workspace=None, type=None, timedelta=None):
 
 
 def get_info_from_report_path(path):
+	"""Get some info from the report path, like workspace, run type and id.
+
+	Args:
+		path (pathlib.Path): Report path.
+
+	Returns:
+		dict: Info dict.
+	"""
 	try:
 		ws, runner_type, number = path.parts[-4], path.parts[-3], path.parts[-2]
 		workspace_path = '/'.join(path.parts[:-3])
@@ -641,6 +696,14 @@ def get_info_from_report_path(path):
 
 
 def human_to_timedelta(time_str):
+	"""Convert human time to a timedelta object.
+
+	Args:
+		str: Time string in human format (like 2 years)
+
+	Returns:
+		datetime.TimeDelta: TimeDelta object.
+	"""
 	if not time_str:
 		return None
 	parts = TIMEDELTA_REGEX.match(time_str)
@@ -661,31 +724,57 @@ def human_to_timedelta(time_str):
 
 
 def deep_merge_dicts(*dicts):
-    """
-    Recursively merges multiple dictionaries by concatenating lists and merging nested dictionaries.
+	"""Recursively merges multiple dictionaries by concatenating lists and merging nested dictionaries.
+
+	Args:
+		dicts (tuple): A tuple of dictionary objects to merge.
+
+	Returns:
+		dict: A new dictionary containing merged keys and values from all input dictionaries.
+	"""
+	def merge_two_dicts(dict1, dict2):
+		"""Helper function that merges two dictionaries.
+
+		Args:
+			dict1 (dict): First dict.
+			dict2 (dict): Second dict.
+		Returns:
+			dict: Merged dict.
+		"""
+		result = dict(dict1)  # Create a copy of dict1 to avoid modifying it.
+		for key, value in dict2.items():
+			if key in result:
+				if isinstance(result[key], dict) and isinstance(value, dict):
+					result[key] = merge_two_dicts(result[key], value)
+				elif isinstance(result[key], list) and isinstance(value, list):
+					result[key] += value  # Concatenating lists
+				else:
+					result[key] = value  # Overwrite if not both lists or both dicts
+			else:
+				result[key] = value
+		return result
+
+	# Use reduce to apply merge_two_dicts to all dictionaries in dicts
+	return reduce(merge_two_dicts, dicts, {})
 
-    Args:
-        dicts (tuple): A tuple of dictionary objects to merge.
 
-    Returns:
-        dict: A new dictionary containing merged keys and values from all input dictionaries.
+def process_wordlist(val):
+	"""Pre-process wordlist option value to allow referencing wordlists from remote URLs or from config keys.
+
+	Args:
+		val (str): Can be a config value in CONFIG.wordlists.defaults or CONFIG.wordlists.templates, or a local path,
+		or a URL.
 	"""
-    def merge_two_dicts(dict1, dict2):
-        """
-        Helper function that merges two dictionaries.
-        """
-        result = dict(dict1)  # Create a copy of dict1 to avoid modifying it.
-        for key, value in dict2.items():
-            if key in result:
-                if isinstance(result[key], dict) and isinstance(value, dict):
-                    result[key] = merge_two_dicts(result[key], value)
-                elif isinstance(result[key], list) and isinstance(value, list):
-                    result[key] += value  # Concatenating lists
-                else:
-                    result[key] = value  # Overwrite if not both lists or both dicts
-            else:
-                result[key] = value
-        return result
-
-    # Use reduce to apply merge_two_dicts to all dictionaries in dicts
-    return reduce(merge_two_dicts, dicts, {})
+	default_wordlist = getattr(CONFIG.wordlists.defaults, val)
+	if default_wordlist:
+		val = default_wordlist
+	template_wordlist = getattr(CONFIG.wordlists.templates, val)
+	if template_wordlist:
+		return template_wordlist
+	else:
+		return download_file(
+			val,
+			target_folder=CONFIG.dirs.wordlists,
+			offline_mode=CONFIG.offline_mode,
+			type='wordlist'
+		)

{secator-0.7.0.dist-info → secator-0.8.0.dist-info}/METADATA

@@ -1,10 +1,11 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: secator
-Version: 0.7.0
+Version: 0.8.0
 Summary: The pentester's swiss knife.
 Project-URL: Homepage, https://github.com/freelabz/secator
 Project-URL: Issues, https://github.com/freelabz/secator/issues
 Author-email: FreeLabz <sales@freelabz.com>
+License-File: LICENSE
 Keywords: automation,cybersecurity,pentest,recon,vulnerability
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -21,6 +22,7 @@ Requires-Python: >=3.8
 Requires-Dist: beautifulsoup4<=5
 Requires-Dist: celery<6
 Requires-Dist: cpe<2
+Requires-Dist: distro<2
 Requires-Dist: dotmap<2
 Requires-Dist: free-proxy<2
 Requires-Dist: furl<3
@@ -68,7 +70,7 @@ Requires-Dist: gevent<25; extra == 'worker'
 Description-Content-Type: text/markdown
 
 <h1 align="center">
-	<img src="https://github.com/freelabz/secator/assets/9629314/ee203af4-e853-439a-af01-edeabfc4bf07/" width="400">
+    <img src="https://github.com/freelabz/secator/assets/9629314/ee203af4-e853-439a-af01-edeabfc4bf07/" width="400">
 </h1>
 
 <h4 align="center">The pentester's swiss knife.</h4>
@@ -119,32 +121,35 @@ and it is designed to improve productivity for pentesters and security researche
 
 `secator` integrates the following tools:
 
-| Name                                                          | Description                                                                    | Category       |
-|---------------------------------------------------------------|--------------------------------------------------------------------------------|----------------|
-| [httpx](https://github.com/projectdiscovery/httpx)            | Fast HTTP prober.                                                              | `http`         |
-| [cariddi](https://github.com/edoardottt/cariddi)              | Fast crawler and endpoint secrets / api keys / tokens matcher.                 | `http/crawler` |
-| [gau](https://github.com/lc/gau)                              | Offline URL crawler (Alien Vault, The Wayback Machine, Common Crawl, URLScan). | `http/crawler` |
-| [gospider](https://github.com/jaeles-project/gospider)        | Fast web spider written in Go.                                                 | `http/crawler` |
-| [katana](https://github.com/projectdiscovery/katana)          | Next-generation crawling and spidering framework.                              | `http/crawler` |
-| [dirsearch](https://github.com/maurosoria/dirsearch)          | Web path discovery.                                                            | `http/fuzzer`  |
-| [feroxbuster](https://github.com/epi052/feroxbuster)          | Simple, fast, recursive content discovery tool written in Rust.                | `http/fuzzer`  |
-| [ffuf](https://github.com/ffuf/ffuf)                          | Fast web fuzzer written in Go.                                                 | `http/fuzzer`  |
-| [h8mail](https://github.com/khast3x/h8mail)                   | Email OSINT and breach hunting tool.                                           | `osint`        |
-| [dnsx](https://github.com/projectdiscovery/dnsx)              | Fast and multi-purpose DNS toolkit designed for running DNS queries.           | `recon/dns`    |
-| [dnsxbrute](https://github.com/projectdiscovery/dnsx)              | Fast and multi-purpose DNS toolkit designed for running DNS queries (bruteforce mode).           | `recon/dns`    |
-| [subfinder](https://github.com/projectdiscovery/subfinder)    | Fast subdomain finder.                                                         | `recon/dns`    |
-| [fping](https://fping.org/)                                   | Find alive hosts on local networks.                                            | `recon/ip`     |
-| [mapcidr](https://github.com/projectdiscovery/mapcidr)        | Expand CIDR ranges into IPs.                                                   | `recon/ip`     |
-| [naabu](https://github.com/projectdiscovery/naabu)            | Fast port discovery tool.                                                      | `recon/port`   |
-| [maigret](https://github.com/soxoj/maigret)                   | Hunt for user accounts across many websites.                                   | `recon/user`   |
-| [gf](https://github.com/tomnomnom/gf)                         | A wrapper around grep to avoid typing common patterns.                         | `tagger`       |
-| [grype](https://github.com/anchore/grype)                     | A vulnerability scanner for container images and filesystems.                  | `vuln/code`    |
-| [dalfox](https://github.com/hahwul/dalfox)                    | Powerful XSS scanning tool and parameter analyzer.                             | `vuln/http`    |
-| [msfconsole](https://docs.rapid7.com/metasploit/msf-overview) | CLI to access and work with the Metasploit Framework.                          | `vuln/http`    |
-| [wpscan](https://github.com/wpscanteam/wpscan)                | WordPress Security Scanner                                                     | `vuln/multi`   |
-| [nmap](https://github.com/nmap/nmap)                          | Vulnerability scanner using NSE scripts.                                       | `vuln/multi`   |
-| [nuclei](https://github.com/projectdiscovery/nuclei)          | Fast and customisable vulnerability scanner based on simple YAML based DSL.    | `vuln/multi`   |
-| [searchsploit](https://gitlab.com/exploit-database/exploitdb) | Exploit searcher. | `exploit/search`    |
+| Name                                                          | Description                                                                    | Category        |
+|---------------------------------------------------------------|--------------------------------------------------------------------------------|-----------------|
+| [httpx](https://github.com/projectdiscovery/httpx)            | Fast HTTP prober.                                                              | `http`          |
+| [cariddi](https://github.com/edoardottt/cariddi)              | Fast crawler and endpoint secrets / api keys / tokens matcher.                 | `http/crawler`  |
+| [gau](https://github.com/lc/gau)                              | Offline URL crawler (Alien Vault, The Wayback Machine, Common Crawl, URLScan). | `http/crawler`  |
+| [gospider](https://github.com/jaeles-project/gospider)        | Fast web spider written in Go.                                                 | `http/crawler`  |
+| [katana](https://github.com/projectdiscovery/katana)          | Next-generation crawling and spidering framework.                              | `http/crawler`  |
+| [dirsearch](https://github.com/maurosoria/dirsearch)          | Web path discovery.                                                            | `http/fuzzer`   |
+| [feroxbuster](https://github.com/epi052/feroxbuster)          | Simple, fast, recursive content discovery tool written in Rust.                | `http/fuzzer`   |
+| [ffuf](https://github.com/ffuf/ffuf)                          | Fast web fuzzer written in Go.                                                 | `http/fuzzer`   |
+| [h8mail](https://github.com/khast3x/h8mail)                   | Email OSINT and breach hunting tool.                                           | `osint`         |
+| [dnsx](https://github.com/projectdiscovery/dnsx)              | Fast and multi-purpose DNS toolkit.                                            | `recon/dns`     |
+| [dnsxbrute](https://github.com/projectdiscovery/dnsx)         | Fast and multi-purpose DNS toolkit (bruteforce mode).                          | `recon/dns`     |
+| [subfinder](https://github.com/projectdiscovery/subfinder)    | Fast subdomain finder.                                                         | `recon/dns`     |
+| [fping](https://fping.org/)                                   | Find alive hosts on local networks.                                            | `recon/ip`      |
+| [mapcidr](https://github.com/projectdiscovery/mapcidr)        | Expand CIDR ranges into IPs.                                                   | `recon/ip`      |
+| [naabu](https://github.com/projectdiscovery/naabu)            | Fast port discovery tool.                                                      | `recon/port`    |
+| [maigret](https://github.com/soxoj/maigret)                   | Hunt for user accounts across many websites.                                   | `recon/user`    |
+| [gf](https://github.com/tomnomnom/gf)                         | A wrapper around grep to avoid typing common patterns.                         | `tagger`        |
+| [grype](https://github.com/anchore/grype)                     | A vulnerability scanner for container images and filesystems.                  | `vuln/code`     |
+| [dalfox](https://github.com/hahwul/dalfox)                    | Powerful XSS scanning tool and parameter analyzer.                             | `vuln/http`     |
+| [msfconsole](https://docs.rapid7.com/metasploit/msf-overview) | CLI to access and work with the Metasploit Framework.                          | `vuln/http`     |
+| [wpscan](https://github.com/wpscanteam/wpscan)                | WordPress Security Scanner                                                     | `vuln/multi`    |
+| [nmap](https://github.com/nmap/nmap)                          | Vulnerability scanner using NSE scripts.                                       | `vuln/multi`    |
+| [nuclei](https://github.com/projectdiscovery/nuclei)          | Fast and customisable vulnerability scanner based on simple YAML based DSL.    | `vuln/multi`    |
+| [bbot](https://github.com/blacklanternsecurity/bbot)          | Multipurpose scanner.                                                          | `multi`         |
+| [searchsploit](https://gitlab.com/exploit-database/exploitdb) | Exploit searcher based on ExploitDB.                                           | `exploit/search`|
+| [bup](https://github.com/laluka/bypass-url-parser)            | 40X bypasser.                                                                  | `http`          |
+
 
 Feel free to request new tools to be added by opening an issue, but please 
 check that the tool complies with our selection criterias before doing so. If it doesn't but you still want to integrate it into `secator`, you can plug it in (see the [dev guide](https://docs.freelabz.com/for-developers/writing-custom-tasks)).
@@ -155,7 +160,7 @@ check that the tool complies with our selection criterias before doing so. If it
 ### Installing secator
 
 <details>
-	<summary>Pipx</summary>
+    <summary>Pipx</summary>
 
 ```sh
 pipx install secator
@@ -164,7 +169,7 @@ pipx install secator
 </details>
 
 <details>
-	<summary>Pip</summary>
+    <summary>Pip</summary>
 
 ```sh
 pip install secator
@@ -182,7 +187,7 @@ wget -O - https://raw.githubusercontent.com/freelabz/secator/main/scripts/instal
 </details>
 
 <details>
-	<summary>Docker</summary>
+    <summary>Docker</summary>
 
 ```sh
 docker run -it --rm --net=host -v ~/.secator:/root/.secator freelabz/secator --help
@@ -203,13 +208,13 @@ secator --help
 </details>
 
 <details>
-	<summary>Docker Compose</summary>
+    <summary>Docker Compose</summary>
 
 ```sh
 git clone https://github.com/freelabz/secator
 cd secator
 docker-compose up -d
-docker-compose exec secator secator --help
+docker-compose exec secator-client secator --help
 ```
 
 </details>
@@ -223,7 +228,7 @@ docker-compose exec secator secator --help
 We provide utilities to install required languages if you don't manage them externally:
 
 <details>
-	<summary>Go</summary>
+    <summary>Go</summary>
 
 ```sh
 secator install langs go
@@ -232,7 +237,7 @@ secator install langs go
 </details>
 
 <details>
-	<summary>Ruby</summary>
+    <summary>Ruby</summary>
 
 ```sh
 secator install langs ruby
@@ -247,7 +252,7 @@ secator install langs ruby
 We provide utilities to install or update each supported tool which should work on all systems supporting `apt`:
 
 <details>
-	<summary>All tools</summary>
+    <summary>All tools</summary>
 
 ```sh
 secator install tools
@@ -256,7 +261,7 @@ secator install tools
 </details>
 
 <details>
-	<summary>Specific tools</summary>
+    <summary>Specific tools</summary>
 
 ```sh
 secator install tools <TOOL_NAME>
@@ -279,7 +284,7 @@ Please make sure you are using the latest available versions for each tool befor
 There are several addons available for `secator`:
 
 <details>
-	<summary>worker</summary>
+    <summary>worker</summary>
 
 Add support for Celery workers (see [Distributed runs with Celery](https://docs.freelabz.com/in-depth/distributed-runs-with-celery)).
 ```sh
@@ -290,7 +295,7 @@ secator install addons worker
 
 
 <details>
-	<summary>google</summary>
+    <summary>google</summary>
 
 Add support for Google Drive exporter (`-o gdrive`).
 
@@ -301,7 +306,7 @@ secator install addons google
 </details>
 
 <details>
-	<summary>mongodb</summary>
+    <summary>mongodb</summary>
 
 Add support for MongoDB driver (`-driver mongodb`).
 ```sh
@@ -311,7 +316,7 @@ secator install addons mongodb
 </details>
 
 <details>
-	<summary>redis</summary>
+    <summary>redis</summary>
 
 Add support for Redis backend (Celery).
 
@@ -322,7 +327,7 @@ secator install addons redis
 </details>
 
 <details>
-	<summary>dev</summary>
+    <summary>dev</summary>
 
 Add development tools like `coverage` and `flake8` required for running tests.
 
@@ -333,7 +338,7 @@ secator install addons dev
 </details>
 
 <details>
-	<summary>trace</summary>
+    <summary>trace</summary>
 
 Add tracing tools like `memray` and `pyinstrument` required for tracing functions.
 
@@ -344,7 +349,7 @@ secator install addons trace
 </details>
 
 <details>
-	<summary>build</summary>
+    <summary>build</summary>
 
 Add `hatch` for building and publishing the PyPI package.