recon-setup 0.1.0__tar.gz

recon_setup-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    name: Build and Publish
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event_name == 'release' && github.event.release.tag_name || github.ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI (OIDC / Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

recon_setup-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.venv/
+dist/
+build/
+*.egg-info/
+
+# Environment
+.env
+
+# Test
+.pytest_cache
+
+# AI
+AGENTS.md
+ARCHITECTURE.md
+backlog/

recon_setup-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mojo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

recon_setup-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: recon-setup
+Version: 0.1.0
+Summary: Automate the setup and enumeration process for offensive security labs.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: impacket
+Requires-Dist: libtmux==0.53.1
+Requires-Dist: requests
+Requires-Dist: rich
+Requires-Dist: urllib3
+Requires-Dist: watchdog

recon_setup-0.1.0/README.md

@@ -0,0 +1,103 @@
+# recon-setup
+
+![Python](https://img.shields.io/badge/python-3.10+-blue.svg)
+![License](https://img.shields.io/badge/license-MIT-blue)
+
+**recon-setup** is a CLI tool that automates tmux session creation, nmap scanning, and port-driven enumeration for offensive security labs.
+
+## Features
+
+- [x] Structured tmux session with dedicated panes for OpenVPN, Ligolo, file serving, nmap, and task logging.
+- [x] Port-driven automation: watches nmap output in real time and dispatches enumeration tasks as ports are discovered.
+- [x] Credential-aware handlers: pass initial credentials to pre-populate authenticated scans across SMB, LDAP, Kerberos, MSSQL, and more.
+- [x] Credential watcher: monitors `creds.txt` for new entries and re-runs relevant handlers automatically.
+- [x] HTB CLI integration: spawn machines directly by name without manually retrieving an IP.
+
+## Requirements
+
+- tmux
+- `/opt/scripts/scan_machine.py` — nmap wrapper script that drives the scan and emits port results to stdout
+- Tools used by enumeration handlers: `nxc`, `bloodhound-ce-python`, `bloodhound-cli`, `bloodyAD`, `certipy`, `aliasr`, `kerbrute`, `hashcat`, `ffuf`, `feroxbuster`, `nuclei`, `wpscan`, `powerview`, `impacket`
+
+## Install
+
+```bash
+# Latest commit (GitHub)
+uv tool install git+https://github.com/Mojo8898/recon-setup
+pipx install git+https://github.com/Mojo8898/recon-setup
+
+# Local development
+git clone https://github.com/Mojo8898/recon-setup
+cd recon-setup
+uv sync
+```
+
+## Usage
+
+```
+usage: recon-setup [-h] [-v VPN_PATH] [-s SESSION_PATH] [-i IP]
+                   [--spawn SPAWN] [-n] [-a] [-u USERNAME] [-p PASSWORD] [-d]
+                   session_name
+
+Automate the setup and enumeration process for offensive security labs.
+
+options:
+  -h, --help            show this help message and exit
+
+Session Arguments:
+  Arguments related to session configuration
+
+  session_name          Name of the tmux session to be created
+  -v VPN_PATH, --vpn_path VPN_PATH
+                        Path of your VPN file
+  -s SESSION_PATH, --session_path SESSION_PATH
+                        Path to where the session will be created (default:
+                        /workspace/machines)
+  -i IP, --ip IP        IP address of the target machine
+
+HTB CLI Arguments:
+  Arguments related to HTB CLI functionality
+
+  --spawn SPAWN         Spawn the target machine using the HTB CLI instead of
+                        providing an IP (requires htb-cli)
+  -n, --new_release     Wait for the scheduled release time (7pm UTC) and
+                        spawn automatically
+
+Automation Arguments:
+  Arguments related to automated tasking
+
+  -a, --automate        Optional flag to enable automated tasks on the fly
+                        from nmap scan results
+  -u USERNAME, --username USERNAME
+                        Username to supply automated tasks (AD only)
+  -p PASSWORD, --password PASSWORD
+                        Password to supply automated tasks (AD only)
+  -d, --debug           Enable debug mode for automation
+```
+
+Standard session without automation:
+
+```bash
+recon-setup pirate -v ~/vpn/lab.ovpn -i 10.10.11.40
+```
+
+Session with full automation and initial credentials:
+
+```bash
+recon-setup pirate -v ~/vpn/lab.ovpn -i 10.10.11.40 -a -u pentest -p 'Password123!'
+```
+
+Spawn an HTB machine by name and automate:
+
+```bash
+recon-setup pirate -v ~/vpn/lab.ovpn --spawn pirate -a
+```
+
+## Contributing
+
+Contributions are welcome. Feel free to open an issue for bugs or feature requests.
+
+## Acknowledgments
+
+- Built on top of [libtmux](https://github.com/tmux-python/libtmux)
+- Enumeration handlers integrate [aliasr](https://github.com/Mojo8898/aliasr), [NetExec](https://github.com/Pennyw0rth/NetExec), and the [Impacket](https://github.com/fortra/impacket) suite

recon_setup-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "recon-setup"
+version = "0.1.0"
+description = "Automate the setup and enumeration process for offensive security labs."
+requires-python = ">=3.10"
+dependencies = [
+    "impacket",
+    "libtmux==0.53.1",
+    "requests",
+    "rich",
+    "urllib3",
+    "watchdog",
+]
+
+[project.scripts]
+recon-setup = "recon_setup.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

recon_setup-0.1.0/recon_setup/main.py

@@ -0,0 +1,185 @@
+#!/usr/bin/python3
+
+import argparse
+import ctypes
+import libtmux
+import os
+import signal
+import subprocess
+import sys
+from time import sleep
+
+from recon_setup.utils.context import Context
+from recon_setup.utils.htb_cli import spawn_machine
+from recon_setup.watchers.nmap_watcher import watch_nmap
+
+def set_death_signal(sig=signal.SIGHUP):
+    """Send SIGHUP to the forked process when its parent dies"""
+    libc = ctypes.CDLL("libc.so.6")
+    PR_SET_PDEATHSIG = 1
+    libc.prctl(PR_SET_PDEATHSIG, sig)
+
+def verify_connection(ip):
+    """Verify connection with target IP."""
+    reachable = False
+    while not reachable:
+        try:
+            subprocess.check_call(
+                ["ping", "-c1", "-W.5", ip],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL
+            )
+            reachable = True
+        except subprocess.CalledProcessError:
+            reachable = False
+        sleep(0.5)
+    sleep(1)
+
+def main():
+    # Initialize parser
+    parser = argparse.ArgumentParser(description="Automate the setup and enumeration process for offensive security labs.")
+
+    # Initialize session arguments
+    session_group = parser.add_argument_group("Session Arguments", "Arguments related to session configuration")
+    session_group.add_argument("session_name", type=str, help="Name of the tmux session to be created")
+    session_group.add_argument("-v", "--vpn_path", type=str, help="Path of your VPN file")
+    session_group.add_argument("-s", "--session_path", type=str, default="/workspace/machines", help="Path to where the session will be created (default: /workspace/machines)")
+    session_group.add_argument("-i", "--ip", type=str, help="IP address of the target machine")
+
+    # Initialize HTB CLI arguments
+    htb_cli_group = parser.add_argument_group("HTB CLI Arguments", "Arguments related to HTB CLI functionality")
+    htb_cli_group.add_argument("--spawn", type=str, help="Spawn the target machine via the HTB API instead of providing an IP (requires HTB_TOKEN env var)")
+    htb_cli_group.add_argument("-n", "--new_release", action="store_true", help="Wait until T-60s before the scheduled release time (7pm UTC) and spawn automatically via the HTB API")
+
+    # Initialize automation arguments
+    automation_group = parser.add_argument_group("Automation Arguments", "Arguments related to automated tasking")
+    automation_group.add_argument("-a", "--automate", action="store_true", help="Optional flag to enable automated tasks on the fly from nmap scan results")
+    automation_group.add_argument("-u", "--username", type=str, help="Username to supply automated tasks (AD only)")
+    automation_group.add_argument("-p", "--password", type=str, help="Password to supply automated tasks (AD only)")
+    automation_group.add_argument("-d", "--debug", action="store_true", help="Enable debug mode for automation")
+
+    # Initialize parser
+    args = parser.parse_args()
+
+    # Define local variables
+    session_name = args.session_name
+    vpn_path = os.path.abspath(args.vpn_path) if args.vpn_path is not None else None
+    session_path = args.session_path
+    ip = args.ip
+    spawn = args.spawn
+    new_release = args.new_release
+    automate = args.automate
+    user = args.username
+    password = args.password
+    debug = args.debug
+
+    # Define file paths
+    scan_script_file = "/opt/scripts/scan_machine.py"
+    target_dir = os.path.join(session_path, session_name)
+    nmap_dir = os.path.join(target_dir, "nmap")
+    log_dir = os.path.join(target_dir, "logs")
+    tmux_pipe_file = os.path.join(log_dir, "tmux_pipe.log")
+    log_file = os.path.join(log_dir, "task.log")
+    debug_file = os.path.join(log_dir, "debug.log")
+    users_file = os.path.join(target_dir, "valid_users.txt")
+    creds_file = os.path.join(target_dir, "creds.txt")
+
+    # Check for nmap wrapper script
+    if not os.path.isfile(scan_script_file):
+        print(f"Error: Required nmap wrapper script not found at {scan_script_file}", file=sys.stderr)
+        sys.exit(1)
+
+    # Initialize HTB machine if relevant arguments are included
+    if spawn:
+        ip = spawn_machine(spawn, new_release)
+        if not ip:
+            print("Error: HTB CLI failed to provide an IP")
+            sys.exit(1)
+    else:
+        ip = args.ip
+
+    # Initialize environment
+    os.makedirs(nmap_dir, exist_ok=True)
+    os.chdir(target_dir)
+
+    # Initialize tmux session
+    server = libtmux.Server()
+    session = server.new_session(
+        session_name=session_name,
+        window_name="services",
+        attach=False
+    )
+    initial_window = session.active_window
+    openvpn_pane = initial_window.active_pane
+    if os.path.isfile(vpn_path):
+        openvpn_pane.send_keys(f"sudo openvpn {vpn_path}")
+    ligolo_pane = openvpn_pane.split(direction=libtmux.pane.PaneDirection.Below)
+    ligolo_pane.send_keys("mkdir -p ligolo; cd ligolo; proxy -selfcert")
+    ip_pane = openvpn_pane.split(direction=libtmux.pane.PaneDirection.Right)
+    ip_pane.send_keys("command -v htb-gui &>/dev/null && htb-gui; ipa")
+    updog_pane = ligolo_pane.split(direction=libtmux.pane.PaneDirection.Right)
+    updog_pane.send_keys("updog -p 8000 -d ~/staging")
+    base_window = session.new_window(window_name=ip)
+
+    # Initialize panes
+    nmap_pane = base_window.active_pane
+    base_pane = base_window.split(direction=libtmux.pane.PaneDirection.Right)
+
+    # Fork process to attach to tmux session while executing additional tasks
+    pid = os.fork()
+    if pid == 0:
+        set_death_signal()
+
+        # Establish connection with VPN and initialize the base window
+        if os.path.isfile(vpn_path):
+            verify_connection(ip)
+            sleep(1)
+        session.select_window(2)
+        base_pane.select()
+
+        # Initialize automation if argument is provided
+        if automate:
+            os.makedirs(log_dir, exist_ok=True)
+            for file in [tmux_pipe_file, debug_file, users_file, creds_file]:
+                if os.path.isfile(file):
+                    os.remove(file)
+
+            # Clear log file while also making sure it exists
+            with open(log_file, 'w'):
+                pass
+
+            # Initialize stdio depending on debug flag
+            with open(os.devnull, "wb") as null:
+                if debug:
+                    with open(debug_file, "wb") as log:
+                        os.dup2(null.fileno(), 0)
+                        os.dup2(log.fileno(), 1)
+                        os.dup2(log.fileno(), 2)
+                else:
+                    os.dup2(null.fileno(), 0)
+                    os.dup2(null.fileno(), 1)
+                    os.dup2(null.fileno(), 2)
+
+            # Initialize context
+            context = Context(session, nmap_pane, nmap_dir, tmux_pipe_file, log_file, users_file, creds_file, ip)
+            if user and password:
+                context.add_initial_cred(user.lower(), password=password)
+
+            # Initialize task logging
+            log_pane = base_pane.split(size=20)
+            sleep(1)
+            log_pane.send_keys(f"clear && tail -n +0 -f {log_file}")
+
+            # Initialize nmap scanning and automation
+            os.remove(tmux_pipe_file)
+            nmap_pane.cmd("pipe-pane", f"cat >> {tmux_pipe_file}")
+            nmap_pane.send_keys(f"{scan_script_file} {ip}")
+            watch_nmap(context)
+        elif ip:
+            nmap_pane.send_keys(f"{scan_script_file} {ip}")
+        os._exit(0)
+    else:
+        os.execvp("tmux", ["tmux", "attach-session", "-t", session_name])
+
+if __name__ == "__main__":
+    main()

recon_setup-0.1.0/recon_setup/utils/active_directory.py

@@ -0,0 +1,93 @@
+import re
+import subprocess
+
+from recon_setup.utils.logger import write_log
+
+_NEGATIVE = re.compile(r"\[\-\]")
+
+
+def anonymous_bind(context):
+    cmd = ["nxc", "ldap", context.ip, "-u", "", "-p", ""]
+    try:
+        p = subprocess.run(cmd, capture_output=True, text=True, timeout=8, check=False)
+    except Exception as e:
+        write_log(context.log_file, f"NetExec ldap subprocess error: {e}", "ERROR")
+        return False
+    out = p.stdout or ""
+    return not _NEGATIVE.search(out)
+
+
+def enum_smb_shares(context):
+    def run_nxc(user, password):
+        cmd = f"nxc smb {context.ip} -u {user} "
+        if password:
+            cmd += f"-p '{password}' -k "
+        else:
+            cmd += f"-p '' "
+        cmd += f"--shares"
+        # write_log(context.log_file, f"Running: {cmd}", "INFO")
+        try:
+            p = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=8, check=False)
+            return p.stdout or ""
+        except Exception as e:
+            write_log(context.log_file, f"Subprocess exception: {e}", "ERROR")
+            return ""
+
+    def parse_shares(raw):
+        lines = [ln.rstrip("\n") for ln in raw.splitlines()]
+        hdr_idx = None
+        for i, ln in enumerate(lines):
+            if "Share" in ln and "Permissions" in ln and "Remark" in ln:
+                hdr_idx = i
+                break
+        if hdr_idx is None or hdr_idx + 2 >= len(lines):
+            return []
+
+        header = lines[hdr_idx]
+        try:
+            c_share = header.index("Share")
+            c_perm = header.index("Permissions")
+            c_remark = header.index("Remark")
+        except ValueError:
+            return []
+
+        shares = []
+        for ln in lines[hdr_idx + 2 :]:
+            if "SMB" not in ln or not ln.strip() or ln.strip().startswith("-----"):
+                continue
+            pad = ln + " " * max(0, c_remark + 1 - len(ln))
+            name = pad[c_share:c_perm].strip()
+            perms = pad[c_perm:c_remark].strip()
+            remark = pad[c_remark:].strip()
+            if not name or name.startswith("-----"):
+                continue
+            access = [p.strip() for p in perms.split(",") if p.strip()] if perms else []
+            shares.append({"name": name, "remark": remark, "access": access})
+
+        return shares
+
+    # 1) user/pass
+    if context.creds_exist():
+        user, password = context.get_initial_cred()
+        if user is not None:
+            out = run_nxc(user, password)
+            shares = parse_shares(out)
+            if shares:
+                return shares, "user/pass"
+            write_log(context.log_file, "Share enum with provided credentials failed; trying null session", "INFO")
+
+    # 2) null
+    out = run_nxc("''", "")
+    shares = parse_shares(out)
+    if shares:
+        write_log(context.log_file, "Null authentication is enabled for reading shares", "SUCCESS")
+        return shares, "null"
+
+    # 3) guest
+    out = run_nxc("a", "")
+    shares = parse_shares(out)
+    if shares:
+        write_log(context.log_file, "Guest authentication is enabled for reading shares", "SUCCESS")
+        return shares, "guest"
+
+    return None, None