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.
- soul_toolkit/__init__.py +3 -0
- soul_toolkit/__main__.py +5 -0
- soul_toolkit/cli.py +273 -0
- soul_toolkit/core/__init__.py +1 -0
- soul_toolkit/core/log.py +101 -0
- soul_toolkit/core/models.py +110 -0
- soul_toolkit/core/progress.py +51 -0
- soul_toolkit/core/runner.py +106 -0
- soul_toolkit/core/target.py +41 -0
- soul_toolkit/data/vhosts.txt +137 -0
- soul_toolkit/data/web-common.txt +141 -0
- soul_toolkit/doctor.py +198 -0
- soul_toolkit/recon/__init__.py +1 -0
- soul_toolkit/recon/engine.py +429 -0
- soul_toolkit/recon/leads.py +101 -0
- soul_toolkit/recon/modules/__init__.py +131 -0
- soul_toolkit/recon/modules/exploits.py +255 -0
- soul_toolkit/recon/modules/ftp.py +178 -0
- soul_toolkit/recon/modules/ldap.py +62 -0
- soul_toolkit/recon/modules/mail.py +125 -0
- soul_toolkit/recon/modules/mysql.py +186 -0
- soul_toolkit/recon/modules/nfs.py +92 -0
- soul_toolkit/recon/modules/postgres.py +133 -0
- soul_toolkit/recon/modules/rdp.py +69 -0
- soul_toolkit/recon/modules/redis.py +115 -0
- soul_toolkit/recon/modules/smb.py +141 -0
- soul_toolkit/recon/modules/smtp.py +128 -0
- soul_toolkit/recon/modules/snmp.py +154 -0
- soul_toolkit/recon/modules/ssh.py +40 -0
- soul_toolkit/recon/modules/web.py +626 -0
- soul_toolkit/recon/modules/winrm.py +28 -0
- soul_toolkit/recon/nmap.py +236 -0
- soul_toolkit/recon/report.py +214 -0
- soul_toolkit/recon/report_html.py +620 -0
- soul_toolkit/recon/settings.py +183 -0
- soul_toolkit/recon/vhosts.py +130 -0
- soul_toolkit/recon/writeup.py +159 -0
- soul_toolkit-0.3.2.dist-info/METADATA +499 -0
- soul_toolkit-0.3.2.dist-info/RECORD +43 -0
- soul_toolkit-0.3.2.dist-info/WHEEL +5 -0
- soul_toolkit-0.3.2.dist-info/entry_points.txt +3 -0
- soul_toolkit-0.3.2.dist-info/licenses/LICENSE +21 -0
- soul_toolkit-0.3.2.dist-info/top_level.txt +1 -0
soul_toolkit/__init__.py
ADDED
soul_toolkit/__main__.py
ADDED
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."""
|
soul_toolkit/core/log.py
ADDED
|
@@ -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()
|