@hoanghainh/komagu 2.4.0 → 2.6.0

package/examples/member-portal/frontend/package.json

@@ -15,7 +15,7 @@
   "devDependencies": {
     "@types/react": "^18.3.5",
     "@types/react-dom": "^18.3.0",
-    "@vitejs/plugin-react": "^4.3.1",
+    "@vitejs/plugin-react": "^6.3.0",
     "typescript": "^5.5.4",
     "vite": "^8.3.4"
   }

package/operate/ai/client.py

@@ -12,6 +12,9 @@ import urllib.error
 import urllib.request
 from typing import Any, Dict, List, Optional, Tuple
 
+# OpenAI-compatible `reasoning_effort` values; Ollama's /v1 also accepts "none" to turn thinking off (#382)
+REASONING_EFFORTS = ("none", "low", "medium", "high")
+
 
 class LLMClient:
     """Standard-library client for OpenAI-compatible /chat/completions endpoints."""
@@ -22,7 +25,10 @@ class LLMClient:
         model: str = "llama3.1",
         api_key: Optional[str] = None,
         timeout: int = 120,
+        reasoning_effort: Optional[str] = None,
     ) -> None:
+        if reasoning_effort is not None and reasoning_effort not in REASONING_EFFORTS:
+            raise ValueError(f"reasoning_effort must be one of {', '.join(REASONING_EFFORTS)}")
         raw_endpoint = endpoint.rstrip("/")
         if not raw_endpoint.endswith("/chat/completions"):
             self.endpoint = f"{raw_endpoint}/chat/completions"
@@ -31,6 +37,7 @@ class LLMClient:
         self.model = model
         self.api_key = api_key or "ollama"
         self.timeout = timeout
+        self.reasoning_effort = reasoning_effort
         # Running totals across chat() calls, read by the runner for ai-run-stats.json
         self.usage: Dict[str, float] = {"calls": 0, "prompt_tokens": 0, "completion_tokens": 0, "seconds": 0.0}
 
@@ -41,15 +48,7 @@ class LLMClient:
         max_tokens: Optional[int] = None,
     ) -> str:
         """Send a chat completion request and return the assistant response content."""
-        payload: Dict[str, Any] = {
-            "model": self.model,
-            "messages": messages,
-            "temperature": temperature,
-        }
-        if max_tokens:
-            payload["max_tokens"] = max_tokens
-
-        data = json.dumps(payload).encode("utf-8")
+        data = json.dumps(self.build_payload(messages, temperature, max_tokens)).encode("utf-8")
         headers = {
             "Content-Type": "application/json",
             "Authorization": f"Bearer {self.api_key}",
@@ -74,6 +73,20 @@ class LLMClient:
         except urllib.error.URLError as e:
             raise RuntimeError(f"Failed to connect to LLM endpoint at {self.endpoint}: {e.reason}") from e
 
+    def build_payload(
+        self,
+        messages: List[Dict[str, str]],
+        temperature: float = 0.1,
+        max_tokens: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Request body for /chat/completions; `reasoning_effort` is sent only when it was set."""
+        payload: Dict[str, Any] = {"model": self.model, "messages": messages, "temperature": temperature}
+        if max_tokens:
+            payload["max_tokens"] = max_tokens
+        if self.reasoning_effort:
+            payload["reasoning_effort"] = self.reasoning_effort
+        return payload
+
     def _record_usage(self, usage: Dict[str, Any], seconds: float) -> None:
         self.usage = {
             "calls": self.usage["calls"] + 1,

package/operate/ai/runner.py

@@ -15,6 +15,7 @@ Standard-library only (Python 3.8+ compatible).
 from __future__ import annotations
 
 import json
+import re
 from pathlib import Path
 import subprocess
 import sys
@@ -35,6 +36,7 @@ FINDING_STATUSES = {"unverified", "confirmed", "likely", "rejected", "needs_revi
 
 
 VERIFY_BATCH_SIZE = 5
+ID_INPUT = re.compile(r"(?i)(?:^id$|id$|_no$|no$|key$|code$)")
 AUTH_MODEL_LIMIT = 6000
 RETRY_REMINDER = ("Your previous reply was empty or not valid JSON. Answer again with the JSON object only, "
                   "exactly in the format requested above, with no other text.")
@@ -165,6 +167,7 @@ class HeadlessAIRunner:
         stats = {
             "model": getattr(self.client, "model", None),
             "endpoint": getattr(self.client, "endpoint", None),
+            "reasoning_effort": getattr(self.client, "reasoning_effort", None),
             "phases": self.phase_stats,
             "totals": self._usage(),
             "parse_failures": self.parse_failures,
@@ -298,8 +301,9 @@ Output MUST be Markdown format adhering to Komagu auth-model.md specification.
                         {"name": p.get("name", "id"), "source": p.get("source", "path")}
                         for p in c.get("id_params", [])
                     ]
-                if not id_inputs:
-                    id_inputs = [{"name": "id", "source": "path"}]
+                # No detected id input stays empty: inventing a path `id` made the BOLA auditor
+                # flag routes that take no object id (#380)
+                id_inputs = id_inputs or []
 
                 mapped_routes.append({
                     "route_id": route_id,
@@ -321,6 +325,16 @@ Output MUST be Markdown format adhering to Komagu auth-model.md specification.
 
         self._log("ok", f"Mapped {len(route_batches)} route inventories")
 
+    @staticmethod
+    def _with_route_target(finding: Dict[str, Any], route: Dict[str, Any]) -> Dict[str, Any]:
+        """Record the request parameter holding the object id, which `komagu test --from-scan` needs."""
+        attack_vector = finding.get("attack_vector") if isinstance(finding.get("attack_vector"), dict) else {}
+        if attack_vector.get("target_param"):
+            return finding
+        name = next((i.get("name") for i in route.get("id_inputs") or []
+                     if isinstance(i, dict) and ID_INPUT.search(str(i.get("name") or ""))), None)
+        return {**finding, "attack_vector": {**attack_vector, "target_param": name}} if name else finding
+
     @staticmethod
     def _sanitize_finding(f: Dict[str, Any]) -> Dict[str, Any]:
         """Normalize finding fields to strictly comply with finding.schema.json."""
@@ -330,6 +344,11 @@ Output MUST be Markdown format adhering to Komagu auth-model.md specification.
         if isinstance(f.get("impact"), list):
             f["impact"] = "; ".join(str(i) for i in f["impact"])
 
+        # routes reach the model with a method list and models echo it; the schema wants one string joined with |
+        endpoint = f.get("endpoint")
+        if isinstance(endpoint, dict) and isinstance(endpoint.get("method"), list):
+            f["endpoint"] = {**endpoint, "method": "|".join(str(m) for m in endpoint["method"])}
+
         # a verdict written into subtype belongs in status; fall back to the category's first subtype
         allowed = CATEGORY_SUBTYPES.get(f.get("category"))
         if allowed and f.get("subtype") not in allowed:
@@ -461,9 +480,10 @@ Write one finding for every "vulnerable" verdict.
                 raw_findings = parsed.get("findings", [])
                 findings = self._anchor([self._sanitize_finding(f) for f in raw_findings])
                 route_verdicts = parsed.get("route_verdicts", [])
+                by_route = {r.get("route_id"): r for r in routes_to_audit}
                 findings = self._with_verdict_findings(
-                    "4a-bola-auditor", findings, route_verdicts, "route_id",
-                    {r.get("route_id"): r for r in routes_to_audit}, "bola")
+                    "4a-bola-auditor", findings, route_verdicts, "route_id", by_route, "bola")
+                findings = [self._with_route_target(f, by_route.get(f.get("route_id")) or {}) for f in findings]
             except Exception:
                 self._parse_failed("4a-bola-auditor", r_file.stem, reply)
                 findings = []

package/operate/cli/__init__.py

@@ -2,4 +2,4 @@
 
 from __future__ import annotations
 
-__version__ = "2.4.0"  # x-release-please-version
+__version__ = "2.6.0"  # x-release-please-version

package/operate/cli/commands/fix.py

@@ -130,6 +130,10 @@ def run_fix(args: argparse.Namespace) -> int:
         for plan in report.plans:
             if plan.diff:
                 print(plan.diff)
+            else:
+                # stderr keeps stdout a valid patch; without this a run with only manual fixes prints nothing
+                print(f"[{plan.status.upper()}] {plan.finding_id} {plan.target_file}:{plan.start_line} - {plan.reason}",
+                      file=sys.stderr)
         return 0
 
     step("[2/2] Remediation execution completed")

package/operate/cli/commands/leak_check.py

@@ -0,0 +1,75 @@
+"""Command: komagu leak-check - find secrets that reached pilot outputs (runbook §9)."""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+from typing import Tuple
+
+from operate.devsecops.leak_check import CanaryFileError, ScanResult, load_canaries, scan_paths
+
+
+def register_subcommand(subparsers: argparse._SubParsersAction) -> None:
+    """Register the leak-check subcommand parser."""
+    parser = subparsers.add_parser(
+        "leak-check",
+        help="Scan ai-raw/, findings and reports for leaked secrets and client canary strings",
+        description=(
+            "Checks audit output for secrets the redaction step missed. Values are always masked in the report. "
+            "Exit codes: 0 clean, 1 suspected leak, 2 incomplete scan or bad input."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  komagu leak-check ~/pilot/out --canary-file ~/pilot/canaries.txt
+  komagu leak-check ~/pilot/out/ai-raw ~/pilot/out/report.md --format json > ~/pilot/leak-check.json
+""",
+    )
+    parser.add_argument("paths", nargs="+", metavar="PATH", help="Output directories or files to scan")
+    parser.add_argument(
+        "--canary-file",
+        help="UTF-8 file with one client-provided canary string per line; keep it outside the repository",
+    )
+    parser.add_argument("--format", choices=["text", "json"], default="text", help="Report format (default: text)")
+    parser.set_defaults(func=run)
+
+
+def _print_text(result: ScanResult) -> None:
+    for hit in result.hits:
+        print(f"{hit.path}:{hit.line}: {hit.detector}: {hit.rule}: {hit.masked}")
+    for path, reason in result.unscanned:
+        print(f"NOT SCANNED {path}: {reason}")
+    print(
+        f"leak-check: {len(result.hits)} suspected leak(s), {result.files_scanned} file(s) scanned, "
+        f"{len(result.unscanned)} not scanned, {result.canaries_loaded} canary string(s)"
+    )
+
+
+def _print_json(result: ScanResult) -> None:
+    report = {
+        "exitCode": result.exit_code,
+        "filesScanned": result.files_scanned,
+        "canariesLoaded": result.canaries_loaded,
+        "hits": [dataclasses.asdict(hit) for hit in result.hits],
+        "notScanned": [{"path": path, "reason": reason} for path, reason in result.unscanned],
+    }
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+
+
+def run(args: argparse.Namespace) -> int:
+    """Run the scan and return its exit code."""
+    canaries: Tuple[str, ...] = ()
+    if args.canary_file is not None:
+        try:
+            canaries = load_canaries(args.canary_file)
+        except CanaryFileError as exc:
+            print(f"leak-check: {exc}", file=sys.stderr)
+            return 2
+    result = scan_paths(args.paths, canaries)
+    if args.format == "json":
+        _print_json(result)
+    else:
+        _print_text(result)
+    return result.exit_code

package/operate/cli/commands/protect.py

@@ -9,6 +9,7 @@ import subprocess
 import sys
 from pathlib import Path
 from typing import Any, Dict
+from urllib.parse import urlsplit
 
 from operate.cli.ui import (
     BOLD,
@@ -110,10 +111,31 @@ Documentation:
 
 
 
+def _valid_target(url: str) -> bool:
+    parts = urlsplit(url)
+    return parts.scheme in ("http", "https") and bool(parts.hostname)
+
+
+def _compose_env(args: argparse.Namespace, config_path: Path) -> Dict[str, str]:
+    """Settings the compose file reads; without them the stack would front its demo backend."""
+    env = dict(os.environ)
+    if args.target:
+        env["KOMAGU_UPSTREAM"] = args.target
+    if args.config:
+        env["KOMAGU_KONG_CONFIG"] = str(config_path)
+    if getattr(args, "patch_out", None):
+        env["KOMAGU_VIRTUAL_PATCH_FILE"] = str(Path(args.patch_out).resolve())
+    return env
+
+
 def execute_protect(args: argparse.Namespace) -> int:
     """Execute perimeter protection actions."""
     step("Validating Komagu Perimeter Protection assets")
 
+    if args.target and not _valid_target(args.target):
+        step_fail(f"--target must be an http(s) URL with a host: {args.target}")
+        return 2
+
     if not EDGE_DIR.is_dir():
         step_fail(f"Edge directory not found at {EDGE_DIR}")
         return 1
@@ -141,6 +163,8 @@ def execute_protect(args: argparse.Namespace) -> int:
         step_info(f"Synthesizing Coraza WAF virtual patches from: {scan_path.name}")
         out_file, manifest = patcher.patch_to_file(scan_path, target_conf)
         step_ok(f"Synthesized {len(manifest)} SecRules into {out_file}")
+        for note in patcher.skipped:
+            step_warn(note)
 
         if manifest:
             patch_rows = [(f"Rule {m['rule_id']} [{m['category'].upper()}]", f"{m['finding_id']} -> {m['endpoint']}") for m in manifest]
@@ -151,7 +175,7 @@ def execute_protect(args: argparse.Namespace) -> int:
             )
 
     # If --target is supplied, report upstream routing
-    upstream_url = args.target or "http://coraza-waf:8080 (internal upstream)"
+    upstream_url = args.target or "http://mock-backend:5000 (demo backend)"
     if args.target:
         step_info(f"Configured upstream target: {args.target}")
 
@@ -160,11 +184,16 @@ def execute_protect(args: argparse.Namespace) -> int:
     compose_cmd = [docker_bin, "compose", "-f", str(EDGE_COMPOSE)] if docker_bin else None
 
     if args.up:
+        patch_out = getattr(args, "patch_out", None)
+        if patch_out and not Path(patch_out).is_file():
+            step_fail(f"Virtual patch file not found, Docker would mount a directory instead: {patch_out}")
+            return 2
         if args.dry_run or not docker_bin:
             step_info(f"[DRY-RUN] Would execute: docker compose -f {EDGE_COMPOSE} up -d")
         else:
             step("Starting perimeter containers (Kong Gateway + Coraza WAF + Mock Backend)")
-            res = subprocess.run(compose_cmd + ["up", "-d"], capture_output=True, text=True)
+            res = subprocess.run(compose_cmd + ["up", "-d"], capture_output=True, text=True,
+                                 env=_compose_env(args, config_path))
             if res.returncode != 0:
                 step_fail("Failed to start perimeter containers")
                 print(res.stderr or res.stdout, file=sys.stderr)
@@ -196,7 +225,7 @@ def execute_protect(args: argparse.Namespace) -> int:
         ("Upstream Target", upstream_url),
         ("Public Proxy Port", "http://localhost:8000"),
         ("Kong Admin API", "http://localhost:8001"),
-        ("Coraza WAF Port", "http://localhost:8080"),
+        ("Coraza WAF", "internal only, port 8080 is not published on the host"),
     ]
 
     print_summary_table(

package/operate/cli/commands/scan.py

@@ -161,6 +161,12 @@ Examples:
         default=120,
         help="Timeout in seconds per LLM request (default: 120)",
     )
+    parser.add_argument(
+        "--ai-reasoning-effort",
+        choices=("none", "low", "medium", "high"),
+        default=None,
+        help="Send reasoning_effort with each LLM request; 'none' turns thinking off on Ollama (default: not sent)",
+    )
     parser.set_defaults(func=execute_scan)
 
 
@@ -284,7 +290,8 @@ def execute_scan(args: argparse.Namespace) -> int:
                 step_info(msg)
 
         try:
-            client = LLMClient(endpoint=endpoint, model=model, api_key=api_key, timeout=timeout)
+            client = LLMClient(endpoint=endpoint, model=model, api_key=api_key, timeout=timeout,
+                               reasoning_effort=getattr(args, "ai_reasoning_effort", None))
             runner = HeadlessAIRunner(target_path, out_dir, client, step_callback=_scan_callback)
             runner.run()
         except Exception as e:

package/operate/cli/commands/test.py

@@ -7,7 +7,7 @@ import json
 import os
 import sys
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Mapping, Optional, Tuple
 
 from operate.cli.ui import (
     BOLD,
@@ -34,6 +34,17 @@ from operate.cross_user_tester.persona_matrix import (
     is_v2_suite,
     load_persona_suite,
 )
+from operate.cross_user_tester.session_config import (
+    SessionOptions,
+    add_session_arguments,
+    build_session_options,
+    check_session,
+    cookie_file_is_open,
+    global_csrf,
+    read_cookie,
+    strict_gaps,
+)
+from operate.cross_user_tester.session_http import SessionConfigError
 from operate.cross_user_tester.runner import (
     CrossUserTestRunner,
     format_report,
@@ -46,6 +57,8 @@ REPO_ROOT = Path(__file__).resolve().parents[3]
 DEFAULT_SUITE = REPO_ROOT / "operate" / "tests" / "test_suite.json"
 # --token is passed to persona-matrix cases through this private env entry.
 CLI_TOKEN_ENV = "KOMAGU_CLI_TOKEN"
+# The attacker's cookie reaches persona-matrix cases the same way, in a private copy of the environment.
+CLI_COOKIE_ENV = "KOMAGU_CLI_COOKIE"
 
 
 def register_subcommand(subparsers: argparse._SubParsersAction) -> None:
@@ -75,6 +88,11 @@ Examples:
   # Persona matrix (suite "version": 2): BFLA and mass assignment checks
   KOMAGU_TOKEN_USER=... KOMAGU_TOKEN_ADMIN=... komagu test --url http://staging:8000 --suite ./personas.json
 
+  # Session-based Java app (JSP / Struts): cookies from the environment, declared denial signal
+  ATTACKER_COOKIE=... OWNER_COOKIE=... komagu test --url http://test:8080 --from-scan ./findings.json --strict \\
+    --attacker-cookie-env ATTACKER_COOKIE --owner-cookie-env OWNER_COOKIE \\
+    --session-check /home.do --deny-status 404 --deny-redirect /login.do
+
 Documentation:
   See docs/cli-guide.md#34-komagu-test--offensive-exploit-verification-bola-invariant--persona-matrix
 """,
@@ -126,7 +144,8 @@ Documentation:
     parser.add_argument(
         "--strict",
         action="store_true",
-        help="Enforce strict 404 requirement (reject 401/403 which leak resource existence)",
+        help="Enforce strict 404 requirement (reject 401/403 which leak resource existence). "
+             "With session cookies, also requires a declared denial signal, --session-check and the owner's cookie",
     )
     parser.add_argument(
         "--token-env",
@@ -139,6 +158,7 @@ Documentation:
         dest="export_poc",
         help="Directory path to export standalone executable Python and cURL exploit PoC scripts",
     )
+    add_session_arguments(parser)
     parser.set_defaults(func=execute_test)
 
 
@@ -150,6 +170,19 @@ def execute_test(args: argparse.Namespace) -> int:
     tests: List[Any] = []
     matrix_cases: List[MatrixCase] = []
 
+    try:
+        session = build_session_options(args, os.environ)
+        csrf = global_csrf(args)
+    except SessionConfigError as e:
+        step_fail(str(e))
+        return 2
+    for cookie_file in (args.attacker_cookie_file, args.owner_cookie_file):
+        if cookie_file_is_open(cookie_file):
+            step_warn("A cookie file can be read by other users; restrict it with chmod 600")
+    # A session run sends the cookie only; the --token default must not go with it.
+    attacker_token = None if session and session.attacker_cookie else args.attacker_token
+    suite_body_format = "form" if args.body_format == "form" else "json"
+
     # 1. Ingest from scan output if provided
     if getattr(args, "from_scan", None):
         scan_file = Path(args.from_scan).resolve()
@@ -161,15 +194,19 @@ def execute_test(args: argparse.Namespace) -> int:
         scan_cases = generate_test_cases_from_findings(
             scan_data_or_path=scan_file,
             default_resource_id=args.resource_id,
-            attacker_token=args.attacker_token,
+            attacker_token=attacker_token,
             min_consensus_score=min_c,
+            body_format=args.body_format,
+            csrf=csrf,
         )
         step_info(f"Synthesized {len(scan_cases)} active verification cases from scan findings")
         tests.extend(scan_cases)
-        matrix_cases.extend(_matrix_cases_from_scan(scan_file, args, min_c))
+        matrix_cases.extend(_matrix_cases_from_scan(scan_file, args, min_c, session, csrf))
 
         # Export PoC exploits if requested
         if getattr(args, "export_poc", None):
+            if session and session.attacker_cookie:
+                step_warn("--export-poc writes Bearer scripts; they do not carry the session cookie")
             from operate.exploit.generator import ExploitGenerator
             gen = ExploitGenerator(
                 base_url=args.base_url,
@@ -191,14 +228,20 @@ def execute_test(args: argparse.Namespace) -> int:
             return 2
         if is_v2_suite(suite_data):
             try:
-                matrix_cases.extend(load_persona_suite(suite_data, default_id=args.resource_id))
-            except SuiteError as e:
+                matrix_cases.extend(load_persona_suite(
+                    suite_data, default_id=args.resource_id,
+                    default_body_format=suite_body_format, default_csrf=csrf,
+                ))
+            except (SuiteError, SessionConfigError) as e:
                 step_fail(f"Invalid persona suite {suite_path.name}: {e}")
                 return 2
             step_info(f"Persona matrix: {len(matrix_cases)} BFLA / mass assignment cases")
         else:
             try:
-                tests.extend(load_suite_from_file(str(suite_path)))
+                tests.extend(load_suite_from_file(str(suite_path), suite_body_format, csrf))
+            except SessionConfigError as e:
+                step_fail(f"Invalid test suite {suite_path.name}: {e}")
+                return 2
             except Exception as e:
                 step_warn(f"Could not load test suite {suite_path}: {e}")
 
@@ -210,16 +253,30 @@ def execute_test(args: argparse.Namespace) -> int:
             generate_crud_test_cases(
                 resource_path=crud_path,
                 resource_id=args.resource_id,
-                attacker_token=args.attacker_token,
+                attacker_token=attacker_token,
+                body_format=suite_body_format,
+                csrf=csrf,
             )
         )
 
 
     runner = CrossUserTestRunner(
         base_url=args.base_url,
-        default_attacker_token=args.attacker_token,
+        default_attacker_token=attacker_token,
+        session=session,
     )
 
+    has_cookie_personas = any(c.persona.cookie_env or c.persona.cookie_file for c in matrix_cases)
+    if args.strict and has_cookie_personas:
+        gaps = strict_gaps(args, False, False)
+        if gaps:
+            step_fail("--strict on a session app needs " + "; ".join(gaps))
+            return 2
+    problem = _session_problem(args, session, matrix_cases, os.environ)
+    if problem:
+        step_fail(f"{problem}. No test was sent.")
+        return 2
+
     results = []
     success = True
     if tests:
@@ -230,7 +287,7 @@ def execute_test(args: argparse.Namespace) -> int:
         print(report_text)
 
     try:
-        matrix_results = _run_matrix(matrix_cases, args)
+        matrix_results = _run_matrix(matrix_cases, args, session)
     except ValueError as e:
         step_fail(str(e))
         return 2
@@ -242,6 +299,12 @@ def execute_test(args: argparse.Namespace) -> int:
         print(matrix_text)
         success = success and matrix_ok
 
+    # A session lost during the run turns refusals into login redirects: the verdicts cannot be trusted.
+    lost_session = _session_problem(args, session, matrix_cases, os.environ)
+    if lost_session:
+        step_fail(f"{lost_session} after the run. The results below are not valid.")
+        success = False
+
     # Save output if requested
     if args.output:
         out_path = Path(args.output).resolve()
@@ -252,6 +315,8 @@ def execute_test(args: argparse.Namespace) -> int:
             "results": [r.to_dict() for r in results],
             "matrix_results": [r.to_dict() for r in matrix_results],
         }
+        if lost_session:
+            report_data["session_check"] = "failed_after_run"
         out_path.write_text(json.dumps(report_data, indent=2), encoding="utf-8")
         step_ok(f"Saved test report to {out_path}")
 
@@ -282,7 +347,7 @@ def execute_test(args: argparse.Namespace) -> int:
             if r.is_breach:
                 verdict = color("CONFIRMED BREACH (EXPLOITABLE)", RED, BOLD)
             elif r.is_secure:
-                verdict = color("PROTECTED (404 INVARIANT)", GREEN, BOLD)
+                verdict = color("PROTECTED (DENIAL SIGNAL)" if session else "PROTECTED (404 INVARIANT)", GREEN, BOLD)
             else:
                 verdict = color(f"UNEXPECTED HTTP {r.status_code}", YELLOW)
             exploit_rows.append((f"{f_id} [{tc.method} {tc.path}]", f"Consensus: {c_score_str} | Verdict: {verdict}"))
@@ -293,29 +358,80 @@ def execute_test(args: argparse.Namespace) -> int:
             footer="Offensive Verification: Green = 404 Enforced, Red = Active BOLA Breach Confirmed.",
         )
 
+    if lost_session:
+        return 2
     return 0 if success else 1
 
 
-def _matrix_cases_from_scan(scan_file: Path, args: argparse.Namespace, min_consensus: float) -> List[MatrixCase]:
+def _session_targets(
+    session: Optional[SessionOptions],
+    cases: List[MatrixCase],
+    env: Mapping[str, str],
+) -> List[Tuple[str, str]]:
+    """(label, cookie) for every session persona in this run."""
+    targets: List[Tuple[str, str]] = []
+    if session and session.attacker_cookie:
+        targets.append(("attacker", session.attacker_cookie))
+    if session and session.owner_cookie:
+        targets.append(("owner", session.owner_cookie))
+    for persona in {c.persona for c in cases if c.persona.cookie_env != CLI_COOKIE_ENV}:
+        cookie = read_cookie(persona.cookie_env, persona.cookie_file, env, persona.name)
+        if cookie:
+            targets.append((persona.name, cookie))
+    return targets
+
+
+def _session_problem(
+    args: argparse.Namespace,
+    session: Optional[SessionOptions],
+    cases: List[MatrixCase],
+    env: Mapping[str, str],
+) -> Optional[str]:
+    """Why a session persona cannot be used, or None when all are alive."""
+    if session is None or not session.session_check:
+        return None
+    try:
+        targets = _session_targets(session, cases, env)
+    except SessionConfigError as err:
+        return str(err)
+    for label, cookie in targets:
+        problem = check_session(args.base_url, label, cookie, session.session_check, session.session_marker, session.denial)
+        if problem:
+            return problem
+    return None
+
+
+def _matrix_cases_from_scan(
+    scan_file: Path,
+    args: argparse.Namespace,
+    min_consensus: float,
+    session: Optional[SessionOptions],
+    csrf: Optional[Any],
+) -> List[MatrixCase]:
     """BFLA and mass assignment findings from findings.json or SARIF."""
     try:
         data = json.loads(scan_file.read_text(encoding="utf-8"))
     except (OSError, ValueError):
         return []
     token_env = getattr(args, "token_env", None) or CLI_TOKEN_ENV
+    cookie_env = CLI_COOKIE_ENV if session and session.attacker_cookie else None
     cases = generate_matrix_cases_from_findings(
-        data, token_env=token_env, default_id=args.resource_id, min_consensus=min_consensus
+        data, token_env=token_env, default_id=args.resource_id, min_consensus=min_consensus,
+        cookie_env=cookie_env, body_format=args.body_format, csrf=csrf,
     )
     if cases:
         step_info(f"Synthesized {len(cases)} BFLA / mass assignment cases from scan findings")
     return cases
 
 
-def _run_matrix(cases: List[MatrixCase], args: argparse.Namespace) -> List[Any]:
+def _run_matrix(cases: List[MatrixCase], args: argparse.Namespace, session: Optional[SessionOptions]) -> List[Any]:
     if not cases:
         return []
     env: Dict[str, str] = dict(os.environ)
     if args.attacker_token:
         env.setdefault(CLI_TOKEN_ENV, args.attacker_token)
+    if session and session.attacker_cookie:
+        env[CLI_COOKIE_ENV] = session.attacker_cookie
     step(f"Executing {len(cases)} persona matrix cases")
-    return PersonaMatrixRunner(args.base_url, env=env, strict=args.strict).run(cases)
+    denial = session.denial if session else None
+    return PersonaMatrixRunner(args.base_url, env=env, strict=args.strict, denial=denial).run(cases)