# AutoPWN Suite
AutoPWN Suite is a project for scanning vulnerabilities and exploiting systems automatically.
## Quick start
1. Install [Nmap](https://nmap.org/download.html) (needed for network scans, not for
website-only dashboard scans) and AutoPWN Suite with [pipx](https://pipx.pypa.io/)
or [uv](https://docs.astral.sh/uv/). It needs Python 3.10 or newer. See
[Installation](#installation) for standalone binaries, Docker and other options:
```console
pipx install autopwn-suite
```
2. Scan a host or network **that you are authorized to test**:
```console
autopwn-suite -t
```
3. Or start the [web dashboard](#web-ui), then sign in with the `admin` account whose
random password is printed once in the terminal on first launch:
```console
autopwn-suite --web
```
Use `-h` for all options. Report problems through [support](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/SUPPORT.md) and
vulnerabilities privately through the [security policy](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/SECURITY.md).
### Security expectations
AutoPWN Suite is an operator-controlled scanner that runs with your privileges and
stores integration credentials in plaintext JSON. Scan only systems you are authorized
to test, do not expose the dashboard to the public internet, keep it behind HTTPS and
trusted network controls, and verify releases before use. See the
[security policy](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/SECURITY.md) for reporting, response times and deployment guidance.
## Achievements and project health
The badges at the top show the status that
[OpenSSF Best Practices project 15518](https://www.bestpractices.dev/projects/15518)
reports for the Best Practices levels and the
[OpenSSF Baseline](https://www.bestpractices.dev/en/projects/15518/baseline-3) levels.
They are updated by OpenSSF, not by this repository. The [roadmap](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/ROADMAP.md) lists
planned work and non-goals, and the [continuity plan](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/CONTINUITY.md) describes
maintainer succession.
## Features
Project documentation: [build from source](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/BUILDING.md),
[dependency management](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/DEPENDENCIES.md), [architecture](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/ARCHITECTURE.md),
[interfaces](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/INTERFACES.md), [governance](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/GOVERNANCE.md),
[changelog](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/CHANGELOG.md), [release verification](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/RELEASING.md), and
[security policy](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/SECURITY.md), [support lifecycle](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/SUPPORT.md),
[threat model](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/THREAT_MODEL.md), [secret management](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/SECRETS.md), and
[security checks](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/SECURITY_TESTING.md), [roadmap](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/ROADMAP.md),
[access continuity](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/CONTINUITY.md), [accessibility](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/ACCESSIBILITY.md) and
[internationalization](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/INTERNATIONALIZATION.md).
### CLI
- Fully [automatic](#usage) scanning and exploitation
- Detect network IP range without any user input
- Vulnerability detection based on service versions
- Web app vulnerability candidates (Unix/Windows LFI, reflected XSS, error-based SQLI)
- Web response header and cookie configuration advisories
- Web app directory discovery with catch-all page filtering
- Get information about vulnerabilities right from your terminal
- Automatically download exploits related to discovered vulnerabilities
- Noise mode for creating traffic on the network
- Evasion mode for stealthy scanning
- Automatically select scan types based on privilege level
- Easy to read output with rich formatting
- Specify arguments using a config file
- Send scan results via webhook or email
- Works on Windows, macOS and Linux
- Use as a [module](#module-usage)
- Use as a [daemon](#install-daemon) to periodically scan the network
### Web UI
AutoPWN Suite includes a built-in web dashboard for managing scans from your browser.
**Signing in.** The dashboard requires a login. On first launch the server creates an `admin`
account with a random password and prints both once in the terminal; only a scrypt hash of the
password is stored in `web_ui_auth.json` (inside `AUTOPWN_DATA_DIR`, or the per-user data directory by
default). Change the username and password after signing in under **Settings → Account**. If you
forget the password, run `autopwn-suite --web-reset-account` on the server to restore `admin`
with a new random password and sign out all sessions. Remote access requires HTTPS (or set
`AUTOPWN_WEB_SECURE_COOKIE=1` behind a TLS-terminating proxy that passes the browser's `Host` header
through, or sign-in is refused as cross-origin); localhost works over plain HTTP.
- **Multiple concurrent scans** - Launch and monitor several scans at the same time
- **Live terminal output** - Watch nmap commands and results in real time via SSE
- **Scan progress** - Live Nmap stage percentages, completed CVE lookup counts and target completion counters. The bar follows the current stage; stages without a reported percentage show ongoing activity. Stopped and failed scans retain their last measured progress.
- **Scan profiles** - Save and reuse scan configurations (technique, speed, timeout, ports, version intensity, OS detection, evasion)
- **Web security dashboard** - Select application checks, inspect captured evidence and remediation, download PoCs, and explicitly replay recorded checks
- **Scheduled scans** - Set up recurring scans on a cron schedule with automatic profile loading
- **Scan techniques** - Choose between TCP SYN, TCP Connect, UDP, Window, ACK, FIN, Xmas, Null and Maimon scans
- **No free-text Nmap options** - Since v2.7.0 the dashboard builds the Nmap arguments only from its own controls (scan technique list, ports, version intensity, OS detection, speed, timeout and mode). It has no box for Nmap options, so it cannot be made to run NSE scripts or to read or write files through Nmap, and the API refuses a non-empty `nmap_flags`. The ports field takes numbers from 1 to 65535, ranges and comma lists (`22,80,1-1000`). A profile saved by an earlier release with Nmap options is kept but not used: its scheduled scans are disabled (when they next come due, or when you save the profile again, which removes the options), and you enable the schedule again by hand afterwards. Custom Nmap flags remain available to the trusted command line (`--nmap-flags`) and the Python API (`nmap_args`)
- **Evasion mode** - Fragmented packets, spoofed source port and padded data length
- **Email notifications** - Get notified on scan completion with inline result summaries
- **Webhook notifications** - Post scan results to any webhook endpoint
- **Persistent settings** - All settings, profiles and schedules are saved to disk
- **Configurable via environment variables** - Set host, port and data directory without touching code
## How Does It Work?
AutoPWN Suite uses nmap TCP-SYN scan to enumerate the host and detect the version of software running on it. After gathering enough information about the host, AutoPWN Suite automatically generates a list of keywords to search the [NIST vulnerability database.](https://www.nist.gov/)
A keyword names the product the way NVD does (Nmap's `Apache httpd` becomes `Apache HTTP Server` and `Samba smbd`
becomes `Samba`) with its upstream release (`8.2p1 Ubuntu 4ubuntu0.5` becomes `8.2p1`). The product is searched,
and a CVE is reported when NVD's applicability data (the CPE configurations of the CVE) marks that release of
the application vulnerable. When Nmap reports CPEs for the service (`cpe:/a:filezilla-project:filezilla_server:0.9.41`),
the CVEs whose applicability lists that product, of any vendor and without a version, are fetched as well,
which finds those whose description does not name it (HTTP/2 Rapid Reset, CVE-2023-44487, for nginx), and
only the entries for the product they name count: that vendor and product in any of NVD's spellings
(`aol:aol_server` for `aol:aolserver`), also as an operating system (NVD's `netapp:data_ontap`), or that product,
possibly with generic words, under a vendor the product's name also gives (`f5:nginx_open_source` for Nmap's
`igor_sysoev:nginx`). So FileZilla Server no longer gets FileZilla client CVEs, nor Sun iPlanet Messaging Server
the Web Server's. Nmap's operating system and device CPEs count only for a service without an application CPE
whose name names that system: `VxWorks ftpd` with `cpe:/o:windriver:vxworks` is searched as `VxWorks` and gets
the CVEs NVD files under VxWorks, while `KarjaSoft Sami ftpd`, which Nmap gives only `cpe:/o:microsoft:windows`,
gets no Windows CVEs. A CPE whose product shares no word with the service's name is ignored, since Nmap
gives some services another product's CPE (`python:python` for Werkzeug, `mysql:mysql` for a MariaDB server
that answers as MySQL). Without a CPE, or when no search result names its product (Nmap's
`matt_johnston:dropbear_ssh_server`), the product's name decides, and an operating system's entries do not count
for a service named after it, such as `OpenBSD ftpd`. A version with fewer numbers than the product's releases (Apache's `2.4`) gets only the CVEs
that affect every release it may be. A CVE whose applicability says nothing about versions (not analyzed yet, or
only "every version" of the product) is reported when its description names the release other than as the fix
("before 2.4.52"), and no CVE is reported whose description says the detected release, or an earlier build of
it, fixed that product ("OpenSSH before 4.4" for `4.4p1`). A release that starts a range ("1.0.2 before 1.0.2e"),
belongs to another product or is followed by a vendor's build ("before 8.0 HP2") is not read as the fix. A
version that names no single release, such as `3.X - 4.X`, a bare major version like `4`, `2.0.0 or later`,
`3.0 or 3.1` or `protocol 3.3`, is not searched.
The CLI, Python API and dashboard use the project's `autopwn_suite/nmap_backend.py` adapter
to run the system Nmap executable directly and parse its
[XML output](https://nmap.org/book/output-formats-xml-output.html) with Python's standard library.
Install Nmap and make sure `nmap` is on `PATH`; no Python Nmap wrapper is required.
Host discovery, TCP/UDP services, OS/vendor detection, custom Nmap flags (command line and
Python API only; the dashboard builds its arguments from its own controls) and NSE
results are supported. Dashboard scans retain live progress and cancellation.
The adapter also exposes complete raw XML, CPE identifiers and nested NSE tables
for callers that need more detail, and rejects failed or incomplete XML output.
`python -m pytest` checks dependency declarations, XML parsing and process cleanup.
With Nmap installed, the suite also scans temporary loopback HTTP/TLS services through
the CLI, Python API and dashboard, and checks IPv6 when available. These live cases
are skipped when the executable is missing; the parser and process tests still run.
Poetry CI installs system Nmap so the live checks run there too.
## Web application checks
The CLI's existing web vulnerability prompt runs directory discovery and passive header/cookie
checks even on sites with no query inputs. When port results are available it checks each detected
TCP HTTP(S) service, including nonstandard ports; otherwise it tries the host's default web ports.
The crawler follows same-origin links and discovers
GET forms, preserving blank inputs, repeated parameter names and other query values. It skips
POST forms, password forms and uploads. The default crawl limits are 250 pages, 1,000 discovered
URLs and five levels of links; reaching a limit is reported as limited coverage. A page with more than
100 forms, with more than 2,000 form controls, or with forms that hold more than 200,000 elements in all, is analysed only in part and reported the same way, and a link or form
URL longer than 8,192 characters is not followed.
SQLi and LFI checks compare against the original response and repeat promising probes before
reporting new database errors or Unix/Windows file signatures. Reflected XSS checks require an
unescaped payload in a script element or HTML event handler in an HTML response; JSON, plain
text, comments and inactive HTML contexts are excluded. Browser execution and CSP bypass are
not verified, so injection findings remain **candidates** requiring review. Directory hits are
**observations**, with random missing-path controls suppressing soft 404 pages and blanket
login redirects. A protected path is not itself a vulnerability.
Configuration checks report **advisories** for missing/invalid `nosniff`, HTML CSP and framing
protection, HTTPS hostname HSTS, and cookie Secure/HttpOnly/SameSite flags. Cookie values are
excluded from these advisories. Recommendations follow the
[OWASP HTTP Headers Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/HTTP_Headers_Cheat_Sheet.html).
They describe the response observed, not a complete configuration audit.
Additional application checks include:
- **Exposed files and directory indexes:** signature checks for environment files, Git metadata,
PHP source backups, database dumps, server configuration and backup archives. Directory listings
require an index heading and multiple child-file links. Sensitive contents are omitted from
findings; archives are not extracted. Known diagnostic pages and HTTP error stack traces are
reported without printing their settings or trace details.
- **CORS:** two arbitrary origins and repeated `null` origins test credential permission. Public
wildcard access alone is not reported as a vulnerability. Wildcard-plus-credentials produces a
configuration advisory because browsers reject credentialed reads. Actual authenticated data
exposure is not verified.
- **Open redirects:** redirect-like query parameters are tested with distinct controlled hosts.
A finding requires repeatable external `Location` destinations; those destinations are never
visited.
- **Boolean SQLi:** two distinct true/false comparisons must agree against a stable original
response. Different content types, HTTP errors, SQL errors, unstable pages and truncated bodies
are excluded. These remain candidates; no timing probes or database extraction are performed.
- **HTTP methods:** OPTIONS advertises capabilities; TRACE requires a repeatable request-line and
marker-header echo. These are observations. PUT, DELETE, PATCH and CONNECT are not sent, and
method probes carry no cookies or authorization headers. Automatic `.netrc` authentication is
suppressed for the additional diagnostic probes.
- **Host headers:** two controlled values for each of Host and X-Forwarded-Host must influence
redirect hosts or generated absolute URLs. Plain text reflection is ignored. These remain
candidates, and password reset poisoning or cache poisoning impact is not verified. Requests
use unique query markers and request cache-control directives.
- **TLS:** certificate expiry, future validity, SAN hostname/IP matching and local trust validation
are checked independently. Exact-version handshakes test TLS 1.0 and 1.1 support. A finding requires
successful negotiation; unsupported client capabilities and failed connections are reported as
incomplete checks. Private CA trust failures are advisories. This is not a complete cipher,
revocation or certificate-chain audit. Certificate parsing uses `cryptography`.
All HTTP checks share a default budget of 10,000 requests per web endpoint, including discovery,
crawling and injection probes. Injection and additional checks sample at most 100 discovered URLs
per check family, with at most five parameters per URL. HTTP method checks run on the starting
endpoint. TLS handshakes run separately. Reaching these limits is logged as
limited coverage. Response bodies are read as prefixes capped at 1 MiB and connections are closed;
file contents are not written to disk. Testing guidance follows the
[OWASP Web Security Testing Guide](https://wstg.owasp.org/v4.2/4-Web_Application_Security_Testing/).
Requests have a default 10-second network-I/O deadline and at most three followed redirects.
The deadline interrupts slow response headers and bodies, including incomplete chunks;
Stop also interrupts active reads. OS DNS resolution is outside this deadline.
Diagnostic HTTP uses private anonymous sessions, ignoring `.netrc` and environment proxies;
operator credentials and cookies are not attached. Redirects are checked
before following them; injection probes cannot leave the target origin. Initial endpoint
discovery also permits the same hostname's HTTP port 80 to upgrade to HTTPS port 443.
Self-signed HTTPS targets remain supported for application probes; TLS findings report certificate
and trust problems separately.
Offline mode continues to disable web probes.
Module callers can supply a host, `host:port`, IPv6 address or explicit application URL:
```python
from autopwn_suite.web.webvuln import webvuln
findings = webvuln("https://example.com:8443/app/", log, console)
```
Each returned finding contains `type`, `url`, `parameter`, `severity`, `confidence`, `evidence`,
an ID, timestamp, detection/impact/remediation context, captured exchanges and a reproduction plan.
A finding replaces a query value with `REDACTED` when its parameter name looks like a credential (`token`, `session`, `code`, `key`, `sig`, `otp`, `pwd`, an `api`, `access`, `private`, `app`, `client`, `consumer`, `license`, `encryption`, `signing`, `master`, `service`, `ssh` or `developer` key, and similar) and drops URL credentials (userinfo and fragment), so that a PoC can still replay the other values; a secret in a parameter with another name, in the URL path, or inside the value of another parameter (a `redirect_uri` or `next` URL) is not recognized there. Everything else the web scan writes about a URL (the line that announces a scan, log lines, coverage notes, and the target a dashboard job record, export, notification or the CLI parameter summary shows) replaces every query value, and a query part without `=`, with `REDACTED` whatever the parameter is called (`?id=REDACTED&x=REDACTED`) and drops userinfo and fragments, for any case of the scheme and for a target typed without a scheme. A target is redacted as one string, so a quote, an angle bracket or any kind of space inside it cannot leave a later part visible; a log line ends a URL at the next space, tab or line break. Only a secret in the URL path, in a query part without `=` inside a word without a scheme, or after a raw space inside a URL that a log line quotes, stays visible (a link in a page is written with `%20` when the scan reads it, so this needs a URL that was typed with a space or a redirect that carries one). The scan itself uses the target as typed. Captured exchanges include request roles,
diagnostic headers, status, response-prefix hash/size, latency and truncation state; response bodies
and cookie values are omitted. The CLI prints these results through its existing console/export flow.
Text that a scanned host or a data provider controls (response headers, crawled links, Nmap banners and hostnames, certificate names, NVD, local-database and Exploit-DB descriptions) is printed, saved and returned as a single line: line breaks, escape sequences and other control characters, bidirectional overrides and zero-width characters are removed or replaced by a space, so a hostile target cannot forge a result line or drive your terminal through it (the response headers that a dashboard replay records are kept as received and are shown escaped). A URL keeps such characters as the percent-encoding that the HTTP client sends (a crawled link with an escape sequence is stored as `%1B...`), so the recorded requests, a replay and the generated PoCs send the request that the scan sent. Nmap script output and the OS fingerprint keep their newlines. The scanned text can still be misleading, so read scan output of an untrusted target with care.
### TLS certificate verification
Website checks verify the target's TLS certificate by default. A target with a self-signed, expired or
otherwise untrusted certificate is skipped with a warning that explains why. For systems you trust, such as lab
machines, opt out explicitly with `--insecure-tls` (or `insecure_tls = true` in the `[AUTOPWN]` configuration
section, or **Accept untrusted certificates** in the dashboard's web controls). Proof-of-concept scripts record
the choice made for the scan that produced them. The TLS check still reports the target's certificate problems.
### Credential files
NVD API keys, SMTP passwords and webhook URLs can be kept in their own files instead of command-line arguments,
configuration or the dashboard settings file. Point the matching variable at a one-line, owner-readable file
(Docker and Kubernetes secrets work directly): `AUTOPWN_NIST_API_KEY_FILE`, `AUTOPWN_SMTP_PASSWORD_FILE` and
`AUTOPWN_WEBHOOK_URL_FILE`. Files are re-read when used, so a credential can be replaced without restarting or
editing configuration; values from files are never written to the dashboard settings.
### Dashboard controls and verification
Enable **Web checks** in the scan form. Use **Network + selected web checks** to check detected HTTP(S)
services after Nmap, or **Website only** to enter an application URL without requiring Nmap or CVE lookup.
Expand **Select checks** to choose among all 13 check groups. The **Light** preset selects headers/cookies
and TLS; **All** selects every group. Expand **Speed, limits & crawl** to control web request pacing, the HTTP request budget,
timeout, crawl pages/URLs/depth, endpoints per injection/check family, parameters and response size cap.
Save the same controls in a profile and use that profile for scheduled scans.
Saved profiles retain their explicit limits when defaults change. Adjustable upper bounds are
50,000 requests, 2,000 pages, 10,000 URLs, depth 10 and 1,000 probe endpoints. Larger scans take
longer and send more requests; reaching any configured limit still reports incomplete coverage.
Web speed is independent of Nmap speed: 0–5 adds minimum delays of 5 seconds, 2 seconds,
500 ms, 100 ms, 25 ms or no delay between request starts. **Minimum request delay** can increase
that delay; timeout controls both HTTP requests and TLS connections. These settings are saved
with profiles and used by scheduled scans.
Use **Resume** on an incomplete, stopped or failed scan, or **Resume scan** in its web coverage
card. Review the suggested speed and limits, then resume the same job. Completed checks,
findings, crawl results, Nmap observations and successful CVE lookups are retained. Unfinished
web checks get fresh request, page, endpoint and per-URL parameter budgets for each attempt; completed inputs
and directory paths are skipped. Discovery, parameter and response caps that blocked the last
attempt are increased in the suggested settings, within the supported bounds. Interrupted
inputs and failed checks are retried. Completion means the selected checks finished; unreachable
pages, response caps and unavailable local TLS capabilities can still leave coverage partial.
Resuming keeps the original target and selected checks. Start a new scan to change either.
The **Web Security** tab prioritizes severity and supports search and confidence/severity/scan filters.
Coverage cards show enabled checks, request counts and incomplete-check reasons. Select a finding for:
- **Overview:** observed evidence, detection method, potential impact, remediation, limitations, steps and CWE/OWASP references.
- **Evidence:** baseline/probe/repeat requests, response metadata, available certificate metadata and the complete finding with verification history.
- **PoC & Verify:** preview, copy or download a standalone Python reproducer, POSIX curl commands or a JSON request plan. XSS and credentialed CORS findings also provide a browser PoC.
Downloading or viewing a PoC does not contact the target. **Verify evidence** explicitly replays only
the stored same-origin plan, without authentication cookies, redirects or arbitrary supplied code.
When detection followed validated same-origin redirects, its PoCs replay the final recorded URLs
directly; the evidence keeps the intermediate redirect exchanges.
Python verification compares baseline/probe evidence and returns reproduced, not reproduced or
inconclusive, with redacted response metadata. Run a downloaded Python PoC after installing
`requests` and `cryptography`; restore any `REDACTED` query inputs locally first. The dashboard refuses
server replay when local input is required. Browser PoCs require an explicit test click; use a
controlled separate origin and an appropriate browser session to assess CORS or XSS behavior.
Evidence reproduction does not establish database access, browser execution, authenticated data
exposure or other full exploit impact.
The dashboard keeps scan findings and resume checkpoints in memory for the current process.
Checkpoints are private and are not included in exports; restarting the dashboard discards them.
**Export report** saves filtered
findings with their full evidence and verification history as JSON. Scan JSON exports include web
findings/coverage, and scan PDF exports include their evidence/remediation summaries. Export results
before restarting the dashboard. Offline mode disables web scans and verification while allowing
existing findings and PoCs to be viewed or exported.
## Offline vulnerability database
AutoPWN can keep a portable local mirror of the [NIST NVD JSON 2.0 feeds](https://nvd.nist.gov/vuln/data-feeds).
These are CVE records (descriptions, CVSS scores, affected-product configurations and references),
not exploit programs. The small NIST `.meta` files describe feed freshness, size and checksums;
downloading only those files is insufficient for vulnerability detection.
On a connected machine, explicitly download the database:
```bash
autopwn-suite --update-vuln-db
autopwn-suite --vuln-db-status
```
The first download covers all yearly feeds from 2002 through the current year, including
older CVEs contained in the 2002 feed. Allow several minutes and several GB of free disk space
for the database, feed processing and a temporary update copy. No NIST API key is required for
feed downloads. Repeat `--update-vuln-db` whenever you want fresh data. Each update checks every
year's metadata and downloads only changed yearly feeds, so updates also cover long periods
without internet. Checksums and record counts are verified before publishing the new database;
a failed or interrupted update preserves the previous database. Concurrent updates are rejected.
If NVD has not published the current year's feed yet (early January) and no record of that year was
ever indexed, the update skips that feed and says so in its last message. The database does not record
the gap and lacks that year's CVEs until a later update indexes them, so repeat the update after a few days.
An update may need to be retried after active scans finish if the operating system locks the database file.
Run an airgapped scan with an explicit target:
```bash
autopwn-suite --offline -t 192.168.1.0/24 -y
autopwn-suite --web --offline
```
Offline mode uses local CVE lookups, skips internet connectivity checks, exploit downloads,
web application probes, automatic Nmap installation and email/webhook delivery, and disables
Nmap reverse DNS. Nmap still communicates with the requested scan targets. Use IP addresses
and locally installed Nmap scripts; user-supplied hostnames or scripts may have their own network
requirements. Install Python dependencies and Nmap before disconnecting, or transfer installation
packages from a connected machine. The dashboard uses local assets and system fonts.
The default `--vuln-source auto` tries online NVD lookups and falls back to a ready local database
if NVD is unavailable, staying local for the rest of that scan. That fallback does not make the scan
offline: its web checks, reports and email/webhook notifications still run, and only an offline mode
you chose skips them. `--vuln-source online` requires
online lookups. Use `--offline` (or `--vuln-source offline`) to avoid trying NVD at all.
Missing or invalid local data fails explicitly rather than reporting a clean vulnerability scan:
when NVD fails and no local database is ready, the scan stops with exit status 1 and a message that
names both failures, and the output recorded so far is still saved. A scan whose host discovery fails
saves its output the same way and ends with that error's text; a failed Nmap port scan ends the scan with
its error text and saves nothing. A saved partial report goes to the usual output file, so it replaces an
earlier report with the same name.
Stored data remains usable without an expiry; its update time is shown in scan logs and dashboard
results. Offline searches match description keyword prefixes, with all query terms required,
and keep versions such as `10.1.18` distinct from a query for `1.1`; the CPE product search reads an index of
the products each record lists, which a database downloaded before v2.9.0 gets, from the records it holds,
at its next update. Until then that search is skipped, so offline scans find fewer CVEs: a scan that reads such a
database logs a warning once, `--vuln-db-status` advises running `--update-vuln-db`, and the dashboard says so
beside the database status in Settings and marks the Settings tab with its **Update** badge. Online and offline scans then keep
the CVEs whose NVD applicability covers the detected release. Findings are possible vulnerabilities, not
proof of exploitability: NVD's version ranges describe upstream releases, so a distribution package with a
backported fix is still reported, a CVE in a bundled library whose description does not name the
product is not found, a CVE that NVD has not analyzed is found only when its description names the release,
and for a service without a usable CPE from Nmap, a product of another vendor with the same name, or a
same-vendor product that Nmap's name does not tell apart, can match (`KarjaSoft Sami ftpd`, which Nmap gives
only the Windows CPE, gets Sami HTTP Server CVEs). A CVE that NVD files under an operating system or device is
reported only for a service whose Nmap CPE names that system (not for `Contiki httpd`, which Nmap gives none).
In the dashboard, **Settings → Offline vulnerability database** provides manual Download/Update,
progress, CVE count, update time and an **Export for airgapped system** link. Select the vulnerability
data source in **New Scan** or save it in a scan profile for scheduled scans. Starting the server
with `--offline` forces every scan to use local data and blocks downloads and test notifications.
The **Offline mode — whole dashboard** toggle in Settings saves this preference across restarts
and overrides the source for all new and scheduled scans. It also blocks downloads and notifications.
Turn it off when you want to download updates. Finish or stop active online scans and let any database
update or pending notification finish before turning it on. A server started with `--offline` keeps offline mode enforced.
On Windows a database that a running scan has open cannot be replaced. A scan that is already running when
the update starts stops it before it downloads anything. A scan that opens the database during the download
blocks the final replace, which is retried for a few seconds, and then the finished download is discarded.
Either way the previous database is kept and the update asks you to close running scans first. Windows
reports a read-only database file the same way, so the update also asks you to make the file writable.
The default file is `vulnerabilities.sqlite3` in the per-user data directory (`~/.local/share/autopwn-suite`,
`%LOCALAPPDATA%\autopwn-suite` or `~/Library/Application Support/autopwn-suite`), or
`AUTOPWN_DATA_DIR/vulnerabilities.sqlite3` when that environment variable is set. Copy this single file to the airgapped machine's data
directory, or select its location explicitly:
```bash
autopwn-suite --offline --vuln-db /media/transfer/vulnerabilities.sqlite3 -t 192.168.1.10
autopwn-suite --web --offline --vuln-db /media/transfer/vulnerabilities.sqlite3
```
The database contains public vulnerability data, without scan targets, credentials or exploit files.
It is portable between platforms. Configuration files also support `offline`, `vulnerability_source`
and `vuln_db` in `[AUTOPWN]`. Python callers can use
`AutoScanner().scan("192.168.1.10", offline=True, vuln_db="/path/vulnerabilities.sqlite3")`.
## Checking for updates and self-updating
```bash
python autopwn.py --check-update
python autopwn.py --check-update --update-channel commit --update-branch main
python autopwn.py --apply-update
python autopwn.py --apply-update --update-channel commit --update-branch main
```
`--check-update` asks GitHub for a newer AutoPWN Suite, prints the result, then exits.
`--apply-update` goes further and fast-forwards this git checkout to that newer release/commit,
then exits. Neither runs automatically during a scan — both are explicit, one-shot commands.
By default both compare against the repo's latest GitHub release tag (`--update-channel
release`, the default). Pass `--update-channel commit` to instead target the latest commit on
`--update-branch` (default `main`). Use `--update-repo OWNER/REPO` (or the `AUTOPWN_UPDATE_REPO`
environment variable) to point at a different fork. The repository must be written `OWNER/REPO` and the branch
must be a plain git branch name; anything else is refused. An explicit `--update-channel` is remembered in
`update_channel.txt` in the data directory. Both need internet access and refuse to run with `--offline`
(or `--vuln-source offline`).
`--apply-update` updates AutoPWN Suite the way it was installed:
| Installed with | `--apply-update` |
| --- | --- |
| A git clone, run as `python autopwn.py` | Fast-forwards the checkout, as described below. |
| pipx or uv | Runs `pipx upgrade autopwn-suite` or `uv tool upgrade autopwn-suite`. |
| pip in a virtual environment, or `install.sh` | Runs `python -m pip install --upgrade autopwn-suite==` in that environment. An `install.sh` installation belongs to root, so run `sudo autopwn-suite --apply-update`. |
| The standalone binary | Refused: download the new binary from the [latest release](https://github.com/GamehunterKaan/AutoPWN-Suite/releases/latest) and verify it. |
| Docker | Refused: on the host, run `docker compose pull && docker compose up -d`. |
A pipx, uv or pip update installs the latest release from PyPI, wheels only, so no package's build code runs.
It trusts PyPI as the first installation did, follows only this repository's releases (`--update-repo` and
`AUTOPWN_UPDATE_REPO` apply to checkouts) and never moves back. On Windows, which locks the files of a running
program, it is refused and tells you the command to run after closing AutoPWN Suite: a package manager that
replaced the running `autopwn-suite.exe` would fail halfway and could leave the installation broken.
`--check-update` prints the same advice under an available update.
For a git checkout (a copy inside another git repository is refused), `--apply-update` needs a clean
working tree, and only fast-forwards — it refuses and leaves your checkout untouched if the
working tree has uncommitted changes or the local branch has diverged from the target (resolve
that manually, e.g. with `git rebase` or by committing/stashing first). It does not verify signatures: it
trusts the repository named by `--update-repo`, so keep the default unless you trust another. Restart
AutoPWN Suite after it reports success so the updated code takes effect. When nothing is newer it changes
nothing and reports `Already up to date`. It never moves a checkout back: a branch or detached HEAD that is
already ahead of the target stays where it is, and the commit channel reports such a checkout as up to date.
When an update changes `pyproject.toml`, `poetry.lock`, `requirements.txt` or `requirements-locked.txt`, it
also tells you to install the dependencies again, as **From source** under Installation describes, before
restarting.
The dashboard offers the same check and update under **Settings → AutoPWN Suite updates**. With
**Check for updates automatically** on (the default), it asks GitHub when a dashboard page opens and then at
most every 6 hours, never in offline mode; turn the switch off to check only when you click
**Check for updates**. When a newer version exists it shows an **Update** badge on the Settings tab. It
applies the update only when you click **Apply update** and confirm. Only the channel can be chosen there: the
repository is `AUTOPWN_UPDATE_REPO` (or the default), and the commit channel always follows `main`. Applying
updates a git checkout, or a pipx, uv or pip installation that the dashboard's account may change, except on
Windows; the dashboard never runs a package manager as root. For any other installation it shows the command
to run instead. Applying is refused while a scan, web verification or database download is running. While
an update is applied, and afterwards until you restart the dashboard, new scans, resumes and web verifications are
refused and scheduled scans wait for the restart: an interval schedule then runs at once, a daily or weekly one
only within an hour of its time (otherwise at its next time). The dashboard notices any change to its checkout, including
`--apply-update` or a `git pull` while it runs, because it compares the commit on disk with the one it
started from, and likewise a package update, by the installed version. Restart the dashboard, then reload the page.
## Interface language
AutoPWN Suite speaks English and Turkish. `--lang tr` (or `--language tr`) selects the language of the CLI,
the daemon installer and the reports, and is remembered in `language.txt` in the data directory. Without
it the language follows the `AUTOPWN_LANG` environment variable, then the last explicit choice, then your
system locale, then English. The dashboard has a language selector on the sign-in page and in Settings.
The Turkish text is machine-translated and not yet reviewed by a native speaker, and scanned data (CVE
descriptions, banners, exploit titles) is never translated. See the
[internationalization notes](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/INTERNATIONALIZATION.md).
## Demo
AutoPWN Suite has a very user friendly easy to read output.
[](https://asciinema.org/a/509345)
## Installation
AutoPWN Suite needs [Nmap](https://nmap.org/download.html) on `PATH` for network scans
(`sudo apt install nmap`, `brew install nmap`, or the installer from nmap.org on Windows).
Website-only dashboard scans do not need it, and the command line offers to install it
on first use. Every method below gives you the `autopwn-suite` command. Verify downloads
as described in [Releasing](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/RELEASING.md#consumer-verification).
### pipx or uv (recommended)
Needs Python 3.10 or newer. This keeps AutoPWN Suite and its dependencies in their own
environment on Linux, macOS and Windows:
```bash
pipx install autopwn-suite # or: uv tool install autopwn-suite
pipx upgrade autopwn-suite # update
pipx uninstall autopwn-suite # remove
```
### Standalone binary
Each [release](https://github.com/GamehunterKaan/AutoPWN-Suite/releases) attaches
single-file binaries that need no Python installation: `linux-amd64`, `linux-arm64`,
`windows-amd64.exe` and `macos-arm64`. Verify the signed `SHA256SUMS`
([how](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/RELEASING.md#consumer-verification)), then on Linux or macOS make the file
executable and run it:
```bash
chmod +x autopwn-suite-v2.9.0-linux-amd64
./autopwn-suite-v2.9.0-linux-amd64 --help
```
The binaries are checksum-verified and Sigstore-signed but not code-signed for Windows or
macOS, so on first run Windows SmartScreen shows an "unrecognized app" warning
(**More info**, then **Run anyway**) and macOS may block the file until you run
`xattr -d com.apple.quarantine `. Only do this for a file whose signature and
checksum you verified. Rename the file to `autopwn-suite` and place it on your `PATH`
if you want the short command.
### Linux system-wide
For a system-wide installation from a checkout (requires root privileges), use the provided script:
```bash
git clone https://github.com/GamehunterKaan/AutoPWN-Suite.git
cd AutoPWN-Suite
# Install as root
sudo bash install.sh
# Uninstall
sudo bash uninstall.sh
```
It creates a virtual environment in `/opt/autopwn-suite`, installs the package into it and
links `/usr/local/bin/autopwn-suite` to it. Run without `sudo`, the script asks for it only where needed and
the installation then belongs to your account, so `--daemon-install` refuses it and `sudo autopwn-suite`
would run files you can change; `sudo bash install.sh` makes the installation belong to root. `PREFIX`, `BINDIR`, `APPDIR` and `DESTDIR` are
honored, and `REQUIREMENTS_FILE=requirements-locked.txt` installs hash-verified dependencies
(see [Building](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/BUILDING.md)).
### From source
```bash
git clone https://github.com/GamehunterKaan/AutoPWN-Suite.git
cd AutoPWN-Suite
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install . # or: pip install -r requirements.txt && python autopwn.py
```
### Docker
The fastest way to get the web UI running. Download the [docker-compose.yml](https://raw.githubusercontent.com/GamehunterKaan/AutoPWN-Suite/main/docker-compose.yml) file and run:
```bash
docker compose up -d
```
The web UI will be available at `http://localhost:8080`.
#### Configuration
Edit `docker-compose.yml` to change host, port or data directory:
```yaml
environment:
- AUTOPWN_DATA_DIR=/data # Where settings/profiles/schedules are stored
- AUTOPWN_WEB_HOST=127.0.0.1 # Listen address (loopback by default)
- AUTOPWN_WEB_PORT=8080 # Listen port
```
> **Note:** Host networking (`network_mode: host`) is required for nmap to discover and scan devices on your local network. It is also why you can sign in over plain HTTP at `http://localhost:8080`: replacing it with a published port (`ports:` or `docker run -p 127.0.0.1:8080:8080`) makes the dashboard see the bridge gateway instead of loopback and refuse sign-in without HTTPS (explained under Usage, Web UI).
You can also run the CLI via Docker:
```bash
docker run -it --net=host gamehunterkaan/autopwn-suite -t 192.168.1.0/24 -y
```
### Where your data lives
The dashboard account, settings, profiles, schedules and the local CVE database are stored
in a per-user directory (`~/.local/share/autopwn-suite`, `%LOCALAPPDATA%\autopwn-suite` or
`~/Library/Application Support/autopwn-suite`), or in `AUTOPWN_DATA_DIR` when set.
Uninstalling never removes it, because it holds your administrator password hash and
plaintext integration settings: delete the directory yourself when you no longer want them.
Scan outputs, downloaded exploits, `api.txt` and configuration files stay in the directory
you run the command from.
### Cloud
You can use Google Cloud Shell.
[](https://shell.cloud.google.com/cloudshell/editor?cloudshell_git_repo=https://github.com/GamehunterKaan/AutoPWN-Suite.git)
## Usage
Running with root privileges (sudo) is always recommended.
### CLI
#### Automatic Mode
```console
autopwn-suite -y
```
#### Scan a Specific Target
```console
autopwn-suite -t
```
#### Change Scanning Speed
```console
autopwn-suite -s <1, 2, 3, 4, 5>
```
#### Change Scanning Mode
```console
autopwn-suite -m
```
For more details about usage and flags use `-h` flag.
#### Install Daemon
```console
autopwn-suite --daemon-install
```
Run it as root on Linux from a root-owned installation of AutoPWN Suite: `sudo bash install.sh` or a
standalone binary kept in a root-owned directory. The service runs as root, so it refuses an installation
that another user can modify (a pipx or `uv tool` environment or a virtual environment in a home directory) and a
source checkout started with `python autopwn.py`, which the service could not import. It checks this before asking any question.
The systemd service starts that same installation, and the generated configuration is kept in
`/opt/autopwn-suite/autopwn-daemon.conf` (mode `0600` from the moment it is created, never copied and tightened afterwards, as it can hold the SMTP password, NVD key or webhook URL).
Running `--daemon-install` again rewrites the service and restarts it, so a new configuration or a newer
installation takes effect. A daemon installed by release 2.6 or earlier keeps running
its old copy of the source until you do (`install.sh` warns when it finds
one).
```console
sudo autopwn-suite --daemon-uninstall
```
stops and disables the service and deletes its unit file and `/opt/autopwn-suite/autopwn-daemon.conf`. The program,
`/var/log/autopwn-daemon.log` and the other files in `/opt/autopwn-suite` stay; remove the program with
`sudo bash uninstall.sh`, `pipx uninstall autopwn-suite` or by deleting the binary.
### Web UI
Launch the web dashboard:
```console
autopwn-suite --web
```
The dashboard listens on `127.0.0.1` by default. With a custom host and port:
```console
autopwn-suite --web --web-host 0.0.0.0 --web-port 3000
```
Listening beyond localhost exposes the sign-in page to the network. Remote clients must then use HTTPS (terminate TLS in a reverse proxy that passes the `Host` header through, e.g. nginx `proxy_set_header Host $http_host;`, which keeps a non-default port, set `AUTOPWN_WEB_SECURE_COOKIE=1`, and firewall the service). Inside containers, `-p 127.0.0.1:8080:8080` keeps the published port off the network, but a port published from Docker's bridge network reaches the dashboard from the bridge gateway, which is not loopback, so sign-in over plain HTTP is refused. For plain-HTTP sign-in on the Docker host use host networking with `AUTOPWN_WEB_HOST=127.0.0.1` (as `docker-compose.yml` does); otherwise put a TLS reverse proxy that keeps the `Host` header in front and set `AUTOPWN_WEB_SECURE_COOKIE=1`.
### REST API
The web UI exposes a full REST API:
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/scans` | List all scan jobs |
| `POST` | `/api/scan/start` | Start a new scan |
| `POST` | `/api/scan/stop` | Stop a running scan |
| `GET` | `/api/hosts` | All discovered hosts (merged) |
| `GET` | `/api/log` | Log history |
| `GET` | `/api/events` | SSE event stream; `after=` or `Last-Event-ID` resumes after a log entry |
| `GET` | `/api/web/catalog` | Web check names, default controls, bounds and offline state |
| `GET` | `/api/web/findings` | Web finding summaries across current scans |
| `GET` | `/api/web/findings//` | Complete finding, evidence and verification history |
| `GET` | `/api/web/findings///poc?format=python` | Download a PoC; formats: python, curl, html, json |
| `POST` | `/api/web/findings///verify` | Explicitly replay the stored plan; send an empty JSON object |
| `GET` | `/api/settings` | Get all settings |
| `PUT` | `/api/settings` | Update settings |
| `GET` | `/api/update` | Update channel, last check result and whether a restart is needed |
| `POST` | `/api/update/check` | Check GitHub for a newer version now; optional `{"channel": "release"}` or `"commit"` |
| `POST` | `/api/update/apply` | Update this copy to the newer release or commit: fast-forward a git checkout, or update a pipx, uv or pip installation |
| `GET` | `/api/profiles` | List scan profiles |
| `POST` | `/api/profiles` | Create a profile |
| `PUT` | `/api/profiles/` | Update a profile |
| `DELETE` | `/api/profiles/` | Delete a profile |
| `GET` | `/api/schedules` | List scheduled scans |
| `POST` | `/api/schedules` | Create a schedule |
| `PUT` | `/api/schedules/` | Update a schedule |
| `DELETE` | `/api/schedules/` | Delete a schedule |
## Module Usage
```python
from autopwn_suite import AutoScanner
scanner = AutoScanner()
json_results = scanner.scan("192.168.0.1")
scanner.save_to_file("autopwn.json")
```
## Development and Testing
Use **Poetry 2.5.1** to install dependencies and run tests. This is the version
required by `pyproject.toml`, pinned in CI, and used to generate `poetry.lock`.
#### Installing Dependencies
```console
pipx install poetry==2.5.1
poetry install
```
After changing dependencies, run `poetry lock` with Poetry 2.5.1 and commit
`pyproject.toml` and `poetry.lock` together. This retains already locked versions
unless their constraints require a change. Use `poetry check --lock` to verify
that the lockfile matches the project; CI runs the same check before installation.
#### Running Tests
```console
# Run all tests with coverage
poetry run pytest
# Run tests without coverage
poetry run pytest --no-cov
# Run only unit tests
poetry run pytest -m unit
# Run only integration tests
poetry run pytest -m integration
# Run tests excluding slow tests
poetry run pytest -m "not slow"
```
#### Running with Docker (Development)
```bash
docker build --tag autopwn-suite:local .
```
See [Build from source](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/docs/BUILDING.md) for prerequisites, package builds and
running the locally built image. The Compose file runs a published image.
## Contributing to AutoPWN Suite
Pull requests with suggested changes and fixes are welcome directly: you do not need to open an issue or ask first. [Click here for more info!](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/.github/CONTRIBUTING.md)
## License
AutoPWN Suite is licensed under the [Apache License 2.0](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/LICENSE). See [NOTICE](https://github.com/GamehunterKaan/AutoPWN-Suite/blob/main/NOTICE) for attribution.
Third-party dependencies are covered by their own licenses.
This tool is intended for authorized security testing only. You are responsible for complying with all applicable laws.
## Support or Contact
Having trouble using this tool? You can [create an issue.](https://github.com/GamehunterKaan/AutoPWN-Suite/issues/new/choose)
