soul-toolkit 0.3.2__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. soul_toolkit/__init__.py +3 -0
  2. soul_toolkit/__main__.py +5 -0
  3. soul_toolkit/cli.py +273 -0
  4. soul_toolkit/core/__init__.py +1 -0
  5. soul_toolkit/core/log.py +101 -0
  6. soul_toolkit/core/models.py +110 -0
  7. soul_toolkit/core/progress.py +51 -0
  8. soul_toolkit/core/runner.py +106 -0
  9. soul_toolkit/core/target.py +41 -0
  10. soul_toolkit/data/vhosts.txt +137 -0
  11. soul_toolkit/data/web-common.txt +141 -0
  12. soul_toolkit/doctor.py +198 -0
  13. soul_toolkit/recon/__init__.py +1 -0
  14. soul_toolkit/recon/engine.py +429 -0
  15. soul_toolkit/recon/leads.py +101 -0
  16. soul_toolkit/recon/modules/__init__.py +131 -0
  17. soul_toolkit/recon/modules/exploits.py +255 -0
  18. soul_toolkit/recon/modules/ftp.py +178 -0
  19. soul_toolkit/recon/modules/ldap.py +62 -0
  20. soul_toolkit/recon/modules/mail.py +125 -0
  21. soul_toolkit/recon/modules/mysql.py +186 -0
  22. soul_toolkit/recon/modules/nfs.py +92 -0
  23. soul_toolkit/recon/modules/postgres.py +133 -0
  24. soul_toolkit/recon/modules/rdp.py +69 -0
  25. soul_toolkit/recon/modules/redis.py +115 -0
  26. soul_toolkit/recon/modules/smb.py +141 -0
  27. soul_toolkit/recon/modules/smtp.py +128 -0
  28. soul_toolkit/recon/modules/snmp.py +154 -0
  29. soul_toolkit/recon/modules/ssh.py +40 -0
  30. soul_toolkit/recon/modules/web.py +626 -0
  31. soul_toolkit/recon/modules/winrm.py +28 -0
  32. soul_toolkit/recon/nmap.py +236 -0
  33. soul_toolkit/recon/report.py +214 -0
  34. soul_toolkit/recon/report_html.py +620 -0
  35. soul_toolkit/recon/settings.py +183 -0
  36. soul_toolkit/recon/vhosts.py +130 -0
  37. soul_toolkit/recon/writeup.py +159 -0
  38. soul_toolkit-0.3.2.dist-info/METADATA +499 -0
  39. soul_toolkit-0.3.2.dist-info/RECORD +43 -0
  40. soul_toolkit-0.3.2.dist-info/WHEEL +5 -0
  41. soul_toolkit-0.3.2.dist-info/entry_points.txt +3 -0
  42. soul_toolkit-0.3.2.dist-info/licenses/LICENSE +21 -0
  43. soul_toolkit-0.3.2.dist-info/top_level.txt +1 -0
@@ -0,0 +1,3 @@
1
+ """soul-toolkit: a modular pentest toolkit for authorized labs and CTFs."""
2
+
3
+ __version__ = "0.3.2"
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from soul_toolkit.cli import main
4
+
5
+ sys.exit(main())
soul_toolkit/cli.py ADDED
@@ -0,0 +1,273 @@
1
+ """Command-line entry point: `toolkit <command> ...`."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ from soul_toolkit import __version__
10
+ from soul_toolkit.core.log import Logger
11
+ from soul_toolkit.core.runner import ToolMissing
12
+ from soul_toolkit.core.target import InvalidTarget, validate_target
13
+ from soul_toolkit.recon.settings import PROFILE_HELP
14
+
15
+ BANNER = f"soul-toolkit v{__version__} :: authorized targets only (see DISCLAIMER.md)"
16
+
17
+
18
+ # --------------------------------------------------------------------------- recon
19
+
20
+
21
+ def add_recon_parser(sub: argparse._SubParsersAction) -> None:
22
+ p = sub.add_parser(
23
+ "recon",
24
+ help="staged nmap scan + service-aware follow-ups + report",
25
+ description="Port sweep -> service scan -> per-service modules -> Markdown/JSON report.",
26
+ formatter_class=argparse.RawDescriptionHelpFormatter,
27
+ epilog=(
28
+ "examples:\n"
29
+ " sudo toolkit recon 10.10.42.17\n"
30
+ " toolkit recon 10.10.42.17 --quick --no-brute\n"
31
+ " toolkit recon cheese.thm --writeup # + writeup.md for your notes vault\n"
32
+ " toolkit recon box.thm -p 80 # also fuzzes *.box.thm vhosts\n"
33
+ " toolkit recon target.thm -p 80,8080 -w /usr/share/seclists/Discovery/Web-Content/common.txt -x php,txt\n"
34
+ ),
35
+ )
36
+ p.add_argument("target", nargs="?", help="IP address or hostname of a host you are authorized to test")
37
+
38
+ scan = p.add_argument_group("scanning")
39
+ scan.add_argument("-p", "--ports", help="skip the port sweep and use these ports (e.g. 22,80,8000-8010)")
40
+ scan.add_argument("--profile", choices=["quick", "default", "thorough"],
41
+ help="bundle of sensible settings: " + "; ".join(f"{k} = {v}" for k, v in PROFILE_HELP.items())
42
+ + ". Explicit flags still win")
43
+ scan.add_argument("--quick", action="store_true", default=None,
44
+ help="sweep the top 1000 ports instead of all 65535")
45
+ scan.add_argument("--min-rate", type=int, metavar="N",
46
+ help="nmap --min-rate for the sweep (default 1000; 0 = nmap default)")
47
+ scan.add_argument("--ping", action="store_true",
48
+ help="do host discovery (default is -Pn, since lab boxes often drop ping)")
49
+ scan.add_argument("--no-scripts", dest="scripts", action="store_false", default=None,
50
+ help="skip nmap default scripts (-sC)")
51
+ scan.add_argument("--resume", action="store_true",
52
+ help="reuse finished nmap results (XML) from an earlier run in the output dir")
53
+ udp = scan.add_mutually_exclusive_group()
54
+ udp.add_argument("--udp", dest="udp", action="store_true", default=None,
55
+ help="scan the top 100 UDP ports (needs root; on by default as root unless -p is given)")
56
+ udp.add_argument("--no-udp", dest="udp", action="store_false", help="never scan UDP")
57
+
58
+ mods = p.add_argument_group("modules")
59
+ mods.add_argument("-m", "--modules", help="comma-separated modules to run (default: all)")
60
+ mods.add_argument("--no-modules", action="store_true", help="nmap only, no follow-up modules")
61
+ mods.add_argument("-j", "--jobs", type=int, metavar="N",
62
+ help="module runs in parallel (default 4; 1 = one at a time)")
63
+ mods.add_argument("--list-modules", action="store_true", help="list available modules and exit")
64
+ mods.add_argument("--no-brute", dest="brute", action="store_false", default=None,
65
+ help="skip content discovery and vhost fuzzing")
66
+ mods.add_argument("--no-vhost", dest="vhosts", action="store_false", default=None,
67
+ help="skip vhost fuzzing only")
68
+ mods.add_argument("--vhost-wordlist", metavar="FILE",
69
+ help="wordlist for vhost fuzzing (default: SecLists subdomains-top1million-5000.txt if found)")
70
+ mods.add_argument("-w", "--wordlist", help="wordlist for gobuster (default: SecLists common.txt if found)")
71
+ mods.add_argument("-x", "--extensions",
72
+ help="extensions for gobuster, e.g. php,txt,html (default: picked from the fingerprint)")
73
+ mods.add_argument("--no-recurse", dest="recurse", action="store_false", default=None,
74
+ help="don't run gobuster again inside the directories it finds")
75
+ mods.add_argument("-t", "--threads", type=int, help="gobuster/ffuf threads (default 30)")
76
+ mods.add_argument("--brute-timeout", type=int, metavar="SEC",
77
+ help="max seconds of content discovery per web port, recursion included (default 600)")
78
+
79
+ out = p.add_argument_group("output")
80
+ out.add_argument("-o", "--output", help="output directory (default: ./results)")
81
+ out.add_argument("--writeup", action="store_true",
82
+ help="also write writeup.md: an Obsidian-friendly skeleton with the Recon section filled in")
83
+ out.add_argument("--room", metavar="NAME", help="room/box name for the writeup (implies --writeup; "
84
+ "default: the target, minus .thm/.htb)")
85
+ out.add_argument("--config", metavar="FILE",
86
+ help="settings file (default: ~/.config/soul-toolkit/config.ini, used if it exists)")
87
+ out.add_argument("-v", "--verbose", action="store_true", help="show the commands being run")
88
+ out.add_argument("-q", "--quiet", action="store_true", help="only print warnings and errors")
89
+
90
+ p.set_defaults(func=cmd_recon)
91
+
92
+
93
+ def cmd_recon(args: argparse.Namespace) -> int:
94
+ # Imported lazily so `toolkit --help` stays fast and other commands don't pay for it.
95
+ from soul_toolkit.recon import nmap
96
+ from soul_toolkit.recon.engine import ReconConfig, run_recon
97
+ from soul_toolkit.recon.modules import Options, all_modules, select_modules
98
+ from soul_toolkit.recon.settings import DEFAULTS, ConfigError, default_config_path, load_config, resolve
99
+
100
+ log = Logger(verbose=args.verbose, quiet=args.quiet)
101
+
102
+ if args.list_modules:
103
+ for m in all_modules():
104
+ print(f"{m.name:<9} {m.description}")
105
+ return 0
106
+
107
+ if not args.target:
108
+ log.error("a target is required (e.g. toolkit recon 10.10.42.17)")
109
+ return 2
110
+
111
+ try:
112
+ target = validate_target(args.target)
113
+ ports = nmap.parse_ports(args.ports) if args.ports else None
114
+ if args.no_modules:
115
+ modules = []
116
+ else:
117
+ modules = select_modules(args.modules.split(",") if args.modules else None)
118
+ config_path = Path(args.config).expanduser() if args.config else default_config_path()
119
+ if args.config and not config_path.is_file():
120
+ raise ConfigError(f"config file not found: {config_path}")
121
+ config, config_profile, warnings = load_config(config_path)
122
+ for w in warnings:
123
+ log.warn(w)
124
+ profile = args.profile or config_profile or "default"
125
+ s = resolve({k: getattr(args, k, None) for k in DEFAULTS}, profile, config)
126
+ except (InvalidTarget, ValueError) as exc:
127
+ log.error(str(exc))
128
+ return 2
129
+
130
+ cfg = ReconConfig(
131
+ target=target,
132
+ output=Path(s["output"]).expanduser(),
133
+ ports=ports,
134
+ full=not s["quick"],
135
+ min_rate=s["min_rate"] or None,
136
+ skip_ping=not args.ping,
137
+ scripts=s["scripts"],
138
+ udp=s["udp"],
139
+ modules=modules,
140
+ writeup=args.writeup or bool(args.room),
141
+ room=args.room,
142
+ jobs=max(1, s["jobs"]),
143
+ resume=args.resume,
144
+ options=Options(
145
+ brute=s["brute"],
146
+ wordlist=s["wordlist"],
147
+ threads=max(1, s["threads"]),
148
+ brute_timeout=max(10, s["brute_timeout"]),
149
+ extensions=s["extensions"],
150
+ recurse=s["recurse"],
151
+ vhosts=s["vhosts"],
152
+ vhost_wordlist=s["vhost_wordlist"],
153
+ ),
154
+ )
155
+
156
+ if not args.quiet:
157
+ log.info(BANNER)
158
+ log.info(f"Target: {target}" + (f" (profile: {profile})" if profile != "default" else ""))
159
+ if config:
160
+ log.debug(f"Settings from {config_path}: {', '.join(sorted(config))}")
161
+ try:
162
+ run_recon(cfg, log)
163
+ except ToolMissing as exc:
164
+ log.error(str(exc))
165
+ return 127
166
+ except nmap.NmapError as exc:
167
+ log.error(str(exc))
168
+ return 1
169
+ except OSError as exc:
170
+ log.error(f"{exc.strerror or exc}: {exc.filename or ''}".rstrip(": "))
171
+ return 1
172
+ except KeyboardInterrupt:
173
+ log.warn("Interrupted - the partial report above has everything that finished.")
174
+ return 130
175
+ return 0
176
+
177
+
178
+ # --------------------------------------------------------------------------- doctor
179
+
180
+
181
+ def add_doctor_parser(sub: argparse._SubParsersAction) -> None:
182
+ p = sub.add_parser("doctor", help="check which external tools are installed and how to install the rest",
183
+ description="Check every external tool recon uses, what each enables, and print the "
184
+ "install commands for Arch, Debian/Kali and macOS.")
185
+ p.add_argument("--all", action="store_true", help="print install commands for every tool, not just missing ones")
186
+ p.set_defaults(func=cmd_doctor)
187
+
188
+
189
+ def cmd_doctor(args: argparse.Namespace) -> int:
190
+ from soul_toolkit.doctor import run_doctor
191
+
192
+ return run_doctor(show_all=args.all)
193
+
194
+
195
+ # --------------------------------------------------------------------------- config
196
+
197
+
198
+ def add_config_parser(sub: argparse._SubParsersAction) -> None:
199
+ p = sub.add_parser("config", help="show the settings file and the values recon will use",
200
+ description="Show where the settings file lives and the effective recon settings "
201
+ "(defaults < profile < config file; flags still override at run time).")
202
+ p.add_argument("--init", action="store_true", help="write a commented example config file if none exists")
203
+ p.add_argument("--path", metavar="FILE", help="config file to use instead of the default location")
204
+ p.set_defaults(func=cmd_config)
205
+
206
+
207
+ def cmd_config(args: argparse.Namespace) -> int:
208
+ from soul_toolkit.recon.settings import (
209
+ DEFAULTS,
210
+ EXAMPLE_CONFIG,
211
+ ConfigError,
212
+ default_config_path,
213
+ load_config,
214
+ resolve,
215
+ )
216
+
217
+ path = Path(args.path).expanduser() if args.path else default_config_path()
218
+ if args.init:
219
+ if path.exists():
220
+ print(f"{path} already exists - not touching it.")
221
+ return 1
222
+ path.parent.mkdir(parents=True, exist_ok=True)
223
+ path.write_text(EXAMPLE_CONFIG, encoding="utf-8")
224
+ print(f"Wrote an example config to {path}")
225
+ return 0
226
+ try:
227
+ config, profile, warnings = load_config(path)
228
+ except ConfigError as exc:
229
+ print(f"error: {exc}", file=sys.stderr)
230
+ return 2
231
+ for w in warnings:
232
+ print(f"warning: {w}", file=sys.stderr)
233
+ state = "found" if path.is_file() else "not found - using defaults; create one with: toolkit config --init"
234
+ print(f"Config file: {path} ({state})")
235
+ print(f"Profile: {profile or 'default'}")
236
+ effective = resolve(dict.fromkeys(DEFAULTS), profile or "default", config)
237
+ for key in DEFAULTS:
238
+ source = "config" if key in config else ("profile" if effective[key] != DEFAULTS[key] else "default")
239
+ value = effective[key]
240
+ if value is None or value == "":
241
+ value = {"udp": "auto (on as root unless -p is given)", "extensions": "auto (from the fingerprint)"}.get(
242
+ key, "auto (SecLists if installed, else bundled)")
243
+ print(f" {key:<15} {value!s:<45} ({source})")
244
+ return 0
245
+
246
+
247
+ # --------------------------------------------------------------------------- main
248
+
249
+
250
+ def build_parser() -> argparse.ArgumentParser:
251
+ parser = argparse.ArgumentParser(
252
+ prog="toolkit",
253
+ description="soul-toolkit - a modular pentest toolkit for authorized labs and CTFs.",
254
+ )
255
+ parser.add_argument("--version", action="version", version=f"soul-toolkit {__version__}")
256
+ sub = parser.add_subparsers(dest="command", metavar="<command>")
257
+ add_recon_parser(sub)
258
+ add_doctor_parser(sub)
259
+ add_config_parser(sub)
260
+ return parser
261
+
262
+
263
+ def main(argv: list[str] | None = None) -> int:
264
+ parser = build_parser()
265
+ args = parser.parse_args(argv)
266
+ if not getattr(args, "command", None):
267
+ parser.print_help()
268
+ return 1
269
+ return args.func(args)
270
+
271
+
272
+ if __name__ == "__main__": # pragma: no cover
273
+ sys.exit(main())
@@ -0,0 +1 @@
1
+ """Shared building blocks used by every toolkit command."""
@@ -0,0 +1,101 @@
1
+ """Tiny console logger with optional colour. No third-party dependencies."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import shutil
7
+ import sys
8
+ import threading
9
+
10
+ _RESET = "\033[0m"
11
+ _COLOURS = {
12
+ "info": "\033[36m", # cyan
13
+ "ok": "\033[32m", # green
14
+ "warn": "\033[33m", # yellow
15
+ "err": "\033[31m", # red
16
+ "step": "\033[35m", # magenta
17
+ "dim": "\033[2m",
18
+ }
19
+ _TAGS = {"info": "[*]", "ok": "[+]", "warn": "[!]", "err": "[-]", "step": "[>]", "dim": " "}
20
+
21
+
22
+ def _use_colour() -> bool:
23
+ return sys.stderr.isatty() and "NO_COLOR" not in os.environ
24
+
25
+
26
+ class Logger:
27
+ """Thread-safe. On a terminal it can also show one live status line at the bottom
28
+ (progress, elapsed time) that normal log lines are printed above."""
29
+
30
+ def __init__(self, verbose: bool = False, quiet: bool = False, colour: bool | None = None,
31
+ live: bool | None = None):
32
+ self.verbose = verbose
33
+ self.quiet = quiet
34
+ self.colour = _use_colour() if colour is None else colour
35
+ self.live = (sys.stderr.isatty() and not quiet) if live is None else live
36
+ self._lock = threading.RLock()
37
+ self._status = ""
38
+ self.main_thread_only = False # set after Ctrl-C: module threads winding down stay quiet
39
+
40
+ def _clear_status(self) -> None:
41
+ if self._status:
42
+ sys.stderr.write("\r\033[K")
43
+
44
+ def _draw_status(self) -> None:
45
+ if self._status:
46
+ width = shutil.get_terminal_size((100, 20)).columns - 1
47
+ text = self._status if len(self._status) <= width else self._status[: width - 3] + "..."
48
+ sys.stderr.write(f"\033[2m{text}\033[0m" if self.colour else text)
49
+ sys.stderr.flush()
50
+
51
+ def status(self, text: str | None) -> None:
52
+ """Show (or with None, remove) the live status line. No-op unless live."""
53
+ if not self.live:
54
+ return
55
+ with self._lock:
56
+ self._clear_status()
57
+ self._status = text or ""
58
+ self._draw_status()
59
+ if not self._status:
60
+ sys.stderr.flush()
61
+
62
+ def _print(self, line: str) -> None:
63
+ if self.main_thread_only and threading.current_thread() is not threading.main_thread():
64
+ return
65
+ with self._lock:
66
+ self._clear_status()
67
+ print(line, file=sys.stderr, flush=True)
68
+ self._draw_status()
69
+
70
+ def _emit(self, kind: str, msg: str) -> None:
71
+ tag = _TAGS[kind]
72
+ if self.colour:
73
+ tag = f"{_COLOURS[kind]}{tag}{_RESET}"
74
+ self._print(f"{tag} {msg}")
75
+
76
+ def info(self, msg: str) -> None:
77
+ if not self.quiet:
78
+ self._emit("info", msg)
79
+
80
+ def ok(self, msg: str) -> None:
81
+ if not self.quiet:
82
+ self._emit("ok", msg)
83
+
84
+ def step(self, msg: str) -> None:
85
+ if not self.quiet:
86
+ self._emit("step", msg)
87
+
88
+ def line(self, msg: str = "") -> None:
89
+ """Untagged output (indented continuation lines, summaries)."""
90
+ if not self.quiet:
91
+ self._print(msg)
92
+
93
+ def debug(self, msg: str) -> None:
94
+ if self.verbose and not self.quiet:
95
+ self._emit("dim", msg)
96
+
97
+ def warn(self, msg: str) -> None:
98
+ self._emit("warn", msg)
99
+
100
+ def error(self, msg: str) -> None:
101
+ self._emit("err", msg)
@@ -0,0 +1,110 @@
1
+ """Data structures shared across the toolkit."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import asdict, dataclass, field
6
+ from typing import Any
7
+
8
+ SEVERITIES = ("info", "low", "medium", "high")
9
+
10
+ WEB_PORTS = {80, 443, 591, 3000, 5000, 8000, 8008, 8080, 8081, 8443, 8888, 9000, 9090}
11
+ TLS_PORTS = {443, 8443}
12
+
13
+
14
+ @dataclass
15
+ class Service:
16
+ port: int
17
+ protocol: str = "tcp"
18
+ state: str = "open"
19
+ name: str = ""
20
+ product: str = ""
21
+ version: str = ""
22
+ extrainfo: str = ""
23
+ tunnel: str = ""
24
+ scripts: dict[str, str] = field(default_factory=dict)
25
+ hostname: str = "" # name the service itself reported (nmap -sV), e.g. a domain controller's
26
+
27
+ @property
28
+ def label(self) -> str:
29
+ return f"{self.port}/{self.protocol}"
30
+
31
+ @property
32
+ def banner(self) -> str:
33
+ parts = [self.product, self.version]
34
+ if self.extrainfo:
35
+ parts.append(f"({self.extrainfo})")
36
+ return " ".join(p for p in parts if p)
37
+
38
+ @property
39
+ def is_web(self) -> bool:
40
+ name = self.name.lower()
41
+ if "http" in name:
42
+ return True
43
+ return self.port in WEB_PORTS and name in ("", "unknown", "tcpwrapped")
44
+
45
+ @property
46
+ def is_tls(self) -> bool:
47
+ name = self.name.lower()
48
+ return self.tunnel == "ssl" or name in ("https", "ssl/http", "https-alt") or self.port in TLS_PORTS
49
+
50
+
51
+ @dataclass
52
+ class Finding:
53
+ module: str
54
+ port: int
55
+ title: str
56
+ severity: str = "info"
57
+ detail: str = ""
58
+ data: dict[str, Any] = field(default_factory=dict)
59
+ protocol: str = "tcp" # set by the engine from the service the module ran on
60
+
61
+ def __post_init__(self) -> None:
62
+ if self.severity not in SEVERITIES:
63
+ raise ValueError(f"unknown severity {self.severity!r}")
64
+
65
+ @property
66
+ def rank(self) -> int:
67
+ return SEVERITIES.index(self.severity)
68
+
69
+
70
+ @dataclass
71
+ class Lead:
72
+ """Something worth trying next, with the reason and a copy-paste command."""
73
+
74
+ kind: str
75
+ port: int
76
+ title: str
77
+ why: str
78
+ command: str = ""
79
+ score: int = 0
80
+ protocol: str = "tcp"
81
+
82
+ @property
83
+ def where(self) -> str:
84
+ return f"{self.port}/{self.protocol}" if self.port else "host"
85
+
86
+
87
+ @dataclass
88
+ class HostResult:
89
+ target: str
90
+ address: str = ""
91
+ hostnames: list[str] = field(default_factory=list)
92
+ status: str = "unknown"
93
+ os_guess: str = ""
94
+ services: list[Service] = field(default_factory=list)
95
+ findings: list[Finding] = field(default_factory=list)
96
+ hints: list[str] = field(default_factory=list)
97
+ leads: list[Lead] = field(default_factory=list)
98
+ commands: list[str] = field(default_factory=list)
99
+ udp_scanned: bool = False
100
+ interrupted: bool = False # Ctrl-C: the report only holds what finished
101
+ incomplete: list[str] = field(default_factory=list) # stages / module runs that didn't finish
102
+ started: str = ""
103
+ finished: str = ""
104
+ duration: float = 0.0
105
+
106
+ def sorted_findings(self) -> list[Finding]:
107
+ return sorted(self.findings, key=lambda f: (-f.rank, f.port, f.module))
108
+
109
+ def to_dict(self) -> dict[str, Any]:
110
+ return asdict(self)
@@ -0,0 +1,51 @@
1
+ """Live progress: redraw a status line (with elapsed time) once a second while work runs."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import threading
6
+ import time
7
+ from typing import Callable
8
+
9
+ from soul_toolkit.core.log import Logger
10
+
11
+
12
+ def fmt_elapsed(seconds: float) -> str:
13
+ m, s = divmod(int(seconds), 60)
14
+ h, m = divmod(m, 60)
15
+ return f"{h}:{m:02d}:{s:02d}" if h else f"{m}:{s:02d}"
16
+
17
+
18
+ class LiveStatus:
19
+ """`with LiveStatus(log, render):` keeps `render()` on the status line, refreshed every
20
+ *interval* seconds, and removes it on exit. Does nothing when the logger isn't live (not a TTY)."""
21
+
22
+ def __init__(self, log: Logger, render: Callable[[], str], interval: float = 1.0):
23
+ self.log, self.render, self.interval = log, render, interval
24
+ self._stop = threading.Event()
25
+ self._thread: threading.Thread | None = None
26
+
27
+ def _loop(self) -> None:
28
+ while not self._stop.is_set():
29
+ self.log.status(self.render())
30
+ self._stop.wait(self.interval)
31
+
32
+ def __enter__(self) -> LiveStatus:
33
+ if self.log.live:
34
+ self._thread = threading.Thread(target=self._loop, name="live-status", daemon=True)
35
+ self._thread.start()
36
+ return self
37
+
38
+ def __exit__(self, *exc) -> None:
39
+ self._stop.set()
40
+ if self._thread:
41
+ self._thread.join(2)
42
+ self.log.status(None)
43
+
44
+
45
+ class Stopwatch:
46
+ def __init__(self) -> None:
47
+ self.start = time.monotonic()
48
+
49
+ @property
50
+ def elapsed(self) -> str:
51
+ return fmt_elapsed(time.monotonic() - self.start)
@@ -0,0 +1,106 @@
1
+ """Run external tools (nmap, gobuster, ...) safely and consistently.
2
+
3
+ Commands are always passed as argument lists, never through a shell, so target
4
+ strings can't be used for command injection.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import shlex
10
+ import shutil
11
+ import subprocess
12
+ import threading
13
+ import time
14
+ from dataclasses import dataclass
15
+
16
+ # Child processes currently running, so an interrupt can stop them all (module threads included).
17
+ _active: set[subprocess.Popen] = set()
18
+ _lock = threading.Lock()
19
+ _stopping = threading.Event()
20
+
21
+
22
+ class ToolMissing(RuntimeError):
23
+ """Raised when a required external binary is not on PATH."""
24
+
25
+
26
+ def which(tool: str) -> str | None:
27
+ return shutil.which(tool)
28
+
29
+
30
+ def require(tool: str, hint: str = "") -> str:
31
+ path = shutil.which(tool)
32
+ if not path:
33
+ msg = f"'{tool}' not found on PATH."
34
+ if hint:
35
+ msg += f" {hint}"
36
+ raise ToolMissing(msg)
37
+ return path
38
+
39
+
40
+ @dataclass
41
+ class CommandResult:
42
+ cmd: list[str]
43
+ returncode: int
44
+ stdout: str
45
+ stderr: str
46
+ duration: float
47
+ timed_out: bool = False
48
+
49
+ @property
50
+ def ok(self) -> bool:
51
+ return self.returncode == 0 and not self.timed_out
52
+
53
+ @property
54
+ def pretty(self) -> str:
55
+ return shlex.join(self.cmd)
56
+
57
+
58
+ def _to_text(data: str | bytes | None) -> str:
59
+ if data is None:
60
+ return ""
61
+ if isinstance(data, bytes):
62
+ return data.decode("utf-8", errors="replace")
63
+ return data
64
+
65
+
66
+ def run(cmd: list[str], timeout: float | None = None) -> CommandResult:
67
+ """Run *cmd* and capture its output. Never raises on non-zero exit.
68
+
69
+ After stop_all() it starts nothing and returns a failed result straight away."""
70
+ start = time.monotonic()
71
+ if _stopping.is_set():
72
+ return CommandResult(cmd, -1, "", "not started: run interrupted", 0.0)
73
+ proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, errors="replace")
74
+ with _lock:
75
+ _active.add(proc)
76
+ try:
77
+ out, err = proc.communicate(timeout=timeout)
78
+ return CommandResult(cmd, proc.returncode, out, err, time.monotonic() - start)
79
+ except subprocess.TimeoutExpired:
80
+ proc.kill()
81
+ out, err = proc.communicate()
82
+ return CommandResult(cmd, -1, _to_text(out), _to_text(err), time.monotonic() - start, timed_out=True)
83
+ except BaseException: # Ctrl-C in the calling thread: don't leave the child behind
84
+ proc.kill()
85
+ proc.wait()
86
+ raise
87
+ finally:
88
+ with _lock:
89
+ _active.discard(proc)
90
+
91
+
92
+ def stop_all() -> None:
93
+ """Terminate every running child process and refuse to start new ones (used on Ctrl-C)."""
94
+ _stopping.set()
95
+ with _lock:
96
+ procs = list(_active)
97
+ for p in procs:
98
+ try:
99
+ p.terminate()
100
+ except OSError:
101
+ pass
102
+
103
+
104
+ def reset() -> None:
105
+ """Allow commands again after stop_all() (tests, or a second run in one process)."""
106
+ _stopping.clear()