@hoanghainh/komagu 2.4.0 → 2.5.0

package/operate/cross_user_tester/runner.py

@@ -23,10 +23,35 @@ import sys
 import re
 import time
 import urllib.error
+import urllib.parse
 import urllib.request
+from dataclasses import replace
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple, Union
 
+if not __package__:  # run directly as a script: the repository root is not on sys.path
+    sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from operate.cross_user_tester.session_config import SessionOptions  # noqa: E402
+from operate.cross_user_tester.session_http import (  # noqa: E402
+    ALLOWED,
+    DENIED,
+    INCONCLUSIVE,
+    WRITE_METHODS,
+    CsrfConfig,
+    DenialSignal,
+    HttpReply,
+    SessionRequest,
+    classify,
+    deliver,
+    is_form_action,
+    parse_body_format,
+    parse_csrf,
+)
+
+_ID_PLACEHOLDER = re.compile(r"\{[a-zA-Z0-9_-]*(?:id|ID)[a-zA-Z0-9_-]*\}")
+_TAMPER_PAYLOAD = {"status": "tampered_by_attacker", "note": "Komagu BOLA exploit verification"}
+
 
 class TestCase:
     """Specification of a cross-user test case."""
@@ -44,6 +69,8 @@ class TestCase:
         insecure_status: Optional[List[int]] = None,
         finding_id: Optional[str] = None,
         consensus_score: Optional[float] = None,
+        body_format: str = "json",
+        csrf: Optional[CsrfConfig] = None,
     ) -> None:
         self.name = name
         self.finding_id = finding_id
@@ -63,6 +90,8 @@ class TestCase:
         self.headers = headers or {}
         self.expected_status = expected_status or [404]
         self.insecure_status = insecure_status or [200, 201, 202, 204]
+        self.body_format = body_format
+        self.csrf = csrf
 
 
 class TestResult:
@@ -77,6 +106,7 @@ class TestResult:
         is_secure: bool,
         duration_ms: float,
         error_message: Optional[str] = None,
+        owner_control: Optional[str] = None,
     ) -> None:
         self.test_case = test_case
         self.status_code = status_code
@@ -85,9 +115,10 @@ class TestResult:
         self.is_secure = is_secure
         self.duration_ms = duration_ms
         self.error_message = error_message
+        self.owner_control = owner_control
 
     def to_dict(self) -> Dict[str, Any]:
-        return {
+        data: Dict[str, Any] = {
             "name": self.test_case.name,
             "finding_id": self.test_case.finding_id,
             "consensus_score": self.test_case.consensus_score,
@@ -99,6 +130,9 @@ class TestResult:
             "duration_ms": round(self.duration_ms, 2),
             "error_message": self.error_message,
         }
+        if self.owner_control is not None:
+            data["owner_control"] = self.owner_control
+        return data
 
 
 
@@ -112,15 +146,76 @@ class CrossUserTestRunner:
         auth_header: str = "Authorization",
         token_prefix: str = "Bearer ",
         timeout: float = 10.0,
+        session: Optional[SessionOptions] = None,
     ) -> None:
         self.base_url = base_url.rstrip("/")
         self.default_attacker_token = default_attacker_token
         self.auth_header = auth_header
         self.token_prefix = token_prefix
         self.timeout = timeout
+        self.session = session
+
+    def _auth_header(self, test: TestCase) -> Optional[Tuple[str, str]]:
+        token = test.attacker_token or self.default_attacker_token
+        return (self.auth_header, f"{self.token_prefix}{token}".strip()) if token else None
+
+    def _deliver(
+        self,
+        test: TestCase,
+        cookie: Optional[str],
+        auth: Optional[Tuple[str, str]],
+        csrf_page: Optional[str] = None,
+    ) -> HttpReply:
+        csrf = replace(test.csrf, page=csrf_page) if test.csrf and csrf_page else test.csrf
+        request = SessionRequest(
+            method=test.method, path=test.path, cookie=cookie, auth_header=auth,
+            payload=test.payload, body_format=test.body_format, csrf=csrf, headers=test.headers,
+        )
+        return deliver(self.base_url, request, self.timeout)
+
+    def _owner_control(self, test: TestCase, options: SessionOptions, signal: DenialSignal) -> Tuple[str, Optional[str]]:
+        """Replay a refused request as the owner: it must work, or the refusal proves nothing."""
+        if not options.owner_cookie:
+            return "not_run", None
+        if test.method in WRITE_METHODS and not options.owner_control_writes:
+            if options.strict:
+                return "skipped_write", "--strict cannot pass a refused write without --owner-control-writes"
+            return "skipped_write", None
+        reply = self._deliver(test, options.owner_cookie, None, options.owner_csrf_page)
+        verdict, reason = classify(signal, reply.status, reply.location, reply.body) if not reply.error else (INCONCLUSIVE, reply.error)
+        if verdict == ALLOWED:
+            return "passed", None
+        return "failed", f"owner control failed ({reason}): the route or resource ID cannot prove a refusal"
+
+    def _execute_session_test(self, test: TestCase) -> TestResult:
+        """Legacy path: no redirects followed, verdict from the denial signal."""
+        options = self.session or SessionOptions()
+        signal = options.denial or DenialSignal(deny_status=tuple(test.expected_status))
+        auth = None if options.attacker_cookie else self._auth_header(test)
+        start_time = time.time()
+        reply = self._deliver(test, options.attacker_cookie, auth)
+        verdict, reason = classify(signal, reply.status, reply.location, reply.body) if not reply.error else (INCONCLUSIVE, reply.error)
+        control: Optional[str] = None
+        if verdict == DENIED:
+            control, problem = self._owner_control(test, options, signal)
+            if problem:
+                verdict, reason = INCONCLUSIVE, problem
+        return TestResult(
+            test_case=test,
+            status_code=reply.status,
+            response_body=reply.body[:1000],
+            is_breach=verdict == ALLOWED,
+            is_secure=verdict == DENIED,
+            duration_ms=(time.time() - start_time) * 1000.0,
+            error_message=reason if verdict == INCONCLUSIVE else None,
+            owner_control=control,
+        )
 
     def execute_test(self, test: TestCase) -> TestResult:
         """Execute a single test case against the target API."""
+        if self.session is not None or test.csrf is not None or test.body_format == "form":
+            return self._execute_session_test(test)
+
         url = f"{self.base_url}{test.path}"
         headers = dict(test.headers)
 
@@ -183,6 +278,8 @@ def generate_crud_test_cases(
     name_prefix: str = "Resource",
     attacker_token: Optional[str] = None,
     sample_payload: Optional[Dict[str, Any]] = None,
+    body_format: str = "json",
+    csrf: Optional[CsrfConfig] = None,
 ) -> List[TestCase]:
     """Generate the standard 3-operation (GET, PUT, DELETE) cross-user test cases."""
     return [
@@ -200,6 +297,8 @@ def generate_crud_test_cases(
             resource_id=resource_id,
             attacker_token=attacker_token,
             payload=sample_payload or {"status": "tampered_by_attacker"},
+            body_format=body_format,
+            csrf=csrf,
         ),
         TestCase(
             name=f"{name_prefix} - Cross-User Destruction (DELETE)",
@@ -207,11 +306,16 @@ def generate_crud_test_cases(
             method="DELETE",
             resource_id=resource_id,
             attacker_token=attacker_token,
+            csrf=csrf,
         ),
     ]
 
 
-def load_suite_from_file(file_path: str) -> List[TestCase]:
+def load_suite_from_file(
+    file_path: str,
+    default_body_format: str = "json",
+    default_csrf: Optional[CsrfConfig] = None,
+) -> List[TestCase]:
     """Load test cases from a JSON configuration file."""
     with open(file_path, "r", encoding="utf-8") as f:
         data = json.load(f)
@@ -220,6 +324,9 @@ def load_suite_from_file(file_path: str) -> List[TestCase]:
     items = data if isinstance(data, list) else data.get("tests", [])
 
     for item in items:
+        where = f"test '{item.get('name', item.get('path'))}'"
+        body_format = parse_body_format(item.get("body_format"), where, default_body_format)
+        csrf = parse_csrf(item.get("csrf"), where, default_csrf)
         # If item specifies auto_crud, generate 3 CRUD operations
         if item.get("auto_crud"):
             cases = generate_crud_test_cases(
@@ -228,6 +335,8 @@ def load_suite_from_file(file_path: str) -> List[TestCase]:
                 name_prefix=item.get("name", item["path"]),
                 attacker_token=item.get("attacker_token"),
                 sample_payload=item.get("payload"),
+                body_format=body_format,
+                csrf=csrf,
             )
             test_cases.extend(cases)
         else:
@@ -242,17 +351,70 @@ def load_suite_from_file(file_path: str) -> List[TestCase]:
                     headers=item.get("headers"),
                     expected_status=item.get("expected_status"),
                     insecure_status=item.get("insecure_status"),
+                    body_format=body_format,
+                    csrf=csrf,
                 )
             )
     return test_cases
 
 
+def _has_id_placeholder(path: str) -> bool:
+    return "{id}" in path or ":id" in path or bool(_ID_PLACEHOLDER.search(path))
+
+
+_WRITE_WORDS = {"update", "save", "delete", "remove", "create", "add", "insert", "submit", "regist", "register",
+                "cancel", "approve", "modify", "change"}
+
+
+def _concrete_method(method: str, path: str) -> str:
+    """Routes declared in XML accept any verb; a write action needs POST to do anything."""
+    if method.strip().upper() != "ANY":
+        return method
+    action = path.split("?", 1)[0].rsplit("/", 1)[-1].rsplit(".", 1)[0]
+    words = {word.lower() for word in re.findall(r"[A-Z]?[a-z]+", action)}
+    return "POST" if words & _WRITE_WORDS else "GET"
+
+
+def _uses_form(path: str, body_format: str) -> bool:
+    return body_format == "form" or (body_format == "auto" and is_form_action(path))
+
+
+def _suggested_form(attack_vector: Dict[str, Any], resource_id: str) -> Dict[str, Any]:
+    """Form fields from attack_vector.suggested_payload ('id={id}&status=x'), if it has that shape."""
+    raw = attack_vector.get("suggested_payload")
+    if not isinstance(raw, str) or "=" not in raw:
+        return {}
+    return dict(urllib.parse.parse_qsl(raw.replace("{id}", resource_id), keep_blank_values=True))
+
+
+def _form_action_request(
+    path: str,
+    method: str,
+    attack_vector: Dict[str, Any],
+    resource_id: str,
+) -> Tuple[str, Optional[Dict[str, Any]]]:
+    """A legacy action takes the id as a parameter, not as a path segment."""
+    param = str(attack_vector.get("target_param") or "id")
+    in_path = _has_id_placeholder(path)
+    if method in ("POST", "PUT", "PATCH"):
+        payload: Dict[str, Any] = _suggested_form(attack_vector, resource_id) or dict(_TAMPER_PAYLOAD)
+        if not in_path:
+            payload.setdefault(param, resource_id)
+        return path, payload
+    if in_path:
+        return path, None
+    separator = "&" if "?" in path else "?"
+    return f"{path}{separator}{param}={urllib.parse.quote(resource_id, safe='')}", None
+
+
 def generate_test_cases_from_findings(
     scan_data_or_path: Union[str, Path, Dict[str, Any], List[Dict[str, Any]]],
     default_resource_id: str = "12345",
     attacker_token: Optional[str] = None,
     min_consensus_score: float = 0.0,
     include_likely: bool = True,
+    body_format: str = "auto",
+    csrf: Optional[CsrfConfig] = None,
 ) -> List[TestCase]:
     """Synthesize active BOLA verification test cases from LSA findings.json or SARIF data.
 
@@ -298,6 +460,7 @@ def generate_test_cases_from_findings(
             ep = item.get("endpoint") or {}
             path = av.get("path") or ep.get("path")
             method = av.get("method") or ep.get("method") or "GET"
+            method = _concrete_method(method, av.get("path") or ep.get("path") or "")
 
             # Fallback: attempt to find path in evidence or title
             if not path:
@@ -311,7 +474,7 @@ def generate_test_cases_from_findings(
 
             # Determine resource_id to inject
             target_id = default_resource_id
-            if "{id}" not in path and ":id" not in path and not re.search(r"\{[a-zA-Z0-9_-]*(?:id|ID)[a-zA-Z0-9_-]*\}", path):
+            if not _has_id_placeholder(path):
                 if not path.endswith("/"):
                     target_path = f"{path}/{target_id}"
                 else:
@@ -324,19 +487,25 @@ def generate_test_cases_from_findings(
             for m in methods:
                 payload = None
                 if m in ("POST", "PUT", "PATCH"):
-                    payload = {"status": "tampered_by_attacker", "note": "Komagu BOLA exploit verification"}
+                    payload = dict(_TAMPER_PAYLOAD)
+                is_form = _uses_form(path, body_format)
+                case_path = target_path
+                if is_form:
+                    case_path, payload = _form_action_request(path, m, av, target_id)
 
                 tc_name = f"[{fid}] {item.get('title', target_path)} ({m})"
                 test_cases.append(
                     TestCase(
                         name=tc_name,
-                        path=target_path,
+                        path=case_path,
                         method=m,
                         resource_id=target_id,
                         attacker_token=attacker_token,
                         payload=payload,
                         finding_id=fid,
                         consensus_score=c_score,
+                        body_format="form" if is_form else "json",
+                        csrf=csrf,
                     )
                 )
 
@@ -360,7 +529,7 @@ def generate_test_cases_from_findings(
                 # Try to extract path and method from SARIF properties or message
                 ep = props.get("endpoint") or {}
                 path = ep.get("path")
-                method = ep.get("method") or "GET"
+                method = _concrete_method(ep.get("method") or "GET", path or "")
 
                 if not path:
                     m = re.search(r"(?:GET|POST|PUT|DELETE|PATCH)?\s*(/[a-zA-Z0-9_\-\./\{\}:]+)", msg)
@@ -371,11 +540,18 @@ def generate_test_cases_from_findings(
                     continue
 
                 target_id = default_resource_id
-                if "{id}" not in path and ":id" not in path and not re.search(r"\{[a-zA-Z0-9_-]*(?:id|ID)[a-zA-Z0-9_-]*\}", path):
+                if not _has_id_placeholder(path):
                     target_path = f"{path}/{target_id}" if not path.endswith("/") else f"{path}{target_id}"
                 else:
                     target_path = path
 
+                is_form = _uses_form(path, body_format)
+                sarif_payload: Optional[Dict[str, Any]] = None
+                if is_form:
+                    target_path, sarif_payload = _form_action_request(
+                        path, str(method).upper(), props.get("attack_vector") or {}, target_id
+                    )
+
                 fid = props.get("finding_id") or result.get("ruleId", "BOLA")
                 tc_name = f"[{fid}] SARIF {result.get('ruleId', 'BOLA')} ({method})"
                 test_cases.append(
@@ -385,8 +561,11 @@ def generate_test_cases_from_findings(
                         method=method,
                         resource_id=target_id,
                         attacker_token=attacker_token,
+                        payload=sarif_payload,
                         finding_id=fid,
                         consensus_score=float(props.get("consensus_score", 1.0)) if "consensus_score" in props else None,
+                        body_format="form" if is_form else "json",
+                        csrf=csrf,
                     )
                 )
 
@@ -426,6 +605,10 @@ def format_report(results: List[TestResult], base_url: str) -> Tuple[str, bool]:
                 f"[PASS - SECURE]      {t.method} {t.path} -> "
                 f"HTTP {res.status_code} ({res.duration_ms:.1f}ms)"
             )
+            if res.owner_control == "skipped_write":
+                lines.append("       Note: owner control skipped for this write; the route was not proven to work.")
+            elif res.owner_control == "not_run":
+                lines.append("       Note: no owner session; the route and resource ID were not proven to work.")
         else:
             error_count += 1
             lines.append(

package/operate/cross_user_tester/session_config.py

@@ -0,0 +1,180 @@
+"""Operator configuration for testing session-based legacy apps.
+
+Cookie values are read from environment variables or files only. There is
+deliberately no flag that takes a cookie value, and no message repeats one.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import stat
+from dataclasses import dataclass, field
+from typing import List, Mapping, Optional
+
+from operate.cross_user_tester.session_http import (
+    DEFAULT_DENY_STATUS,
+    STRICT_DENY_STATUS,
+    CsrfConfig,
+    DenialSignal,
+    SessionConfigError,
+    SessionRequest,
+    fetch_page,
+)
+
+__all__ = ["SessionConfigError", "SessionOptions", "read_cookie"]
+
+
+@dataclass(frozen=True)
+class SessionOptions:
+    attacker_cookie: Optional[str] = field(default=None, repr=False)
+    owner_cookie: Optional[str] = field(default=None, repr=False)
+    denial: Optional[DenialSignal] = None
+    owner_control_writes: bool = False
+    owner_csrf_page: Optional[str] = None
+    strict: bool = False
+    session_check: Optional[str] = None
+    session_marker: Optional[str] = None
+
+
+def _validated(value: str, label: str) -> str:
+    cookie = value.strip()
+    if not cookie:
+        raise SessionConfigError(f"{label}: the session cookie is empty")
+    if "=" not in cookie or not cookie.isascii() or any(ord(c) < 32 or ord(c) == 127 for c in cookie):
+        raise SessionConfigError(f"{label}: the session cookie must be one line such as NAME=VALUE; NAME2=VALUE2")
+    return cookie
+
+
+def read_cookie(env_name: Optional[str], file_path: Optional[str], env: Mapping[str, str], label: str) -> Optional[str]:
+    """Read a persona's Cookie header value. None when no source is configured."""
+    if env_name and file_path:
+        raise SessionConfigError(f"{label}: use either a cookie environment variable or a cookie file, not both")
+    if env_name:
+        if not env.get(env_name):
+            raise SessionConfigError(f"{label}: environment variable {env_name} is not set")
+        return _validated(env[env_name], label)
+    if file_path:
+        try:
+            with open(file_path, "r", encoding="utf-8") as handle:
+                return _validated(handle.read(), label)
+        except (OSError, UnicodeDecodeError) as err:
+            raise SessionConfigError(f"{label}: cannot read the cookie file ({type(err).__name__})") from err
+    return None
+
+
+def cookie_file_is_open(file_path: Optional[str]) -> bool:
+    """True when group or others can read a cookie file."""
+    if not file_path or os.name != "posix":
+        return False
+    try:
+        return bool(stat.S_IMODE(os.stat(file_path).st_mode) & 0o077)
+    except OSError:
+        return False
+
+
+def add_session_arguments(parser: argparse.ArgumentParser) -> None:
+    """Flags for session-based apps. None of them takes a secret value."""
+    group = parser.add_argument_group("session-based apps (JSP / Struts / old Spring MVC)")
+    group.add_argument("--attacker-cookie-env", metavar="VAR", help="Environment variable holding the attacker's Cookie value, e.g. JSESSIONID=...")
+    group.add_argument("--attacker-cookie-file", metavar="PATH", help="File holding the attacker's Cookie value")
+    group.add_argument("--owner-cookie-env", metavar="VAR", help="Environment variable holding the resource owner's Cookie value")
+    group.add_argument("--owner-cookie-file", metavar="PATH", help="File holding the resource owner's Cookie value")
+    group.add_argument("--body-format", choices=["auto", "json", "form"], default="auto",
+                       help="Request body encoding. auto: form for --from-scan routes ending in .do, .action, .jsp or .jspx; otherwise JSON")
+    group.add_argument("--csrf-page", metavar="PATH", help="Page the attacker can open that contains a CSRF or Struts token")
+    group.add_argument("--csrf-field", metavar="NAME", help="Token field name, e.g. org.apache.struts.taglib.html.TOKEN")
+    group.add_argument("--deny-status", type=int, action="append", metavar="CODE", help="Status that means refused (repeatable)")
+    group.add_argument("--deny-redirect", action="append", metavar="TEXT", help="Redirect target containing TEXT means refused (repeatable)")
+    group.add_argument("--deny-marker", action="append", metavar="TEXT", help="2xx body containing TEXT means refused (repeatable)")
+    group.add_argument("--allow-redirect", action="append", metavar="TEXT", help="Redirect target containing TEXT means the request succeeded (repeatable)")
+    group.add_argument("--allow-marker", action="append", metavar="TEXT", help="If set, a 2xx body must contain TEXT to count as served data (repeatable)")
+    group.add_argument("--session-check", metavar="PATH", help="Page every session persona can open; checked before and after the run")
+    group.add_argument("--session-marker", metavar="TEXT", help="Text that --session-check page must contain")
+    group.add_argument("--owner-control-writes", action="store_true",
+                       help="Also replay writes as the owner after a denial. This changes the owner's data. Required for --strict to pass a refused write")
+    group.add_argument("--owner-csrf-page", metavar="PATH", help="Token page for the owner's replayed writes (default: --csrf-page)")
+
+
+def _signal(args: argparse.Namespace) -> DenialSignal:
+    fallback = STRICT_DENY_STATUS if args.strict else DEFAULT_DENY_STATUS
+    texts = (args.deny_redirect or []) + (args.deny_marker or []) + (args.allow_redirect or []) + (args.allow_marker or [])
+    if not all(texts):
+        raise SessionConfigError("--deny-redirect, --deny-marker, --allow-redirect and --allow-marker cannot be empty")
+    return DenialSignal(
+        deny_status=tuple(args.deny_status or fallback),
+        deny_redirects=tuple(args.deny_redirect or ()),
+        deny_markers=tuple(args.deny_marker or ()),
+        allow_redirects=tuple(args.allow_redirect or ()),
+        allow_markers=tuple(args.allow_marker or ()),
+    )
+
+
+def declared_denial(args: argparse.Namespace) -> bool:
+    return bool(args.deny_status or args.deny_redirect or args.deny_marker)
+
+
+def strict_gaps(args: argparse.Namespace, cookie_attacker: bool, cookie_owner: bool) -> List[str]:
+    """What --strict still needs to give a trustworthy verdict on a session app."""
+    gaps: List[str] = []
+    if not declared_denial(args):
+        gaps.append("a denial signal (--deny-status, --deny-redirect or --deny-marker)")
+    if not args.session_check:
+        gaps.append("--session-check, so an expired session is not read as a refusal")
+    if cookie_attacker and not cookie_owner:
+        gaps.append("the owner's cookie, so a missing record is not read as a refusal")
+    return gaps
+
+
+def build_session_options(args: argparse.Namespace, env: Mapping[str, str]) -> Optional[SessionOptions]:
+    """Options for this run, or None when it is an ordinary Bearer run."""
+    attacker = read_cookie(args.attacker_cookie_env, args.attacker_cookie_file, env, "attacker")
+    owner = read_cookie(args.owner_cookie_env, args.owner_cookie_file, env, "owner")
+    if not (attacker or owner or declared_denial(args) or args.allow_redirect or args.allow_marker or args.session_check):
+        return None
+    if args.strict and attacker:
+        gaps = strict_gaps(args, True, bool(owner))
+        if gaps:
+            raise SessionConfigError("--strict on a session app needs " + "; ".join(gaps))
+    return SessionOptions(
+        attacker_cookie=attacker,
+        owner_cookie=owner,
+        denial=_signal(args),
+        owner_control_writes=args.owner_control_writes,
+        owner_csrf_page=args.owner_csrf_page,
+        strict=args.strict,
+        session_check=args.session_check,
+        session_marker=args.session_marker,
+    )
+
+
+def global_csrf(args: argparse.Namespace) -> Optional[CsrfConfig]:
+    if bool(args.csrf_page) != bool(args.csrf_field):
+        raise SessionConfigError("--csrf-page and --csrf-field must be given together")
+    if not args.csrf_page:
+        return None
+    if not args.csrf_page.startswith("/"):
+        raise SessionConfigError("--csrf-page must start with '/'")
+    return CsrfConfig(page=args.csrf_page, field=args.csrf_field)
+
+
+def check_session(
+    base_url: str,
+    label: str,
+    cookie: str,
+    path: str,
+    marker: Optional[str],
+    denial: Optional[DenialSignal],
+    timeout: float = 10.0,
+) -> Optional[str]:
+    """Return why this session is unusable, or None when it is alive."""
+    reply = fetch_page(base_url.rstrip("/"), path, SessionRequest("GET", path, cookie=cookie), timeout)
+    if reply.error:
+        return f"{label}: session check failed ({reply.error})"
+    if not 200 <= reply.status < 300:
+        return f"{label}: session check {path} returned HTTP {reply.status}; the session is expired or invalid"
+    if denial and any(m in reply.body for m in denial.deny_markers):
+        return f"{label}: session check {path} shows a denial page"
+    if marker and marker not in reply.body:
+        return f"{label}: session check {path} does not contain the expected text"
+    return None