websec-validator 0.2.6__tar.gz → 0.2.8__tar.gz

{websec_validator-0.2.6/src/websec_validator.egg-info → websec_validator-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: websec-validator
-Version: 0.2.6
+Version: 0.2.8
 Summary: Local-first security recon that briefs your AI coding agent: facts + tailored probe scripts, code-in / artifacts-out. No LLM, no server, no running app.
 Author: Ricardo Accioly
 License: MIT

{websec_validator-0.2.6 → websec_validator-0.2.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "websec-validator"
-version = "0.2.6"
+version = "0.2.8"
 description = "Local-first security recon that briefs your AI coding agent: facts + tailored probe scripts, code-in / artifacts-out. No LLM, no server, no running app."
 readme = "README.md"
 requires-python = ">=3.11"

{websec_validator-0.2.6 → websec_validator-0.2.8}/src/websec_validator/dynamic.py

@@ -308,19 +308,24 @@ def forged_token_bypass(target: str, facts: dict, cookie_names=None,
         base_code, _ = _request(method, url, token=None, data=body)
         if base_code not in (401, 403):
             continue  # only routes that are gated WITHOUT auth tell us anything about forgery
-        attempts = [("Authorization: Bearer", _request(method, url, token=forged, data=body)[0])]
-        for cn in cookie_names:
-            attempts.append((f"cookie:{cn}", _request(method, url, token=None, data=body, cookie=f"{cn}={forged}")[0]))
-        hit = next(((via, code) for via, code in attempts if code in _REACHED_HANDLER), None)
-        if hit:
-            via, fcode = hit
-            row = {"method": method, "path": path, "baseline": base_code, "forged": fcode,
-                   "via": via, "verdict": "BYPASS"}
-            bypassed.append(row)
+        # Bearer first (cheapest, most universal); only forge into each known auth cookie if
+        # Bearer didn't reach the handler — short-circuits to keep request volume (and
+        # rate-limiter pressure) down. cookie_names is what catches cookie-ONLY session apps.
+        hit, bearer_code = None, _request(method, url, token=forged, data=body)[0]
+        if bearer_code in _REACHED_HANDLER:
+            hit = ("Authorization: Bearer", bearer_code)
         else:
-            row = {"method": method, "path": path, "baseline": base_code,
-                   "forged": attempts[0][1], "via": "Authorization: Bearer", "verdict": "rejected"}
+            for cn in (cookie_names or []):
+                cc = _request(method, url, token=None, data=body, cookie=f"{cn}={forged}")[0]
+                if cc in _REACHED_HANDLER:
+                    hit = (f"cookie:{cn}", cc)
+                    break
+        via, fcode = hit if hit else ("Authorization: Bearer", bearer_code)
+        row = {"method": method, "path": path, "baseline": base_code, "forged": fcode,
+               "via": via, "verdict": "BYPASS" if hit else "rejected"}
         results.append(row)
+        if hit:
+            bypassed.append(row)
 
     return {
         "target": target,
@@ -338,8 +343,10 @@ def forged_token_bypass(target: str, facts: dict, cookie_names=None,
 
 def run_unauth(target: str, facts_path: Path, outdir: Path, probe_writes: bool = False) -> dict:
     facts = json.loads(Path(facts_path).read_text())
+    cookie_names = (facts.get("auth") or {}).get("cookie_names")
     res = {"unauth_reachability": unauth_reachability(target, facts),
-           "forged_token_bypass": forged_token_bypass(target, facts, probe_writes=probe_writes)}
+           "forged_token_bypass": forged_token_bypass(target, facts, cookie_names=cookie_names,
+                                                       probe_writes=probe_writes)}
     if probe_writes:
         res["write_auth_enforcement"] = write_auth_enforcement(target, facts)
     outdir.mkdir(parents=True, exist_ok=True)

{websec_validator-0.2.6 → websec_validator-0.2.8}/src/websec_validator/extractors/auth.py

@@ -17,6 +17,15 @@ PASSPORT = re.compile(r"\bpassport\b|passport-jwt|passport-local")
 SESSION = re.compile(r"express-session|cookie-session|iron-session|flask\.session|request\.session|getServerSession|getToken", re.I)
 APIKEY = re.compile(r"x-api-key|api[_-]?key|apikey", re.I)
 GUARDS = re.compile(r"requireAuth|requirePermission|requireRole|isAuthenticated|@login_required|@require|ensureAuth|withAuth|getServerSession|verifyToken|authMiddleware|@roles_required|can\(|ability\.", re.I)
+# Cookie READ sites — the names the app pulls a token/session from. The forged-token probe
+# forges into these (not just Authorization: Bearer) so a cookie-ONLY session app isn't a
+# false negative. Covers cookies.get('X') / cookies['X'] / getCookie('X') / req.cookies.X.
+COOKIE_READ = re.compile(
+    r"""cookies\s*(?:\.get\(|\[)\s*['"]([A-Za-z0-9_.\-]{2,64})['"]"""      # cookies.get('X') / cookies['X']
+    r"""|getCookie\(\s*['"]([A-Za-z0-9_.\-]{2,64})['"]"""                 # getCookie('X')
+    r"""|\.cookies\.([A-Za-z_][A-Za-z0-9_]{1,63})\b(?!\s*\()""")          # req.cookies.X (not a .get()/.set() call)
+_COOKIE_RESERVED = {"get", "set", "getall", "has", "delete", "clear", "tostring",
+                    "foreach", "entries", "keys", "values", "size", "name", "value", "length"}
 
 
 class AuthExtractor(Extractor):
@@ -31,6 +40,7 @@ class AuthExtractor(Extractor):
         # scheme: framework/route signals first, then grep
         jwt = passport = session = apikey = 0
         guard_files = []
+        cookie_names: list[str] = []
         for _p, rel, text in ctx.iter_code():
             if JWT_LIBS.search(text):
                 jwt += 1
@@ -42,6 +52,11 @@ class AuthExtractor(Extractor):
                 apikey += 1
             if GUARDS.search(text) and len(guard_files) < 25:
                 guard_files.append(rel)
+            if len(cookie_names) < 20:
+                for m in COOKIE_READ.finditer(text):
+                    name = m.group(1) or m.group(2) or m.group(3)
+                    if name and name.lower() not in _COOKIE_RESERVED and name not in cookie_names:
+                        cookie_names.append(name)
 
         nextauth = "nextauth" in frameworks or any("nextauth" in e.lower() for e in auth_eps)
 
@@ -70,6 +85,7 @@ class AuthExtractor(Extractor):
             "schemes_detected": detected,
             "token_location": token_location,
             "login_endpoints": auth_eps,
+            "cookie_names": cookie_names[:15],
             "guard_files": guard_files,
             "signal_counts": {"jwt": jwt, "passport": passport, "session": session, "api_key": apikey},
             "note": "AGENT: confirm the PRIMARY auth flow + how a test token is minted before the JWT/auth "

{websec_validator-0.2.6 → websec_validator-0.2.8}/src/websec_validator/probes.py

@@ -111,6 +111,7 @@ def build_context(facts: dict) -> dict:
         "auth": {
             "scheme": auth.get("scheme"),
             "token_location": auth.get("token_location"),
+            "cookie_names": auth.get("cookie_names", []),
             "login_endpoints": tgt.get("auth_endpoints", [])[:10],
             "how_to_authenticate": "cookie-session (e.g. NextAuth) → send the session cookie; "
                                    "bearer → Authorization: Bearer <jwt>; api-key → the documented key header",

{websec_validator-0.2.6 → websec_validator-0.2.8}/src/websec_validator/scanners.py

@@ -217,6 +217,27 @@ def _generic_secret(rule: str) -> bool:
     return r in _GENERIC_SECRET_RULES or "generic" in r or "entropy" in r
 
 
+# Secrets matched in DOCUMENTATION / EXAMPLE files are overwhelmingly placeholders, not live
+# credentials — e.g. `curl -H "Authorization: Bearer <token>"` in a README/API doc, or a
+# value in `.env.example`. Tier those to LOW + a verify note (still visible — a real key CAN be
+# pasted into docs by mistake). Dogfooding flagged 4 HIGH curl-auth-header FPs across an API's
+# README + docs/*.md (bug below).
+_DOC_EXT = (".md", ".mdx", ".markdown", ".rst", ".txt", ".adoc")
+_DOC_DIR_MARKERS = ("/docs/", "/doc/", "/examples/", "/example/", "/samples/", "/sample/", "/.github/")
+_DOC_NAME_PREFIX = ("readme", "changelog", "contributing", "license", "authors", "history", "notice")
+_EXAMPLE_SUFFIX = (".example", ".sample", ".dist", ".template", ".tmpl")
+_DOC_NOTE = "in a documentation/example file — almost always a placeholder, verify before treating as real"
+
+
+def _is_doc_or_example(path: str) -> bool:
+    p = (path or "").replace("\\", "/").lower()
+    base = p.rsplit("/", 1)[-1]
+    return (p.endswith(_DOC_EXT)
+            or any(m in p for m in _DOC_DIR_MARKERS)
+            or any(base.startswith(m) for m in _DOC_NAME_PREFIX)
+            or any(s in base for s in _EXAMPLE_SUFFIX))
+
+
 def _norm_trivy(data: dict) -> list:
     out = []
     for res in (data.get("Results") or []):
@@ -231,6 +252,8 @@ def _norm_trivy(data: dict) -> list:
             sev, note = _aws_secret_tier(s.get("Match", ""), s.get("Code", "") or "")
             if not sev and _generic_secret(rid):
                 sev, note = "MEDIUM", _GENERIC_NOTE
+            if _is_doc_or_example(tgt):
+                sev, note = "LOW", (note + "; " if note else "") + _DOC_NOTE
             title = f"secret: {s.get('Title') or rid}" + (f" — {note}" if note else "")
             out.append({"tool": "trivy", "category": "secret", "severity": sev or _sev(s.get("Severity") or "HIGH"),
                         "key": rid, "file": tgt, "line": s.get("StartLine", 0),
@@ -250,6 +273,8 @@ def _norm_gitleaks(data) -> list:
         sev, note = _aws_secret_tier(x.get("Secret", ""), x.get("Match", ""))
         if not sev and _generic_secret(rule):
             sev, note = "MEDIUM", _GENERIC_NOTE
+        if _is_doc_or_example(f):
+            sev, note = "LOW", (note + "; " if note else "") + _DOC_NOTE
         title = f"secret: {(x.get('Description') or rule)[:80]}" + (f" — {note}" if note else "")
         out.append({"tool": "gitleaks", "category": "secret", "severity": sev or "HIGH",
                     "key": rule, "file": f, "line": x.get("StartLine", 0),

{websec_validator-0.2.6 → websec_validator-0.2.8}/src/websec_validator/templates/probes/forged-token.sh

@@ -26,6 +26,16 @@ def b(o): return base64.urlsafe_b64encode(json.dumps(o).encode()).rstrip(b'=').d
 print(b({'alg':'RS256','typ':'JWT','kid':'forged'})+'.'+b({'sub':'websec-forged','email':'websec-forged@example.com','role':'admin','roles':['admin'],'exp':9999999999})+'.d2Vic2VjLWZvcmdlZC1zaWc')
 ")
 
+# Auth cookie names the app reads (from recon → probe-context.json) + an optional COOKIE_NAME
+# override. We forge into these too, not just Authorization: Bearer, so a cookie-ONLY app isn't
+# a false negative. (portable; macOS bash 3.2 lacks `mapfile`.)
+COOKIES=()
+[ -n "${COOKIE_NAME:-}" ] && COOKIES+=("$COOKIE_NAME")
+while IFS= read -r cn; do [ -n "$cn" ] && COOKIES+=("$cn"); done < <(python3 -c "
+import json
+for c in json.load(open('$ctx')).get('auth',{}).get('cookie_names',[]): print(c)
+" 2>/dev/null)
+
 # Routes to test: GET reads + GET idor/ssrf candidates (always); writes when PROBE_WRITES=1.
 # Skip any path with an unfilled {param}. (portable; macOS bash 3.2 lacks `mapfile`.)
 ROUTES=()
@@ -64,9 +74,11 @@ for ep in "${ROUTES[@]}"; do
   if [ "$na" != "401" ] && [ "$na" != "403" ]; then skip=$((skip+1)); continue; fi   # not gated unauthenticated → N/A here
   fg=$(curl -s -o /dev/null -w '%{http_code}' -X "$method" "$BASE$path" -H "Authorization: Bearer $FORGED" ${data[@]+"${data[@]}"} --max-time 15)
   via="Bearer"
-  if ! reached "$fg" && [ -n "${COOKIE_NAME:-}" ]; then
-    fg=$(curl -s -o /dev/null -w '%{http_code}' -X "$method" "$BASE$path" -H "Cookie: $COOKIE_NAME=$FORGED" ${data[@]+"${data[@]}"} --max-time 15)
-    via="cookie:$COOKIE_NAME"
+  if ! reached "$fg"; then   # Bearer didn't reach the handler → try forging into each known auth cookie
+    for cn in ${COOKIES[@]+"${COOKIES[@]}"}; do
+      cfg=$(curl -s -o /dev/null -w '%{http_code}' -X "$method" "$BASE$path" -H "Cookie: $cn=$FORGED" ${data[@]+"${data[@]}"} --max-time 15)
+      if reached "$cfg"; then fg="$cfg"; via="cookie:$cn"; break; fi
+    done
   fi
   if reached "$fg"; then
     printf '  BYPASS  %s→%s  %s %s   (forged token accepted via %s)\n' "$na" "$fg" "$method" "$path" "$via"; bypass=$((bypass+1))

{websec_validator-0.2.6 → websec_validator-0.2.8/src/websec_validator.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: websec-validator
-Version: 0.2.6
+Version: 0.2.8
 Summary: Local-first security recon that briefs your AI coding agent: facts + tailored probe scripts, code-in / artifacts-out. No LLM, no server, no running app.
 Author: Ricardo Accioly
 License: MIT

{websec_validator-0.2.6 → websec_validator-0.2.8}/tests/test_hardening.py

@@ -17,6 +17,8 @@ ROOT = Path(__file__).resolve().parents[1]
 sys.path.insert(0, str(ROOT / "src"))
 
 from websec_validator import dynamic, findings, probes, scanners  # noqa: E402
+from websec_validator.extractors.auth import AuthExtractor  # noqa: E402
+from websec_validator.extractors.base import RepoContext  # noqa: E402
 
 FACTS = {"routes": {"endpoints": [
     {"method": "GET", "path": "/api/bypass"},      # gated; accepts forged token  -> BYPASS
@@ -169,5 +171,65 @@ class SecretPrecisionTests(unittest.TestCase):
         self.assertEqual(hit["confidence"], "MEDIUM")
 
 
+class DocExampleSecretTests(unittest.TestCase):
+    """0.2.8: secrets in documentation/example files (curl examples in a README, .env.example
+    placeholders) tier to LOW + a verify note. Real code files are untouched."""
+
+    def test_is_doc_or_example(self):
+        self.assertTrue(scanners._is_doc_or_example("README.md"))
+        self.assertTrue(scanners._is_doc_or_example("docs/API-REFERENCE.md"))
+        self.assertTrue(scanners._is_doc_or_example(".env.example"))
+        self.assertTrue(scanners._is_doc_or_example("config/settings.sample.json"))
+        self.assertFalse(scanners._is_doc_or_example("src/app/route.ts"))
+
+    def test_gitleaks_doc_secret_to_low_code_stays_high(self):
+        rows = [
+            {"File": "README.md", "RuleID": "curl-auth-header", "Secret": "x" * 30, "Match": "Authorization: Bearer x", "StartLine": 1},
+            {"File": "src/server.ts", "RuleID": "private-key", "Secret": "-----BEGIN", "Match": "-----BEGIN", "StartLine": 1},
+        ]
+        by = {r["file"]: r for r in scanners._norm_gitleaks(rows)}
+        self.assertEqual(by["README.md"]["severity"], "LOW")
+        self.assertIn("documentation/example", by["README.md"]["title"])
+        self.assertEqual(by["src/server.ts"]["severity"], "HIGH")  # real code file untouched
+
+    def test_trivy_doc_secret_to_low(self):
+        data = {"Results": [{"Target": "docs/SECURITY.md", "Secrets": [
+            {"RuleID": "curl-auth-header", "Title": "Auth header", "Match": "Bearer x", "StartLine": 1}]}]}
+        secs = [f for f in scanners._norm_trivy(data) if f["category"] == "secret"]
+        self.assertEqual(secs[0]["severity"], "LOW")
+
+
+class CookieCoverageTests(unittest.TestCase):
+    """0.2.7: extract auth cookie names so the forged-token engine covers cookie-ONLY apps."""
+
+    def test_extracts_cookie_names(self):
+        with tempfile.TemporaryDirectory() as d:
+            d = Path(d)
+            (d / "auth.ts").write_text(
+                "const s = request.cookies.get('agent_wallet_session');\n"
+                "const p = req.cookies['ping_id_token'];\n"
+                "const x = getCookie('dynamic_authentication_token');\n")
+            out = AuthExtractor().extract(RepoContext(d), {"stack": {"frameworks": []}, "routes": {}})
+        names = set(out["cookie_names"])
+        self.assertIn("agent_wallet_session", names)
+        self.assertIn("ping_id_token", names)
+        self.assertIn("dynamic_authentication_token", names)
+        self.assertNotIn("get", names)  # reserved method name filtered
+
+    def test_forged_bypass_detected_via_cookie(self):
+        facts = {"routes": {"endpoints": [{"method": "GET", "path": "/api/cookieonly"}]}}
+
+        def fake(method, url, token=None, timeout=20, data=None, cookie=None):
+            if token:
+                return 401, "x"                       # Bearer rejected
+            if cookie and "sess=" in cookie:
+                return 200, "x"                        # forged cookie accepted (cookie-only app)
+            return 401, "x"                            # no-auth baseline (gated)
+        with mock.patch.object(dynamic, "_request", fake):
+            r = dynamic.forged_token_bypass("http://t", facts, cookie_names=["sess"])
+        self.assertEqual([b["path"] for b in r["bypassed"]], ["/api/cookieonly"])
+        self.assertTrue(r["bypassed"][0]["via"].startswith("cookie:"))
+
+
 if __name__ == "__main__":
     unittest.main()