hackable 1.0.0__py3-none-any.whl

hackable/report.py

@@ -0,0 +1,244 @@
+"""Reports: terminal, JSON, and self-contained HTML."""
+
+import html
+import json
+from datetime import datetime, timezone
+
+from . import __version__
+from .findings import SEVERITIES, score_findings
+
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+
+SEV_COLOR = {
+    "critical": "\033[1;31m",
+    "high": "\033[31m",
+    "medium": "\033[33m",
+    "low": "\033[34m",
+    "info": "\033[90m",
+}
+
+SEV_ICON = {
+    "critical": "\u2716",  # ✖
+    "high": "\u2716",
+    "medium": "!",
+    "low": "i",
+    "info": "\u2139",
+}
+
+VERDICTS = {
+    "A": "Solid. Scan again after every deploy to stay here.",
+    "B": "Good shape. Fix the mediums when you get an afternoon.",
+    "C": "Shaky. The highs above are worth fixing this week.",
+    "D": "Risky. An attacker would enjoy this site.",
+    "F": "A beginner hacker could break in within minutes. Fix the criticals today.",
+}
+
+SEV_CSS = {
+    "critical": "#ff5555",
+    "high": "#ff8c42",
+    "medium": "#f1c40f",
+    "low": "#5aa9ff",
+    "info": "#8a8f98",
+}
+
+
+def _c(text, code, use_color):
+    return "%s%s%s" % (code, text, RESET) if use_color else text
+
+
+def render_terminal(findings, base, elapsed, req_count, use_color=True):
+    score, grade = score_findings(findings)
+    L = []
+    c = lambda t, code: _c(t, code, use_color)  # noqa: E731
+
+    L.append("")
+    L.append(c("hackable v" + __version__, BOLD) + c("  -  hack yourself before they do.", DIM))
+    L.append("")
+    L.append("Target: %s   (%d requests in %.1fs)" % (base, req_count, elapsed))
+    L.append("")
+
+    grouped = {s: [f for f in findings if f.severity == s] for s in SEVERITIES}
+    if not findings:
+        L.append(c("No issues found. Either your site is solid, or it hid well.", BOLD))
+    for sev in SEVERITIES:
+        items = grouped[sev]
+        if not items:
+            continue
+        L.append(c("%s (%d)" % (sev.upper(), len(items)), SEV_COLOR[sev] + BOLD))
+        for f in items:
+            L.append(
+                "  %s %s"
+                % (c(SEV_ICON[sev], SEV_COLOR[sev]), c(f.title, BOLD))
+            )
+            L.append("    What this means: %s" % f.meaning)
+            L.append("    Fix: %s" % f.fix)
+            if f.url:
+                L.append(c("    Found at: %s" % f.url, DIM))
+            if f.evidence:
+                ev = f.evidence.replace("\n", " ")
+                L.append(c("    Evidence: %s%s" % (ev[:140], "..." if len(ev) > 140 else ""), DIM))
+        L.append("")
+
+    L.append(c("-" * 60, DIM))
+    L.append(
+        "SCORE  %s   GRADE  %s"
+        % (c("%d/100" % score, BOLD), c(grade, SEV_COLOR["critical"] if grade in "DF" else BOLD))
+    )
+    L.append(VERDICTS[grade])
+    L.append("")
+    return "\n".join(L)
+
+
+def render_json(findings, base, elapsed, req_count):
+    score, grade = score_findings(findings)
+    return json.dumps(
+        {
+            "tool": "hackable " + __version__,
+            "target": base,
+            "scanned_at": datetime.now(timezone.utc).isoformat(),
+            "requests": req_count,
+            "elapsed_s": round(elapsed, 1),
+            "score": score,
+            "grade": grade,
+            "findings": [
+                {
+                    "check": f.check,
+                    "severity": f.severity,
+                    "title": f.title,
+                    "meaning": f.meaning,
+                    "fix": f.fix,
+                    "evidence": f.evidence,
+                    "url": f.url,
+                }
+                for f in findings
+            ],
+        },
+        indent=2,
+    )
+
+
+SARIF_LEVELS = {
+    "critical": "error",
+    "high": "error",
+    "medium": "warning",
+    "low": "note",
+    "info": "note",
+}
+
+
+def render_sarif(findings, base, elapsed, req_count):
+    """SARIF 2.1.0 output, consumable by GitHub code scanning."""
+    rules, seen = [], set()
+    for f in findings:
+        if f.check not in seen:
+            seen.add(f.check)
+            rules.append({
+                "id": "hackable/" + f.check,
+                "name": f.check.replace("_", " ").title(),
+                "shortDescription": {"text": f.title},
+                "helpUri": "https://github.com/Shifu34/hackable",
+            })
+    results = []
+    for f in findings:
+        results.append({
+            "ruleId": "hackable/" + f.check,
+            "level": SARIF_LEVELS.get(f.severity, "note"),
+            "message": {"text": "%s. %s" % (f.title, f.fix or "")},
+            "locations": [{
+                "physicalLocation": {
+                    "artifactLocation": {"uri": f.url or base},
+                }
+            }],
+        })
+    return json.dumps(
+        {
+            "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+            "version": "2.1.0",
+            "runs": [{
+                "tool": {"driver": {
+                    "name": "hackable",
+                    "version": __version__,
+                    "informationUri": "https://github.com/Shifu34/hackable",
+                    "rules": rules,
+                }},
+                "results": results,
+            }],
+        },
+        indent=2,
+    )
+
+def render_html(findings, base, elapsed, req_count):
+    score, grade = score_findings(findings)
+    esc = html.escape
+    cards = []
+    for f in findings:
+        color = SEV_CSS[f.severity]
+        cards.append(
+            """
+        <div class="card">
+          <div class="card-head" style="border-left-color: {color}">
+            <span class="sev" style="background: {color}">{sev}</span>
+            <span class="title">{title}</span>
+          </div>
+          <p><b>What this means:</b> {meaning}</p>
+          <p><b>How to fix it:</b> {fix}</p>
+          {url}
+          {evidence}
+        </div>""".format(
+                color=color,
+                sev=f.severity.upper(),
+                title=esc(f.title),
+                meaning=esc(f.meaning),
+                fix=esc(f.fix),
+                url='<p class="meta">Found at: <code>%s</code></p>' % esc(f.url) if f.url else "",
+                evidence='<p class="meta">Evidence: <code>%s</code></p>' % esc(f.evidence[:200])
+                if f.evidence
+                else "",
+            )
+        )
+    if not cards:
+        cards.append('<div class="card"><p><b>No issues found.</b></p></div>')
+    return """<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8">
+<title>hackable report: {base}</title>
+<style>
+body {{ font-family: -apple-system, Segoe UI, Roboto, sans-serif; background: #0d1117;
+  color: #e6edf3; max-width: 860px; margin: 0 auto; padding: 32px 20px; }}
+h1 {{ font-size: 22px; }} .dim {{ color: #8a8f98; }}
+.scorebox {{ display: flex; align-items: center; gap: 24px; background: #161b22;
+  border: 1px solid #30363d; border-radius: 12px; padding: 20px 24px; margin: 20px 0; }}
+.score {{ font-size: 56px; font-weight: 800; }}
+.grade {{ font-size: 40px; font-weight: 800; width: 72px; height: 72px; border-radius: 50%;
+  display: flex; align-items: center; justify-content: center; border: 3px solid; }}
+.card {{ background: #161b22; border: 1px solid #30363d; border-radius: 12px;
+  padding: 16px 20px; margin: 14px 0; }}
+.card-head {{ border-left: 5px solid; padding-left: 12px; margin-bottom: 8px;
+  display: flex; align-items: center; gap: 10px; }}
+.sev {{ color: #0d1117; font-weight: 700; font-size: 12px; padding: 3px 8px; border-radius: 6px; }}
+.title {{ font-weight: 700; font-size: 16px; }}
+.meta {{ color: #8a8f98; font-size: 13px; }} code {{ font-size: 12.5px; }}
+.footer {{ margin-top: 28px; color: #8a8f98; font-size: 13px; }}
+</style></head><body>
+<h1>hackable report</h1>
+<p class="dim">Target: {base} &middot; {nreq} requests in {elapsed:.1f}s &middot; {date}</p>
+<div class="scorebox">
+  <div class="score">{score}<span style="font-size:22px;color:#8a8f98">/100</span></div>
+  <div class="grade" style="border-color:{gcolor};color:{gcolor}">{grade}</div>
+  <div><b>{verdict}</b></div>
+</div>
+{cards}
+<p class="footer">Generated by hackable " + __version__ + " &mdash; hack yourself before they do.
+Only scan apps you own or have permission to test.</p>
+</body></html>""".format(
+        base=esc(base),
+        nreq=req_count,
+        elapsed=elapsed,
+        date=datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC"),
+        score=score,
+        grade=grade,
+        gcolor="#ff5555" if grade in "DF" else "#f1c40f" if grade == "C" else "#3fb950",
+        verdict=esc(VERDICTS[grade]),
+        cards="\n".join(cards),
+    )

hackable/scanner.py

@@ -0,0 +1,60 @@
+"""Scan orchestration."""
+
+import time
+
+from .checks import CHECKS
+from .crawler import discover
+from .polite import PoliteClient
+
+# checks that probe the crawler's discovered inputs
+INJECTION_CHECKS = ("sqli", "xss", "open_redirect")
+
+
+def normalize_target(target, http):
+    target = target.strip().rstrip("/")
+    if "://" not in target:
+        for scheme in ("https://", "http://"):
+            r = http.get(scheme + target + "/")
+            if r is not None and r.status_code < 500:
+                return scheme + target
+        return "http://" + target
+    return target
+
+
+def scan(target, http=None, on_check=None, include=None, exclude=None):
+    """Run checks. Returns (base_url, findings, elapsed_s, requests_made).
+
+    include/exclude are optional sets of check ids (--only / --skip).
+    """
+    http = http or PoliteClient()
+    base = normalize_target(target, http)
+    findings = []
+    started = time.time()
+
+    wanted = [c for c in CHECKS
+              if (include is None or c[0] in include)
+              and (exclude is None or c[0] not in exclude)]
+
+    discovered = []
+    if any(cid in INJECTION_CHECKS for cid, _l, _f in wanted):
+        if on_check:
+            on_check("mapping the app")
+        try:
+            discovered = discover(base, http)
+        except Exception:
+            discovered = []
+
+    for cid, label, fn in wanted:
+        if on_check:
+            on_check(label)
+        try:
+            if cid in INJECTION_CHECKS:
+                findings.extend(fn(base, http, discovered) or [])
+            else:
+                findings.extend(fn(base, http) or [])
+        except RuntimeError:
+            break  # request budget exceeded: stop gracefully
+        except Exception:
+            continue  # one broken check must never kill the scan
+    elapsed = time.time() - started
+    return base, findings, elapsed, http.count

hackable-1.0.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: hackable
+Version: 1.0.0
+Summary: Hack yourself before they do. One-command website security check for people who have never run a security tool.
+Author: Shafqat Mehmood
+License: MIT
+Project-URL: Homepage, https://github.com/Shifu34/hackable
+Keywords: security,pentest,scanner,web,vulnerability,dast
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# hackable
+
+**Hack yourself before they do.**
+
+One-command website security check for people who have never run a security tool. Point it at your app, and in about ten seconds it tells you, in plain English, how a hacker would break in and exactly how to stop them.
+
+```
+$ pip install hackable
+$ hackable https://myapp.com
+```
+
+![hackable scanning a deliberately vulnerable demo app](demo/demo.gif)
+
+## The problem
+
+Millions of apps are being built with AI right now by people who have never heard of OWASP. The apps work. They also leak database keys, take SQL injection, and let anyone log in as anyone. The existing scanners (ZAP, Nuclei, Burp) are expert tools with expert UX. They might as well be in another language.
+
+hackable is the Let's Encrypt of pentesting: free, one command, plain English.
+
+## What it checks
+
+14 checks. Before probing, hackable crawls your app like a visitor would,
+collecting real links and forms, so injection tests hit your actual inputs
+instead of guessed parameter names.
+
+| Check | What it finds |
+|---|---|
+| SQL injection | Error-based probes plus boolean differential checks (safe, GET-only) |
+| Exposed files | Public `/.env`, `/.git/`, config backups, with content verification (no false alarms from SPA fallbacks) |
+| XSS | Your input reflected unescaped into the page |
+| Open redirects | Your site redirecting visitors to attacker domains |
+| CORS | Arbitrary origins trusted with credentials |
+| Debug mode | Stack traces leaking from error pages |
+| Login rate limiting | 10 rapid wrong passwords, checking for pushback |
+| Security headers | HSTS, CSP, X-Frame-Options, and friends |
+| Cookie flags | Session cookies missing Secure, HttpOnly, or SameSite |
+| TLS | Missing HTTPS, expired certs, ancient TLS versions |
+| Version disclosure | Server headers announcing exact versions |
+| HTTP methods | Risky methods like TRACE |
+| robots.txt | Hidden paths handed to attackers on a plate |
+| security.txt | No standard contact for researchers to report issues |
+
+Every finding comes with **what this means** (one sentence, no jargon) and **how to fix it** (one sentence, actionable). You get a 0-100 score and an A-F grade.
+
+## Output
+
+Terminal report, machine-readable JSON (`--json`), SARIF 2.1.0 for GitHub code
+scanning (`--sarif`), and a self-contained shareable HTML report card
+(`--html report.html`).
+
+```bash
+hackable https://myapp.com --html report.html
+hackable https://myapp.com --fail-under 70   # exit 1 in CI if score < 70
+hackable https://myapp.com --only sqli,xss   # run a subset of checks
+```
+
+## GitHub Action
+
+Drop it into your workflow and every push gets scanned:
+
+```yaml
+- uses: Shifu34/hackable@v1
+  with:
+    target: https://myapp.com
+    fail-under: 70
+```
+
+Results upload to the Security tab automatically.
+
+## Safety
+
+hackable only sends harmless probes: no destructive payloads, no data deletion, no login attempts with real credentials, ~50-150 requests with delays and an identifying User-Agent. It will ask for confirmation before scanning unless you pass `--yes`.
+
+**Only scan apps you own or have explicit permission to test.** Scanning without permission may be illegal.
+
+## Roadmap
+
+- Authenticated scans (test behind a login)
+- JavaScript-rendered app support
+- Scheduled scans with diff alerts
+
+## License
+
+MIT

hackable-1.0.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+hackable/__init__.py,sha256=dZjbcpwg8kXe8j8-QOzByBECRIGLst5KKhUNAjDLgno,69
+hackable/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+hackable/cli.py,sha256=DJMID9N2jVYWF7BgdlxZ0PLuWgnD6C9gREKe8n6enR4,4368
+hackable/crawler.py,sha256=Y-SnvIr_GAeVK36_WL_UjicTMtIjxrb0wxo8BNRBoGg,3174
+hackable/findings.py,sha256=GgIwafofuTzezOgwNVOAlHuD98d0E882kmRFLvmjWtk,975
+hackable/polite.py,sha256=AqRK5-46HlN0ZgfH2inShs7BdWrmxem_5EtqJ8oGwGo,1483
+hackable/report.py,sha256=5mv-mT0SWi2vkTtjdf-g0ktvuQamttUhS20FwX0XuMc,8414
+hackable/scanner.py,sha256=RpV50JkV1WEgJta6psbs8NjvTga4VTrcxXR9-tmOLlE,1875
+hackable/checks/__init__.py,sha256=7KeJ_28kasDva6d6EVYrbcjp9qFl5_j5VuJj4ojID98,1095
+hackable/checks/cookies.py,sha256=23aRpp7uLQxP51OgqdUG7NST82K_PPAA7cvS149SsjM,2464
+hackable/checks/cors.py,sha256=XKLTC14_YuicsSDDsaJJ6BSmTNfTG1G0afyG4PH0D5g,2648
+hackable/checks/debug.py,sha256=uUiVnmVp0gEJzeF8NwcWA7jnSrDY_YDMTwM-rHezFIE,1266
+hackable/checks/disclosure.py,sha256=PwvrEsQDGw5a1-glZxG-BYgSfmKTifHHL6GuG8JGBGI,1129
+hackable/checks/exposed_files.py,sha256=Xd5szLa9_TEA3tjw1s_P_0srhXBjw7y5L-YKiqzIUMY,3933
+hackable/checks/headers.py,sha256=xtqFUHQlYQqSURNyRThd2dwCQ75cIG2sJ_VZGwDgg9I,2452
+hackable/checks/methods.py,sha256=gJcKZN_rGBDq5BD_StpdPBhcSYszaDndsNlgONjxHSs,970
+hackable/checks/open_redirect.py,sha256=DN0GhbPSw8mrnuB6VDrIX_sES87CDDKad-bJu7CK4xI,1908
+hackable/checks/rate_limit.py,sha256=HmESBgfPNi0f1mdH_YBbxneKEVF_ccBM-1ySACjr2oE,1864
+hackable/checks/robots.py,sha256=ZgJTS3hR6DTQPfyOP5oC8aik8fry6kOe7UyfywhWpwg,1068
+hackable/checks/securitytxt.py,sha256=_1MmH7giAx7LqieXnKjMgjDK9gdoQqja4IiOI5ycuV0,903
+hackable/checks/sqli.py,sha256=1yggTDA_o00QtKKYERumDE_KAr7VSd7kCEorwBF6vZ4,5839
+hackable/checks/tls.py,sha256=97zjljxwA7ejj-oZb7JLJwi8VmwVMEeuldnU8wIUCyY,3492
+hackable/checks/xss.py,sha256=V3I1o_HhRPC3zCuVdqzkJKYSS8KhwyVZcL-qBi5qLgA,2868
+hackable-1.0.0.dist-info/licenses/LICENSE,sha256=hPiqvko3E-3DQj4evYl0HLpJAgaXnwIsTSDOB0_PQz8,1072
+hackable-1.0.0.dist-info/METADATA,sha256=y286pySg-C_oTAwojPRjRAJlNV9fDAc2FBmSV0Ot95Y,4009
+hackable-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+hackable-1.0.0.dist-info/entry_points.txt,sha256=3PoYi5B1CfebEKG9oGn0Wpd5493b8ewDsMy6brfM3r4,47
+hackable-1.0.0.dist-info/top_level.txt,sha256=xl05JWEasdJ0My8hhPg-WnE_Kwn0BnczLA5LhHbBl24,9
+hackable-1.0.0.dist-info/RECORD,,

hackable-1.0.0.dist-info/WHEEL

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

hackable-1.0.0.dist-info/entry_points.txt

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

hackable-1.0.0.dist-info/licenses/LICENSE

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

hackable-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+hackable