blackops-cli 0.1.5__py3-none-any.whl

blackops_cli/__init__.py

@@ -0,0 +1,62 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 CommonHuman-Lab
+"""
+blackops-cli — shared CLI/terminal UX primitives for BlackOpsSQL tools.
+
+Quick imports:
+
+    from blackops_cli.output import success, warning, error
+    from blackops_cli.logging import setup_logging, get_logger
+    from blackops_cli.reporter import ScanResultBase
+    from blackops_cli.prompts import prompt, prompt_bool, section
+    from blackops_cli.entrypoint import load_url_list, parse_headers
+"""
+
+from blackops_cli.colour import (
+    RED, GREEN, YELLOW, CYAN, BOLD, DIM,
+    render_banner,
+)
+from blackops_cli.logging import (
+    FINDING, StingLogger, get_logger, setup_logging, ScanResultHandler,
+)
+from blackops_cli.output import (
+    success, warning, error, info, debug,
+    print_header, print_footer, print_scan_meta,
+    print_finding, print_finding_severity, print_severity_summary, print_errors,
+    proof_url,
+)
+from blackops_cli.severity import (
+    Severity,
+    CRITICAL, HIGH, MEDIUM, LOW, INFO,
+    severity_colour, severity_label, severity_score,
+    SEVERITY_ORDER,
+)
+from blackops_cli.prompts import safe_int, prompt, prompt_bool, section
+from blackops_cli.reporter import ScanResultBase
+from blackops_cli.entrypoint import (
+    load_url_list, compile_exclude_patterns, parse_headers, validate_timeout,
+)
+
+__version__ = "0.1.5"
+
+__all__ = [
+    "__version__",
+    # colour
+    "RED", "GREEN", "YELLOW", "CYAN", "BOLD", "DIM", "render_banner",
+    # logging
+    "FINDING", "StingLogger", "get_logger", "setup_logging", "ScanResultHandler",
+    # output
+    "success", "warning", "error", "info", "debug",
+    "print_header", "print_footer", "print_scan_meta",
+    "print_finding", "print_finding_severity", "print_severity_summary",
+    "print_errors", "proof_url",
+    # severity
+    "Severity", "CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO",
+    "severity_colour", "severity_label", "severity_score", "SEVERITY_ORDER",
+    # prompts
+    "safe_int", "prompt", "prompt_bool", "section",
+    # reporter
+    "ScanResultBase",
+    # entrypoint
+    "load_url_list", "compile_exclude_patterns", "parse_headers", "validate_timeout",
+]

blackops_cli/colour.py

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 CommonHuman-Lab
+from __future__ import annotations
+
+import sys
+
+
+def _use_colour() -> bool:
+    """Evaluated at call time so stdout redirections are always respected."""
+    return sys.stdout.isatty()
+
+
+def _c(code: str, text: str) -> str:
+    if not _use_colour():
+        return text
+    return f"\033[{code}m{text}\033[0m"
+
+
+RED    = lambda t: _c("31;1",    t)  # noqa: E731
+GREEN  = lambda t: _c("38;5;46", t)  # noqa: E731
+YELLOW = lambda t: _c("33;1",    t)  # noqa: E731
+CYAN   = lambda t: _c("36",      t)  # noqa: E731
+BOLD   = lambda t: _c("1",       t)  # noqa: E731
+DIM    = lambda t: _c("2",       t)  # noqa: E731
+
+
+def render_banner(text: str) -> str:
+    """Wrap a banner string in CYAN, ready for print()."""
+    return CYAN(text)

blackops_cli/entrypoint.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 CommonHuman-Lab
+from __future__ import annotations
+
+import re
+import sys
+
+__all__ = [
+    "load_url_list",
+    "compile_exclude_patterns",
+    "parse_headers",
+    "parse_auth_cred",
+    "validate_timeout",
+]
+
+
+def load_url_list(path: str) -> list[str]:
+    """Read a file of target URLs, one per line. Skips blanks and # comments.
+
+    Exits with code 2 on I/O error.
+    """
+    try:
+        with open(path) as fh:
+            return [
+                line.strip()
+                for line in fh
+                if line.strip() and not line.strip().startswith("#")
+            ]
+    except OSError as e:
+        print(f"[!] Cannot read URL list: {e}", file=sys.stderr)
+        sys.exit(2)
+
+
+def compile_exclude_patterns(
+    patterns: list[str],
+    exit_on_error: bool = True,
+) -> list[re.Pattern]:
+    """Compile a list of regex strings into Pattern objects.
+
+    exit_on_error=True (default): prints to stderr and sys.exit(2) on bad regex.
+    exit_on_error=False:          raises ValueError instead (useful in tests).
+    """
+    compiled: list[re.Pattern] = []
+    for pat in patterns:
+        try:
+            compiled.append(re.compile(pat))
+        except re.error as e:
+            msg = f"[!] Invalid --exclude pattern '{pat}': {e}"
+            if exit_on_error:
+                print(msg, file=sys.stderr)
+                sys.exit(2)
+            raise ValueError(msg) from e
+    return compiled
+
+
+def parse_headers(header_list: list[str]) -> dict[str, str]:
+    """Convert a list of "KEY:VALUE" strings into a dict.
+
+    Splits on the first colon only so header values may contain colons
+    (e.g. "Authorization: Bearer token:extra").
+    Entries without a colon are silently ignored.
+    """
+    headers: dict[str, str] = {}
+    for h in header_list:
+        if ":" in h:
+            k, _, v = h.partition(":")
+            headers[k.strip()] = v.strip()
+    return headers
+
+
+def parse_auth_cred(cred: str) -> tuple[str, str]:
+    """Split ``"username:password"`` into ``(username, password)``.
+
+    Splits on the first colon only, so passwords that themselves contain
+    colons are handled correctly.
+
+    Raises:
+        ValueError: *cred* is empty or contains no colon.
+    """
+    if not cred or ":" not in cred:
+        raise ValueError(
+            f"auth_cred must be in 'username:password' format, got {cred!r}"
+        )
+    username, _, password = cred.partition(":")
+    return username, password
+
+
+def validate_timeout(timeout: int, min_val: int = 5) -> None:
+    """Warn to stderr if *timeout* is below *min_val*. Does not clamp."""
+    if timeout < min_val:
+        print(
+            f"[!] --timeout {timeout} is below minimum; clamping to {min_val}s",
+            file=sys.stderr,
+        )

blackops_cli/logging.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 CommonHuman-Lab
+from __future__ import annotations
+
+import logging
+import traceback
+
+from blackops_cli.colour import GREEN, YELLOW, CYAN, DIM
+
+__all__ = [
+    "FINDING",
+    "StingLogger",
+    "get_logger",
+    "setup_logging",
+    "ScanResultHandler",
+]
+
+# Custom level for confirmed findings — sits between INFO (20) and WARNING (30).
+FINDING = 25
+logging.addLevelName(FINDING, "FINDING")
+
+
+class StingLogger(logging.Logger):
+    """Logger subclass that adds a .finding() convenience method."""
+
+    def finding(self, msg: str, *args, **kwargs) -> None:
+        if self.isEnabledFor(FINDING):
+            self._log(FINDING, msg, args, **kwargs)
+
+
+# Called once at import so all tool logger hierarchies use StingLogger.
+logging.setLoggerClass(StingLogger)
+
+
+def get_logger(name: str) -> StingLogger:
+    """Return (or create) a StingLogger for *name*."""
+    return logging.getLogger(name)  # type: ignore[return-value]
+
+
+class _ColorHandler(logging.StreamHandler):
+    """Writes log records to stdout with ANSI colour based on level."""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            msg = record.getMessage()
+            if record.levelno >= logging.WARNING:
+                print(YELLOW(f"[!] {msg}"))
+            elif record.levelno == FINDING:
+                print(GREEN(f"[+] {msg}"))
+            elif record.levelno == logging.DEBUG:
+                print(CYAN(f"[~] {msg}"))
+            else:
+                print(DIM(f"[*] {msg}"))
+            if record.exc_info:
+                traceback.print_exception(*record.exc_info)
+            self.flush()
+        except Exception:
+            self.handleError(record)
+
+
+def setup_logging(verbose: bool, quiet: bool, logger_name: str) -> None:
+    """Configure the *logger_name* hierarchy with colour output.
+
+    Each tool passes its own logger_name (e.g. "blackops-sql", "stingxss") so
+    namespaces remain isolated even when both are imported in the same process.
+    """
+    root = get_logger(logger_name)
+    for h in root.handlers[:]:
+        h.close()
+        root.handlers.remove(h)
+    root.propagate = False
+    if quiet:
+        root.setLevel(logging.ERROR)
+        return
+    handler = _ColorHandler()
+    root.setLevel(logging.DEBUG if verbose else logging.INFO)
+    root.addHandler(handler)
+
+
+class ScanResultHandler(logging.Handler):
+    """Appends formatted log messages to a ScanResult.log list."""
+
+    def __init__(self, result) -> None:
+        super().__init__()
+        self._result = result
+
+    def emit(self, record: logging.LogRecord) -> None:
+        self._result.append_log(self.format(record))

blackops_cli/output.py

@@ -0,0 +1,202 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 CommonHuman-Lab
+"""Terminal output helpers: status printers, summary blocks, and PoC URL builder."""
+
+from __future__ import annotations
+
+import sys
+import urllib.parse as _up
+from typing import Callable
+
+from blackops_cli.colour import BOLD, CYAN, DIM, GREEN, RED, YELLOW
+
+__all__ = [
+    "success", "warning", "error", "info", "debug",
+    "print_header", "print_footer", "print_scan_meta",
+    "print_finding", "print_finding_severity", "print_severity_summary", "print_errors",
+    "proof_url",
+]
+
+
+# ---------------------------------------------------------------------------
+# One-liner status printers
+# ---------------------------------------------------------------------------
+
+def success(msg: str) -> None:
+    """Print a GREEN [+] confirmation line."""
+    print(GREEN(f"[+] {msg}"))
+
+
+def warning(msg: str) -> None:
+    """Print a YELLOW [!] warning line."""
+    print(YELLOW(f"[!] {msg}"))
+
+
+def error(msg: str) -> None:
+    """Print a RED [!] error line to stderr."""
+    print(RED(f"[!] {msg}"), file=sys.stderr)
+
+
+def info(msg: str) -> None:
+    """Print a DIM [*] informational line."""
+    print(DIM(f"[*] {msg}"))
+
+
+def debug(msg: str) -> None:
+    """Print a CYAN [~] debug line."""
+    print(CYAN(f"[~] {msg}"))
+
+
+# ---------------------------------------------------------------------------
+# Summary block helpers
+# ---------------------------------------------------------------------------
+
+def print_header(title: str, width: int = 60) -> None:
+    """Print a BOLD === title === header block."""
+    print()
+    print(BOLD("=" * width))
+    print(BOLD(f"  {title}"))
+    print(BOLD("=" * width))
+
+
+def print_footer(width: int = 60) -> None:
+    """Print a BOLD === closing separator."""
+    print(BOLD("=" * width))
+
+
+def print_scan_meta(
+    target: str,
+    duration_s: float,
+    requests_sent: int,
+    crawled_urls: int,
+    params_tested: int,
+    *,
+    waf_detected: str | None = None,
+    evasion_applied: str | None = None,
+    **extra: str,
+) -> None:
+    """Print the standard scan metadata block.
+
+    The five required positional args cover fields common to every tool.
+    Pass tool-specific rows as keyword arguments, e.g.:
+        print_scan_meta(..., **{"DBMS detected": result.dbms_detected or "Unknown"})
+    """
+    print(f"  Target        : {target}")
+    print(f"  Duration      : {duration_s}s")
+    print(f"  Requests sent : {requests_sent}")
+    print(f"  URLs crawled  : {crawled_urls}")
+    print(f"  Params tested : {params_tested}")
+    print(f"  WAF detected  : {waf_detected or 'None'}")
+    print(f"  Evasion used  : {evasion_applied or 'None'}")
+    for key, val in extra.items():
+        print(f"  {key:<14}: {val}")
+    print()
+
+
+def print_finding(
+    index: int,
+    tag: str,
+    tag_colour_fn: Callable[[str], str],
+    fields: list[tuple[str, str]],
+    proof: str = "",
+) -> None:
+    """Print a single numbered finding block.
+
+    Args:
+        index:         1-based finding number.
+        tag:           Finding label, e.g. "ERROR-BASED SQLi".
+        tag_colour_fn: Colour function to wrap the tag, e.g. RED or YELLOW.
+        fields:        Ordered list of (label, value) rows.
+        proof:         Optional PoC URL; omitted when empty.
+    """
+    print(f"  {index}. {tag_colour_fn(f'[{tag}]')}")
+    for label, value in fields:
+        print(f"     {label:<10}: {value}")
+    if proof:
+        print(f"     {'Proof':<10}: {CYAN(proof)}")
+    print()
+
+
+def print_finding_severity(
+    index: int,
+    tag: str,
+    severity: str,
+    fields: list[tuple[str, str]],
+    proof: str = "",
+) -> None:
+    """Like print_finding but colours the tag by severity automatically.
+
+    Args:
+        index:    1-based finding number.
+        tag:      Finding label, e.g. "REFLECTED XSS".
+        severity: Severity string from ``blackops_cli.severity.Severity``.
+        fields:   Ordered list of (label, value) rows.
+        proof:    Optional PoC URL; omitted when empty.
+    """
+    from blackops_cli.severity import severity_colour, severity_label
+    colour_fn = severity_colour(severity)
+    full_tag  = f"{tag} [{severity_label(severity).strip()}]"
+    print(f"  {index}. {colour_fn(f'[{full_tag}]')}")
+    for label, value in fields:
+        print(f"     {label:<10}: {value}")
+    if proof:
+        print(f"     {'Proof':<10}: {CYAN(proof)}")
+    print()
+
+
+def print_severity_summary(counts: dict[str, int]) -> None:
+    """Print a compact severity count summary line.
+
+    Args:
+        counts: Dict mapping severity string → number of findings.
+                Unknown severity strings are grouped under "other".
+
+    Example output::
+
+        Severity  : CRITICAL 0  HIGH 3  MEDIUM 1  LOW 0  INFO 2
+    """
+    from blackops_cli.severity import SEVERITY_ORDER, severity_colour
+    parts: list[str] = []
+    for sev in SEVERITY_ORDER:
+        n = counts.get(sev, 0)
+        colour_fn = severity_colour(sev) if n > 0 else DIM
+        parts.append(colour_fn(f"{sev.upper()} {n}"))
+    print(f"  {'Severity':<14}: {'  '.join(parts)}")
+
+
+def print_errors(errors: list[str]) -> None:
+    """Print a RED errors block; no-ops on an empty list."""
+    if not errors:
+        return
+    print(RED("  Errors:"))
+    for e in errors:
+        print(f"    - {e}")
+
+
+# ---------------------------------------------------------------------------
+# PoC URL builder
+# ---------------------------------------------------------------------------
+
+def proof_url(url: str, param: str, payload: str, *, append: bool = True) -> str:
+    """Build a percent-encoded PoC URL with *payload* injected into *param*.
+
+    append=True  (default): appends payload to the existing param value.
+                            Matches SQLi scanner injection style.
+    append=False:           replaces the param value with the raw payload.
+                            Matches XSS scanner injection style.
+
+    Returns "" if the URL has no scheme/netloc or cannot be reconstructed.
+    """
+    try:
+        parsed = _up.urlparse(url)
+        if not parsed.scheme or not parsed.netloc:
+            return ""
+        qs = _up.parse_qs(parsed.query, keep_blank_values=True)
+        if append:
+            orig = qs.get(param, ["1"])[0]
+            qs[param] = [orig + payload]
+        else:
+            qs[param] = [payload]
+        return _up.urlunparse(parsed._replace(query=_up.urlencode(qs, doseq=True)))
+    except (ValueError, AttributeError):
+        return ""

blackops_cli/prompts.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 CommonHuman-Lab
+from __future__ import annotations
+
+import sys
+
+from blackops_cli.colour import BOLD, DIM, YELLOW
+
+__all__ = ["safe_int", "prompt", "prompt_bool", "section"]
+
+
+def safe_int(val: str, default: int, lo: int, hi: int) -> int:
+    """Parse *val* as int, clamped to [lo, hi]. Returns *default* on error."""
+    try:
+        return max(lo, min(int(val), hi))
+    except (TypeError, ValueError):
+        return default
+
+
+def prompt(label: str, default: str = "", hint: str = "") -> str:
+    """Display a labelled input prompt and return the entered value.
+
+    Returns *default* if the user presses Enter with no input.
+    Exits cleanly on Ctrl+C or EOF.
+    """
+    hint_str = f"  {DIM(hint)}" if hint else ""
+    if default:
+        display = f"{BOLD(label)} {DIM(f'[{default}]')}{hint_str}: "
+    else:
+        display = f"{BOLD(label)}{hint_str}: "
+    try:
+        val = input(display).strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        sys.exit(0)
+    return val if val else default
+
+
+def prompt_bool(label: str, default: bool = False) -> bool:
+    """Display a Y/n prompt and return the boolean result."""
+    default_str = "Y/n" if default else "y/N"
+    display = f"{BOLD(label)} {DIM(f'[{default_str}]')}: "
+    try:
+        val = input(display).strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        sys.exit(0)
+    if not val:
+        return default
+    return val in ("y", "yes", "1", "true")
+
+
+def section(title: str) -> None:
+    """Print a dimmed section divider for interactive mode."""
+    print()
+    print(DIM("  ─── " + title + " " + "─" * max(0, 40 - len(title))))