Asynchronous subdomain and web-interface scanner.
subsonar takes a domain you are allowed to assess, collects possible hostnames, resolves them, and reports the ones that actually answer as a web page. It uses free public sources, an optional wordlist, a fixed pool of privacy-focused DNS resolvers, and a curated port list. A hostname is reported only when an HTTP or HTTPS probe looks like a real interface, and every finding gets a 0–100 confidence score with the reasons attached.
Python 3.11 or newer. Windows, Linux, and macOS. MIT license.
Everything below is in the scanner today.
- Three ways to run it: a headless console (
subsonar scan), a full-screen Textual TUI (subsonarorsubsonar tui), and a local Streamlit dashboard (subsonar web). - Ten free OSINT sources, no API keys. Built in: crt.sh, HackerTarget, Anubis. Plugins: CertSpotter, RapidDNS, urlscan.io, AlienVault OTX, ThreatMiner, Common Crawl, subdomain.center.
- Eleven wordlists. Ten public lists streamed from SecLists (and cached under
.subsonar_cache/for 30 days) plusai-super, a 23,052-label list that ships inside the package.subsonar wordlistsprints them. The scan profile decides how many labels are used. - Eight scan profiles, from a passive pass to a slow stealth sweep.
subsonar profilesprints the live table. - Port matrices. Core is 50 curated ports. Extended is 172.
webis 10,auditis 30 admin ports. You can also pass lists and ranges (--ports 8000-8100,11434). - Custom DNS client. Queries are raw UDP on asyncio sockets, sent only to the resolver pool below. The operating-system resolver is not used, including for the HTTP client.
- Wildcard DNS filtering, so a domain that answers for every name does not flood the report.
- Provider-host policy. Hosts whose CNAME chain ends on a shared mail, identity, or collaboration tenant (Exchange Online, SharePoint, Microsoft 365 identity, Okta, Auth0, and similar) are recorded and skipped. CDN and PaaS names (CloudFront, S3, Heroku, Netlify, Akamai, and similar) are still scanned, and the report notes the provider.
--scan-provider-hostsscans the skipped families too. - Active discovery: TLS certificate SAN names, CNAME chasing, and hostname permutations (
admin→admin-dev,dev-admin, …). - Web mining.
robots.txt, sitemaps,/.well-known/security.txt, and selected response headers are mined for more in-scope names, then resolved in a second wave. - Apex DNS notes: MX platform, SPF (including
include:expansion), DKIM selectors, DMARC, CAA, NS/SOA, DNSSEC, and common third-party verification tokens. - Fingerprints: favicon hash, 131 technology signatures, and status-only probes of sensitive paths such as
/.envand/.git/config. Those probes do not read the file body. - Offline country and ASN for each resolved address, from a local index built out of a public BGP dump. Lookups stay on the machine.
--no-geoskips it. - Reverse DNS (PTR) for resolved addresses.
- Rate limits on DNS queries and TCP connects, with per-profile defaults.
--dns-rateand--port-rateoverride them (0removes the cap). - Carry-over. A later scan of the same domain merges the previous report instead of starting from an empty table.
--no-carry-overstarts fresh. - Resume, diff, and TOML config. Interrupted scans can continue, and
subsonar diffcompares a report with a saved baseline. - Optional zone transfer (
--axfr) and IPv6 (--ipv6). Zone transfer talks directly to the target's nameservers. - Reports in JSON, CSV, Markdown, HTML, and plain text. URLs-only and SARIF are opt-in.
An offline engine check, subsonar selftest, runs the pipeline against loopback servers and does not send traffic to the public internet.
- Python 3.11+ (
python3 --version). - Outbound network access for a real scan: DNS to the resolver pool, HTTPS to the OSINT sources, and HTTP to the target. Wordlists other than
ai-superare downloaded on first use. The geo index is a separate one-time download of about 10 MB. - On Debian and Ubuntu, the standard library venv module is a separate package. If
python3 -m venvfails, install it (sudo apt install python3-venv, orpython3.12-venvon some releases) and try again.
No paid APIs and no accounts.
After any of the installs below, subsonar --help should print the command list.
pipx installs the tool into its own environment and puts subsonar on your PATH.
pipx install "git+https://github.com/REFFIX-X/subsonar"
subsonar --helppipx puts the command in ~/.local/bin. If the shell says subsonar: command not found, run pipx ensurepath and open a new terminal.
To update later:
pipx install --force "git+https://github.com/REFFIX-X/subsonar"Install into a virtual environment. Debian, Ubuntu, and other externally managed Pythons refuse pip install into the system interpreter.
python3 -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install "git+https://github.com/REFFIX-X/subsonar"
subsonar --helpFrom a directory that already contains this repository, with the same virtual environment activated:
python -m pip install .
python -m pip install -e ".[dev]" # editable checkout, plus pytestgit clone https://github.com/REFFIX-X/subsonar
cd subsonar
python3 -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]" # omit [dev] if you do not want pytest
subsonar --helppython main.py ... from the checkout runs the same program. python -m subsonar ... works once the package is installed.
A helper in the clone installs with pipx when pipx is on PATH. Otherwise it creates .venv in the checkout and installs there (so it still works when the system Python rejects pip). Running it again upgrades that same install.
./install.shWithout pipx, the command is .venv/bin/subsonar until you activate .venv.
On Windows, this creates .venv, installs the checkout, and opens the dashboard:
powershell -ExecutionPolicy Bypass -File .\install.ps1| Flag | Effect |
|---|---|
-Port 8502 |
dashboard port (default 8501) |
-NoBrowser |
do not open a browser |
-Reinstall |
delete .venv and install again |
pip install -r requirements.txt still installs the libraries a checkout needs, including pytest, and python main.py still runs. That path does not create the subsonar command. Prefer pip install -e ..
The image includes the CLI, the TUI, and the web dashboard, so the build is large (Streamlit and pandas). Reports and the cache are written under /data.
docker build -t subsonar .
docker run --rm subsonar --help
docker run --rm subsonar --version
docker run --rm subsonar selftest
mkdir -p output
docker run --rm -v "$PWD/output:/data/output" subsonar scan example.com -p 1 --no-geo-downloadThe image starts as root only to make /data writable, then runs the scanner as the user subsonar (uid 1000). Reports in the mounted output directory are owned by that user. Mount the whole data directory if you also want the cache kept:
mkdir -p subsonar-data
docker run --rm -v "$PWD/subsonar-data:/data" subsonar scan example.com -p 1 --no-geo-downloadDashboard, then open http://localhost:8501:
docker run --rm -p 8501:8501 subsonar web --headless --port 8501subsonar --help
subsonar profiles
subsonar wordlists
# Offline engine check. Loopback only, about a minute, no public-internet traffic.
subsonar selftest
# Small passive scan of the documentation domain. No wordlist brute force.
# It still queries OSINT sources and checks discovered names on ports 80 and 443.
subsonar scan example.com -p 1 --no-geo --no-geo-downloadexample.com is reserved for documentation. Scan domains you are allowed to test. A finished scan with no confirmed web interface exits 2. That is a completed run, not a crash.
A real scan needs outbound UDP port 53 to the resolver pool. If none of those resolvers answer, the scan stops with exit code 1 and a short error. It does not keep retrying every name.
A few more useful invocations:
# Built-in wordlist (no download) and the short web port list.
subsonar scan example.com -p 2 --wordlist ai-super --port-matrix web
# Write a commented subsonar.toml, then scan with those settings.
subsonar init
subsonar scan example.com
# Full-screen UI on a terminal. With no TTY, this prints the command list.
subsonar
# Local dashboard at http://127.0.0.1:8501
subsonar web
subsonar web example.com --headless --port 8501A profile sets three things: how many wordlist labels to take, which ports to sweep, and the default DNS and connect rates. --wordlist, --port-matrix / --ports, --dns-rate, and --port-rate each override one of those.
| # | Name | Wordlist slice | Ports | Default pace |
|---|---|---|---|---|
| 1 | Passive Only | none | web (10), verify only | 60 DNS q/s, no port sweep |
| 2 | Light Brute | first 1,000 | core 50 | 150 q/s · 400 connects/s |
| 3 | Medium Brute (default) | first 5,000 | core 50 | 250 q/s · 600 connects/s |
| 4 | Deep Brute | first 20,000 | core 50 | 300 q/s · 800 connects/s |
| 5 | Full Postal | first 5,000 | core 50 | 250 q/s · 500 connects/s |
| 6 | HTTP Quick Check | first 500 | web (10) | 300 q/s · 800 connects/s |
| 7 | Infrastructure Audit | first 2,000 | audit (30) | 250 q/s · 500 connects/s |
| 8 | Stealth Mode | first 5,000 | core 50 | 25 q/s · 60 connects/s, with pauses |
Profile 1 does not brute-force. It still collects OSINT and checks what it found over HTTP. Profiles 2–8 add a wordlist. Profile 5 is OSINT plus the medium brute. Profile 8 inserts randomised delays of about 0.35–1.25 seconds.
subsonar scan example.com -p passive
subsonar scan example.com -p 8 --dns-rate 20 --port-rate 30subsonar scan --help lists every flag. These are the ones that change a run the most:
| Flag | What it does |
|---|---|
-p, --profile |
Profile number 1–8 or its key (passive, light, medium, …). Default is 3. |
--wordlist NAME |
Which list to draw labels from. Default seclists-top1m. ai-super needs no download. |
--port-matrix NAME |
core, extended, web, or audit. |
--ports SPEC |
Replace the matrix: 80,443,8443 or 8000-8100 or a mix. |
--dns-rate QPS |
DNS queries per second for the whole pool. 0 means no cap. |
--port-rate CPS |
TCP connects per second. 0 means no cap. |
--offline |
Do not download wordlists. Uses the cache, the built-in ai-super list, or a small embedded seed. OSINT, DNS, and HTTP still run. |
--no-geo |
Skip country / ASN enrichment and the geo download. |
--no-geo-download |
Use a geo index you already have. Do not download one. |
--no-dns-intel |
Skip MX, SPF, DKIM, DMARC, CAA, NS/SOA, DNSSEC. |
--no-reverse-dns |
Skip PTR lookups. |
--no-mining |
Skip robots.txt, sitemap, security.txt, and header mining. |
--no-carry-over |
Do not merge the previous report for this domain. |
--no-discovery |
Skip SAN harvesting, permutations, and CNAME chasing. |
--scan-provider-hosts |
Also probe shared mail / identity / collaboration tenants. |
--resume |
Continue a saved scan of this domain. |
--domains a.com,b.com |
More targets, scanned one after another. |
--formats LIST |
json,csv,md,html,txt by default. Also urls, sarif, jsonl. |
--jsonl |
Stream each finding to a live .jsonl file as it is confirmed. |
--output DIR |
Report directory. |
--no-reports |
Print progress and do not write report files. |
--axfr |
Try a DNS zone transfer. This connects to the target's own nameservers. |
--ipv6 |
Also resolve AAAA and probe IPv6 addresses. |
--config FILE |
TOML file to load. Default is ./subsonar.toml when that file exists. |
subsonar init writes a commented subsonar.toml in the current directory. If that file is present, subsonar scan example.com uses it, and flags you pass on the command line win. Keys the program does not recognise are ignored. The domain itself is still the command argument.
Environment variables:
| Variable | Effect |
|---|---|
SUBSONAR_OUTPUT |
Default report directory when --output is not set. |
SUBSONAR_CACHE |
Default cache directory (wordlists, DNS cache, geo index, resume state). |
SUBSONAR_GEOIP_OFFLINE |
Set to 1 to refuse the geo download. An index that is already on disk is still used. |
Where files go. An installed subsonar (pip, pipx, or Docker) writes ./output and ./.subsonar_cache in the directory where you run it, unless you override them. A source checkout, including pip install -e . of a clone, keeps those directories in the repository root, which is the layout python main.py has always used.
Other commands: subsonar geoip --build, --stats, --lookup 23.227.38.74; subsonar diff example.com; subsonar resume --all; subsonar selftest.
A scan writes a timestamped set of files. The default set is:
subsonar_<domain>_<timestamp>.json— full result, including score reasons.csv— one row per finding.md— Markdown report with links.html— a single dark HTML file.txt— plain text
urls writes a list of links. sarif writes a SARIF document. Ask for either with --formats.
Exit codes: 0 a report was written and it contains findings, 2 the scan finished and no web interface was confirmed, 1 an error, 130 interrupted (Ctrl+C).
A finding is a hostname whose HTTP response looks like an application:
| Response | Kind | Meaning |
|---|---|---|
| 2xx or a same-port 3xx with a body or a title | interface |
a page is there |
| 401, 403, 407, 429, 451 | restricted |
something is answering and refusing the request |
| a redirect to a different port, and nothing else on that host answered | redirect |
the link points at the destination |
| plain HTTP sent to a TLS-only port, empty 404s, bare 5xx | dropped | not reported as an interface |
Several ports that serve the same page are collapsed into one row. The extra ports are listed as aliases.
The score is an integer from 0 to 100 stored as confidence, with a label and two lists, reasons and penalties.
| Label | Score |
|---|---|
high |
75–100 |
medium |
45–74 |
low |
0–44 |
Points are added for a real 2xx, a page title, a plausible body size, TLS, a Server header, a favicon hash, technology matches, security headers, data-file responses, a fingerprint that is not shared with siblings, and more than one resolver agreeing on the address. Points are taken away for client and server errors, redirect-only ports, a missing or empty title, a tiny or empty body, a fingerprint or body size shared with other findings, a wildcard address, alias ports, and a single-resolver answer. A gated status such as 401 or 403 gets credit for "an application is present" and a penalty because the content was not served, so it ranks below an open page and above an empty error. The JSON report includes the exact reason strings for that row.
DNS queries do leave your machine. They go to this pool, and only this pool. The client speaks DNS itself over UDP, so the resolver configured on your operating system (and therefore your ISP's resolver, if that is what the OS uses) is not asked. The HTTP client uses the same pool, so web probes do not fall back to the system resolver either.
| Address | Also | Operator |
|---|---|---|
9.9.9.10 |
149.112.112.10 |
Quad9, uncensored |
194.242.2.2 |
194.242.2.4 |
Mullvad DNS |
185.228.168.168 |
185.228.169.168 |
CleanBrowsing |
76.76.2.0 |
76.76.19.19 |
Control D |
94.140.14.14 |
94.140.15.15 |
AdGuard DNS |
194.150.168.168 |
5.175.46.10 |
OpenNIC |
84.200.69.80 |
84.200.70.40 |
DNS.WATCH |
91.239.100.100 |
89.233.43.71 |
UncensoredDNS |
159.89.120.20 |
185.95.218.42 |
Blindside Networks, Applied Privacy |
The pool is checked when the package is imported. It refuses Google Public DNS (8.8.8.8, 8.8.4.4), Cloudflare DNS (1.1.1.1, 1.0.0.1), and Quad9's filtered address (9.9.9.9). Before a scan, each node is probed and silent ones are skipped for that run.
What else is sent, and what is not:
- OSINT sources receive the apex domain you asked to scan. They are third-party websites.
- HTTP probes connect to the target hostnames.
--axfrconnects to the target's authoritative nameservers. It is off unless you ask.- Country and ASN come from a local database. Building it downloads public BGP and RIR files once (about 10 MB). The scanned addresses are not submitted to a geo API. Skip the download with
--no-geo,--no-geo-download, orSUBSONAR_GEOIP_OFFLINE=1. - Flag pictures in the web dashboard and the HTML report are loaded from
flagcdn.comusing the two-letter country code only.
Those resolver operators can see the names you look up. "Privacy-focused" here means the pool is a fixed, documented set that leaves out Google, Cloudflare, and the system resolver. It does not mean the queries are invisible.
subsonar is for authorised security testing, for inventory of domains you operate, and for labs and CTFs. Scanning, brute-forcing, or probing systems you do not have permission to test is unlawful in many places and can disrupt someone else's service. You are responsible for every target you pass to this tool. If you are not sure you are allowed to scan it, do not scan it.
python -m pip install -e ".[dev]"
python -m pytest tests -q
subsonar selftestselftest is the network-free check of the whole engine. The pytest suite covers the engine, the reporters, and the TUI without a real terminal.
MIT © 2026 REFFIX-X
