hackable 1.0.0__py3-none-any.whl

hackable/checks/sqli.py

@@ -0,0 +1,152 @@
+"""SQL injection probes (safe: benign payloads, GET only).
+
+Two techniques, both harmless:
+- error-based: a single quote that makes the database complain out loud
+- boolean differential: AND 1=1 vs AND 1=2 must not change the page; when it
+  does, input is very likely reaching the query unsanitized (blind SQLi)
+
+We never send destructive payloads, stacked queries, or time-based probes.
+"""
+
+from ..findings import Finding
+
+# (path, param) pairs, most likely first. Used when the crawler found no
+# real inputs, so the request budget is spent across endpoints instead of
+# being eaten by one page's params.
+CANDIDATES = [
+    ("/search", "q"),
+    ("/search", "search"),
+    ("/search", "query"),
+    ("", "q"),
+    ("", "id"),
+    ("", "search"),
+    ("/product", "id"),
+    ("/user", "id"),
+    ("/item", "id"),
+    ("/page", "id"),
+]
+
+ERROR_SIGS = [
+    "you have an error in your sql syntax",
+    "warning: mysql",
+    "unclosed quotation mark",
+    "quoted string not properly terminated",
+    "pg_query()",
+    "postgresql",
+    "sqlite3",
+    "ora-",
+    "odbc",
+    "sqlstate",
+    "jdbc",
+    "database error",
+]
+
+
+def _looks_like_sql_error(text):
+    t = text.lower()
+    return any(sig in t for sig in ERROR_SIGS)
+
+
+def _pairs(base, targets):
+    """Discovered (url, params) first, then guesses. All absolute URLs."""
+    pairs, seen = [], set()
+    for url, params in (targets or [])[:8]:
+        for param in params[:3]:
+            key = (url, param)
+            if key not in seen:
+                seen.add(key)
+                pairs.append(key)
+    for path, param in CANDIDATES[:7]:
+        key = (base + path, param)
+        if key not in seen:
+            seen.add(key)
+            pairs.append(key)
+    return pairs[:14]
+
+
+def _error_based(base, http, pairs):
+    for url, param in pairs:
+        baseline = http.get(url, params={param: "1"})
+        if baseline is None:
+            continue
+        probe = http.get(url, params={param: "1'"})
+        if probe is None:
+            continue
+        full_url = url + "?%s=1'" % param
+        if _looks_like_sql_error(probe.text):
+            return [Finding(
+                check="sqli",
+                severity="critical",
+                title="SQL injection in %s" % url.replace(base, "") or "/",
+                meaning="Your database complained out loud when I typed a single "
+                "quote into the '%s' field. That means an attacker can talk "
+                "directly to your database: read every table, and often take "
+                "over the server." % param,
+                fix="Never build database queries by gluing strings together. "
+                "Use parameterized queries / prepared statements in your "
+                "framework, and validate input.",
+                evidence=probe.text.strip().replace("\n", " ")[:160],
+                url=full_url,
+            )]
+        if baseline.status_code < 500 <= probe.status_code:
+            return [Finding(
+                check="sqli",
+                severity="medium",
+                title="Possible SQL injection in %s" % url.replace(base, "") or "/",
+                meaning="The page works fine normally but crashes with a server "
+                "error when I type a quote into '%s'. That pattern often means "
+                "user input reaches the database unsanitized." % param,
+                fix="Have a developer check how the '%s' parameter is used in "
+                "database queries, and switch to parameterized queries." % param,
+                evidence="HTTP %s -> HTTP %s on quote payload"
+                % (baseline.status_code, probe.status_code),
+                url=full_url,
+            )]
+    return []
+
+
+def _boolean_based(base, http, pairs):
+    """Differential check: the page must not change between AND 1=1 / 1=2.
+
+    Conservative: the two baselines must agree first, the true-condition must
+    match the baseline closely, and the false-condition must differ clearly.
+    """
+    for url, param in pairs[:3]:
+        b1 = http.get(url, params={param: "1"})
+        b2 = http.get(url, params={param: "1"})
+        if b1 is None or b2 is None or len(b1.text) != len(b2.text):
+            continue
+        n = len(b1.text)
+        if n == 0:
+            continue
+        true = http.get(url, params={param: "1 AND 1=1"})
+        false = http.get(url, params={param: "1 AND 1=2"})
+        if true is None or false is None:
+            continue
+        true_diff = abs(len(true.text) - n)
+        false_diff = abs(len(false.text) - n)
+        if true_diff < 0.05 * n and false_diff > max(100, 0.3 * n):
+            return [Finding(
+                check="sqli",
+                severity="high",
+                title="Likely blind SQL injection in %s" % url.replace(base, "") or "/",
+                meaning="The page looks identical for a true database condition "
+                "but changes clearly for a false one. No error is shown, yet "
+                "the '%s' value is very likely reaching your SQL query, which "
+                "lets an attacker extract data bit by bit." % param,
+                fix="Use parameterized queries / prepared statements for the "
+                "'%s' parameter, and validate that it is the expected type." % param,
+                evidence="page length %d -> %d on AND 1=2" % (n, len(false.text)),
+                url=url + "?%s=1 AND 1=2" % param,
+            )]
+    return []
+
+
+def run(base, http, targets=None):
+    pairs = _pairs(base, targets)
+    findings = _error_based(base, http, pairs)
+    if findings:
+        return findings  # one confirmed SQLi is enough
+    # boolean differential only on real discovered inputs, to limit requests
+    discovered = [(u, p) for (u, p) in pairs if targets and u in [t[0] for t in targets]]
+    return _boolean_based(base, http, discovered or pairs[:3])

hackable/checks/tls.py

@@ -0,0 +1,89 @@
+"""TLS / HTTPS posture."""
+
+import datetime
+import socket
+import ssl
+
+from ..findings import Finding
+
+
+def _cert_info(host, port):
+    ctx = ssl.create_default_context()
+    with socket.create_connection((host, port), timeout=8) as sock:
+        with ctx.wrap_socket(sock, server_hostname=host) as ssock:
+            cert = ssock.getpeercert()
+            version = ssock.version()
+    return cert, version
+
+
+def run(base, http):
+    if not base.startswith("https://"):
+        return [
+            Finding(
+                check="tls",
+                severity="medium",
+                title="Site does not use HTTPS",
+                meaning="Traffic between your visitors and your server travels in plain "
+                "text. Anyone on the same network (coffee shop Wi-Fi, compromised "
+                "router) can read passwords and cookies.",
+                fix="Put the site behind HTTPS with a free certificate (e.g. Let's "
+                "Encrypt via your host or certbot), then redirect all HTTP to HTTPS.",
+                url=base + "/",
+            )
+        ]
+    host = base.split("://", 1)[1].split("/", 1)[0].split(":")[0]
+    try:
+        cert, version = _cert_info(host, 443)
+    except Exception:
+        return [
+            Finding(
+                check="tls",
+                severity="info",
+                title="Could not verify TLS certificate",
+                meaning="The TLS handshake did not complete from here, so the "
+                "certificate could not be checked. This may be a network issue.",
+                fix="Check the certificate manually and ensure it is valid.",
+                url=base + "/",
+            )
+        ]
+    findings = []
+    try:
+        not_after = cert.get("notAfter")
+        exp = datetime.datetime.strptime(not_after, "%b %d %H:%M:%S %Y %Z")
+        days = (exp - datetime.datetime.utcnow()).days
+        if days < 0:
+            findings.append(
+                Finding(
+                    check="tls", severity="critical",
+                    title="TLS certificate has expired",
+                    meaning="Browsers show visitors a full-page security warning, and "
+                    "the encryption cannot be trusted.",
+                    fix="Renew the certificate immediately and automate renewal.",
+                    evidence="expired %d days ago" % abs(days), url=base + "/",
+                )
+            )
+        elif days < 30:
+            findings.append(
+                Finding(
+                    check="tls", severity="medium",
+                    title="TLS certificate expires in %d days" % days,
+                    meaning="When it lapses, visitors get scary browser warnings and "
+                    "may not come back.",
+                    fix="Renew soon, and automate renewal so it never lapses.",
+                    evidence="expires %s" % not_after, url=base + "/",
+                )
+            )
+    except Exception:
+        pass
+    if version and version in ("TLSv1", "TLSv1.1", "SSLv2", "SSLv3"):
+        findings.append(
+            Finding(
+                check="tls", severity="high",
+                title="Outdated TLS version negotiated (%s)" % version,
+                meaning="Old TLS versions have known attacks that let eavesdroppers "
+                "decrypt traffic.",
+                fix="Disable everything below TLS 1.2 on your server.",
+                evidence="negotiated %s" % version, url=base + "/",
+            )
+        )
+    return findings

hackable/checks/xss.py

@@ -0,0 +1,83 @@
+"""Reflected cross-site scripting (XSS) probe.
+
+We inject a unique, inert marker tag and check whether it comes back
+unescaped. We never execute JavaScript.
+"""
+
+import secrets
+import string
+
+from ..findings import Finding
+
+CANDIDATES = [
+    ("/search", "q"),
+    ("/hello", "name"),
+    ("/greet", "name"),
+    ("", "q"),
+    ("", "search"),
+    ("/user", "name"),
+]
+
+
+def _pairs(base, targets):
+    pairs, seen = [], set()
+    for url, params in (targets or [])[:8]:
+        for param in params[:3]:
+            key = (url, param)
+            if key not in seen:
+                seen.add(key)
+                pairs.append(key)
+    for path, param in CANDIDATES:
+        key = (base + path, param)
+        if key not in seen:
+            seen.add(key)
+            pairs.append(key)
+    return pairs[:14]
+
+
+def run(base, http, targets=None):
+    findings = []
+    token = "hkx" + "".join(
+        secrets.choice(string.ascii_lowercase + string.digits) for _ in range(6)
+    )
+    payload = "<%s>" % token
+    for url, param in _pairs(base, targets):
+        r = http.get(url, params={param: payload})
+        if r is None:
+            continue
+        body = r.text
+        path = url.replace(base, "") or "/"
+        if payload in body:
+            findings.append(
+                Finding(
+                    check="xss",
+                    severity="high",
+                    title="Cross-site scripting in %s" % (path or "/"),
+                    meaning="Whatever I typed into '%s' came straight back inside the "
+                    "page, unescaped. An attacker can replace my text with a "
+                    "script that runs in every visitor's browser: stealing logins, "
+                    "defacing the page, or redirecting to malware." % param,
+                    fix="Escape all user input before putting it into HTML "
+                    "(your template engine usually does this if you let it), and "
+                    "add a Content-Security-Policy header as a seatbelt.",
+                    evidence="payload reflected unescaped at %s" % url,
+                    url=url + "?%s=%s" % (param, payload),
+                )
+            )
+            return findings
+        if token in body:
+            findings.append(
+                Finding(
+                    check="xss",
+                    severity="low",
+                    title="User input reflected in %s (encoded)" % (path or "/"),
+                    meaning="Your input appears in the page but is encoded, so it "
+                    "cannot run as a script today. Still worth a look: one template "
+                    "change could un-encode it.",
+                    fix="Keep output encoding on for this field and add automated "
+                    "XSS tests.",
+                    url=url,
+                )
+            )
+            return findings
+    return findings

hackable/cli.py

@@ -0,0 +1,117 @@
+"""CLI: hackable <target>"""
+
+import argparse
+import sys
+
+from . import __version__
+from .findings import score_findings
+from .polite import PoliteClient
+from .checks import CHECKS
+from .report import render_html, render_json, render_sarif, render_terminal
+from .scanner import scan
+
+CONSENT = """\
+hackable will send ~100 harmless test requests to {target}.
+It never tries to break anything, delete data, or log in as anyone.
+
+Only scan apps you own or have explicit permission to test.
+Scanning without permission may be illegal.
+"""
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="hackable",
+        description="Hack yourself before they do. One-command website security "
+        "check in plain English.",
+    )
+    p.add_argument("target", help="URL of your app, e.g. https://myapp.com")
+    p.add_argument("--yes", "-y", action="store_true",
+                   help="skip the permission confirmation")
+    p.add_argument("--json", action="store_true", help="print machine-readable JSON")
+    p.add_argument("--sarif", metavar="FILE",
+                   help="write SARIF 2.1.0 output to FILE (GitHub code scanning)")
+    p.add_argument("--html", metavar="FILE",
+                   help="also write a self-contained HTML report to FILE")
+    p.add_argument("--only", metavar="CHECKS",
+                   help="run only these checks, comma-separated "
+                   "(e.g. sqli,xss). choices: " + ",".join(c[0] for c in CHECKS))
+    p.add_argument("--skip", metavar="CHECKS",
+                   help="skip these checks, comma-separated")
+    p.add_argument("--color", choices=["auto", "always", "never"], default="auto")
+    p.add_argument("--fail-under", type=int, metavar="SCORE",
+                   help="exit 1 if the score is below SCORE (for CI)")
+    p.add_argument("--max-requests", type=int, default=150)
+    p.add_argument("--timeout", type=float, default=8)
+    p.add_argument("--delay", type=float, default=0.15,
+                   help="seconds between requests (be nice)")
+    p.add_argument("--version", action="version", version="hackable " + __version__)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+
+    if not args.yes and sys.stdin.isatty():
+        print(CONSENT.format(target=args.target))
+        try:
+            answer = input("Continue? [y/N] ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            print("\nAborted.")
+            return 130
+        if answer not in ("y", "yes"):
+            print("Aborted. Only ever scan with permission.")
+            return 130
+    elif not args.yes:
+        print("Not a terminal: pass --yes to confirm you have permission to scan.",
+              file=sys.stderr)
+        return 2
+
+    http = PoliteClient(delay=args.delay, timeout=args.timeout,
+                        max_requests=args.max_requests)
+
+    def split(s):
+        return {c.strip() for c in s.split(",") if c.strip()} if s else None
+
+    include, exclude = split(args.only), split(args.skip)
+    known = {c[0] for c in CHECKS}
+    for cid in (include or set()) | (exclude or set()):
+        if cid not in known:
+            print("Unknown check: %s (choices: %s)" % (cid, ",".join(sorted(known))),
+                  file=sys.stderr)
+            return 2
+
+    def on_check(label):
+        if not args.json:
+            print("  checking %-28s" % label, flush=True)
+
+    base, findings, elapsed, req_count = scan(
+        args.target, http, on_check=on_check, include=include, exclude=exclude)
+
+    use_color = (
+        args.color == "always"
+        or (args.color == "auto" and sys.stdout.isatty())
+    )
+    if args.json:
+        print(render_json(findings, base, elapsed, req_count))
+    else:
+        print(render_terminal(findings, base, elapsed, req_count, use_color=use_color))
+
+    if args.sarif:
+        with open(args.sarif, "w") as fh:
+            fh.write(render_sarif(findings, base, elapsed, req_count))
+        print("SARIF report written to %s" % args.sarif)
+
+    if args.html:
+        with open(args.html, "w") as fh:
+            fh.write(render_html(findings, base, elapsed, req_count))
+        print("HTML report written to %s" % args.html)
+
+    score, _grade = score_findings(findings)
+    if args.fail_under is not None and score < args.fail_under:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hackable/crawler.py

@@ -0,0 +1,98 @@
+"""Mini-crawler: discover the app's real inputs before probing.
+
+Guessing common parameter names (q, id, search...) works, but testing the
+app's actual links and forms is far more effective. The crawler walks
+same-origin pages breadth-first and returns (url, [param names]) pairs that
+the injection checks probe first.
+"""
+
+from html.parser import HTMLParser
+from urllib.parse import urljoin, urlparse, parse_qsl
+
+
+class _PageParser(HTMLParser):
+    def __init__(self):
+        super().__init__()
+        self.links = []
+        self.forms = []  # list of (action, method, [input names])
+        self._current = None
+
+    def handle_starttag(self, tag, attrs):
+        a = dict(attrs)
+        if tag == "a" and a.get("href"):
+            self.links.append(a["href"])
+        elif tag == "form":
+            self._current = (a.get("action", ""),
+                             a.get("method", "get").lower(), [])
+            self.forms.append(self._current)
+        elif tag in ("input", "textarea", "select") and self._current is not None:
+            if a.get("name"):
+                self._current[2].append(a["name"])
+
+    def handle_endtag(self, tag):
+        if tag == "form":
+            self._current = None
+
+
+def _same_origin(a, b):
+    pa, pb = urlparse(a), urlparse(b)
+    return (pa.scheme, pa.hostname, pa.port) == (pb.scheme, pb.hostname, pb.port)
+
+
+def _clean(url):
+    p = urlparse(url)
+    return p.scheme + "://" + p.netloc + p.path
+
+
+def discover(base, http, max_pages=20):
+    """Crawl same-origin pages, return [(url, [params...]), ...]."""
+    seen = set()
+    queue = [base + "/"]
+    found = []
+    seen_pairs = set()
+    pages = 0
+
+    while queue and pages < max_pages:
+        url = queue.pop(0)
+        if url in seen:
+            continue
+        seen.add(url)
+        r = http.get(url)
+        pages += 1
+        if r is None or r.status_code != 200:
+            continue
+        if "html" not in r.headers.get("content-type", "").lower():
+            continue
+        parser = _PageParser()
+        try:
+            parser.feed(r.text)
+        except Exception:
+            continue
+
+        for href in parser.links:
+            absolute = urljoin(url, href).split("#")[0]
+            if not _same_origin(absolute, base):
+                continue
+            clean = _clean(absolute)
+            query = parse_qsl(urlparse(absolute).query)
+            if query:
+                key = (clean, tuple(sorted(n for n, _ in query)))
+                if key not in seen_pairs:
+                    seen_pairs.add(key)
+                    found.append((clean, [n for n, _ in query]))
+            if clean not in seen and len(queue) < max_pages * 3:
+                queue.append(clean)
+
+        for action, _method, inputs in parser.forms:
+            if not inputs:
+                continue
+            absolute = urljoin(url, action or url).split("#")[0]
+            if not _same_origin(absolute, base):
+                continue
+            clean = _clean(absolute)
+            key = (clean, tuple(sorted(inputs)))
+            if key not in seen_pairs:
+                seen_pairs.add(key)
+                found.append((clean, inputs))
+
+    return found

hackable/findings.py

@@ -0,0 +1,43 @@
+"""Findings: the unit of a hackable report."""
+
+from dataclasses import dataclass
+
+SEVERITIES = ("critical", "high", "medium", "low", "info")
+
+SEVERITY_WEIGHT = {
+    "critical": 25,
+    "high": 15,
+    "medium": 8,
+    "low": 3,
+    "info": 0,
+}
+
+
+@dataclass
+class Finding:
+    check: str       # check id, e.g. "sqli"
+    severity: str    # one of SEVERITIES
+    title: str       # short headline
+    meaning: str     # plain-English: what this means for a non-expert
+    fix: str         # plain-English: how to fix it
+    evidence: str = ""
+    url: str = ""
+
+
+def score_findings(findings):
+    """Return (score 0-100, grade A-F)."""
+    score = 100
+    for f in findings:
+        score -= SEVERITY_WEIGHT.get(f.severity, 0)
+    score = max(0, score)
+    if score >= 90:
+        grade = "A"
+    elif score >= 75:
+        grade = "B"
+    elif score >= 60:
+        grade = "C"
+    elif score >= 40:
+        grade = "D"
+    else:
+        grade = "F"
+    return score, grade

hackable/polite.py

@@ -0,0 +1,47 @@
+"""A polite HTTP client: slow, identifiable, bounded.
+
+hackable only ever sends harmless probe requests (no destructive payloads,
+no DoS-style flooding). This client enforces that politeness in one place:
+a small delay between requests, a hard cap on total requests, timeouts,
+and an honest User-Agent.
+"""
+
+import time
+
+import requests
+
+USER_AGENT = (
+    "hackable/1.0.0 (+https://github.com/Shifu34/hackable; "
+    "automated security self-check; scans only with owner permission)"
+)
+
+
+class PoliteClient:
+    def __init__(self, delay=0.15, timeout=8, max_requests=150):
+        self.session = requests.Session()
+        self.session.headers["User-Agent"] = USER_AGENT
+        self.delay = delay
+        self.timeout = timeout
+        self.max_requests = max_requests
+        self.count = 0
+
+    def request(self, method, url, **kwargs):
+        if self.count >= self.max_requests:
+            raise RuntimeError("request budget exceeded")
+        if self.count:
+            time.sleep(self.delay)
+        kwargs.setdefault("timeout", self.timeout)
+        self.count += 1
+        try:
+            return self.session.request(method, url, **kwargs)
+        except requests.RequestException:
+            return None
+
+    def get(self, url, **kwargs):
+        return self.request("GET", url, **kwargs)
+
+    def post(self, url, **kwargs):
+        return self.request("POST", url, **kwargs)
+
+    def options(self, url, **kwargs):
+        return self.request("OPTIONS", url, **kwargs)