GPT_Vuln-analyzer: turning nmap and DNS output into a written assessment

A report layer, not a detection layer

The clearest way to understand this project is that it adds no detection capability of its own. It runs tools that already exist, collects their raw output, and passes that output to a large language model which returns a structured, pentester-oriented analysis. The README describes it as an AI-assisted reconnaissance and vulnerability-analysis toolkit, and the mechanism is stated plainly: it runs the scan with nmap, DNS, subdomains, JWT, PCAP and GeoIP, then hands the raw output to a large language model.

That is a different proposition from a scanner. A scanner decides what is a vulnerability. This project decides how to explain what a scanner found, in prose, with a structure a human can read. The value depends entirely on whether you find that useful, and many people do, because reading raw nmap output and deciding what matters is the part of the job that consumes the most time.

The top-level tree shows the shape of it: gpt_vuln.py is the CLI, GVA_gui.py is the desktop GUI, components/ holds the pieces, lists/ holds wordlists, outputs/ holds results, and package/ is there for packaged builds. The primary language is Python and the licence is MIT.

The project ships with both a command-line interface and a desktop GUI, which is an unusual combination for a security tool and suggests the author wanted the same engine usable by a person who does not want a terminal.

The collection modules and what each one needs

The feature list is a list of collection modules, and each one has a distinct external requirement, which is the practical constraint on running the toolkit.

The nmap analysis has ten curated scan profiles, from a fast unprivileged triage to a full-port SYN audit. DNS recon does forward, reverse and zone-transfer lookups, analysed into typed records. Subdomain enumeration resolves a wordlist of subdomains against a domain. JWT analysis decodes a token and surfaces likely attacks and endpoints to test. PCAP analysis inspects a capture for traffic, ARP and MAC spoofing, and cleartext credentials. GeoIP geolocates an address through ipgeolocation.io. Password cracking does wordlist and brute-force cracking with common hash algorithms.

The requirements section lists the binaries you need: nmap on PATH for the nmap attack, Wireshark or tshark on PATH for the pcap attack, an ipgeolocation.io key for the geo attack, and Docker only if you use the local Ollama provider. The dependency list in pyproject.toml matches, with python-nmap, scapy, dnspython, requests and pyjwt covering the scanning and analysis work.

One detail in the nmap notes matters more than it looks. The nmap attack shells out to the system nmap binary through python-nmap, so nmap has to be installed and runnable, and profiles 6 to 10 need root because of SYN, UDP and OS-detection flags. GVA escalates only the nmap step with sudo, or you can pass --sudo. Profiles 1 to 5 run unprivileged and profile 1 is the default.

The same notes handle a common breakage: on immutable distros such as Bazzite and Silverblue the system nmap can fail with libssh2.so.1 missing, and the suggested fix is a conda-forge nmap, or layering the library with rpm-ostree, or brew, or a distrobox container. The README also notes that if nmap is missing or broken, the attack reports a clean error instead of crashing.

Installing without handing the machine to root

The install script is designed to run as your normal user, and the README makes a point of why.

./install.sh              # full install
./install.sh --no-system  # skip system packages (uv + Python deps only)

It auto-detects your package manager, listing apt, dnf, pacman, zypper, apk, brew and rpm-ostree, installs uv at user level, runs uv sync, and creates .env. The elevation is deliberately narrow: the script elevates only the system-package step with sudo.

The instruction not to run sudo su first is worth repeating because it is the kind of thing that wastes an afternoon. If the project sits on a user-only mount such as /run/host or /media, root cannot read it, so the normal-user invocation is the reliable path.

If you prefer to do it by hand, uv sync is the command, and pip install -r requirements.txt works as a fallback. The requirements file says itself that pyproject.toml managed with uv is the source of truth, and it lists the same providers and scanners, minus pydantic-ai, which is a notable difference between the two paths.

Configuration is a copied environment file.

cp .env.example .env

The keys are the ones you would expect.

GEOIP_API_KEY=
OPENAI_API_KEY=
ANTHROPIC_API_KEY=
GEMINI_API_KEY=

Any provider without a key is skipped automatically, so the file doubles as a record of which backends you have enabled.

Several models, and one of them writes the final report

The AI layer is the part that distinguishes this from a wrapper around nmap, and it has three stages.

First, every provider is a Pydantic AI agent that returns a validated, structured result, so the model output is checked against a schema rather than parsed as free text. Second, when you select more than one provider, each model analyses the scan independently and concurrently. Third, a deliberation agent, which is one of the selected models, reconciles those analyses into a single consolidated report. A live progress board shows each model's status, timing and the deliberation step while it runs.

The provider table gives defaults and indicative prices per million tokens: OpenAI defaults to gpt-5.6-luna at roughly $0.20 in and $1.20 out, Anthropic to claude-haiku-4-5 at $1.00 in and $5.00 out, Google to gemini-3.6-flash at $0.75 in and $3.75 out, and Ollama to llama3 running locally and free. Any model can be overridden with the matching *_MODEL variable in .env, and the .env.example file lists alternatives including gpt-5.6-cyber, described as a security-testing variant.

Using a second, stronger model as the summarizer is a reasonable cost strategy, since the reconciliation step is the one that matters most for the final document. The CLI exposes it directly with --summarizer and --show_individual.

Running the CLI, and what the output looks like

The entry point is gpt_vuln.py, run with uv run gpt_vuln.py or with python gpt_vuln.py inside an activated virtual environment.

python gpt_vuln.py --target scanme.nmap.org --attack nmap --ai openai

That is a nmap scan on the default profile 1, analysed by OpenAI. The profile is selectable, --list_profiles prints the table, and the other attacks take their own flag. DNS recon needs no profile, subdomain enumeration takes an optional --sub_list path, and PCAP analysis can write a JSON output with --output.

python gpt_vuln.py --target example.com --attack sub --sub_list path/to/list.txt

Several providers can run at once, in which case each analyses independently and one consolidated report is produced.

python gpt_vuln.py --target example.com --attack dns --ai openai,claude,gemini

And the summarizer can be chosen while still showing each model's own analysis.

python gpt_vuln.py --target example.com --attack dns --ai all --summarizer claude --show_individual

For people who would rather not remember flags, the --menu option opens a guided interface that prompts for the target, options and providers for each attack, listing the seven options: nmap scan, DNS recon, subdomain enum, GeoIP lookup, JWT analysis, PCAP analysis and hash cracker, with q to quit.

The hash cracking invocation takes the hash, a wordlist file, an algorithm such as md5 and a --parallel switch.

The limits of a model summarising someone else's scan

There are two honest limits, and the second one is a design issue rather than a bug.

The first is that the report cannot contain findings the underlying tools did not produce. nmap does the service and version detection, the DNS module does the records, the wordlist does the subdomain coverage, and the JWT and PCAP parsers do their own work. If a scanner misses a service or a misconfiguration, the model has nothing to reason about, and a fluent report can make a thin scan look thorough. The value of a structured report rises and falls with the quality of the raw output behind it.

The second is that the output is a model generated document, so it needs the same review as any generated text. There is no test suite in the tree to check that a finding in the report is actually justified, and the reporting is the part of the pipeline with no deterministic component.

The scope of the toolkit is also worth naming. It includes a hash cracking module with wordlist and brute-force modes, and a full-port SYN scan mode, so it can be used for things other than assessing your own infrastructure. Authorisation is not enforced by the software, and the README does not discuss it. If you are evaluating this for a team, the operational question is less about the model quality and more about who can run it and against what.

On the version question, the last push was on 2026-09-25 and the recent releases are 1.1.9, 1.1.8 and 1.1.7 from 2023, while pyproject.toml already declares version 2.0.0. So the branch has moved well past the last tag, which is what you would expect for a tool that tracks fast moving LLM APIs, and it means there is no released artefact to fall back on.

Editorial conclusion

Adopt GVA when you want a written assessment of scan output rather than raw tool output, and only for systems you are authorised to test, since the toolkit includes an nmap SYN scan mode and a hash cracking module. Do not adopt it as a replacement for a scanner, because it adds no detection of its own. Before running it, install nmap and tshark as the README requires, set only the provider keys you need in .env, and note that the last push was on 2026-09-25 while the latest tagged release is 1.1.9 from 2023, so the working version is the branch rather than a release.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. morpheuslord/GPT_Vuln-analyzer on GitHub
4. README
5. Releases