alienrecon 3.0.0__py3-none-any.whl

alienrecon/__init__.py

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

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/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",
+        ))

alienrecon/agent/brain.py

@@ -0,0 +1,317 @@
+"""Claude-powered brain for the AlienRecon instructor.
+
+All Claude API calls go through the AlienRecon API proxy.
+Users do not need their own Anthropic API key.
+"""
+
+import logging
+from typing import Optional
+
+from .. import api
+
+logger = logging.getLogger(__name__)
+
+
+def is_available() -> bool:
+    """Check if the user is logged in and can use the AI instructor."""
+    return api.is_logged_in()
+
+
+# ── Instructor tools ─────────────────────────────────────────────────────
+
+INSTRUCTOR_TOOLS = [
+    {
+        "name": "run_command",
+        "description": "Execute a shell command on the student's machine against the target. Use this when the student is ready to run a scan, exploit, or other tool. The output will be returned to you for discussion.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "The shell command to execute. Use {target} as placeholder for the target IP."
+                },
+                "explanation": {
+                    "type": "string",
+                    "description": "Brief explanation of what this command does (shown to student before execution)."
+                }
+            },
+            "required": ["command"]
+        }
+    },
+    {
+        "name": "show_hint",
+        "description": "Give the student a progressive hint. Use level 1 for nudges, level 2 for more direct guidance, level 3 for nearly the answer. Only use when the student is stuck.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "hint": {
+                    "type": "string",
+                    "description": "The hint text."
+                },
+                "level": {
+                    "type": "integer",
+                    "description": "Hint level: 1=nudge, 2=direct, 3=nearly answer",
+                    "enum": [1, 2, 3]
+                }
+            },
+            "required": ["hint", "level"]
+        }
+    },
+    {
+        "name": "check_answer",
+        "description": "Check if the student's answer to a platform question is correct. Use when the student provides an answer to a TryHackMe question.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "question_id": {
+                    "type": "string",
+                    "description": "The question ID from the YAML (e.g. t1-q1, q1)."
+                },
+                "student_answer": {
+                    "type": "string",
+                    "description": "The student's answer to check."
+                }
+            },
+            "required": ["question_id", "student_answer"]
+        }
+    },
+    {
+        "name": "advance_step",
+        "description": "Signal that the student has understood the current step and is ready to move on. Only call this when the student has demonstrated understanding of the key concept — not just after running a command.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "summary": {
+                    "type": "string",
+                    "description": "Brief summary of what was learned in this step."
+                }
+            },
+            "required": ["summary"]
+        }
+    },
+]
+
+# ── System prompt ────────────────────────────────────────────────────────
+
+INSTRUCTOR_SYSTEM = """You are AlienRecon, a cybersecurity mentor walking a student through a CTF room.
+
+You are having a CONVERSATION, not reading a script. You are the senior operator — the student is shadowing you.
+
+## How You Teach
+
+1. ORIENT: Explain what we need to accomplish, ask the student how they'd approach it
+2. GUIDE: Based on their response, guide them toward the right tool/approach
+3. EXECUTE: When ready, use the run_command tool to run the appropriate command
+4. ANALYZE: After seeing output, ask the student what they notice before explaining
+5. CONNECT: Help them understand why this matters and what it means for our next move
+6. ADVANCE: When they understand the key concept, use advance_step to move on
+
+## Rules
+
+- Keep responses to 2-4 sentences. This is a conversation, not a lecture.
+- Ask questions BEFORE showing commands. Make the student think.
+- After command output, ask what they notice before you explain.
+- Never give flags directly — let them find flags in output.
+- Only call advance_step when understanding is demonstrated, not just after running a command.
+- If the student is stuck, use show_hint with progressive levels before giving answers.
+- If they suggest a different approach, evaluate it honestly.
+- Match their energy — if they clearly know nmap, don't explain what port scanning is.
+
+## Context
+
+Room: {room_name} ({difficulty})
+Brief: {room_brief}
+Phase: {phase_name} — {phase_objective}
+
+## Your Cheat Sheet (DO NOT dump this to the student)
+
+{step_knowledge}"""
+
+
+SYSTEM_PROMPT = """\
+You are AlienRecon, a cybersecurity mentor walking a student through a CTF room.
+
+You are the senior operator. The student is shadowing you. You show your work, \
+explain your thinking, and answer questions. You are NOT a quiz master — you're \
+a mentor working alongside them.
+
+Style:
+- Direct, clear, no fluff — like a real hacker mentoring a junior
+- Explain the WHY, not just the WHAT
+- Keep responses to 2-4 sentences unless explaining a concept in depth
+- Reference real tools and real-world context
+- Celebrate when they notice something good
+
+Room brief: {room_brief}
+Phase: {phase_name} — {phase_objective}
+Step: {step_id}
+
+{step_context}
+
+Rules:
+- NEVER give flags directly — let them find flags in command output
+- If they suggest a different approach, evaluate it honestly
+- When analyzing output, focus on what matters for THIS room, not generic observations
+- If output looks wrong/empty, help troubleshoot specifically"""
+
+
+def _handle_api_error(result: dict) -> None:
+    """Log API errors for debugging."""
+    if result.get("error"):
+        logger.warning(f"API error ({result.get(status)}): {result.get(detail)}")
+
+
+def ask_claude(
+    student_input: str,
+    room_name: str = "",
+    room_brief: str = "",
+    room_slug: str = "",
+    phase_name: str = "",
+    phase_objective: str = "",
+    step_id: str = "",
+    step_instruction: str = "",
+    look_for: Optional[list[str]] = None,
+    key_takeaway: str = "",
+    if_fails: str = "",
+    skill_level: str = "beginner",
+    hints_used: int = 0,
+    conversation_history: Optional[list[dict]] = None,
+) -> Optional[str]:
+    """Legacy v1 interface — used for intro, debrief, non-step contexts."""
+    if not is_available():
+        return None
+
+    step_parts = []
+    if look_for:
+        step_parts.append("What to look for in output:\n" + "\n".join(f"- {item}" for item in look_for))
+    if key_takeaway:
+        step_parts.append(f"Key takeaway for student: {key_takeaway}")
+    if if_fails:
+        step_parts.append(f"If this step fails: {if_fails}")
+    step_context = "\n\n".join(step_parts)
+
+    system = SYSTEM_PROMPT.format(
+        room_brief=room_brief or f"Room: {room_name}" if room_name else "Free mode",
+        phase_name=phase_name or "N/A",
+        phase_objective=phase_objective or "N/A",
+        step_id=step_id or "N/A",
+        step_context=step_context or "No additional context for this step.",
+    )
+
+    messages = []
+    if conversation_history:
+        for entry in conversation_history[-20:]:
+            messages.append(entry)
+    messages.append({"role": "user", "content": student_input})
+
+    result = api.chat_sync(
+        messages=messages,
+        system=system,
+        room_slug=room_slug,
+    )
+
+    if result.get("error"):
+        _handle_api_error(result)
+        return None
+
+    # Parse Anthropic response format
+    try:
+        content = result.get("content", [])
+        for block in content:
+            if block.get("type") == "text":
+                return block.get("text")
+    except Exception as e:
+        logger.warning(f"Failed to parse response: {e}")
+
+    return None
+
+
+def teach_step(
+    message: str,
+    step_knowledge: dict,
+    phase_name: str = "",
+    phase_objective: str = "",
+    room_name: str = "",
+    room_brief: str = "",
+    room_slug: str = "",
+    difficulty: str = "",
+    conversation_history: Optional[list[dict]] = None,
+):
+    """Conversation-driven Claude call with tool_use.
+
+    Returns:
+        tuple: (text_response: str, tool_calls: list[dict])
+    """
+    if not is_available():
+        return None, []
+
+    # Build step knowledge text
+    parts = []
+    if step_knowledge.get("step_id"):
+        parts.append(f"Step: {step_knowledge[step_id]}")
+    if step_knowledge.get("narration"):
+        parts.append(f"What to teach: {step_knowledge[narration]}")
+    if step_knowledge.get("command"):
+        parts.append(f"Command to run: {step_knowledge[command]}")
+    if step_knowledge.get("expected_output"):
+        out = step_knowledge["expected_output"]
+        if len(out) > 1500:
+            out = out[:1500] + "..."
+        parts.append(f"Expected output:\n{out}")
+    if step_knowledge.get("explanation"):
+        parts.append(f"Technical explanation: {step_knowledge[explanation]}")
+    if step_knowledge.get("look_for"):
+        parts.append("Key observations:\n" + "\n".join(f"  - {i}" for i in step_knowledge["look_for"]))
+    if step_knowledge.get("key_takeaway"):
+        parts.append(f"Key takeaway: {step_knowledge[key_takeaway]}")
+    if step_knowledge.get("if_fails"):
+        parts.append(f"If command fails: {step_knowledge[if_fails]}")
+    if step_knowledge.get("conversation"):
+        parts.append(f"Discussion prompt: {step_knowledge[conversation]}")
+    if step_knowledge.get("questions"):
+        for q in step_knowledge["questions"]:
+            parts.append(f"Question: {q.get(text, )} (id: {q.get(id, )}, answer: {q.get(answer, N/A)})")
+
+    system = INSTRUCTOR_SYSTEM.format(
+        room_name=room_name or "Unknown",
+        difficulty=difficulty or "unknown",
+        room_brief=room_brief or "No brief.",
+        phase_name=phase_name or "N/A",
+        phase_objective=phase_objective or "N/A",
+        step_knowledge="\n".join(parts) if parts else "No additional context.",
+    )
+
+    messages = []
+    if conversation_history:
+        messages.extend(conversation_history[-30:])
+    messages.append({"role": "user", "content": message})
+
+    result = api.chat_sync(
+        messages=messages,
+        system=system,
+        tools=INSTRUCTOR_TOOLS,
+        room_slug=room_slug,
+    )
+
+    if result.get("error"):
+        _handle_api_error(result)
+        return None, []
+
+    # Parse Anthropic response format
+    text_parts = []
+    tool_calls = []
+    try:
+        content = result.get("content", [])
+        for block in content:
+            if block.get("type") == "text":
+                text_parts.append(block.get("text", ""))
+            elif block.get("type") == "tool_use":
+                tool_calls.append({
+                    "id": block.get("id"),
+                    "name": block.get("name"),
+                    "input": block.get("input", {}),
+                })
+    except Exception as e:
+        logger.warning(f"Failed to parse response: {e}")
+
+    return "\n".join(text_parts) if text_parts else None, tool_calls