alienrecon 3.0.0

AI-powered CTF instructor. Guided walkthroughs for TryHackMe rooms.

AlienRecon

Your guide through the box. Hack first. Understand after.

AlienRecon is a CLI that walks you through cybersecurity rooms step by step. You pick a room, it runs the tools, shows you the output, and teaches you what is happening along the way.

Install

pip install alienrecon

Requires Python 3.11+.

Setup

1. Get a Claude API key

Sign up at console.anthropic.com and grab an API key.

2. Set it

export ANTHROPIC_API_KEY=your-key-here

Add it to your shell profile (~/.bashrc, ~/.zshrc) so it persists.

3. Install pentesting tools

AlienRecon calls real tools on your machine. You need at least:

Tool	What it does
nmap	Port scanning
gobuster	Directory brute-forcing
nikto	Web vulnerability scanning
hydra	Password brute-forcing
curl	HTTP requests
openvpn	VPN connections (TryHackMe / HackTheBox)

Optional but useful: sqlmap, john, hashcat, ffuf, whatweb, wpscan, searchsploit, enum4linux-ng

On Kali or Parrot, most of these come pre-installed. On Debian/Ubuntu:

sudo apt install nmap nikto hydra curl openvpn

4. Check your setup

alienrecon doctor

Tells you what is installed and what is missing.

Usage

Start a room

alienrecon start -r lazyadmin

Loads the walkthrough for that room and teaches you through it. It runs commands, explains output, asks you questions, and moves on when you understand.

Let the curriculum pick

alienrecon start

Picks the next room based on your progress.

Resume where you left off

alienrecon start --resume

Free recon mode

alienrecon recon -t 10.10.10.10

No walkthrough. Just you and the assistant against a target.

Check your progress

alienrecon profile

Browse available rooms

alienrecon curriculum

Reset your profile

alienrecon reset

How it works

Each room has a YAML walkthrough with every phase, step, command, expected output, and answer. The instructor uses this as a cheat sheet — it knows what to do, but teaches you like a conversation, not a script.

The instructor:

• Runs real tools on real machines (nmap, gobuster, nikto, etc.)
• Explains what each command does and why
• Asks you questions before revealing answers
• Adapts to your responses
• Does not move on until you get it

Claude Sonnet under the hood, using tool_use for running commands, showing hints, checking answers, and advancing through steps.

Rooms

40 guided walkthroughs covering:

• Network fundamentals and enumeration
• Web application attacks
• Privilege escalation (Linux + Windows)
• Brute forcing and credential attacks
• SQL injection
• Active Directory basics
• Metasploit

List them with alienrecon curriculum or browse at alien37.com/rooms.

Project structure

src/alienrecon/
├── cli.py              # CLI entry point (Typer)
├── agent/
│   ├── instructor.py   # Guided walkthrough agent
│   ├── assistant.py    # Free recon mode
│   └── brain.py        # Claude API + tool definitions
├── curriculum/
│   ├── rooms.py        # Room database + YAML loader
│   └── profile.py      # Student progress tracking
├── display/
│   └── ui.py           # Rich terminal output
├── tools/
│   ├── checker.py      # Environment checker (doctor)
│   └── vpn.py          # VPN management
└── data/
    └── rooms/          # 40 YAML walkthroughs

Legal

Offensive security education tool. Use it on machines you have permission to test. TryHackMe, HackTheBox — you are good. Do not be stupid.

Links

• alien37.com
• GitHub