sm0g-cli 0.1.3__py3-none-any.whl

sm0g_cli/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+from .emit import (
+    ok, warn, fail, note, trace,
+    emit_header, emit_footer, emit_meta,
+    emit_hit, emit_hit_graded, emit_grade_summary, emit_errors,
+    evidence_url,
+)
+from .colour import red, green, yellow, cyan, bold, dim, draw_banner
+from .level import FIND, ScanLogger, ColorSink, ReportSink, get_scan_logger, setup_logging
+from .grade import Grade, grade_colour, grade_label, grade_score, GRADE_ORDER
+from .ask import safe_int, ask, ask_bool, section
+from .load import load_url_list, compile_skip_patterns, parse_headers, parse_credential, validate_timeout
+from .render import dump_table, print_banner, clip_url
+from .base import ScanBase
+
+__all__ = [
+    "ok", "warn", "fail", "note", "trace",
+    "emit_header", "emit_footer", "emit_meta",
+    "emit_hit", "emit_hit_graded", "emit_grade_summary", "emit_errors",
+    "evidence_url",
+    "red", "green", "yellow", "cyan", "bold", "dim", "draw_banner",
+    "FIND", "ScanLogger", "ColorSink", "ReportSink", "get_scan_logger", "setup_logging",
+    "Grade", "grade_colour", "grade_label", "grade_score", "GRADE_ORDER",
+    "safe_int", "ask", "ask_bool", "section",
+    "load_url_list", "compile_skip_patterns", "parse_headers", "parse_credential", "validate_timeout",
+    "dump_table", "print_banner", "clip_url",
+    "ScanBase",
+]

sm0g_cli/ansi.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+from __future__ import annotations
+
+import os
+
+_NO_COLOR = bool(os.environ.get("NO_COLOR", ""))
+
+_ESC = "\033["
+
+
+def _wrap(code: str, text: str) -> str:
+    if _NO_COLOR:
+        return text
+    return f"{_ESC}{code}m{text}{_ESC}0m"
+
+
+def bold(text: str) -> str:
+    return _wrap("1", text)
+
+
+def dim(text: str) -> str:
+    return _wrap("2", text)
+
+
+def red(text: str) -> str:
+    return _wrap("31", text)
+
+
+def green(text: str) -> str:
+    return _wrap("32", text)
+
+
+def yellow(text: str) -> str:
+    return _wrap("33", text)
+
+
+def cyan(text: str) -> str:
+    return _wrap("36", text)
+
+
+def strip_color(text: str) -> str:
+    """Remove all ANSI escape sequences from text."""
+    import re
+    return re.sub(r"\033\[[0-9;]*m", "", text)

sm0g_cli/ask.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+from __future__ import annotations
+
+import sys
+
+from sm0g_cli.colour import bold, dim
+
+__all__ = ["safe_int", "ask", "ask_bool", "section"]
+
+_SECTION_WIDTH = 46
+_TRUTHY = frozenset(("y", "yes", "1", "true"))
+
+
+def safe_int(val: str, default: int, lo: int, hi: int) -> int:
+    try:
+        return max(lo, min(int(val), hi))
+    except (TypeError, ValueError):
+        return default
+
+
+def ask(label: str, default: str = "", hint: str = "") -> str:
+    prompt = bold(label)
+    if default:
+        prompt = f"{prompt} {dim('[' + default + ']')}"
+    if hint:
+        prompt = f"{prompt}  {dim(hint)}"
+    prompt += ": "
+    try:
+        val = input(prompt).strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        sys.exit(0)
+    return val if val else default
+
+
+def ask_bool(label: str, default: bool = False) -> bool:
+    indicator = "Y/n" if default else "y/N"
+    prompt = f"{bold(label)} {dim('[' + indicator + ']')}: "
+    try:
+        val = input(prompt).strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        sys.exit(0)
+    if not val:
+        return default
+    return val in _TRUTHY
+
+
+def section(title: str) -> None:
+    fill = "─" * max(0, _SECTION_WIDTH - len(title))
+    print()
+    print(dim(f"  ── {title} {fill}"))

sm0g_cli/base.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["ScanBase"]
+
+
+@dataclass
+class ScanBase:
+    target: str
+    started_at: float = field(default_factory=time.time)
+    finished_at: float = 0.0
+    duration_s: float = 0.0
+    waf_detected: str | None = None
+    evasion_applied: str | None = None
+    crawled_urls: int = 0
+    params_tested: int = 0
+    requests_sent: int = 0
+    log: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    _lock: threading.Lock = field(
+        default_factory=threading.Lock,
+        repr=False,
+        compare=False,
+    )
+
+    def close_scan(self) -> "ScanBase":
+        now = time.time()
+        self.finished_at = now
+        self.duration_s = round(now - self.started_at, 2)
+        return self
+
+    def _record(self, attr: str, item: Any) -> None:
+        with self._lock:
+            lst: list = getattr(self, attr)
+            lst.append(item)
+
+    def append_error(self, msg: str) -> None:
+        self._record("errors", msg)
+
+    def append_log(self, msg: str) -> None:
+        self._record("log", msg)
+
+    @property
+    def success(self) -> bool:
+        return not bool(self.errors) or bool(getattr(self, "total_findings", 0))
+
+    def _summary_fields(self) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        out["target"] = self.target
+        out["duration_s"] = self.duration_s
+        out["requests_sent"] = self.requests_sent
+        out["crawled_urls"] = self.crawled_urls
+        out["params_tested"] = self.params_tested
+        out["waf_detected"] = self.waf_detected
+        out["evasion_applied"] = self.evasion_applied
+        out["success"] = self.success
+        out["errors"] = self.errors
+        out["log"] = self.log
+        return out

sm0g_cli/colour.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+from __future__ import annotations
+
+import os
+import sys
+
+
+def _tty_active() -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    stream = sys.__stdout__ or sys.stdout
+    return getattr(stream, "isatty", lambda: False)()
+
+
+def _ansi(code: str, text: str) -> str:
+    return text if not _tty_active() else "\x1b[" + code + "m" + text + "\x1b[0m"
+
+
+def red(t: str)    -> str: return _ansi("31;1",    t)
+def green(t: str)  -> str: return _ansi("38;5;46", t)
+def yellow(t: str) -> str: return _ansi("33;1",    t)
+def cyan(t: str)   -> str: return _ansi("36",      t)
+def bold(t: str)   -> str: return _ansi("1",       t)
+def dim(t: str)    -> str: return _ansi("2",       t)
+
+
+def draw_banner(text: str) -> str:
+    return cyan(text)

sm0g_cli/emit.py

@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+from __future__ import annotations
+
+import sys
+import urllib.parse as _up
+from typing import Callable
+
+from sm0g_cli.colour import bold, cyan, dim, green, red, yellow
+
+__all__ = [
+    "ok", "warn", "fail", "note", "trace",
+    "emit_header", "emit_footer", "emit_meta",
+    "emit_hit", "emit_hit_graded", "emit_grade_summary", "emit_errors",
+    "evidence_url",
+]
+
+_META_COL  = 14
+_FIELD_COL = 10
+
+
+def ok(msg: str) -> None:
+    print(green(f"[+] {msg}"))
+
+
+def warn(msg: str) -> None:
+    print(yellow(f"[!] {msg}"))
+
+
+def fail(msg: str) -> None:
+    print(red(f"[!] {msg}"), file=sys.stderr)
+
+
+def note(msg: str) -> None:
+    print(dim(f"[*] {msg}"))
+
+
+def trace(msg: str) -> None:
+    print(cyan(f"[~] {msg}"))
+
+
+def emit_header(title: str, width: int = 60) -> None:
+    print()
+    print(bold("=" * width))
+    print(bold(f"  {title}"))
+    print(bold("=" * width))
+
+
+def emit_footer(width: int = 60) -> None:
+    print(bold("=" * width))
+
+
+def _row(label: str, value: str) -> None:
+    print(f"  {label:<{_META_COL}}: {value}")
+
+
+def emit_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:
+    rows = [
+        ("Target",        target),
+        ("Duration",      f"{duration_s}s"),
+        ("Requests sent", str(requests_sent)),
+        ("URLs crawled",  str(crawled_urls)),
+        ("Params tested", str(params_tested)),
+        ("WAF detected",  waf_detected or "None"),
+        ("Evasion used",  evasion_applied or "None"),
+    ]
+    for k, v in extra.items():
+        rows.append((k, v))
+    for label, value in rows:
+        _row(label, value)
+    print()
+
+
+def emit_hit(
+    index: int,
+    tag: str,
+    tag_colour_fn: Callable[[str], str],
+    fields: list[tuple[str, str]],
+    proof: str = "",
+) -> None:
+    print(f"  {index}. {tag_colour_fn(f'[{tag}]')}")
+    for label, value in fields:
+        print(f"     {label:<{_FIELD_COL}}: {value}")
+    if proof:
+        print(f"     {'Proof':<{_FIELD_COL}}: {cyan(proof)}")
+    print()
+
+
+def emit_hit_graded(
+    index: int,
+    tag: str,
+    severity: str,
+    fields: list[tuple[str, str]],
+    proof: str = "",
+) -> None:
+    from sm0g_cli.grade import grade_colour, grade_label
+    colour_fn = grade_colour(severity)
+    full_tag  = f"{tag} [{grade_label(severity).strip()}]"
+    print(f"  {index}. {colour_fn(f'[{full_tag}]')}")
+    for label, value in fields:
+        print(f"     {label:<{_FIELD_COL}}: {value}")
+    if proof:
+        print(f"     {'Proof':<{_FIELD_COL}}: {cyan(proof)}")
+    print()
+
+
+def emit_grade_summary(counts: dict[str, int]) -> None:
+    from sm0g_cli.grade import GRADE_ORDER, grade_colour
+    parts: list[str] = []
+    for sev in GRADE_ORDER:
+        n = counts.get(sev, 0)
+        colour_fn = grade_colour(sev) if n > 0 else dim
+        parts.append(colour_fn(f"{sev.upper()} {n}"))
+    print(f"  {'Severity':<{_META_COL}}: {'  '.join(parts)}")
+
+
+def emit_errors(errors: list[str]) -> None:
+    if not errors:
+        return
+    print(red("  Errors:"))
+    for e in errors:
+        print(f"    - {e}")
+
+
+def evidence_url(url: str, param: str, payload: str, *, append: bool = True) -> str:
+    try:
+        parsed = _up.urlparse(url)
+        if not parsed.scheme or not parsed.netloc:
+            return ""
+        qs = _up.parse_qs(parsed.query, keep_blank_values=True)
+        injected = (qs.get(param, ["1"])[0] + payload) if append else payload
+        qs[param] = [injected]
+        return _up.urlunparse(parsed._replace(query=_up.urlencode(qs, doseq=True)))
+    except (ValueError, AttributeError):
+        return ""

sm0g_cli/grade.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+from __future__ import annotations
+
+from typing import Callable
+
+from sm0g_cli.colour import red, yellow, cyan, dim
+
+__all__ = [
+    "Grade",
+    "CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO",
+    "grade_colour", "grade_label", "grade_score",
+    "GRADE_ORDER",
+]
+
+
+class Grade:
+    CRITICAL = "critical"
+    HIGH     = "high"
+    MEDIUM   = "medium"
+    LOW      = "low"
+    INFO     = "info"
+
+
+CRITICAL = Grade.CRITICAL
+HIGH     = Grade.HIGH
+MEDIUM   = Grade.MEDIUM
+LOW      = Grade.LOW
+INFO     = Grade.INFO
+
+GRADE_ORDER: list[str] = [CRITICAL, HIGH, MEDIUM, LOW, INFO]
+
+_GRADE_SCORE: dict[str, int] = {
+    CRITICAL: 4,
+    HIGH:     3,
+    MEDIUM:   2,
+    LOW:      1,
+    INFO:     0,
+}
+
+
+def grade_colour(severity: str) -> Callable[[str], str]:
+    if severity in (CRITICAL, HIGH):
+        return red
+    if severity == MEDIUM:
+        return yellow
+    if severity == LOW:
+        return cyan
+    return dim
+
+
+def grade_label(severity: str) -> str:
+    return f"{severity.upper():<8}"
+
+
+def grade_score(severity: str) -> int:
+    return _GRADE_SCORE.get(severity, 0)

sm0g_cli/html_render.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+from __future__ import annotations
+
+import html
+from .report import ProbeReport
+
+
+def build_html_report(report: ProbeReport) -> str:
+    """Render a ProbeReport as a self-contained HTML document string."""
+    rows = ""
+    for hit in report.hits:
+        rows += (
+            f"<tr>"
+            f"<td>{html.escape(hit.url)}</td>"
+            f"<td>{html.escape(hit.parameter)}</td>"
+            f"<td>{html.escape(hit.method)}</td>"
+            f"<td><code>{html.escape(hit.payload)}</code></td>"
+            f"<td>{html.escape(hit.risk.label())}</td>"
+            f"<td>{html.escape(hit.evidence)}</td>"
+            f"</tr>\n"
+        )
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>SM0G Report — {html.escape(report.tool)}</title>
+  <style>
+    body {{ font-family: monospace; background: #111; color: #eee; padding: 1rem; }}
+    h1 {{ color: #0f0; }}
+    table {{ border-collapse: collapse; width: 100%; }}
+    th, td {{ border: 1px solid #444; padding: 6px 10px; text-align: left; }}
+    th {{ background: #222; color: #0f0; }}
+    tr:nth-child(even) {{ background: #1a1a1a; }}
+    code {{ color: #f90; }}
+  </style>
+</head>
+<body>
+  <h1>SM0G :: {html.escape(report.tool)}</h1>
+  <p>Target: {html.escape(report.target)} &mdash; Findings: {report.hit_count}</p>
+  <table>
+    <thead><tr><th>URL</th><th>Param</th><th>Method</th><th>Payload</th><th>Risk</th><th>Evidence</th></tr></thead>
+    <tbody>{rows}</tbody>
+  </table>
+</body>
+</html>"""

sm0g_cli/level.py

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+
+from __future__ import annotations
+
+import logging
+import traceback
+
+from sm0g_cli.colour import green, yellow, cyan, bold
+
+__all__ = [
+    "FIND",
+    "ScanLogger",
+    "ColorSink",
+    "ReportSink",
+    "get_scan_logger",
+    "setup_logging",
+]
+
+FIND = 25
+logging.addLevelName(FIND, "FIND")
+
+
+class ScanLogger(logging.Logger):
+    def hit(self, msg: str, *args, **kwargs) -> None:
+        if self.isEnabledFor(FIND):
+            self._log(FIND, msg, args, **kwargs)
+
+
+logging.setLoggerClass(ScanLogger)
+
+
+def get_scan_logger(name: str) -> ScanLogger:
+    return logging.getLogger(name)  # type: ignore[return-value]
+
+
+# Console styling is data-driven: each severity selects a painter + badge.
+# WARNING and above share the alert style and always render (even an empty
+# message); quieter levels collapse an empty message to a bare line.
+_ALERT_STYLE = (yellow, "[!]")
+_PLAIN_STYLE = (bold, "[*]")
+_LEVEL_STYLES: dict[int, tuple] = {
+    FIND: (green, "[+]"),
+    logging.DEBUG: (cyan, "[~]"),
+}
+
+
+class ColorSink(logging.StreamHandler):
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            text = record.getMessage()
+            level = record.levelno
+            if level >= logging.WARNING:
+                paint, badge = _ALERT_STYLE
+                rendered: str | None = paint(f"{badge} {text}")
+            else:
+                paint, badge = _LEVEL_STYLES.get(level, _PLAIN_STYLE)
+                rendered = paint(f"{badge} {text}") if text else None
+            print(rendered if rendered is not None else "")
+            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:
+    root = get_scan_logger(logger_name)
+    while root.handlers:
+        root.handlers.pop().close()
+    root.propagate = False
+    if quiet:
+        root.setLevel(logging.ERROR)
+        return
+    root.setLevel(logging.DEBUG if verbose else logging.INFO)
+    root.addHandler(ColorSink())
+
+
+class ReportSink(logging.Handler):
+    def __init__(self, result) -> None:
+        super().__init__()
+        self._result = result
+
+    def emit(self, record: logging.LogRecord) -> None:
+        self._result._record("log", self.format(record))

sm0g_cli/load.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+__all__ = [
+    "load_url_list",
+    "compile_skip_patterns",
+    "parse_headers",
+    "parse_credential",
+    "validate_timeout",
+]
+
+
+def load_url_list(path: str) -> list[str]:
+    try:
+        lines = Path(path).read_text(encoding="utf-8").splitlines()
+        return [ln for ln in (l.strip() for l in lines) if ln and not ln.startswith("#")]
+    except OSError as exc:
+        print(f"[!] Cannot read URL list: {exc}", file=sys.stderr)
+        sys.exit(2)
+
+
+def compile_skip_patterns(
+    patterns: list[str],
+    exit_on_error: bool = True,
+) -> list[re.Pattern]:
+    out: list[re.Pattern] = []
+    for pat in patterns:
+        try:
+            out.append(re.compile(pat))
+        except re.error as exc:
+            msg = f"[!] Invalid --exclude pattern '{pat}': {exc}"
+            if exit_on_error:
+                print(msg, file=sys.stderr)
+                sys.exit(2)
+            raise ValueError(msg) from exc
+    return out
+
+
+def parse_headers(header_list: list[str]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for item in header_list:
+        if ":" not in item:
+            continue
+        name, value = item.split(":", 1)
+        result[name.strip()] = value.strip()
+    return result
+
+
+def parse_credential(cred: str) -> tuple[str, str]:
+    if not cred or ":" not in cred:
+        raise ValueError(
+            f"credential must be in 'username:password' format, got {cred!r}"
+        )
+    idx = cred.index(":")
+    return cred[:idx], cred[idx + 1:]
+
+
+def validate_timeout(timeout: int, min_val: int = 5) -> None:
+    if timeout < min_val:
+        print(
+            f"[!] --timeout {timeout} is below {min_val}s minimum; raising to {min_val}s",
+            file=sys.stderr,
+        )

sm0g_cli/log.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (c) 2026 SM0G-Community
+from __future__ import annotations
+
+import logging
+import sys
+from typing import TextIO
+
+FMT: str = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
+DATE_FMT: str = "%H:%M:%S"
+
+
+def setup_log(level: int = logging.INFO, stream: TextIO = sys.stderr) -> logging.Logger:
+    """Configure and return the root sm0g logger."""
+    logger = logging.getLogger("sm0g")
+    if logger.handlers:
+        return logger
+    handler = logging.StreamHandler(stream)
+    handler.setFormatter(logging.Formatter(FMT, datefmt=DATE_FMT))
+    logger.addHandler(handler)
+    logger.setLevel(level)
+    return logger
+
+
+def get_log(name: str) -> logging.Logger:
+    """Return a child logger under the sm0g namespace."""
+    return logging.getLogger(f"sm0g.{name}")