alienrecon 3.0.0__tar.gz

alienrecon-3.0.0/PKG-INFO

@@ -0,0 +1,187 @@
+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)
+

alienrecon-3.0.0/README.md

@@ -0,0 +1,163 @@
+# 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)

alienrecon-3.0.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "alienrecon"
+version = "3.0.0"
+description = "AI-powered CTF instructor. Guided walkthroughs for TryHackMe rooms."
+authors = [{name = "Russell J. Adams"}]
+license = {text = "MIT"}
+readme = "README.md"
+keywords = ["ctf", "hacking", "security", "instructor", "pentesting", "cybersecurity"]
+requires-python = ">=3.11,<4.0"
+dependencies = [
+    "rich~=13.7.0",
+    "typer[all]~=0.16.0",
+    "pyyaml~=6.0.1",
+    "python-dotenv~=1.0.0",
+    "httpx>=0.25.0",
+]
+
+[project.urls]
+"Homepage" = "https://alien37.com"
+"Repository" = "https://github.com/russelljadams/alienrecon"
+
+[project.scripts]
+alienrecon = "alienrecon.cli:main"
+
+[tool.poetry.group.dev.dependencies]
+ruff = "^0.11.9"
+mypy = "^1.15.0"
+pytest = "^8.0.0"
+pytest-cov = "^5.0.0"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]
+ignore = ["E501", "UP007"]
+
+[tool.mypy]
+python_version = "3.11"
+check_untyped_defs = true
+ignore_missing_imports = true
+show_error_codes = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

alienrecon-3.0.0/src/alienrecon/__init__.py

@@ -0,0 +1 @@
+__version__ = "3.0.0"

alienrecon-3.0.0/src/alienrecon/__main__.py

@@ -0,0 +1,5 @@
+"""Main entry point for alienrecon when run as a module."""
+from alienrecon.cli import main
+
+if __name__ == "__main__":
+    main()

alienrecon-3.0.0/src/alienrecon/agent/assistant.py

@@ -0,0 +1,88 @@
+"""Free mode assistant — student picks target, agent assists."""
+
+import logging
+from typing import Optional
+
+from rich.console import Console
+from rich.panel import Panel
+
+from ..curriculum.profile import StudentProfile
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+class Assistant:
+    """Assistant for free-form reconnaissance."""
+
+    def __init__(self, profile: StudentProfile, dry_run: bool = False):
+        self.profile = profile
+        self.dry_run = dry_run
+
+    def start(self, target: str):
+        """Start a free-form recon session."""
+        from ..core.input_validator import InputValidator
+
+        # Validate target
+        try:
+            validated = InputValidator.validate_target(target)
+        except Exception as e:
+            console.print(f"[red]Invalid target: {e}[/red]")
+            return
+
+        console.print(Panel(
+            f"[green]Target:[/green] {validated}\n"
+            f"[dim]Free mode — you lead, I assist.[/dim]\n\n"
+            f"Type commands to run, or ask me questions.\n"
+            f"Type [cyan]help[/cyan] for options, [cyan]exit[/cyan] to quit.",
+            title="Free Recon",
+            border_style="cyan",
+        ))
+
+        # Interactive loop
+        while True:
+            try:
+                cmd = console.input("\n[green]  alienrecon> [/green]")
+            except (KeyboardInterrupt, EOFError):
+                console.print("\n[yellow]Session ended.[/yellow]")
+                break
+
+            cmd = cmd.strip()
+            if not cmd:
+                continue
+
+            if cmd.lower() in ("exit", "quit", "q"):
+                console.print("[yellow]Session ended.[/yellow]")
+                break
+
+            if cmd.lower() == "help":
+                self._show_help()
+                continue
+
+            # For now, basic command pass-through
+            # TODO: Add smart suggestions and explanations
+            if self.dry_run:
+                console.print(f"[dim][dry-run] Would execute: {cmd}[/dim]")
+            else:
+                import subprocess
+                try:
+                    result = subprocess.run(
+                        cmd, shell=True, capture_output=True, text=True, timeout=300
+                    )
+                    output = result.stdout + result.stderr
+                    if output.strip():
+                        console.print(Panel(output.strip()[:5000], title="Output", border_style="dim"))
+                except subprocess.TimeoutExpired:
+                    console.print("[red]Command timed out.[/red]")
+                except Exception as e:
+                    console.print(f"[red]Error: {e}[/red]")
+
+    def _show_help(self):
+        console.print(Panel(
+            "[cyan]help[/cyan]     — Show this help\n"
+            "[cyan]exit[/cyan]     — End session\n"
+            "[cyan]<command>[/cyan] — Run a shell command\n\n"
+            "[dim]Tip: Try nmap, gobuster, nikto, wpscan, etc.[/dim]",
+            title="Commands",
+            border_style="cyan",
+        ))