Metadata-Version: 2.4
Name: alienrecon
Version: 3.0.0
Summary: AI-powered CTF instructor. Guided walkthroughs for TryHackMe rooms.
License: MIT
Keywords: ctf,hacking,security,instructor,pentesting,cybersecurity
Author: Russell J. Adams
Requires-Python: >=3.11,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: httpx (>=0.25.0)
Requires-Dist: python-dotenv (>=1.0.0,<1.1.0)
Requires-Dist: pyyaml (>=6.0.1,<6.1.0)
Requires-Dist: rich (>=13.7.0,<13.8.0)
Requires-Dist: typer[all] (>=0.16.0,<0.17.0)
Project-URL: Homepage, https://alien37.com
Project-URL: Repository, https://github.com/russelljadams/alienrecon
Description-Content-Type: text/markdown

# 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

```bash
pip install alienrecon
```

Requires Python 3.11+.

## Setup

### 1. Get a Claude API key

Sign up at [console.anthropic.com](https://console.anthropic.com) and grab an API key.

### 2. Set it

```bash
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:

```bash
sudo apt install nmap nikto hydra curl openvpn
```

### 4. Check your setup

```bash
alienrecon doctor
```

Tells you what is installed and what is missing.

## Usage

### Start a room

```bash
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

```bash
alienrecon start
```

Picks the next room based on your progress.

### Resume where you left off

```bash
alienrecon start --resume
```

### Free recon mode

```bash
alienrecon recon -t 10.10.10.10
```

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

### Check your progress

```bash
alienrecon profile
```

### Browse available rooms

```bash
alienrecon curriculum
```

### Reset your profile

```bash
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](https://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](https://alien37.com)
- [GitHub](https://github.com/russelljadams/alienrecon)

