reconflow 0.2.2__py3-none-any.whl

reconflow/__init__.py

@@ -0,0 +1,3 @@
+"""reconflow package."""
+
+__version__ = "0.2.2"

reconflow/__main__.py

@@ -0,0 +1,6 @@
+"""reconflow - Command line execution module."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

reconflow/cli.py

@@ -0,0 +1,118 @@
+"""reconflow.cli - Command-line interface and subcommand routing."""
+
+import argparse
+import sys
+from . import __version__, scan
+
+
+def build_parser():
+    """Construct the main argument parser with subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="reconflow",
+        description="Recon pipeline for bug bounty hunters",
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        title="subcommands",
+        description="available operations",
+    )
+
+    # scan subcommand
+    p_scan = subparsers.add_parser(
+        "scan",
+        help="Run recon on a domain",
+        description="Discover subdomains, filter wildcard DNS, and probe live web services.",
+    )
+    p_scan.add_argument(
+        "domain",
+        help="Target domain (must be in scope!)",
+    )
+    p_scan.add_argument(
+        "-o",
+        "--output",
+        default="output",
+        help="Output folder (default: output)",
+    )
+    p_scan.add_argument(
+        "--threads",
+        type=int,
+        default=10,
+        help="Number of threads for probing (default: 10)",
+    )
+    p_scan.add_argument(
+        "--timeout",
+        type=int,
+        default=5,
+        help="Timeout in seconds for probing (default: 5)",
+    )
+    p_scan.add_argument(
+        "--keep-wildcard",
+        action="store_true",
+        help="Warn about wildcard DNS but don't filter wildcard results",
+    )
+    p_scan.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_report",
+        help="Also write structured results to report.json",
+    )
+    p_scan.add_argument(
+        "--screenshots",
+        action="store_true",
+        help="Capture screenshots of live hosts using gowitness",
+    )
+
+    # diff subcommand
+    p_diff = subparsers.add_parser(
+        "diff",
+        help="Compare the latest two scans for a domain",
+        description=(
+            "Compare the latest two scan snapshots to detect "
+            "newly discovered subdomains and host changes."
+        ),
+    )
+    p_diff.add_argument(
+        "domain",
+        help="Target domain to compare runs for",
+    )
+    p_diff.add_argument(
+        "-o",
+        "--output",
+        default="output",
+        help="Output folder (default: output)",
+    )
+    p_diff.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_report",
+        help="Output diff comparison as JSON",
+    )
+
+    return parser
+
+
+def main(args=None):
+    """Main entrypoint for CLI command dispatch."""
+    parser = build_parser()
+    parsed_args = parser.parse_args(args)
+
+    if parsed_args.command == "scan":
+        scan.run(parsed_args)
+    elif parsed_args.command == "diff":
+        from . import diff
+
+        diff.run(parsed_args)
+    else:
+        parser.print_help()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

reconflow/diff.py

@@ -0,0 +1,206 @@
+"""reconflow.diff - Differential change detection between scan runs."""
+
+import json
+import sys
+from pathlib import Path
+from urllib.parse import urlparse
+from . import history
+
+
+# Tags that flip between runs because of CDN/transport behavior, not app changes
+IGNORED_TECH = {"HTTP/2", "HTTP/3", "HSTS"}
+
+
+def _hostname(url):
+    return (urlparse(url).hostname or url).lower()
+
+
+def _by_host(hosts):
+    """Map hostname -> host record. If a host answers on both schemes, prefer https."""
+    result = {}
+    for h in hosts or []:
+        if not isinstance(h, dict) or "url" not in h:
+            continue
+        name = _hostname(h["url"])
+        current = result.get(name)
+        if current is None or (
+            h["url"].startswith("https://") and not current["url"].startswith("https://")
+        ):
+            result[name] = h
+    return result
+
+
+def _meaningful_tech(tech):
+    return {t for t in (tech or []) if t not in IGNORED_TECH}
+
+
+def compare(old, new):
+    """Compare two scan snapshots and return differences.
+
+    Hosts are matched by hostname, so a scheme flip (http <-> https) is not
+    reported as one host disappearing and another appearing.
+    """
+    old_hosts = _by_host(old.get("hosts"))
+    new_hosts = _by_host(new.get("hosts"))
+
+    changed = {}
+    for name in old_hosts.keys() & new_hosts.keys():
+        o, n = old_hosts[name], new_hosts[name]
+        diffs = {}
+        if o.get("status_code") != n.get("status_code"):
+            diffs["status_code"] = (o.get("status_code"), n.get("status_code"))
+        if o.get("title") != n.get("title"):
+            diffs["title"] = (o.get("title"), n.get("title"))
+        if _meaningful_tech(o.get("technologies")) != _meaningful_tech(n.get("technologies")):
+            diffs["technologies"] = (o.get("technologies") or [], n.get("technologies") or [])
+        if diffs:
+            changed[n["url"]] = diffs
+
+    old_subs = set(old.get("subdomains") or [])
+    new_subs = set(new.get("subdomains") or [])
+    return {
+        "new_subdomains": sorted(new_subs - old_subs),
+        "removed_subdomains": sorted(old_subs - new_subs),
+        "new_live": sorted(new_hosts[h]["url"] for h in new_hosts.keys() - old_hosts.keys()),
+        "gone_live": sorted(old_hosts[h]["url"] for h in old_hosts.keys() - new_hosts.keys()),
+        "changed": changed,
+    }
+
+
+def format_diff(diff_result, old_id, new_id, new_data=None):
+    """Render a human-readable comparison summary between two runs."""
+    lines = [
+        f"[*] Recon diff: {old_id} -> {new_id}",
+        "=" * 60,
+    ]
+
+    new_subs = diff_result.get("new_subdomains", [])
+    new_live = diff_result.get("new_live", [])
+    changed = diff_result.get("changed", {})
+    removed_subs = diff_result.get("removed_subdomains", [])
+    gone_live = diff_result.get("gone_live", [])
+
+    has_changes = any([new_subs, new_live, changed, removed_subs, gone_live])
+    if not has_changes:
+        lines.append("[+] No changes detected between scans.")
+        return "\n".join(lines)
+
+    if new_subs:
+        lines.append(f"\n[+] NEW SUBDOMAINS ({len(new_subs)}):")
+        for s in new_subs:
+            lines.append(f"    + {s}")
+
+    if new_live:
+        lines.append(f"\n[+] NEWLY LIVE HOSTS ({len(new_live)}):")
+        hosts_map = {}
+        if new_data and isinstance(new_data, dict):
+            hosts_map = {
+                h["url"]: h
+                for h in (new_data.get("hosts") or [])
+                if isinstance(h, dict) and "url" in h
+            }
+        for h in new_live:
+            meta = hosts_map.get(h)
+            if meta:
+                code = meta.get("status_code")
+                title = meta.get("title")
+                tech = meta.get("technologies") or []
+                parts = []
+                if code:
+                    parts.append(f"[{code}]")
+                if title:
+                    parts.append(f"[{title}]")
+                if tech:
+                    tech_str = ", ".join(tech) if isinstance(tech, list) else str(tech)
+                    parts.append(f"[{tech_str}]")
+                detail = (" " + " ".join(parts)) if parts else ""
+                lines.append(f"    + {h}{detail}")
+            else:
+                lines.append(f"    + {h}")
+
+    if changed:
+        lines.append(f"\n[*] CHANGED HOSTS ({len(changed)}):")
+        for url, diffs in changed.items():
+            lines.append(f"    ~ {url}")
+            if "status_code" in diffs:
+                o, n = diffs["status_code"]
+                lines.append(f"        status: {o} -> {n}")
+            if "title" in diffs:
+                o, n = diffs["title"]
+                lines.append(f"        title: '{o}' -> '{n}'")
+            if "technologies" in diffs:
+                o, n = diffs["technologies"]
+                lines.append(f"        tech: {o} -> {n}")
+
+    if removed_subs:
+        lines.append(f"\n[-] Removed subdomains ({len(removed_subs)}) [informational]:")
+        for s in removed_subs:
+            lines.append(f"    - {s}")
+
+    if gone_live:
+        lines.append(f"\n[-] Inactive hosts ({len(gone_live)}) [informational]:")
+        for h in gone_live:
+            lines.append(f"    - {h}")
+
+    lines.append("\n" + "=" * 60)
+    return "\n".join(lines)
+
+
+def run(args):
+    """Execute diff comparison for a domain between its latest two scan runs."""
+    domain = getattr(args, "domain", None)
+    if not domain:
+        sys.exit("Error: Target domain is required.")
+
+    output_dir = getattr(args, "output", "output") or "output"
+    json_output = bool(getattr(args, "json_report", False) or getattr(args, "json", False))
+    out_dir = Path(output_dir) / domain
+
+    runs = history.list_runs(out_dir)
+    if len(runs) < 2:
+        if not runs:
+            msg = f"[!] No scan history found for {domain} in {out_dir}. Run a scan first."
+        else:
+            msg = (
+                f"[!] Only 1 scan run found for {domain} ({runs[0].name}). "
+                "Need at least 2 runs to compare."
+            )
+        if json_output:
+            print(json.dumps({"domain": domain, "error": msg, "runs_count": len(runs)}))
+        else:
+            print(msg)
+        sys.exit(0)
+
+    old_run = runs[-2]
+    new_run = runs[-1]
+    old_data = history.load_snapshot(old_run)
+    new_data = history.load_snapshot(new_run)
+
+    diff_result = compare(old_data, new_data)
+    has_changes = any([
+        diff_result["new_subdomains"],
+        diff_result["new_live"],
+        diff_result["changed"],
+        diff_result["removed_subdomains"],
+        diff_result["gone_live"],
+    ])
+
+    if json_output:
+        payload = {
+            "domain": domain,
+            "old_run": old_data.get("run_id", old_run.name),
+            "new_run": new_data.get("run_id", new_run.name),
+            "has_changes": has_changes,
+            **diff_result,
+        }
+        print(json.dumps(payload, indent=2))
+    else:
+        output_text = format_diff(
+            diff_result,
+            old_data.get("run_id", old_run.name),
+            new_data.get("run_id", new_run.name),
+            new_data=new_data,
+        )
+        print(output_text)
+
+    sys.exit(1 if has_changes else 0)

reconflow/history.py

@@ -0,0 +1,46 @@
+"""reconflow.history - Snapshot tracking and scan history management."""
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+
+def save_snapshot(out_dir: Path, subs, hosts):
+    """Save scan results as a timestamped snapshot under out_dir/runs/<run_id>/."""
+    base_id = datetime.now().strftime("%Y-%m-%d_%H%M%S")
+    run_id = base_id
+    runs_dir = out_dir / "runs"
+    runs_dir.mkdir(parents=True, exist_ok=True)
+
+    counter = 1
+    while (runs_dir / run_id).exists():
+        run_id = f"{base_id}_{counter}"
+        counter += 1
+
+    run_dir = runs_dir / run_id
+    run_dir.mkdir(parents=True, exist_ok=True)
+    data = {
+        "run_id": run_id,
+        "timestamp": datetime.now().isoformat(),
+        "subdomains": sorted(subs),
+        "hosts": hosts or [],
+    }
+    (run_dir / "snapshot.json").write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    return run_id
+
+
+def list_runs(out_dir: Path):
+    """Return a sorted list of run directories containing snapshot.json."""
+    runs_dir = out_dir / "runs"
+    if not runs_dir.exists() or not runs_dir.is_dir():
+        return []
+    valid_runs = [p for p in runs_dir.iterdir() if p.is_dir() and (p / "snapshot.json").exists()]
+    return sorted(valid_runs, key=lambda p: p.name)
+
+
+def load_snapshot(run_dir: Path):
+    """Load and parse snapshot.json from the specified run directory."""
+    snapshot_file = run_dir / "snapshot.json"
+    if not snapshot_file.exists():
+        raise FileNotFoundError(f"Snapshot file not found: {snapshot_file}")
+    return json.loads(snapshot_file.read_text(encoding="utf-8"))

reconflow/scan.py

@@ -0,0 +1,448 @@
+"""reconflow.scan - subdomain discovery and live host probing pipeline."""
+
+import argparse
+import json
+import random
+import shutil
+import socket
+import string
+import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime
+from pathlib import Path
+
+RESOLVE_THREADS = 50
+
+
+TOOL_DOWNLOAD_URLS = {
+    "subfinder": "https://github.com/projectdiscovery/subfinder/releases",
+    "httpx": "https://github.com/projectdiscovery/httpx/releases (ProjectDiscovery Go binary)",
+    "gowitness": "https://github.com/sensepost/gowitness/releases",
+}
+
+
+def run_cmd(cmd):
+    """Run an external command and return the completed process."""
+    return subprocess.run(
+        cmd,
+        stdin=subprocess.DEVNULL,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+
+# Backwards compatibility alias
+run_subprocess = run_cmd
+
+
+def resolve_httpx_binary():
+    """Find and verify ProjectDiscovery httpx binary (checking httpx-toolkit then httpx)."""
+    for candidate in ["httpx-toolkit", "httpx"]:
+        if shutil.which(candidate) is None:
+            continue
+        try:
+            res = run_cmd([candidate, "-version"])
+            out = (res.stdout + " " + res.stderr).lower()
+            if "projectdiscovery" in out:
+                return candidate
+            if candidate == "httpx-toolkit":
+                return candidate
+        except Exception:
+            pass
+
+    if shutil.which("httpx"):
+        try:
+            res = run_cmd(["httpx", "-h"])
+            out = (res.stdout + " " + res.stderr).lower()
+            if "projectdiscovery" in out or "-status-code" in out:
+                return "httpx"
+        except Exception:
+            pass
+        return "httpx"
+    return None
+
+
+def check_tools(tools):
+    """Check that required external binaries are available in PATH."""
+    missing = []
+    for t in tools:
+        if t == "httpx":
+            if not resolve_httpx_binary():
+                missing.append("httpx")
+        elif shutil.which(t) is None:
+            missing.append(t)
+
+    if missing:
+        lines = [
+            f"[!] Missing required tools: {', '.join(missing)}",
+            "",
+            "Installation links:",
+        ]
+        for t in missing:
+            url = TOOL_DOWNLOAD_URLS.get(t, "See README for details")
+            lines.append(f"  - {t}: {url}")
+        lines.append("")
+        lines.append(
+            "Note: 'httpx' must be ProjectDiscovery's binary "
+            "(https://github.com/projectdiscovery/httpx),"
+        )
+        lines.append("      not the Python 'httpx' library from PyPI.")
+        sys.exit("\n".join(lines))
+
+
+def resolve(host):
+    """Return the set of IP addresses a hostname resolves to (empty set if none)."""
+    try:
+        return {info[4][0] for info in socket.getaddrinfo(host, None)}
+    except (socket.gaierror, UnicodeError, OSError):
+        return set()
+
+
+def detect_wildcard(domain, min_samples=5, max_samples=20, stable_rounds=3, resolve_fn=None):
+    """Resolve random nonexistent names to detect wildcard DNS and rotating IP pools.
+
+    Returns the set of wildcard IPs (empty set means no wildcard detected).
+    If a domain uses wildcard DNS with round-robin or rotating pools, continues
+    sampling until the IP set stabilizes or max_samples is reached.
+    """
+    _resolve = resolve_fn or resolve
+    first_label = "".join(random.choices(string.ascii_lowercase + string.digits, k=14))
+    first_ips = _resolve(f"{first_label}.{domain}")
+    if not first_ips:
+        return set()
+
+    ips = set(first_ips)
+    consecutive_stable = 0
+
+    for i in range(1, max_samples):
+        label = "".join(random.choices(string.ascii_lowercase + string.digits, k=14))
+        resolved_ips = _resolve(f"{label}.{domain}")
+        new_ips = resolved_ips - ips
+        if new_ips:
+            ips |= new_ips
+            consecutive_stable = 0
+        else:
+            consecutive_stable += 1
+            if i >= min_samples and consecutive_stable >= stable_rounds:
+                break
+
+    return ips
+
+
+def filter_wildcard(subs, wildcard_ips, resolve_fn=None):
+    """Drop subdomains whose IPs all fall inside the wildcard IP set."""
+    _resolve = resolve_fn or resolve
+    with ThreadPoolExecutor(max_workers=RESOLVE_THREADS) as pool:
+        resolved = list(pool.map(_resolve, subs))
+    kept = [s for s, ips in zip(subs, resolved) if ips and not ips <= wildcard_ips]
+    return kept
+
+
+def find_subdomains(domain, out_file):
+    """Discover subdomains using subfinder and write to out_file."""
+    print(f"[*] Finding subdomains for {domain}...")
+    result = run_cmd(["subfinder", "-d", domain, "-silent"])
+    subs = set(result.stdout.split())
+    subs.add(domain.strip().lower())
+    subs_sorted = sorted(subs)
+    out_file.write_text("\n".join(subs_sorted) + "\n", encoding="utf-8")
+    print(f"[+] Found {len(subs_sorted)} subdomains")
+    return subs_sorted
+
+
+def probe_hosts(
+    subs_file,
+    out_file,
+    threads=None,
+    timeout=None,
+    json_report=False,
+    httpx_bin=None,
+):
+    """Probe subdomains for live HTTP/HTTPS services using httpx."""
+    bin_name = httpx_bin or resolve_httpx_binary() or "httpx"
+    print("[*] Probing for live hosts (this can take a while on big targets)...")
+    cmd = [
+        bin_name,
+        "-l",
+        str(subs_file),
+        "-silent",
+        "-status-code",
+        "-title",
+        "-tech-detect",
+    ]
+    if json_report:
+        cmd.append("-json")
+    if threads is not None:
+        cmd.extend(["-threads", str(threads)])
+    if timeout is not None:
+        cmd.extend(["-timeout", str(int(timeout))])
+
+    lines = []
+    hosts_data = []
+    error_lines = []
+    with subprocess.Popen(
+        cmd,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    ) as proc:
+        for line in proc.stdout:
+            stripped = line.strip()
+            if not stripped:
+                continue
+            if json_report:
+                try:
+                    data = json.loads(stripped)
+                    url = data.get("url") or ""
+                    code = data.get("status_code", data.get("status-code", 0))
+                    title = data.get("title", "")
+                    tech = data.get("tech") or data.get("technologies") or []
+                    hosts_data.append({
+                        "url": url,
+                        "status_code": code,
+                        "title": title,
+                        "technologies": tech,
+                    })
+                    display = f"{url} [{code}]"
+                    if title:
+                        display += f" [{title}]"
+                    if tech:
+                        tech_str = ", ".join(tech) if isinstance(tech, list) else tech
+                        display += f" [{tech_str}]"
+                    lines.append(display)
+                    print(f"[*] [{len(lines)} alive] {display}")
+                except json.JSONDecodeError:
+                    error_lines.append(stripped)
+            else:
+                if stripped.startswith("http://") or stripped.startswith("https://"):
+                    lines.append(stripped)
+                    print(f"[*] [{len(lines)} alive] {stripped}")
+                else:
+                    error_lines.append(stripped)
+        proc.wait()
+
+    if proc.returncode != 0:
+        if error_lines:
+            err_msg = "\n".join(error_lines)
+            print(f"[!] httpx probing error (exit code {proc.returncode}):\n{err_msg}")
+        elif not lines:
+            print(f"[!] httpx probing failed (exit code {proc.returncode})")
+
+    out_file.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
+    print(f"[+] Probing complete: {len(lines)} hosts are alive")
+    return lines, (hosts_data if json_report else None)
+
+
+def capture_screenshots(live_hosts, screenshots_dir):
+    """Capture screenshots of live hosts using gowitness."""
+    screenshots_dir.mkdir(parents=True, exist_ok=True)
+    urls = [line.split()[0] for line in live_hosts if line.strip()]
+    if not urls:
+        return []
+    print("[*] Capturing screenshots of live hosts with gowitness...")
+    urls_file = screenshots_dir / ".targets.txt"
+    urls_file.write_text("\n".join(urls) + "\n", encoding="utf-8")
+    cmd = [
+        "gowitness",
+        "scan",
+        "file",
+        "-f",
+        str(urls_file),
+        "--screenshot-path",
+        str(screenshots_dir),
+    ]
+    run_cmd(cmd)
+    try:
+        urls_file.unlink(missing_ok=True)
+    except OSError:
+        pass
+    images = sorted(p.name for p in screenshots_dir.glob("*.png"))
+    print(f"[+] Captured {len(images)} screenshots in {screenshots_dir}")
+    return images
+
+
+def write_report(
+    domain,
+    subs,
+    live,
+    out_dir,
+    wildcard_ips=None,
+    dropped=0,
+    hosts_data=None,
+    screenshots=None,
+):
+    """Write markdown and optional JSON reports to out_dir."""
+    report = out_dir / "report.md"
+    warning = ""
+    if wildcard_ips:
+        warning = (
+            f"> **Wildcard DNS detected** (resolves to {', '.join(sorted(wildcard_ips))}). "
+            f"{dropped} subdomains that only pointed there were filtered out.\n\n"
+        )
+    screenshot_section = ""
+    if screenshots:
+        screenshot_section = (
+            f"## Screenshots\n\nCaptured {len(screenshots)} screenshot(s) in `screenshots/`.\n\n"
+        )
+    report.write_text(
+        f"# reconflow report: {domain}\n\n"
+        f"Generated: {datetime.now():%Y-%m-%d %H:%M}\n\n"
+        f"{warning}"
+        f"- Subdomains found: {len(subs)}\n"
+        f"- Live hosts: {len(live)}\n\n"
+        f"## Live hosts\n\n```\n" + "\n".join(live) + "\n```\n\n"
+        f"{screenshot_section}",
+        encoding="utf-8",
+    )
+    print(f"[+] Report saved to {report}")
+
+    if hosts_data is not None:
+        json_report_path = out_dir / "report.json"
+        report_dict = {
+            "domain": domain,
+            "generated": datetime.now().isoformat(),
+            "subdomains_count": len(subs),
+            "live_count": len(live),
+            "wildcard_detected": bool(wildcard_ips),
+            "wildcard_ips": sorted(wildcard_ips) if wildcard_ips else [],
+            "wildcard_filtered_count": dropped,
+            "screenshots_count": len(screenshots) if screenshots else 0,
+            "live_hosts": hosts_data,
+        }
+        json_report_path.write_text(json.dumps(report_dict, indent=2) + "\n", encoding="utf-8")
+        print(f"[+] JSON report saved to {json_report_path}")
+
+
+def run(args):
+    """Run the core recon pipeline using provided arguments namespace."""
+    domain = getattr(args, "domain", None)
+    if not domain:
+        sys.exit("Error: Target domain is required.")
+
+    output_dir = getattr(args, "output", "output") or "output"
+    threads = getattr(args, "threads", None)
+    timeout = getattr(args, "timeout", None)
+    keep_wildcard = getattr(args, "keep_wildcard", False)
+    json_report = bool(getattr(args, "json_report", False) or getattr(args, "json", False))
+    screenshots_enabled = getattr(args, "screenshots", False)
+
+    required_tools = ["subfinder", "httpx"]
+    if screenshots_enabled:
+        required_tools.append("gowitness")
+    check_tools(required_tools)
+
+    out_dir = Path(output_dir) / domain
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        subs = find_subdomains(domain, out_dir / "subdomains.txt")
+
+        wildcard_ips = detect_wildcard(domain)
+        dropped = 0
+        if wildcard_ips:
+            ips_str = ", ".join(sorted(wildcard_ips))
+            print(f"[!] Wildcard DNS detected: random names resolve to {ips_str}")
+            if keep_wildcard:
+                print("[!] --keep-wildcard set, results will not be filtered")
+            else:
+                kept = filter_wildcard(subs, wildcard_ips)
+                dropped = len(subs) - len(kept)
+                print(f"[*] Filtered out {dropped} wildcard-only subdomains, {len(kept)} remain")
+                subs = kept
+                (out_dir / "subdomains.txt").write_text(
+                    "\n".join(subs) + ("\n" if subs else ""), encoding="utf-8"
+                )
+
+        screenshots = []
+        if not subs:
+            print("[!] No subdomains left to probe.")
+            live = []
+            hosts_data = []
+        else:
+            httpx_bin = resolve_httpx_binary() or "httpx"
+            live, hosts_data = probe_hosts(
+                out_dir / "subdomains.txt",
+                out_dir / "live.txt",
+                threads=threads,
+                timeout=timeout,
+                json_report=True,
+                httpx_bin=httpx_bin,
+            )
+            if screenshots_enabled and live:
+                screenshots = capture_screenshots(live, out_dir / "screenshots")
+
+        write_report(
+            domain,
+            subs,
+            live,
+            out_dir,
+            wildcard_ips=wildcard_ips,
+            dropped=dropped,
+            hosts_data=(hosts_data if json_report else None),
+            screenshots=screenshots,
+        )
+
+        from . import history
+
+        run_id = history.save_snapshot(out_dir, subs, hosts_data or [])
+        print(f"[+] Saved scan snapshot ({run_id})")
+
+        return {
+            "domain": domain,
+            "run_id": run_id,
+            "subdomains": subs,
+            "live": live,
+            "hosts": hosts_data or [],
+            "output_dir": str(out_dir),
+        }
+    except KeyboardInterrupt:
+        sys.exit(f"\n[!] Interrupted. Partial results (if any) are in {out_dir}")
+
+
+def main():
+    """Standalone entry point for scan module."""
+    parser = argparse.ArgumentParser(
+        description="reconflow: subdomain discovery + live host probing in one command"
+    )
+    parser.add_argument("-d", "--domain", required=True, help="target domain (must be in scope!)")
+    parser.add_argument("-o", "--output", default="output", help="output folder (default: output)")
+    parser.add_argument(
+        "--keep-wildcard",
+        action="store_true",
+        help="warn about wildcard DNS but don't filter wildcard results",
+    )
+    parser.add_argument(
+        "--threads",
+        type=int,
+        default=None,
+        help="number of threads for httpx probing (default: httpx default)",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=5,
+        help="timeout in seconds for httpx probing (default: 5)",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        dest="json_report",
+        help="also write results to report.json",
+    )
+    parser.add_argument(
+        "--screenshots",
+        action="store_true",
+        help="capture screenshots of live hosts using gowitness",
+    )
+    args = parser.parse_args()
+    run(args)
+
+
+if __name__ == "__main__":
+    main()

reconflow-0.2.2.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: reconflow
+Version: 0.2.2
+Summary: Recon pipeline for bug bounty hunters with differential change tracking
+Author: Nithishvelan M
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ErenYeager1836/reconflow
+Project-URL: Repository, https://github.com/ErenYeager1836/reconflow
+Project-URL: Issues, https://github.com/ErenYeager1836/reconflow/issues
+Keywords: bugbounty,recon,reconnaissance,subdomain,subfinder,httpx,differential,security,infosec
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Classifier: Intended Audience :: Information Technology
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# reconflow
+
+Recon for bug bounty hunters that tells you **what changed** since your last scan.
+
+`reconflow` chains [subfinder](https://github.com/projectdiscovery/subfinder) and [httpx](https://github.com/projectdiscovery/httpx) into one command, filters out wildcard DNS noise, saves a snapshot of every run, and lets you `diff` any two runs to see new subdomains, newly live hosts, and changed responses.
+
+> **Use responsibly.** Only scan domains you own or that are explicitly in scope for a bug bounty / pentest program you are authorized to test.
+
+## Features
+
+- **`scan`**: finds subdomains, drops wildcard DNS false positives (including rotating IP pools), probes live hosts for status code, title and technologies, and writes a Markdown report
+- **`diff`**: compares your two most recent scans of a domain and highlights what's new
+- **Scan history**: every scan saves a structured snapshot, so nothing is overwritten
+- **Cron-friendly**: `diff` exits `1` when something changed and `0` when nothing did
+- No Python dependencies beyond the standard library
+
+## Requirements
+
+- Python 3.8+
+- [`subfinder`](https://github.com/projectdiscovery/subfinder/releases) and [`httpx`](https://github.com/projectdiscovery/httpx/releases) (ProjectDiscovery's Go versions) on your `PATH`
+- [`gowitness`](https://github.com/sensepost/gowitness/releases) (optional, only for `--screenshots`)
+
+> **Note:** `httpx` must be ProjectDiscovery's tool, not the Python `httpx` library. On Kali/Debian/Ubuntu it is often packaged as `httpx-toolkit`. reconflow checks for both names and verifies the binary.
+
+Check your tools:
+
+```
+subfinder -version
+httpx -version
+```
+
+## Install
+
+From PyPI:
+
+```
+pip install reconflow
+```
+
+From source:
+
+```
+git clone https://github.com/ErenYeager1836/reconflow.git
+cd reconflow
+pip install -e .
+```
+
+## Usage
+
+```
+reconflow scan example.com
+reconflow diff example.com
+```
+
+You can also run it as a module: `python -m reconflow scan example.com`
+
+### `scan`
+
+| Option | Description |
+| --- | --- |
+| `domain` | Target domain (required, must be in scope) |
+| `-o`, `--output` | Output folder (default: `output`) |
+| `--threads` | Number of threads for probing (default: 10) |
+| `--timeout` | Timeout in seconds for probing (default: 5) |
+| `--keep-wildcard` | Warn about wildcard DNS but don't filter wildcard results |
+| `--json` | Also write structured results to `report.json` |
+| `--screenshots` | Capture screenshots of live hosts (requires gowitness) |
+
+### `diff`
+
+| Option | Description |
+| --- | --- |
+| `domain` | Target domain to compare runs for (required) |
+| `-o`, `--output` | Output folder (default: `output`) |
+| `--json` | Print the comparison as JSON |
+
+`diff` needs at least two saved scans of the same domain. Run `scan` twice first.
+
+## Track changes with `diff`
+
+Most recon tools tell you what exists. reconflow also tells you what changed. New subdomains and newly live hosts are often the least-tested parts of a target.
+
+Example output (illustrative):
+
+```
+[*] Recon diff: 2026-10-18_185218 -> 2026-10-18_190412
+============================================================
+[+] NEW SUBDOMAINS (2):
+    + beta.example.com
+    + staging-api.example.com
+[+] NEWLY LIVE HOSTS (1):
+    + https://beta.example.com [200] [Beta Portal] [Nginx, React]
+[*] CHANGED HOSTS (1):
+    ~ https://admin.example.com
+        status: 403 -> 200
+        title: 'Forbidden' -> 'Admin Login'
+        tech: ['Apache'] -> ['Apache', 'PHP']
+[-] Removed subdomains (1) [informational]:
+    - old.example.com
+============================================================
+```
+
+Removed subdomains are informational only, because subfinder's sources can return slightly different results between runs.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | No changes found (or not enough history to compare) |
+| `1` | Changes were detected |
+
+### Run it on a schedule
+
+```
+# Every 6 hours: rescan and log changes
+0 */6 * * * reconflow scan example.com && reconflow diff example.com >> ~/recon-changes.log
+```
+
+## Output
+
+Files are saved under `output/<domain>/`:
+
+```
+subdomains.txt      all discovered subdomains
+live.txt            live hosts with status code, title, tech
+report.md           summary report
+report.json         structured report (with --json)
+screenshots/        screenshots of live hosts (with --screenshots)
+runs/<run_id>/      snapshot of each scan, used by diff
+```
+
+## Known limitations
+
+- **Wildcard DNS domains** return many fake "live" hosts that all point to the same server. reconflow detects them and filters those hosts (use `--keep-wildcard` to disable).
+- Discovery depends on subfinder's sources, so results can vary between runs.
+
+## Roadmap
+
+- [x] Subdomain discovery and live host probing
+- [x] Wildcard DNS detection (including rotating IP pools)
+- [x] `--threads` and `--timeout` options
+- [x] JSON report output
+- [x] Screenshots of live hosts
+- [x] Scan history and `reconflow diff`
+- [ ] `reconflow scope`: check targets against program scope
+- [ ] `reconflow report`: regenerate reports from saved scans
+- [ ] `--notify`: Discord/Slack webhook alerts for diff results
+- [ ] Save results as they come in
+
+## Contributing
+
+Contributions are welcome. Look for issues labelled `good first issue`. Run the tests with:
+
+```
+python -m unittest discover tests -v
+```
+
+## License
+
+MIT

reconflow-0.2.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+reconflow/__init__.py,sha256=gehFXwC1xM7i8O2qYBEV_RqKlKFvwnT7X9hsmlSW2Zc,51
+reconflow/__main__.py,sha256=wpBqS9iZ2nMOe2-p-l8XuWuH8_PV48KXFqZ6YJyHGhY,111
+reconflow/cli.py,sha256=8MPmd2qonuenPy2Lo-dEyr0miklQKhHqJVBlk_sHzPM,2968
+reconflow/diff.py,sha256=3Cth3uMJfDr-s5Mii1xcXOiDY4cwXtjgkW9F5_5BkdA,7359
+reconflow/history.py,sha256=1i7YjXMLmEkiDCRbyYqg1N1DWrYudGDU_At2SXF9-Uk,1599
+reconflow/scan.py,sha256=VDKMcHzwb-c8J6sj5K8CFPy1ktiyhnczcQHx08fjc08,15391
+reconflow-0.2.2.dist-info/licenses/LICENSE,sha256=UFvdfYlWb-XfYbEF6dpNGc3ZrEm4tI2udofy9B2JGAw,1092
+reconflow-0.2.2.dist-info/METADATA,sha256=7be1EjOhnKBqr8npc7rt13h_Zq3hVASME7Po8iEd-0g,6547
+reconflow-0.2.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+reconflow-0.2.2.dist-info/entry_points.txt,sha256=aSmnkq5yjZuuKH50rZRYdl_H3qSzRa6ifLBMN534AEI,49
+reconflow-0.2.2.dist-info/top_level.txt,sha256=oraasyX3DZYbNo2cUI3a0calvKNBOohjcb3gQ5b5O1M,10
+reconflow-0.2.2.dist-info/RECORD,,

reconflow-0.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

reconflow-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+reconflow = reconflow.cli:main

reconflow-0.2.2.dist-info/licenses/LICENSE

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

reconflow-0.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+reconflow