blackops-sql 0.1.6__py3-none-any.whl

blackopssql/engine/http/injector.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 CommonHuman-Lab
+"""BlackOpsSQL — engine/http/injector.py"""
+
+from blackops_core.http import HttpClient, parse_cookie_string, parse_post_data
+
+# Alias: Injector IS HttpClient — no subclass needed, all methods already present.
+Injector = HttpClient
+
+__all__ = ["Injector", "HttpClient", "parse_cookie_string", "parse_post_data"]

blackopssql/engine/http/waf_detect.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 CommonHuman-Lab
+"""BlackOpsSQL — WAF detection"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from blackops_payloads.waf import WafResult, detect as _detect
+from blackops_payloads.waf.signatures import WafSignature  # noqa: F401 (re-export)
+from blackops_payloads.encoders import (
+    EVASION_NONE,
+    EVASION_CASE_MIXING,
+    EVASION_HTML_ENCODE,
+    EVASION_UNICODE,
+    EVASION_DOUBLE_ENCODE,
+    EVASION_CHUNKED_TAGS,
+    EVASION_NULL_BYTE,
+    EVASION_NEWLINE,
+    EVASION_COMMENT_BREAK,
+    EVASION_BACKTICK,
+    EVASION_SQL_COMMENT,
+    EVASION_SQL_WHITESPACE,
+    EVASION_SQL_CASE,
+    EVASION_SQL_ENCODE,
+    EVASION_SQL_MULTILINE,
+)
+
+# SQLi probe — triggers most SQL-aware WAFs
+_PROBE_PAYLOAD = "' OR '1'='1\"-- -"
+
+__all__ = [
+    "WafResult", "WafSignature", "detect",
+    "EVASION_NONE", "EVASION_CASE_MIXING", "EVASION_HTML_ENCODE",
+    "EVASION_UNICODE", "EVASION_DOUBLE_ENCODE", "EVASION_CHUNKED_TAGS",
+    "EVASION_NULL_BYTE", "EVASION_NEWLINE", "EVASION_COMMENT_BREAK",
+    "EVASION_BACKTICK",
+    "EVASION_SQL_COMMENT", "EVASION_SQL_WHITESPACE", "EVASION_SQL_CASE",
+    "EVASION_SQL_ENCODE", "EVASION_SQL_MULTILINE",
+]
+
+
+def detect(injector, url: str, param: Optional[str] = None) -> WafResult:
+    """Probe for a WAF using the SQLi probe payload."""
+    return _detect(
+        injector.get,
+        url,
+        param,
+        probe_payload=_PROBE_PAYLOAD,
+        check_reflection=False,
+    )

blackopssql/engine/log.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 CommonHuman-Lab
+"""BlackOpsSQL — engine/log.py — re-exported from blackops_cli.logging."""
+
+from blackops_cli.logging import FINDING, StingLogger, get_logger, ScanResultHandler  # noqa: F401
+
+__all__ = ["FINDING", "get_logger", "ScanResultHandler"]

blackopssql/engine/reporter.py

@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 CommonHuman-Lab
+"""BlackOpsSQL — engine/reporter.py — scan result dataclasses and serialisation."""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from blackops_cli.reporter import ScanResultBase
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+class FindingType(str, Enum):
+    ERROR_BASED  = "error_based_sqli"
+    BOOLEAN      = "boolean_based_sqli"
+    TIME_BASED   = "time_based_sqli"
+    UNION_BASED  = "union_based_sqli"
+    OOB          = "oob_sqli"
+    STACKED      = "stacked_sqli"
+    EXTRACTION   = "extraction"
+
+
+# ---------------------------------------------------------------------------
+# Finding dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ErrorBasedFinding:
+    """DB error pattern visible in response — confirmed SQLi."""
+    url:       str
+    parameter: str
+    method:    str
+    payload:   str
+    dbms:      str
+    evidence:  str = ""
+
+
+@dataclass
+class BooleanFinding:
+    """True/false response divergence — likely SQLi."""
+    url:           str
+    parameter:     str
+    method:        str
+    payload_true:  str
+    payload_false: str
+    diff_score:    float
+    confirmed:     bool
+    evidence:      str = ""
+
+
+@dataclass
+class TimeFinding:
+    """Response time delta exceeds threshold — time-based blind SQLi."""
+    url:            str
+    parameter:      str
+    method:         str
+    payload:        str
+    dbms:           str
+    observed_delay: float
+    threshold:      int
+
+
+@dataclass
+class UnionFinding:
+    """UNION SELECT reflection confirmed — union-based SQLi."""
+    url:          str
+    parameter:    str
+    method:       str
+    payload:      str
+    column_count: int
+    extracted:    str = ""
+
+
+@dataclass
+class OOBFinding:
+    """Out-of-band payload injected — callback confirmation required externally."""
+    url:          str
+    parameter:    str
+    method:       str
+    payload:      str
+    callback_url: str
+    confirmed:    bool = False
+
+
+@dataclass
+class StackedFinding:
+    """Stacked (batched) query injection confirmed — second statement was executed."""
+    url:       str
+    parameter: str
+    method:    str
+    payload:   str
+    dbms:      str
+    evidence:  str = ""
+
+
+@dataclass
+class ExtractionFinding:
+    """Data extracted via blind char-by-char extraction (boolean or time mode)."""
+    url:       str
+    parameter: str
+    method:    str
+    expr:      str
+    value:     str
+    mode:      str
+
+
+@dataclass
+class TableDumpFinding:
+    """Rows extracted from a table via table dump."""
+    table:     str
+    columns:   List[str]
+    rows:      List[List[str]]
+    url:       str
+    parameter: str
+    method:    str
+
+
+# ---------------------------------------------------------------------------
+# Finding type → list attribute mapping
+# ---------------------------------------------------------------------------
+
+_FINDING_LISTS: List[tuple[str, FindingType]] = [
+    ("error_based",   FindingType.ERROR_BASED),
+    ("boolean_based", FindingType.BOOLEAN),
+    ("time_based",    FindingType.TIME_BASED),
+    ("union_based",   FindingType.UNION_BASED),
+    ("oob",           FindingType.OOB),
+    ("stacked",       FindingType.STACKED),
+    ("extracted",     FindingType.EXTRACTION),
+]
+
+_FINDING_SEVERITY: dict[FindingType, str] = {
+    FindingType.ERROR_BASED:  "high",
+    FindingType.BOOLEAN:      "high",
+    FindingType.TIME_BASED:   "high",
+    FindingType.UNION_BASED:  "high",
+    FindingType.OOB:          "high",
+    FindingType.STACKED:      "critical",
+    FindingType.EXTRACTION:   "critical",
+}
+
+
+# ---------------------------------------------------------------------------
+# Top-level ScanResult
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ScanResult(ScanResultBase):
+    # DBMS (auto-detected during scan) — BlackOpsSQL-specific
+    dbms_detected: Optional[str] = None
+
+    # Findings
+    error_based:   List[ErrorBasedFinding] = field(default_factory=list)
+    boolean_based: List[BooleanFinding]    = field(default_factory=list)
+    time_based:    List[TimeFinding]       = field(default_factory=list)
+    union_based:   List[UnionFinding]      = field(default_factory=list)
+    oob:           List[OOBFinding]        = field(default_factory=list)
+    stacked:       List[StackedFinding]    = field(default_factory=list)
+    extracted:     List[ExtractionFinding] = field(default_factory=list)
+    table_dumps:   List[TableDumpFinding]  = field(default_factory=list)
+
+    # --- Append helpers -------------------------------------------------------
+
+    def append_error_based(self, f)   -> None: self._append("error_based", f)
+    def append_boolean(self, f)       -> None: self._append("boolean_based", f)
+    def append_time(self, f)          -> None: self._append("time_based", f)
+    def append_union(self, f)         -> None: self._append("union_based", f)
+    def append_oob(self, f)           -> None: self._append("oob", f)
+    def append_stacked(self, f)       -> None: self._append("stacked", f)
+
+    def append_extraction(self, f) -> None:
+        with self._lock:
+            for existing in self.extracted:
+                if existing.parameter == f.parameter and existing.expr == f.expr:
+                    return
+            self.extracted.append(f)
+
+    # --- Computed properties --------------------------------------------------
+
+    @property
+    def total_findings(self) -> int:
+        return sum(len(getattr(self, attr)) for attr, _ in _FINDING_LISTS)
+
+    def to_dict(self) -> Dict[str, Any]:
+        findings: List[Dict[str, Any]] = []
+        for attr, ftype in _FINDING_LISTS:
+            for item in getattr(self, attr):
+                d = dataclasses.asdict(item)
+                d["type"]     = ftype.value
+                d["severity"] = _FINDING_SEVERITY.get(ftype, "info")
+                findings.append(d)
+
+        result = self._base_dict()
+        result["dbms_detected"] = self.dbms_detected
+        result["total_findings"] = self.total_findings
+        result["findings"] = findings
+        return result
+
+    def dumps_to_dict(self) -> Dict[str, Any]:
+        return {
+            "table_dumps": [dataclasses.asdict(td) for td in self.table_dumps],
+        }

blackopssql/engine/scanner.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 CommonHuman-Lab
+"""
+BlackOpsSQL — engine/scanner.py
+Top-level scan() entry point.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from .log import ScanResultHandler, get_logger
+from .http.injector import Injector
+from .reporter import ScanResult
+from .http import waf_detect  # noqa: F401 (patch target for tests)
+from ._scanner.options import ScanOptions  # noqa: F401 (re-exported)
+from ._scanner.pipeline import run
+
+logger = get_logger("blackopssql.scanner")
+
+
+_OUTPUT_EXTS = {".json", ".txt", ".html"}
+
+
+def _output_stem(path: str) -> str:
+    """Strip extension only if it's one of our known output types (not e.g. '.1' in an IP)."""
+    root, ext = os.path.splitext(path)
+    return root if ext.lower() in _OUTPUT_EXTS else path
+
+
+def _unique_stem(stem: str) -> str:
+    """Return *stem* unchanged if no collision exists, else append _1, _2, …"""
+    suffixes = (".json", ".txt", "_dump.json", ".html")
+    if not any(os.path.exists(stem + s) for s in suffixes):
+        return stem
+    counter = 1
+    while any(os.path.exists(f"{stem}_{counter}{s}") for s in suffixes):
+        counter += 1
+    return f"{stem}_{counter}"
+
+
+def scan(url: str, options: ScanOptions | None = None) -> ScanResult:
+    """Run a full BlackOpsSQL scan against *url* and return a ScanResult."""
+    if options is None:
+        options = ScanOptions()
+
+    result   = ScanResult(target=url)
+    _root    = get_logger("blackopssql")
+    _handler = ScanResultHandler(result)
+    _handler.setFormatter(__import__("logging").Formatter("%(name)s: %(message)s"))
+    _root.addHandler(_handler)
+
+    injector = Injector(
+        timeout=options.timeout,
+        proxy=options.proxy or None,
+        headers=options.headers or None,
+        cookies=options.cookies or None,
+        delay=options.delay,
+    )
+
+    try:
+        run(url, options, injector, result)
+    except Exception as exc:
+        result.append_error(f"Scan aborted: {exc}")
+        logger.exception("BlackOpsSQL scan error")
+    finally:
+        _root.removeHandler(_handler)
+        injector.close()
+        result.requests_sent = injector.request_count
+        result.finish()
+
+    if options.output:
+        stem = _output_stem(options.output)
+        try:
+            with open(stem + ".json", "w", encoding="utf-8") as fh:
+                json.dump(result.to_dict(), fh, indent=2)
+        except OSError as exc:
+            result.append_error(f"Failed to write JSON output: {exc}")
+        try:
+            from blackopssql._cli.summary import format_summary
+            with open(stem + ".txt", "w", encoding="utf-8") as fh:
+                fh.write(format_summary(result))
+        except OSError as exc:
+            result.append_error(f"Failed to write text output: {exc}")
+
+    if options.output and result.table_dumps:
+        stem = _output_stem(options.output)
+        try:
+            with open(stem + "_dump.json", "w", encoding="utf-8") as fh:
+                json.dump(result.dumps_to_dict(), fh, indent=2)
+        except OSError as exc:
+            result.append_error(f"Failed to write dump file: {exc}")
+
+    return result