soul-toolkit 0.3.2__tar.gz
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-0.3.2/CHANGELOG.md +189 -0
- soul_toolkit-0.3.2/CONTRIBUTING.md +77 -0
- soul_toolkit-0.3.2/DISCLAIMER.md +12 -0
- soul_toolkit-0.3.2/LICENSE +21 -0
- soul_toolkit-0.3.2/MANIFEST.in +6 -0
- soul_toolkit-0.3.2/PKG-INFO +499 -0
- soul_toolkit-0.3.2/README.md +470 -0
- soul_toolkit-0.3.2/pyproject.toml +59 -0
- soul_toolkit-0.3.2/scripts/release_notes.py +58 -0
- soul_toolkit-0.3.2/setup.cfg +4 -0
- soul_toolkit-0.3.2/src/soul_toolkit/__init__.py +3 -0
- soul_toolkit-0.3.2/src/soul_toolkit/__main__.py +5 -0
- soul_toolkit-0.3.2/src/soul_toolkit/cli.py +273 -0
- soul_toolkit-0.3.2/src/soul_toolkit/core/__init__.py +1 -0
- soul_toolkit-0.3.2/src/soul_toolkit/core/log.py +101 -0
- soul_toolkit-0.3.2/src/soul_toolkit/core/models.py +110 -0
- soul_toolkit-0.3.2/src/soul_toolkit/core/progress.py +51 -0
- soul_toolkit-0.3.2/src/soul_toolkit/core/runner.py +106 -0
- soul_toolkit-0.3.2/src/soul_toolkit/core/target.py +41 -0
- soul_toolkit-0.3.2/src/soul_toolkit/data/vhosts.txt +137 -0
- soul_toolkit-0.3.2/src/soul_toolkit/data/web-common.txt +141 -0
- soul_toolkit-0.3.2/src/soul_toolkit/doctor.py +198 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/__init__.py +1 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/engine.py +429 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/leads.py +101 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/__init__.py +131 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/exploits.py +255 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/ftp.py +178 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/ldap.py +62 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/mail.py +125 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/mysql.py +186 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/nfs.py +92 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/postgres.py +133 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/rdp.py +69 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/redis.py +115 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/smb.py +141 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/smtp.py +128 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/snmp.py +154 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/ssh.py +40 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/web.py +626 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/modules/winrm.py +28 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/nmap.py +236 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/report.py +214 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/report_html.py +620 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/settings.py +183 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/vhosts.py +130 -0
- soul_toolkit-0.3.2/src/soul_toolkit/recon/writeup.py +159 -0
- soul_toolkit-0.3.2/src/soul_toolkit.egg-info/PKG-INFO +499 -0
- soul_toolkit-0.3.2/src/soul_toolkit.egg-info/SOURCES.txt +115 -0
- soul_toolkit-0.3.2/src/soul_toolkit.egg-info/dependency_links.txt +1 -0
- soul_toolkit-0.3.2/src/soul_toolkit.egg-info/entry_points.txt +3 -0
- soul_toolkit-0.3.2/src/soul_toolkit.egg-info/requires.txt +4 -0
- soul_toolkit-0.3.2/src/soul_toolkit.egg-info/top_level.txt +1 -0
- soul_toolkit-0.3.2/tests/conftest.py +8 -0
- soul_toolkit-0.3.2/tests/fixtures/ffuf-vhosts.json +1 -0
- soul_toolkit-0.3.2/tests/fixtures/fowsniff-gobuster-80.txt +9 -0
- soul_toolkit-0.3.2/tests/fixtures/fowsniff-services.xml +42 -0
- soul_toolkit-0.3.2/tests/fixtures/gobuster-vhosts.txt +2 -0
- soul_toolkit-0.3.2/tests/fixtures/searchsploit-apache-2.4.18.json +14 -0
- soul_toolkit-0.3.2/tests/fixtures/searchsploit-apache.json +10 -0
- soul_toolkit-0.3.2/tests/fixtures/searchsploit-proftpd.json +11 -0
- soul_toolkit-0.3.2/tests/fixtures/services.xml +20 -0
- soul_toolkit-0.3.2/tests/fixtures/udp-services.xml +14 -0
- soul_toolkit-0.3.2/tests/lab/README.md +39 -0
- soul_toolkit-0.3.2/tests/lab/docker-compose.yml +47 -0
- soul_toolkit-0.3.2/tests/lab/ftp/Dockerfile +12 -0
- soul_toolkit-0.3.2/tests/lab/ftp/files/backups/README.txt +2 -0
- soul_toolkit-0.3.2/tests/lab/ftp/files/note.txt +4 -0
- soul_toolkit-0.3.2/tests/lab/ftp/vsftpd.conf +17 -0
- soul_toolkit-0.3.2/tests/lab/ftp/xinetd-ftp +14 -0
- soul_toolkit-0.3.2/tests/lab/nfs/Dockerfile +8 -0
- soul_toolkit-0.3.2/tests/lab/nfs/files/home/ops/.ssh/authorized_keys +1 -0
- soul_toolkit-0.3.2/tests/lab/nfs/files/home/ops/notes.txt +1 -0
- soul_toolkit-0.3.2/tests/lab/nfs/ganesha.conf +16 -0
- soul_toolkit-0.3.2/tests/lab/nfs/start.sh +7 -0
- soul_toolkit-0.3.2/tests/lab/smb/Dockerfile +7 -0
- soul_toolkit-0.3.2/tests/lab/smb/files/onboarding.txt +3 -0
- soul_toolkit-0.3.2/tests/lab/smb/smb.conf +18 -0
- soul_toolkit-0.3.2/tests/lab/web/Dockerfile +15 -0
- soul_toolkit-0.3.2/tests/lab/web/nginx.conf +24 -0
- soul_toolkit-0.3.2/tests/lab/web/site/app/admin/index.html +1 -0
- soul_toolkit-0.3.2/tests/lab/web/site/app/backup/index.html +1 -0
- soul_toolkit-0.3.2/tests/lab/web/site/app/index.html +3 -0
- soul_toolkit-0.3.2/tests/lab/web/site/app/login.html +1 -0
- soul_toolkit-0.3.2/tests/lab/web/site/app/robots.txt +3 -0
- soul_toolkit-0.3.2/tests/lab/web/site/dev/index.html +3 -0
- soul_toolkit-0.3.2/tests/lab/web/site/lab/about.html +1 -0
- soul_toolkit-0.3.2/tests/lab/web/site/lab/index.html +4 -0
- soul_toolkit-0.3.2/tests/test_config.py +103 -0
- soul_toolkit-0.3.2/tests/test_core.py +59 -0
- soul_toolkit-0.3.2/tests/test_doctor.py +98 -0
- soul_toolkit-0.3.2/tests/test_engine.py +72 -0
- soul_toolkit-0.3.2/tests/test_exploits.py +191 -0
- soul_toolkit-0.3.2/tests/test_lab.py +162 -0
- soul_toolkit-0.3.2/tests/test_leads.py +130 -0
- soul_toolkit-0.3.2/tests/test_mail.py +121 -0
- soul_toolkit-0.3.2/tests/test_modules.py +260 -0
- soul_toolkit-0.3.2/tests/test_mysql.py +166 -0
- soul_toolkit-0.3.2/tests/test_nfs.py +112 -0
- soul_toolkit-0.3.2/tests/test_nmap.py +87 -0
- soul_toolkit-0.3.2/tests/test_parallel.py +181 -0
- soul_toolkit-0.3.2/tests/test_postgres.py +166 -0
- soul_toolkit-0.3.2/tests/test_redis.py +108 -0
- soul_toolkit-0.3.2/tests/test_release_notes.py +39 -0
- soul_toolkit-0.3.2/tests/test_report_cli.py +80 -0
- soul_toolkit-0.3.2/tests/test_report_html.py +185 -0
- soul_toolkit-0.3.2/tests/test_resume.py +115 -0
- soul_toolkit-0.3.2/tests/test_settings.py +69 -0
- soul_toolkit-0.3.2/tests/test_smb.py +153 -0
- soul_toolkit-0.3.2/tests/test_smtp.py +117 -0
- soul_toolkit-0.3.2/tests/test_snmp.py +177 -0
- soul_toolkit-0.3.2/tests/test_udp.py +146 -0
- soul_toolkit-0.3.2/tests/test_vhosts.py +259 -0
- soul_toolkit-0.3.2/tests/test_web_enum.py +284 -0
- soul_toolkit-0.3.2/tests/test_web_files.py +117 -0
- soul_toolkit-0.3.2/tests/test_windows.py +118 -0
- soul_toolkit-0.3.2/tests/test_writeup.py +113 -0
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project. The format is based on
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
|
|
5
|
+
[Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## Unreleased
|
|
8
|
+
|
|
9
|
+
## 0.3.2 - 2026-10-27
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- **On PyPI.** Releases are now published to PyPI as well, so from this version
|
|
14
|
+
`pipx install soul-toolkit` works. The `git+https://...` install keeps working. Publishing uses
|
|
15
|
+
PyPI's trusted publishing from the release workflow, so no upload token is stored anywhere.
|
|
16
|
+
- **Demo GIF** at the top of the README: a real run against the bundled lab, with the long waits
|
|
17
|
+
sped up.
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
|
|
21
|
+
- README links and images are absolute, so they also work on the PyPI project page.
|
|
22
|
+
- The source distribution now includes the test fixtures, the Docker lab and `scripts/`, so its
|
|
23
|
+
test suite runs on its own.
|
|
24
|
+
|
|
25
|
+
## 0.3.1 - 2026-10-27
|
|
26
|
+
|
|
27
|
+
Fixes from the first run by someone other than the author: a fresh Linux Mint Debian Edition 6
|
|
28
|
+
install against a TryHackMe box with SSH, HTTP, POP3 and IMAP.
|
|
29
|
+
|
|
30
|
+
### Added
|
|
31
|
+
|
|
32
|
+
- **`mail` module** for POP3, IMAP, POP3S and IMAPS (ports 110, 143, 993, 995, or nmap's
|
|
33
|
+
`pop3` / `imap` / `pop3s` / `imaps`). It reports the server and its capabilities from nmap's
|
|
34
|
+
`pop3-capabilities` / `imap-capabilities` (cleaned of the greeting words nmap mixes in), and
|
|
35
|
+
flags a server that takes passwords in clear text with no STLS / STARTTLS (low). One lead per
|
|
36
|
+
host, "Keep the mail server for when you have credentials", ranks just above the SSH one,
|
|
37
|
+
since mailboxes often hold more credentials. It comes with ready commands to read a mailbox by
|
|
38
|
+
hand (`curl -u '<user>:<password>' pop3://...`, or `nc` then `USER` / `PASS` / `RETR`). Recon
|
|
39
|
+
only: it works from nmap's results and never logs in or guesses passwords. Writeups get a
|
|
40
|
+
`mail` tag.
|
|
41
|
+
- **Files worth reading.** Text-like files that content discovery finds with a 2xx (`.txt`,
|
|
42
|
+
`.bak`, `.old`, `.log`, `.md`, `.conf`, `.xml`, `.json`, `security.txt`, `humans.txt`...),
|
|
43
|
+
except robots.txt, are listed as a "Files worth reading" finding. A lead, ranked like the
|
|
44
|
+
interesting-paths one, gives a `curl` command for the most promising file and lists the rest.
|
|
45
|
+
Backups, dumps, configs and logs come first. The tester's box had a `/security.txt` that recon
|
|
46
|
+
listed but never pointed at.
|
|
47
|
+
|
|
48
|
+
### Fixed
|
|
49
|
+
|
|
50
|
+
- **No more `<IP>`-style placeholders to trip over.** The tester typed `<IP>` literally and bash
|
|
51
|
+
read `<` as a redirect. The README, the getting-started guide, `--help`, and the leads and
|
|
52
|
+
hints recon prints now use real example values (`10.10.42.17`, the vhost that was found, the
|
|
53
|
+
EDB-ID from the table) wherever they can. The guide says to replace example values and never
|
|
54
|
+
type the `< >` around placeholders. Placeholders only remain where a value can't be known, like
|
|
55
|
+
`ssh <user>@...`.
|
|
56
|
+
- **robots.txt that only says `Disallow: /`** (or has no entries) no longer becomes a lead. On
|
|
57
|
+
the tester's box it was the #1 lead in "Where to start", pointing at nothing. It's now an info
|
|
58
|
+
finding, "robots.txt only blocks the whole site". The lead appears only when robots.txt names
|
|
59
|
+
specific paths, and it counts only those.
|
|
60
|
+
|
|
61
|
+
## 0.3.0 - 2026-10-27
|
|
62
|
+
|
|
63
|
+
The "easy to pick up" release: a redesigned HTML report, a step-by-step guide for new users,
|
|
64
|
+
install commands that work on every major distro, and runs that tell you where your results are.
|
|
65
|
+
"Where to start" is sharper too: SMB shares are checked for read access, and Exploit-DB and
|
|
66
|
+
stock-Apache noise no longer crowds out real discoveries.
|
|
67
|
+
|
|
68
|
+
### Added
|
|
69
|
+
|
|
70
|
+
- **[Getting started guide](docs/getting-started.md)**: from a fresh machine to the first report,
|
|
71
|
+
with per-distro install commands (Arch, Kali, Debian/Ubuntu/Mint/LMDE, WSL2), the VPN and the
|
|
72
|
+
first scan, reading the results, everyday commands, updating, and troubleshooting for the
|
|
73
|
+
errors new users actually hit. Linked from the top of the README.
|
|
74
|
+
|
|
75
|
+
- **SMB share access.** After listing shares with a null session, the `smb` module checks
|
|
76
|
+
whether each share (except IPC$) can actually be read, using one
|
|
77
|
+
`smbclient //HOST/SHARE -N -c ls` per share, with a 20-second timeout each. The share table in
|
|
78
|
+
`report.md` and `report.html` gets an Access column (READ / NO ACCESS, or TIMED OUT / UNKNOWN
|
|
79
|
+
when it can't tell). A non-default share confirmed readable now ranks just below anonymous
|
|
80
|
+
FTP in "Where to start". If no non-default share is readable, the lead drops to a low "come
|
|
81
|
+
back with credentials" one. It is a read check only: write access is never tested and nothing
|
|
82
|
+
is created on the target, which is why smbmap's permission check (it writes a temporary
|
|
83
|
+
directory) isn't used.
|
|
84
|
+
|
|
85
|
+
- Every run now ends by printing the full folder its results were saved in (home shown as `~`,
|
|
86
|
+
the sudo user's home under `sudo`) and a copy-paste `xdg-open` / `open` command for the HTML
|
|
87
|
+
report. The README's Output section explains where results go, how to open them, and how to
|
|
88
|
+
keep them in one place with `-o` or the config file.
|
|
89
|
+
|
|
90
|
+
### Changed
|
|
91
|
+
|
|
92
|
+
- Redesigned the HTML report. It now has a summary card with severity chips, a sticky section
|
|
93
|
+
nav (sidebar on wide screens, top bar on phones), and "Where to start" as numbered cards with a
|
|
94
|
+
Copy button. Findings are cards you can filter by severity and expand or collapse all at once.
|
|
95
|
+
The tables are easier to read, with HTTP status codes in colour and UDP ports marked. An
|
|
96
|
+
interrupted run gets a clear "Partial report" banner. Light and dark themes meet WCAG AA
|
|
97
|
+
contrast, and the page works at phone width. It prints in the light theme with every section
|
|
98
|
+
expanded. It is still one offline file: no network requests, and readable with JavaScript off.
|
|
99
|
+
|
|
100
|
+
### Fixed
|
|
101
|
+
|
|
102
|
+
- `toolkit doctor` on plain Debian, Ubuntu, Linux Mint and LMDE printed one `apt install` line that
|
|
103
|
+
included the Kali-only `exploitdb` and `seclists` packages, so apt refused to install anything.
|
|
104
|
+
Kali/Parrot and Debian/Ubuntu/Mint are now detected separately; on the latter those two are
|
|
105
|
+
installed from their upstream repos (`/opt/exploitdb` + a `searchsploit` symlink,
|
|
106
|
+
`/usr/share/seclists`), which is where recon already looks.
|
|
107
|
+
- Checked against gobuster 3.5 (Debian 12 / LMDE 6's version) as well as 3.6 and 3.8.
|
|
108
|
+
- **Smarter Exploit-DB leads**, from the first real run against a TryHackMe box. searchsploit
|
|
109
|
+
matches titles and version ranges loosely, and three kinds of noise were outranking real
|
|
110
|
+
discoveries in "Where to start":
|
|
111
|
+
- DoS-only matches (Exploit-DB files some as "remote") no longer become leads.
|
|
112
|
+
- For Apache httpd, titles about other Apache projects (Tomcat, Struts, ...) are dropped.
|
|
113
|
+
- Each title's version range is checked against the detected version for *that* product
|
|
114
|
+
(`OpenSSH 2.3 < 7.7` covers 7.2p2; `Apache + PHP < 5.3.12` is PHP's range, not httpd's).
|
|
115
|
+
Unconfirmed matches become a low-ranked "check whether these really apply" lead, confirmed
|
|
116
|
+
username-enumeration a weak one, and only confirmed code execution stays near the top.
|
|
117
|
+
- Apache's stock 403s (`.ht*`, `server-status`) are hidden from the content-discovery table and
|
|
118
|
+
never used as an "interesting path" lead (on a real box they were half of a 70-row table); the
|
|
119
|
+
report says how many were hidden, and the raw gobuster files still have them. Paths you can open
|
|
120
|
+
(2xx, then directories) come first.
|
|
121
|
+
|
|
122
|
+
## 0.2.0 - 2026-10-27
|
|
123
|
+
|
|
124
|
+
The "what do I try next" release: recon now ends with a ranked list of leads, writes reports you
|
|
125
|
+
can use straight away, and covers a lot more services.
|
|
126
|
+
|
|
127
|
+
### Added
|
|
128
|
+
|
|
129
|
+
- **Where to start**: a ranked list of the 3-5 most promising leads across all services, each with
|
|
130
|
+
why it matters and a copy-paste command - at the top of the report and printed when the run ends.
|
|
131
|
+
Ranking is rules-based and deterministic (`recon/leads.py`).
|
|
132
|
+
- **HTML report**: `report.html` next to `report.md` - one self-contained file, light/dark,
|
|
133
|
+
collapsible sections, severity colours, copy buttons.
|
|
134
|
+
- **`--writeup` / `--room NAME`**: `writeup.md`, an Obsidian-friendly skeleton (frontmatter, Recon
|
|
135
|
+
section pre-filled, empty Foothold / PrivEsc / Flags). Never overwrites an existing writeup.
|
|
136
|
+
- **Exploit-DB lookups** (`exploits` module): `searchsploit` for every service with a product and
|
|
137
|
+
version, deduped, remote exploits first.
|
|
138
|
+
- **Web**: vhost fuzzing (ffuf, else gobuster vhost) with wildcard filtering and the `/etc/hosts`
|
|
139
|
+
line to add; gobuster extensions picked from the fingerprint (PHP, ASP.NET, Java, static);
|
|
140
|
+
one level of recursion; one time budget per port.
|
|
141
|
+
- **UDP**: top 100 UDP ports when running as root (`--udp` / `--no-udp`).
|
|
142
|
+
- **New modules**: `nfs` (showmount), `smtp` (banner, VRFY/EXPN enumeration check), `snmp`
|
|
143
|
+
(default communities, process arguments, users), `mysql` (empty root/anonymous password),
|
|
144
|
+
`postgres` (trust auth), `redis` (unauthenticated INFO), `rdp`, `winrm` and `ldap` (notes +
|
|
145
|
+
hints from nmap's results).
|
|
146
|
+
- **`toolkit doctor`**: checks every external tool and prints install commands for Arch,
|
|
147
|
+
Debian/Kali and macOS.
|
|
148
|
+
- **`toolkit config`** and `~/.config/soul-toolkit/config.ini` for default wordlists, threads,
|
|
149
|
+
output dir and profile.
|
|
150
|
+
- **`--profile quick|default|thorough`**.
|
|
151
|
+
- **Parallel modules** (`--jobs`), a live progress line with elapsed time, and **Ctrl-C writes a
|
|
152
|
+
partial report** instead of losing the run.
|
|
153
|
+
- **`--resume`**: reuse finished nmap results from an earlier run.
|
|
154
|
+
- Install with **pipx**: `pipx install git+https://github.com/Soulsagate/soul-toolkit`.
|
|
155
|
+
- **`tests/lab/`**: a deliberately vulnerable Docker lab (anonymous FTP, a web app with an exposed
|
|
156
|
+
`.git` and a hidden vhost, null-session SMB, a world-readable NFS export) and an integration test
|
|
157
|
+
that runs recon against it.
|
|
158
|
+
- GitHub Actions CI (ruff + pytest on Python 3.9-3.13), `docs/writing-a-module.md`,
|
|
159
|
+
`CONTRIBUTING.md`, this changelog.
|
|
160
|
+
|
|
161
|
+
### Changed
|
|
162
|
+
|
|
163
|
+
- "Suggested next steps" is replaced by **Where to start** plus "Other leads and ideas".
|
|
164
|
+
- `--brute-timeout` is the content-discovery budget for a whole web port (recursion included),
|
|
165
|
+
not per gobuster run.
|
|
166
|
+
- `--no-brute` also skips vhost fuzzing.
|
|
167
|
+
|
|
168
|
+
### Fixed
|
|
169
|
+
|
|
170
|
+
- gobuster 3.8 compatibility (`--no-progress` instead of `-z`; vhost results without the
|
|
171
|
+
`Found:` prefix).
|
|
172
|
+
- A path is listed once even when gobuster prints it twice.
|
|
173
|
+
- Anonymous FTP is still reported (with a "list it by hand" lead) when login works but the
|
|
174
|
+
directory listing fails, e.g. passive mode blocked.
|
|
175
|
+
- Writeup tags fold NFS's RPC helper services (mountd, nlockmgr, rquotad...) into one `nfs` tag.
|
|
176
|
+
|
|
177
|
+
## 0.1.0 - 2026-10-27
|
|
178
|
+
|
|
179
|
+
First release.
|
|
180
|
+
|
|
181
|
+
### Added
|
|
182
|
+
|
|
183
|
+
- `toolkit recon`: staged nmap scan (port sweep, then `-sV -sC` on open ports), then per-service
|
|
184
|
+
modules, then a Markdown + JSON report.
|
|
185
|
+
- Modules: `web` (fingerprint, vhost-redirect detection, robots.txt, exposed `.git`, gobuster with
|
|
186
|
+
wildcard handling), `ftp` (anonymous login, filesystem-root and world-writable detection,
|
|
187
|
+
vsftpd 2.3.4 backdoor), `ssh` (version notes), `smb` (null-session share listing, signing).
|
|
188
|
+
- Results are handed back to the invoking user when run under sudo; reports scrub the home
|
|
189
|
+
directory.
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Thanks for wanting to make soul-toolkit better. It's a recon tool for **authorized** labs and
|
|
4
|
+
CTFs; every contribution has to keep it that way (see [DISCLAIMER.md](DISCLAIMER.md)).
|
|
5
|
+
|
|
6
|
+
## What we're building
|
|
7
|
+
|
|
8
|
+
Tools like AutoRecon already scan broadly. This one tries to win on two things:
|
|
9
|
+
|
|
10
|
+
1. telling the user **exactly what to try next**, ranked (the "Where to start" list), and
|
|
11
|
+
2. output they can **use immediately** - reports, writeups.
|
|
12
|
+
|
|
13
|
+
A good change serves one of those, or makes the tool easier to install and run.
|
|
14
|
+
|
|
15
|
+
## Ground rules
|
|
16
|
+
|
|
17
|
+
- **Python 3.9+, standard library only** at runtime. Dev tools (pytest, ruff) are fine.
|
|
18
|
+
- **Wrap existing tools** (nmap, gobuster, ffuf, searchsploit, smbclient, showmount, snmpwalk...)
|
|
19
|
+
instead of reimplementing them. A missing optional tool is a warning plus an install hint,
|
|
20
|
+
never a crash.
|
|
21
|
+
- **Recon only.** No exploitation, no brute-forcing logins, nothing that writes to the target.
|
|
22
|
+
Suggesting the next command in a lead is fine; running it isn't.
|
|
23
|
+
- **Commands are argument lists**, never shell strings (`ctx.run(["tool", "-x", target])`).
|
|
24
|
+
- **Every feature ships with tests that run offline**: recorded output as fixtures, fakes for
|
|
25
|
+
`runner.run`, or throwaway servers on `127.0.0.1`. Tests that need a real tool or Docker skip
|
|
26
|
+
when it's missing.
|
|
27
|
+
- **No fabricated output in the README or docs.** Example output must come from a real run, e.g.
|
|
28
|
+
against the lab in [`tests/lab/`](tests/lab/).
|
|
29
|
+
- **No personal info** in any file: no real names, emails, or home-directory paths (reports scrub
|
|
30
|
+
your home directory to `~`; fixtures must too).
|
|
31
|
+
|
|
32
|
+
## Setup
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
git clone https://github.com/Soulsagate/soul-toolkit.git
|
|
36
|
+
cd soul-toolkit
|
|
37
|
+
python3 -m venv .venv && source .venv/bin/activate
|
|
38
|
+
pip install -e '.[dev]'
|
|
39
|
+
toolkit doctor # which external tools you have
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Before you open a pull request
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
ruff check .
|
|
46
|
+
pytest -q
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
CI runs the same on Python 3.9-3.13. Then try your change for real - the lab gives you a
|
|
50
|
+
deliberately vulnerable box on your own machine:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
docker compose -f tests/lab/docker-compose.yml up -d --build
|
|
54
|
+
toolkit recon 172.29.99.10
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Adding a service module
|
|
58
|
+
|
|
59
|
+
Most contributions are a new module (one file in `src/soul_toolkit/recon/modules/`).
|
|
60
|
+
[docs/writing-a-module.md](docs/writing-a-module.md) walks through one end to end: the module
|
|
61
|
+
interface, registering it, giving its lead a score, tests, and docs.
|
|
62
|
+
|
|
63
|
+
## Commits
|
|
64
|
+
|
|
65
|
+
One focused commit per change, with a message that says what changed and **why** - note any
|
|
66
|
+
non-obvious decision (a default you picked, something you deliberately didn't do). Add a line to
|
|
67
|
+
[CHANGELOG.md](CHANGELOG.md) under "Unreleased".
|
|
68
|
+
|
|
69
|
+
## Releasing
|
|
70
|
+
|
|
71
|
+
1. Move the "Unreleased" entries into a dated `## X.Y.Z - YYYY-MM-DD` section of CHANGELOG.md and
|
|
72
|
+
set the same version in `pyproject.toml` and `src/soul_toolkit/__init__.py`.
|
|
73
|
+
2. Once CI is green on main, push an annotated tag:
|
|
74
|
+
`git tag -a vX.Y.Z -m "soul-toolkit vX.Y.Z" && git push origin vX.Y.Z`.
|
|
75
|
+
3. The Release workflow publishes the GitHub release, with that CHANGELOG section as its notes
|
|
76
|
+
(`scripts/release_notes.py`), then uploads the same version to PyPI with trusted publishing.
|
|
77
|
+
It refuses to publish if the tag and the code disagree.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Authorized use only
|
|
2
|
+
|
|
3
|
+
soul-toolkit is built for **learning and authorized security testing**: your own
|
|
4
|
+
machines, lab platforms such as TryHackMe and Hack The Box, CTF events, and
|
|
5
|
+
engagements where you hold written permission from the system owner.
|
|
6
|
+
|
|
7
|
+
Scanning, brute-forcing or probing systems you do not have permission to test is
|
|
8
|
+
illegal in most countries and can cause real harm. You are solely responsible
|
|
9
|
+
for how you use this software. The author accepts no liability for misuse or
|
|
10
|
+
for any damage caused by it.
|
|
11
|
+
|
|
12
|
+
If you are unsure whether you are allowed to scan something, you are not.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 S0uls
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
# The source distribution carries everything the test suite needs (fixtures, the Docker lab,
|
|
2
|
+
# the release-notes script it tests) and the docs a user reads first. The wheel is code only.
|
|
3
|
+
graft tests
|
|
4
|
+
graft scripts
|
|
5
|
+
include CHANGELOG.md DISCLAIMER.md CONTRIBUTING.md
|
|
6
|
+
global-exclude __pycache__ *.py[cod]
|