A controlled, research-oriented workflow that integrates ShellGPT (
sgpt) with the OpenAI API to accelerate the offensive-security lifecycle — reconnaissance, OSINT, scanning, vulnerability assessment, and supervised exploitation — during authorized penetration tests. The goal is to turn natural-language intent into precise, auditable shell commands while keeping a human in the loop for every action.
ShellGPT converting plain-English intent ("scan all 65535 ports", "detect OS and services")
into validated nmap commands, with an explicit Execute / Describe / Abort gate before anything runs.
This project is for authorized penetration testing, cybersecurity education, and defensive research only. Every technique shown here must be used exclusively against systems you own or have explicit, written permission to test.
Unauthorized scanning, enumeration, brute-forcing, or exploitation of systems you do not own is illegal in virtually every jurisdiction and can lead to criminal charges and civil liability. AI-generated commands can be destructive — always review before executing, and never pipe AI output blindly into a shell. See DISCLAIMER.md before using anything in this repository.
- Overview
- Why Combine ShellGPT with Pentesting
- How It Works
- Tools & Technologies
- Workflow at a Glance
- Quick Start
- Walkthrough
- Custom Pentest Roles
- Helper Scripts
- Outcome & Impact
- Repository Structure
- Documentation
- References
- Author
- License
Penetration testing is front-loaded with repetitive, syntax-heavy command work: remembering
exact nmap flags, crafting hydra strings, chaining recon tools, and translating an objective
("enumerate subdomains", "find SUID binaries") into the right invocation. That friction costs
time and invites human error.
This project uses ShellGPT — a command-line productivity tool powered by the OpenAI API — as an AI command co-pilot for the offensive workflow:
- Describe intent in plain English;
sgptreturns the precise shell command. - Every command is gated behind an
[E]xecute / [D]escribe / [A]bortprompt — nothing runs without explicit human approval. - Generate recon, scanning, and exploitation commands across standard Kali tooling.
- Produce supporting code (e.g., a Python port scanner, a Bash ping sweep) on demand.
The result is a faster, repeatable, and auditable assessment workflow that keeps the operator in full control.
| Pain point in manual pentesting | How ShellGPT helps |
|---|---|
| Memorizing dozens of tool-specific flag combinations | Natural-language → correct, idiomatic command |
| Context-switching to docs / cheat sheets mid-engagement | On-demand --describe explains any command |
| Transcription errors in long command strings | AI produces the string; operator reviews once |
| Writing throwaway automation (sweeps, parsers) | --code emits ready-to-run Python/Bash |
| Onboarding junior testers to tooling | Commands come with an explain-before-run gate |
ShellGPT does not replace the tester's judgment — it removes the typing, not the thinking.
Natural-language intent
│
▼
┌─────────────┐ HTTPS ┌──────────────┐
│ sgpt CLI │ ───────────► │ OpenAI API │ (model: gpt-4o by default)
│ (ShellGPT) │ ◄─────────── │ │
└─────────────┘ command └──────────────┘
│
▼
[E]xecute / [D]escribe / [A]bort ◄── human-in-the-loop gate
│
▼
Local shell → nmap / amass / hydra / … on the authorized target
sgpt sends the prompt (plus a system role) to the OpenAI API, receives a single shell command,
and — in --shell mode — presents it for review. Only on Execute does it hand the command to
the local shell.
| Category | Tools |
|---|---|
| AI / LLM | ShellGPT (sgpt), OpenAI API (gpt-4o) |
| Platform | Kali Linux, Python 3.12, Bash |
| Recon / OSINT | Sublist3r, Amass, crt.sh, dig, nslookup |
| Scanning / Vuln | Nmap (+ NSE vuln scripts), Nikto, Gobuster, FFUF |
| Exploitation | searchsploit, Metasploit Framework, Hydra, Hashcat |
| Wireless | Airodump-ng, Aireplay-ng |
⚠️ All offensive tools above are to be used only against authorized, in-scope targets.
| Phase | Objective | Representative AI-generated command |
|---|---|---|
| 1. Setup | Integrate sgpt with the OpenAI API |
sgpt "Generate an Nmap command for scanning all ports" |
| 2. Recon / OSINT | Map the attack surface | amass enum -d example.com · dig AXFR @8.8.8.8 example.com |
| 3. Scanning | Find open ports & vulnerabilities | nmap -p- -sV -sC 192.168.1.1 · nmap --script=vuln <host> |
| 4. Web testing | Enumerate web attack surface | nikto -h example.com · gobuster dir -u <url> -w <wordlist> |
| 5. Exploitation | Validate findings (supervised) | searchsploit apache 2.4.49 · guided Metasploit setup |
| 6. Post-exploit | Privilege-escalation checks | find / -perm -4000 -type f 2>/dev/null |
# 1. Install ShellGPT
pip install shell-gpt # on Kali: add --break-system-packages
# 2. Provide your OpenAI API key (never hard-code it)
export OPENAI_API_KEY="sk-...your-key..."
# 3. Generate a command from natural language
sgpt "Generate an Nmap command for scanning all ports on a target"
# -> nmap -p- -sC -sV -T4 <target>
# 4. Generate AND review-before-running a shell command
sgpt --shell "Perform a full port scan on 192.168.1.1"
# -> nmap -p- -sV -sC 192.168.1.1
# [E]xecute, [D]escribe, [A]bort:A convenience installer is provided in scripts/setup.sh. Full details are in
docs/01-installation-setup.md.
ShellGPT installs as a Python package and authenticates to the OpenAI API via the
OPENAI_API_KEY environment variable. On Kali, --break-system-packages is required for the
system Python.
sgpt --help shows the full option surface — --shell / -s (generate & execute shell commands),
--describe-shell / -d, --code / -c, --chat, --repl, roles, model selection, and
temperature control:
Details: docs/01-installation-setup.md.
Natural-language prompts drive subdomain enumeration, DNS interrogation, and certificate OSINT.
In --code mode, sgpt can also emit purpose-built tooling (here, a Python TCP port scanner):
sgpt --shell "Use Amass to enumerate subdomains for example.com"
# -> amass enum -d example.com
sgpt --shell "Attempt a DNS zone transfer for example.com"
# -> dig AXFR @8.8.8.8 example.com
sgpt --code "Write a Python script for port scanning"
# -> a ready-to-run socket-based scannerDetails: docs/02-reconnaissance-osint.md.
sgpt streamlines Nmap (port, service, OS, and NSE vuln scans) and web scanners such as Nikto,
Gobuster, and FFUF. It can also generate quick host-discovery automation — e.g., a Bash ping
sweep across a /24:
sgpt --shell "Scan a target for vulnerabilities using Nmap"
# -> nmap --script=vuln 192.168.1.1
sgpt --shell "Write a Bash script to ping all hosts in the 192.168.1.0/24 subnet"
# -> for i in {1..254}; do ping -c 1 -W 1 192.168.1.$i & doneDetails: docs/03-scanning-vulnerability-assessment.md.
For the supervised exploitation phase, sgpt helps locate public exploits and scaffold
framework commands. Every exploit is reviewed and run only against authorized targets:
sgpt --shell "Find exploits for Apache 2.4.49"
# -> searchsploit apache 2.4.49
sgpt --shell "Find all SUID binaries on a Linux system"
# -> find / -perm -4000 -type f 2>/dev/null
⚠️ Brute-force and exploitation commands (Hydra, Metasploit, Hashcat) are included for completeness. Run them only in controlled, authorized environments. See docs/04-exploitation-post-exploitation.md.
The OpenAI API is pay-as-you-go. Command generation is text-only and inexpensive — a full session of recon/scan prompts in this project cost cents, not dollars:
API keys are provisioned from the OpenAI dashboard and must be kept secret — store them in an
environment variable or a .env file (see .env.example), never in source
control.
ShellGPT supports system roles that constrain and focus the model's output. This repo ships
three ready-to-use role definitions in config/roles/:
| Role | Purpose |
|---|---|
pentest-recon |
OSINT & enumeration commands only |
pentest-scanner |
Port/service/vuln scanning commands |
pentest-exploit |
Supervised exploitation scaffolding |
sgpt --role pentest-recon --shell "enumerate subdomains of example.com"See docs/05-shellgpt-roles-and-automation.md.
| Script | Description |
|---|---|
scripts/setup.sh |
Install ShellGPT + verify the OpenAI API key |
scripts/install-roles.sh |
Install the custom pentest roles into ~/.config/shell_gpt/roles |
scripts/recon.sh |
AI-assisted recon harness (subdomains + DNS + ports) |
scripts/helpers/port_scanner.py |
Standalone threaded TCP port scanner |
scripts/helpers/ping_sweep.sh |
/24 host-discovery ping sweep |
All scripts are authorization-gated and print a scope reminder before acting.
- Reduced manual effort — repetitive command crafting is offloaded to the AI co-pilot.
- Fewer syntax errors — commands are generated correctly and reviewed once, not retyped.
- Faster, repeatable assessments — recon → scan → exploit flows are reproducible via prompts and roles.
- Human-in-the-loop safety — the
[E]xecute / [D]escribe / [A]bortgate keeps every action deliberate. - Low cost — text-only API usage kept total spend to ~$0.02 for the full demonstration.
.
├── README.md # This file
├── DISCLAIMER.md # Legal & ethical notice (read first)
├── LICENSE # MIT License
├── CITATION.cff # How to cite this work
├── CONTRIBUTING.md # Contribution guidelines
├── CHANGELOG.md # Version history
├── requirements.txt # Python dependencies
├── .env.example # Template for the OpenAI API key
├── .gitignore
├── config/
│ └── roles/ # Custom ShellGPT system roles
│ ├── pentest-recon.json
│ ├── pentest-scanner.json
│ └── pentest-exploit.json
├── docs/
│ ├── 01-installation-setup.md # Install, API key, configuration
│ ├── 02-reconnaissance-osint.md # Subdomain, DNS, certificate OSINT
│ ├── 03-scanning-vulnerability-assessment.md
│ ├── 04-exploitation-post-exploitation.md
│ ├── 05-shellgpt-roles-and-automation.md
│ ├── methodology.md # End-to-end reproducible methodology
│ └── command-reference.md # Prompt → command cheat sheet
├── scripts/
│ ├── README.md
│ ├── setup.sh # Install ShellGPT + verify key
│ ├── install-roles.sh # Deploy custom roles
│ ├── recon.sh # AI-assisted recon harness
│ └── helpers/
│ ├── port_scanner.py # Threaded TCP port scanner
│ └── ping_sweep.sh # /24 ping sweep
├── examples/
│ └── sgpt-prompts.md # Curated prompt library by phase
└── assets/
└── images/ # Screenshots from the demonstration
- Methodology — the full, reproducible end-to-end workflow.
- Installation & Setup — install, authenticate, configure.
- Reconnaissance & OSINT
- Scanning & Vulnerability Assessment
- Exploitation & Post-Exploitation
- Roles & Automation
- Command Reference — prompt → command cheat sheet.
- Prompt Library
- ShellGPT (
sgpt) — TheR1D: https://github.com/TheR1D/shell_gpt - OpenAI API documentation: https://platform.openai.com/docs
- OpenAI API pricing: https://openai.com/api/pricing/
- Nmap reference guide: https://nmap.org/book/man.html
- OWASP Web Security Testing Guide: https://owasp.org/www-project-web-security-testing-guide/
- Exploit-DB / searchsploit: https://www.exploit-db.com/searchsploit
- Metasploit Framework: https://docs.metasploit.com/
Released under the MIT License — see LICENSE. The license covers the scripts and documentation in this repository. It does not authorize testing any system without permission. Use responsibly, legally, and only within an authorized scope — see DISCLAIMER.md.