loginscan 0.1.0__py3-none-any.whl

loginscan/__init__.py

@@ -0,0 +1,17 @@
+"""loginscan - a lightweight, dependency-free self-audit scanner for login endpoints.
+
+Only use it against systems you own or are authorized to test. It does not crack
+passwords and runs low-volume; the goal is to detect issues and suggest fixes.
+"""
+from .authorization import AUTHORIZATION_NOTICE, NotAuthorized
+from .models import Finding, ScanConfig, Severity, Status
+from .report import Report
+from .scanner import Scanner
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Scanner", "ScanConfig", "Report", "Finding",
+    "Severity", "Status", "NotAuthorized", "AUTHORIZATION_NOTICE",
+    "__version__",
+]

loginscan/authorization.py

@@ -0,0 +1,22 @@
+"""Authorization gate. Only scan systems you own or are permitted to test."""
+from __future__ import annotations
+
+AUTHORIZATION_NOTICE = (
+    "WARNING: loginscan must only be used against systems you own or have written\n"
+    "permission to test. Unauthorized scanning is illegal and unethical. By scanning,\n"
+    "you assert that you are authorized to test the target."
+)
+
+
+class NotAuthorized(Exception):
+    pass
+
+
+def ensure_authorized(authorized: bool) -> None:
+    if not authorized:
+        raise NotAuthorized(
+            "Scan refused: authorization not confirmed.\n\n"
+            + AUTHORIZATION_NOTICE
+            + "\n\nPython API: Scanner(config, authorized=True)\n"
+            "CLI:        add the --i-own-this flag."
+        )

loginscan/checks/__init__.py

@@ -0,0 +1,11 @@
+"""Check modules. Each exposes run(client, cfg) -> List[Finding]."""
+from . import (cookies, csrf, enumeration, headers, jwt, open_redirect,
+               ratelimit, session, sqli)
+
+# enumeration runs before sqli so sqli's many failed logins don't trip the
+# target's rate limiter and pollute the enumeration measurement.
+ALL_CHECKS = [headers, csrf, open_redirect, enumeration, sqli, cookies,
+              session, jwt, ratelimit]
+
+__all__ = ["ALL_CHECKS", "sqli", "enumeration", "ratelimit", "cookies", "session",
+           "headers", "csrf", "jwt", "open_redirect"]

loginscan/checks/base.py

@@ -0,0 +1,77 @@
+"""Shared helpers: build login data, get a baseline failed login, guess success."""
+from __future__ import annotations
+
+import re
+import secrets
+from typing import Dict, List, Optional
+
+from ..http import HttpClient, Response
+from ..models import ScanConfig
+
+SQL_ERROR_SIGNS = [
+    "sql syntax", "sqlite3.", "sqlite error", "psycopg2", "pg::",
+    "mysql_fetch", "you have an error in your sql",
+    "unclosed quotation mark", "quoted string not properly terminated",
+    "odbc", "ora-0", "syntax error", "sqlalchemy",
+]
+
+SESSION_COOKIE_HINT = re.compile(r"sess|token|auth|sid|jwt|login", re.I)
+
+
+def random_username(prefix: str = "nouser") -> str:
+    return f"{prefix}_{secrets.token_hex(4)}"
+
+
+def build_data(cfg: ScanConfig, username: str, password: str) -> Dict[str, str]:
+    data = dict(cfg.extra_fields)
+    data[cfg.username_field] = username
+    data[cfg.password_field] = password
+    return data
+
+
+def submit_login(client: HttpClient, cfg: ScanConfig, username: str, password: str) -> Response:
+    return client.request(cfg.method, cfg.url, data=build_data(cfg, username, password),
+                          content_type=cfg.content_type)
+
+
+def cookie_names(resp: Response) -> List[str]:
+    return [c.split("=", 1)[0].strip() for c in resp.set_cookies if c.split("=", 1)[0].strip()]
+
+
+def session_cookies(resp: Response) -> List[str]:
+    return [n for n in cookie_names(resp) if SESSION_COOKIE_HINT.search(n)]
+
+
+def baseline_fail(client: HttpClient, cfg: ScanConfig) -> Response:
+    return submit_login(client, cfg, random_username(), "wrong_" + secrets.token_hex(3))
+
+
+def has_sql_error(body: str) -> Optional[str]:
+    low = body.lower()
+    for sign in SQL_ERROR_SIGNS:
+        if sign in low:
+            return sign
+    return None
+
+
+def looks_like_success(resp: Response, baseline: Response, cfg: ScanConfig) -> Optional[str]:
+    """Return a reason string if resp looks like a successful login, else None.
+
+    Conservative on purpose to limit false positives; evidence goes in the report.
+    """
+    for token in cfg.success_indicators:
+        if token and token.lower() in resp.body.lower():
+            return f"success text seen in response: '{token}'"
+
+    new_sess = set(session_cookies(resp)) - set(session_cookies(baseline))
+    if new_sess:
+        return f"session cookie set that the failed baseline did not get: {sorted(new_sess)}"
+
+    if resp.status < 400 and baseline.status >= 400:
+        return f"status upgraded vs failed baseline (HTTP {resp.status} vs {baseline.status})"
+
+    if 300 <= resp.status < 400 and not (300 <= baseline.status < 400):
+        loc = resp.header("location") or "?"
+        return f"redirect not present in failed baseline (HTTP {resp.status} -> {loc})"
+
+    return None

loginscan/checks/cookies.py

@@ -0,0 +1,61 @@
+"""Session cookie flag check: HttpOnly, Secure, SameSite."""
+from __future__ import annotations
+
+from typing import List
+from urllib.parse import urlparse
+
+from ..http import HttpClient
+from ..models import Finding, ScanConfig, Severity, Status
+from .base import baseline_fail
+
+CHECK = "cookies"
+
+
+def _parse_flags(raw: str) -> dict:
+    name = raw.split("=", 1)[0].strip() if raw else "?"
+    low = raw.lower()
+    return {
+        "name": name,
+        "httponly": "httponly" in low,
+        "secure": "secure" in low,
+        "samesite": "samesite" in low,
+    }
+
+
+def run(client: HttpClient, cfg: ScanConfig) -> List[Finding]:
+    resp = baseline_fail(client, cfg)
+    is_https = urlparse(cfg.url).scheme == "https"
+
+    if not resp.set_cookies:
+        return [Finding(
+            check=CHECK, status=Status.SKIPPED, severity=Severity.INFO,
+            title="No cookies to inspect",
+            detail="No Set-Cookie on this request (session may be set only on successful login).",
+        )]
+
+    findings: List[Finding] = []
+    for raw in resp.set_cookies:
+        f = _parse_flags(raw)
+        missing = []
+        if not f["httponly"]:
+            missing.append("HttpOnly")
+        if is_https and not f["secure"]:
+            missing.append("Secure")
+        if not f["samesite"]:
+            missing.append("SameSite")
+
+        if missing:
+            findings.append(Finding(
+                check=CHECK, status=Status.VULNERABLE, severity=Severity.MEDIUM,
+                title=f"Cookie missing security flags: {f['name']}",
+                detail=f"Missing: {', '.join(missing)}.",
+                remediation="Set HttpOnly, Secure and SameSite=Lax/Strict on session cookies.",
+                evidence={"cookie": f["name"], "missing": missing},
+            ))
+        else:
+            findings.append(Finding(
+                check=CHECK, status=Status.OK, severity=Severity.INFO,
+                title=f"Cookie flags complete: {f['name']}",
+                detail="HttpOnly / Secure / SameSite present.",
+            ))
+    return findings

loginscan/checks/csrf.py

@@ -0,0 +1,44 @@
+"""CSRF protection check (passive).
+
+Looks at the login page for a defense: a CSRF token field/meta, a CSRF cookie,
+or a SameSite cookie. If none is present, CSRF is likely possible.
+"""
+from __future__ import annotations
+
+import re
+from typing import List
+
+from ..http import HttpClient
+from ..models import Finding, ScanConfig, Severity, Status
+
+CHECK = "csrf"
+
+_TOKEN_INPUT = re.compile(
+    r'<input[^>]*name=["\']?[^"\'>\s]*(?:csrf|xsrf|authenticity|_token)[^"\'>\s]*', re.I)
+_META_TOKEN = re.compile(r'<meta[^>]+name=["\'](?:csrf|xsrf)[-_]?token["\']', re.I)
+_CSRF_COOKIE = re.compile(r"csrf|xsrf", re.I)
+
+
+def run(client: HttpClient, cfg: ScanConfig) -> List[Finding]:
+    page = client.get(cfg.login_page_url or cfg.url)
+    body = page.body
+
+    has_token = bool(_TOKEN_INPUT.search(body) or _META_TOKEN.search(body))
+    has_csrf_cookie = any(_CSRF_COOKIE.search(c.split("=", 1)[0]) for c in page.set_cookies)
+    has_samesite = any("samesite" in c.lower() for c in page.set_cookies)
+
+    if has_token or has_csrf_cookie or has_samesite:
+        how = ("CSRF token" if has_token else
+               "CSRF cookie" if has_csrf_cookie else "SameSite cookie")
+        return [Finding(
+            check=CHECK, status=Status.OK, severity=Severity.INFO,
+            title="CSRF defense present",
+            detail=f"Found a CSRF defense on the login page ({how}).",
+        )]
+
+    return [Finding(
+        check=CHECK, status=Status.WARNING, severity=Severity.MEDIUM,
+        title="No CSRF protection detected on login",
+        detail="No CSRF token, CSRF cookie, or SameSite cookie found; login may be forgeable.",
+        remediation="Add a per-session CSRF token to the login form or set SameSite=Lax/Strict on cookies.",
+    )]

loginscan/checks/enumeration.py

@@ -0,0 +1,74 @@
+"""User enumeration detection: does the server treat existing vs unknown users differently?"""
+from __future__ import annotations
+
+from typing import List
+
+from ..http import HttpClient
+from ..models import Finding, ScanConfig, Severity, Status
+from .base import random_username, submit_login
+
+CHECK = "enumeration"
+
+LEN_DIFF_RATIO = 0.15
+TIME_DIFF_SECONDS = 0.5
+
+
+def _norm_body(text: str) -> str:
+    return " ".join(text.split())[:400].lower()
+
+
+def run(client: HttpClient, cfg: ScanConfig) -> List[Finding]:
+    wrong_pw = "wrong-Password-123"
+    r_absent = submit_login(client, cfg, random_username("ghost"), wrong_pw)
+
+    if not cfg.known_username:
+        r_absent2 = submit_login(client, cfg, random_username("ghost2"), wrong_pw)
+        consistent = _norm_body(r_absent.body) == _norm_body(r_absent2.body)
+        return [Finding(
+            check=CHECK, status=Status.SKIPPED, severity=Severity.INFO,
+            title="Enumeration test limited (no known_username)",
+            detail=("Provide a username that really exists (password not needed) for a full test. "
+                    + ("Two unknown-user responses were consistent."
+                       if consistent else "Two unknown-user responses differed, which is suspicious.")),
+            remediation="Re-run with --user / known_username.",
+        )]
+
+    r_present = submit_login(client, cfg, cfg.known_username, wrong_pw)
+
+    if 429 in (r_present.status, r_absent.status):
+        return [Finding(
+            check=CHECK, status=Status.SKIPPED, severity=Severity.INFO,
+            title="Enumeration test unreliable due to rate limiting",
+            detail="One request returned HTTP 429, so the responses cannot be compared fairly.",
+            remediation="Re-run with a higher --delay or after the rate-limit window resets.",
+            evidence={"http": f"{r_present.status} vs {r_absent.status}"},
+        )]
+
+    body_diff = _norm_body(r_present.body) != _norm_body(r_absent.body)
+    len_a, len_b = len(r_present.body), len(r_absent.body)
+    len_diff = abs(len_a - len_b) / max(len_a, len_b, 1) > LEN_DIFF_RATIO
+    status_diff = r_present.status != r_absent.status
+    time_diff = abs(r_present.elapsed - r_absent.elapsed) > TIME_DIFF_SECONDS
+
+    if body_diff or len_diff or status_diff:
+        return [Finding(
+            check=CHECK, status=Status.VULNERABLE, severity=Severity.MEDIUM,
+            title="User enumeration possible",
+            detail="The server answers existing and unknown users differently; valid usernames leak.",
+            remediation="Return the same generic message and HTTP status in both cases.",
+            evidence={"body_differs": body_diff, "length": f"{len_a} vs {len_b}",
+                      "http": f"{r_present.status} vs {r_absent.status}"},
+        )]
+    if time_diff:
+        return [Finding(
+            check=CHECK, status=Status.WARNING, severity=Severity.LOW,
+            title="Timing difference (possible enumeration)",
+            detail="Bodies match but response times differ, hinting password hashing runs only for real users.",
+            remediation="Run a dummy hash verification for unknown users to equalize timing.",
+            evidence={"time": f"{r_present.elapsed:.3f}s vs {r_absent.elapsed:.3f}s"},
+        )]
+    return [Finding(
+        check=CHECK, status=Status.OK, severity=Severity.INFO,
+        title="Responses consistent against enumeration",
+        detail="Existing and unknown users were indistinguishable.",
+    )]

loginscan/checks/headers.py

@@ -0,0 +1,88 @@
+"""Transport and security-header checks (HTTPS, HSTS, nosniff, clickjacking, etc.)."""
+from __future__ import annotations
+
+from typing import List
+from urllib.parse import urlparse
+
+from ..http import HttpClient
+from ..models import Finding, ScanConfig, Severity, Status
+
+CHECK = "headers"
+
+
+def run(client: HttpClient, cfg: ScanConfig) -> List[Finding]:
+    findings: List[Finding] = []
+    parsed = urlparse(cfg.url)
+    is_https = parsed.scheme == "https"
+
+    if not is_https:
+        findings.append(Finding(
+            check=CHECK, status=Status.VULNERABLE, severity=Severity.HIGH,
+            title="Login is not served over HTTPS",
+            detail="Username and password travel unencrypted; anyone on the network can read them.",
+            remediation="Serve the whole site over HTTPS and redirect HTTP to HTTPS.",
+            evidence={"scheme": parsed.scheme},
+        ))
+
+    probe_url = cfg.login_page_url or cfg.url
+    try:
+        resp = client.get(probe_url)
+    except Exception as e:  # noqa: BLE001
+        findings.append(Finding(
+            check=CHECK, status=Status.SKIPPED, severity=Severity.INFO,
+            title="Could not read headers",
+            detail=f"GET {probe_url} failed: {e}",
+        ))
+        return findings
+
+    def missing(header: str) -> bool:
+        return resp.header(header) is None
+
+    csp = (resp.header("content-security-policy") or "").lower()
+
+    if is_https and missing("strict-transport-security"):
+        findings.append(Finding(
+            check=CHECK, status=Status.WARNING, severity=Severity.LOW,
+            title="Missing HSTS header",
+            detail="No Strict-Transport-Security; a first request may be downgraded to HTTP.",
+            remediation="Add Strict-Transport-Security: max-age=31536000; includeSubDomains.",
+        ))
+    if missing("x-content-type-options"):
+        findings.append(Finding(
+            check=CHECK, status=Status.WARNING, severity=Severity.LOW,
+            title="Missing X-Content-Type-Options",
+            detail="No nosniff; the browser may MIME-sniff responses.",
+            remediation="Add X-Content-Type-Options: nosniff.",
+        ))
+    if missing("x-frame-options") and "frame-ancestors" not in csp:
+        findings.append(Finding(
+            check=CHECK, status=Status.WARNING, severity=Severity.MEDIUM,
+            title="No clickjacking protection",
+            detail="No X-Frame-Options or CSP frame-ancestors; the login page can be framed.",
+            remediation="Add X-Frame-Options: DENY or CSP frame-ancestors 'none'.",
+        ))
+    if missing("referrer-policy"):
+        findings.append(Finding(
+            check=CHECK, status=Status.WARNING, severity=Severity.LOW,
+            title="Missing Referrer-Policy",
+            detail="No Referrer-Policy; sensitive URL data may leak to third parties.",
+            remediation="Add Referrer-Policy: no-referrer or strict-origin-when-cross-origin.",
+        ))
+
+    leak = resp.header("server") or resp.header("x-powered-by")
+    if leak and any(ch.isdigit() for ch in leak):
+        findings.append(Finding(
+            check=CHECK, status=Status.WARNING, severity=Severity.LOW,
+            title="Server/tech version disclosed",
+            detail=f"Response header reveals version info: '{leak}'.",
+            remediation="Strip version details from Server / X-Powered-By headers.",
+            evidence={"header": leak},
+        ))
+
+    if not any(f.check == CHECK and f.status != Status.VULNERABLE for f in findings):
+        findings.append(Finding(
+            check=CHECK, status=Status.OK, severity=Severity.INFO,
+            title="Core security headers present",
+            detail="No gaps found in HSTS/nosniff/frame protection/Referrer-Policy.",
+        ))
+    return findings

loginscan/checks/jwt.py

@@ -0,0 +1,81 @@
+"""Passive JWT weakness check.
+
+If the login flow exposes a JWT (in a cookie or the response body), inspect its
+header/payload without cracking anything: unsigned tokens (alg=none) and missing
+expiry are flagged.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import re
+from typing import List, Optional
+
+from ..http import HttpClient
+from ..models import Finding, ScanConfig, Severity, Status
+from .base import baseline_fail
+
+CHECK = "jwt"
+
+_JWT_RE = re.compile(r"eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*")
+
+
+def _b64url_json(segment: str) -> Optional[dict]:
+    pad = "=" * (-len(segment) % 4)
+    try:
+        return json.loads(base64.urlsafe_b64decode(segment + pad))
+    except Exception:
+        return None
+
+
+def _find_jwt(client: HttpClient, cfg: ScanConfig) -> Optional[str]:
+    for _, value in client.observed_session_tokens:
+        if _JWT_RE.fullmatch(value):
+            return value
+    resp = baseline_fail(client, cfg)
+    for cookie in resp.set_cookies:
+        m = _JWT_RE.search(cookie)
+        if m:
+            return m.group(0)
+    m = _JWT_RE.search(resp.body)
+    return m.group(0) if m else None
+
+
+def run(client: HttpClient, cfg: ScanConfig) -> List[Finding]:
+    token = _find_jwt(client, cfg)
+    if not token:
+        return [Finding(
+            check=CHECK, status=Status.SKIPPED, severity=Severity.INFO,
+            title="No JWT observed",
+            detail="No JSON Web Token seen in cookies or responses; check skipped.",
+        )]
+
+    parts = token.split(".")
+    header = _b64url_json(parts[0]) or {}
+    payload = _b64url_json(parts[1]) if len(parts) > 1 else {}
+    payload = payload or {}
+    alg = str(header.get("alg", "")).lower()
+
+    findings: List[Finding] = []
+    if alg == "none" or (len(parts) >= 3 and parts[2] == ""):
+        findings.append(Finding(
+            check=CHECK, status=Status.VULNERABLE, severity=Severity.CRITICAL,
+            title="JWT is unsigned (alg=none)",
+            detail="The token has no signature, so anyone can forge one and impersonate any user.",
+            remediation="Reject alg=none; verify a strong signature (e.g. RS256/ES256) server-side.",
+            evidence={"alg": header.get("alg")},
+        ))
+    if "exp" not in payload:
+        findings.append(Finding(
+            check=CHECK, status=Status.WARNING, severity=Severity.MEDIUM,
+            title="JWT has no expiry (exp)",
+            detail="Without exp the token never expires; a leaked token stays valid forever.",
+            remediation="Add a short exp claim and validate it on every request.",
+        ))
+    if not findings:
+        findings.append(Finding(
+            check=CHECK, status=Status.OK, severity=Severity.INFO,
+            title="JWT looks acceptable",
+            detail=f"Signed token (alg={header.get('alg')}) with an exp claim.",
+        ))
+    return findings

loginscan/checks/open_redirect.py

@@ -0,0 +1,52 @@
+"""Open redirect check.
+
+Sends a benign external sentinel via common redirect parameters and checks
+whether the server issues a redirect (3xx Location) to that external host.
+"""
+from __future__ import annotations
+
+from typing import List
+from urllib.parse import urlencode, urlparse, urlsplit, urlunsplit
+
+from ..http import HttpClient
+from ..models import Finding, ScanConfig, Severity, Status
+
+CHECK = "open_redirect"
+
+REDIRECT_PARAMS = ["next", "redirect", "redirect_uri", "returnUrl", "return_to",
+                   "url", "dest", "continue"]
+SENTINEL = "https://loginscan-external.example/"
+
+
+def _with_query(base_url: str, param: str, value: str) -> str:
+    parts = urlsplit(base_url)
+    query = urlencode({param: value})
+    return urlunsplit((parts.scheme, parts.netloc, parts.path, query, ""))
+
+
+def run(client: HttpClient, cfg: ScanConfig) -> List[Finding]:
+    base = cfg.login_page_url or cfg.url
+    sentinel_host = urlparse(SENTINEL).netloc
+
+    for param in REDIRECT_PARAMS:
+        if client.remaining <= 0:
+            break
+        try:
+            resp = client.get(_with_query(base, param, SENTINEL))
+        except Exception:  # noqa: BLE001
+            continue
+        location = resp.header("location") or ""
+        if 300 <= resp.status < 400 and sentinel_host in location:
+            return [Finding(
+                check=CHECK, status=Status.VULNERABLE, severity=Severity.MEDIUM,
+                title="Open redirect via login parameter",
+                detail=f"'{param}' is reflected into a redirect to an external host without validation.",
+                remediation="Allow redirects only to a fixed allowlist of internal paths/hosts.",
+                evidence={"param": param, "location": location},
+            )]
+
+    return [Finding(
+        check=CHECK, status=Status.OK, severity=Severity.INFO,
+        title="No open redirect via common parameters",
+        detail="Common redirect parameters did not trigger an external redirect.",
+    )]

loginscan/checks/ratelimit.py

@@ -0,0 +1,58 @@
+"""Brute-force protection presence check.
+
+Not a brute-forcer: it sends a few failed attempts with a fixed dummy password
+and only checks whether the server starts blocking. It never tries to crack anything.
+"""
+from __future__ import annotations
+
+from typing import List
+
+from ..http import HttpClient, RequestBudgetExceeded
+from ..models import Finding, ScanConfig, Severity, Status
+from .base import random_username, submit_login
+
+CHECK = "ratelimit"
+
+BLOCK_STATUSES = {429, 403, 503}
+BLOCK_HINTS = ["too many", "rate limit", "try again later", "captcha", "locked", "blocked"]
+
+
+def run(client: HttpClient, cfg: ScanConfig, attempts: int = 6) -> List[Finding]:
+    target_user = cfg.known_username or random_username("probe")
+    wrong_pw = "definitely-wrong-pw"
+
+    statuses = []
+    blocked_at = None
+    try:
+        for i in range(1, attempts + 1):
+            if client.remaining <= 0:
+                break
+            resp = submit_login(client, cfg, target_user, wrong_pw)
+            statuses.append(resp.status)
+            low = resp.body.lower()
+            if resp.status in BLOCK_STATUSES or any(h in low for h in BLOCK_HINTS):
+                blocked_at = i
+                break
+    except RequestBudgetExceeded:
+        pass
+
+    if blocked_at:
+        return [Finding(
+            check=CHECK, status=Status.OK, severity=Severity.INFO,
+            title="Brute-force protection active",
+            detail=f"Server blocked at attempt {blocked_at} (rate limiting present).",
+            evidence={"statuses": statuses},
+        )]
+    if not statuses:
+        return [Finding(
+            check=CHECK, status=Status.SKIPPED, severity=Severity.INFO,
+            title="Rate-limit test could not run",
+            detail="Request budget was exhausted.",
+        )]
+    return [Finding(
+        check=CHECK, status=Status.VULNERABLE, severity=Severity.MEDIUM,
+        title="No brute-force protection",
+        detail=f"{len(statuses)} failed attempts in a row were accepted without blocking.",
+        remediation="Add IP- and account-based rate limiting; use delays/CAPTCHA/temporary lockout.",
+        evidence={"attempts": len(statuses), "statuses": statuses},
+    )]

loginscan/checks/session.py

@@ -0,0 +1,70 @@
+"""Session token strength check: predictable, short, sequential or low-entropy tokens."""
+from __future__ import annotations
+
+import math
+from collections import Counter
+from typing import List
+
+from ..http import HttpClient
+from ..models import Finding, ScanConfig, Severity, Status
+
+CHECK = "session"
+
+MIN_TOKEN_LEN = 16
+
+
+def _entropy_bits(s: str) -> float:
+    if not s:
+        return 0.0
+    counts = Counter(s)
+    n = len(s)
+    per_char = -sum((c / n) * math.log2(c / n) for c in counts.values())
+    return per_char * n
+
+
+def run(client: HttpClient, cfg: ScanConfig) -> List[Finding]:
+    tokens = [v for _, v in client.observed_session_tokens]
+    if not tokens:
+        return [Finding(
+            check=CHECK, status=Status.SKIPPED, severity=Severity.INFO,
+            title="No session token observed",
+            detail="Server issued no session token here (usually set only on success). Skipped.",
+        )]
+
+    uniq = list(dict.fromkeys(tokens))
+    sample = uniq[0]
+
+    numeric = [t for t in uniq if t.isdigit()]
+    if len(numeric) >= 2:
+        nums = sorted(int(t) for t in numeric)
+        if all(b - a == 1 for a, b in zip(nums, nums[1:])):
+            return [Finding(
+                check=CHECK, status=Status.VULNERABLE, severity=Severity.HIGH,
+                title="Session token is sequential and predictable",
+                detail=f"Tokens are consecutive numbers: {nums}. An attacker can guess other sessions.",
+                remediation="Use cryptographically random tokens (e.g. secrets.token_urlsafe(32)); never counters.",
+                evidence={"samples": nums[:5]},
+            )]
+
+    reasons = []
+    if len(sample) < MIN_TOKEN_LEN:
+        reasons.append(f"too short ({len(sample)} chars)")
+    if sample.isdigit():
+        reasons.append("all numeric")
+    entropy = _entropy_bits(sample)
+    if entropy < 64:
+        reasons.append(f"low entropy (~{entropy:.0f} bits)")
+
+    if reasons:
+        return [Finding(
+            check=CHECK, status=Status.WARNING, severity=Severity.MEDIUM,
+            title="Session token looks weak",
+            detail="Weak on: " + ", ".join(reasons) + ".",
+            remediation="Use a cryptographically random token with at least 128 bits of entropy.",
+            evidence={"sample_len": len(sample), "entropy_bits": round(entropy)},
+        )]
+    return [Finding(
+        check=CHECK, status=Status.OK, severity=Severity.INFO,
+        title="Session token looks reasonable",
+        detail=f"Length {len(sample)}, ~{entropy:.0f} bits of entropy.",
+    )]