crowdsec-local-mcp 0.2.0__py3-none-any.whl → 0.8.0.post1.dev0__py3-none-any.whl

crowdsec_local_mcp/mcp_waf.py

@@ -1,20 +1,34 @@
+import json
 import subprocess
+import tempfile
 import time
 import urllib.parse
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional, Tuple
+from typing import Any
+from collections.abc import Callable
 
 import jsonschema
 import requests
 import yaml
 
-import mcp.types as types
+from mcp import types
 
-from .mcp_core import LOGGER, PROMPTS_DIR, REGISTRY, SCRIPT_DIR, ToolHandler
+from .mcp_core import (
+    LOGGER,
+    PROMPTS_DIR,
+    REGISTRY,
+    SCRIPT_DIR,
+    ToolHandler,
+    ensure_docker_cli,
+    ensure_docker_compose_cli,
+)
 
+WAF_TOP_LEVEL_PROMPT_FILE = PROMPTS_DIR / "prompt-waf-top-level.txt"
 WAF_PROMPT_FILE = PROMPTS_DIR / "prompt-waf.txt"
 WAF_EXAMPLES_FILE = PROMPTS_DIR / "prompt-waf-examples.txt"
 WAF_DEPLOY_FILE = PROMPTS_DIR / "prompt-waf-deploy.txt"
+WAF_TESTS_PROMPT_FILE = PROMPTS_DIR / "prompt-waf-tests.txt"
+WAF_PR_PROMPT_FILE = PROMPTS_DIR / "prompt-waf-pr.txt"
 
 CROWDSEC_SCHEMAS_DIR = SCRIPT_DIR / "yaml-schemas"
 WAF_SCHEMA_FILE = CROWDSEC_SCHEMAS_DIR / "appsec_rules_schema.yaml"
@@ -22,20 +36,13 @@ WAF_SCHEMA_FILE = CROWDSEC_SCHEMAS_DIR / "appsec_rules_schema.yaml"
 WAF_TEST_COMPOSE_DIR = SCRIPT_DIR / "compose" / "waf-test"
 WAF_TEST_COMPOSE_FILE = WAF_TEST_COMPOSE_DIR / "docker-compose.yml"
 WAF_TEST_RULE_PATH = WAF_TEST_COMPOSE_DIR / "rules" / "current-rule.yaml"
-WAF_TEST_APPSEC_TEMPLATE = (
-    WAF_TEST_COMPOSE_DIR
-    / "crowdsec"
-    / "appsec-configs"
-    / "mcp-appsec.yaml.template"
-)
-WAF_TEST_APPSEC_CONFIG = (
-    WAF_TEST_COMPOSE_DIR
-    / "crowdsec"
-    / "appsec-configs"
-    / "mcp-appsec.yaml"
-)
+WAF_TEST_APPSEC_TEMPLATE = WAF_TEST_COMPOSE_DIR / "crowdsec" / "appsec-configs" / "mcp-appsec.yaml.template"
+WAF_TEST_APPSEC_CONFIG = WAF_TEST_COMPOSE_DIR / "crowdsec" / "appsec-configs" / "mcp-appsec.yaml"
 WAF_RULE_NAME_PLACEHOLDER = "__PLACEHOLDER_FOR_USER_RULE__"
 WAF_TEST_PROJECT_NAME = "crowdsec-mcp-waf"
+WAF_TEST_NETWORK_NAME = f"{WAF_TEST_PROJECT_NAME}_waf-net"
+WAF_DEFAULT_TARGET_URL = "http://nginx-appsec"
+WAF_DEFAULT_NUCLEI_IMAGE = "projectdiscovery/nuclei:latest"
 
 DEFAULT_EXPLOIT_REPOSITORIES = [
     "https://github.com/projectdiscovery/nuclei-templates.git",
@@ -45,45 +52,11 @@ DEFAULT_EXPLOIT_TARGET_DIR = SCRIPT_DIR / "cached-exploits"
 CASE_SENSITIVE_MATCH_TYPES = ["regex", "contains", "startsWith", "endsWith", "equals"]
 SQL_KEYWORD_INDICATORS = ["union", "select", "insert", "update", "delete", "drop"]
 
-_COMPOSE_CMD_CACHE: Optional[List[str]] = None
-_COMPOSE_STACK_PROCESS: Optional[subprocess.Popen] = None
-
-
-def _detect_compose_command() -> List[str]:
-    """Detect whether docker compose or docker-compose is available."""
-    global _COMPOSE_CMD_CACHE
-    if _COMPOSE_CMD_CACHE is not None:
-        return _COMPOSE_CMD_CACHE
-
-    candidates = [["docker", "compose"], ["docker-compose"]]
-
-    for candidate in candidates:
-        try:
-            result = subprocess.run(
-                candidate + ["version"],
-                check=True,
-                capture_output=True,
-                text=True,
-            )
-            if result.returncode == 0:
-                _COMPOSE_CMD_CACHE = candidate
-                LOGGER.info("Detected compose command: %s", " ".join(candidate))
-                return candidate
-        except FileNotFoundError:
-            continue
-        except subprocess.CalledProcessError:
-            continue
-
-    LOGGER.error(
-        "Failed to detect Docker Compose command; ensure Docker is installed and available"
-    )
-    raise RuntimeError(
-        "Docker Compose is required but was not found. Install Docker and ensure `docker compose` or `docker-compose` is available."
-    )
+_COMPOSE_STACK_PROCESS: subprocess.Popen | None = None
 
 
-def _collect_compose_logs(services: Optional[List[str]] = None, tail_lines: int = 200) -> str:
-    cmd = _detect_compose_command() + [
+def _collect_compose_logs(services: list[str] | None = None, tail_lines: int = 200) -> str:
+    cmd = ensure_docker_compose_cli() + [
         "-p",
         WAF_TEST_PROJECT_NAME,
         "-f",
@@ -101,11 +74,7 @@ def _collect_compose_logs(services: Optional[List[str]] = None, tail_lines: int
         check=False,
     )
 
-    combined = "\n".join(
-        part.strip()
-        for part in ((result.stdout or ""), (result.stderr or ""))
-        if part
-    ).strip()
+    combined = "\n".join(part.strip() for part in ((result.stdout or ""), (result.stderr or "")) if part).strip()
 
     if not combined:
         return ""
@@ -117,11 +86,9 @@ def _collect_compose_logs(services: Optional[List[str]] = None, tail_lines: int
     return "\n".join(lines)
 
 
-def _run_compose_command(
-    args: List[str], capture_output: bool = True, check: bool = True
-) -> subprocess.CompletedProcess:
+def _run_compose_command(args: list[str], capture_output: bool = True, check: bool = True) -> subprocess.CompletedProcess:
     """Run a docker compose command inside the WAF test harness directory."""
-    base_cmd = _detect_compose_command()
+    base_cmd = ensure_docker_compose_cli()
     full_cmd = base_cmd + ["-p", WAF_TEST_PROJECT_NAME, "-f", str(WAF_TEST_COMPOSE_FILE)] + args
     LOGGER.info("Executing compose command: %s", " ".join(full_cmd))
 
@@ -133,9 +100,9 @@ def _run_compose_command(
             capture_output=capture_output,
             text=True,
         )
-    except FileNotFoundError as error:
+    except (FileNotFoundError, PermissionError) as error:
         LOGGER.error("Compose command failed to start: %s", error)
-        raise RuntimeError(f"Failed to run {' '.join(base_cmd)}: {error}") from error
+        raise RuntimeError("Docker Compose is required but could not be executed. Install Docker and ensure the current user can run `docker compose` commands.") from error
     except subprocess.CalledProcessError as error:
         stdout = (error.stdout or "").strip()
         stderr = (error.stderr or "").strip()
@@ -147,14 +114,10 @@ def _run_compose_command(
             error.returncode,
             combined.splitlines()[0] if combined else "no output",
         )
-        raise RuntimeError(
-            f"docker compose {' '.join(args)} failed (exit code {error.returncode}):\n{combined}"
-        ) from error
+        raise RuntimeError(f"docker compose {' '.join(args)} failed (exit code {error.returncode}):\n{combined}") from error
 
 
-def _run_compose_exec(
-    args: List[str], capture_output: bool = True, check: bool = True
-) -> subprocess.CompletedProcess:
+def _run_compose_exec(args: list[str], capture_output: bool = True, check: bool = True) -> subprocess.CompletedProcess:
     """Run docker compose exec against the CrowdSec container."""
     exec_args = ["exec", "-T"] + args
     return _run_compose_command(exec_args, capture_output=capture_output, check=check)
@@ -164,9 +127,7 @@ def _teardown_compose_stack(check: bool = True) -> None:
     """Stop the compose stack and ensure any supervising process is terminated."""
     global _COMPOSE_STACK_PROCESS
     if not WAF_TEST_COMPOSE_FILE.exists():
-        LOGGER.warning(
-            "Requested stack teardown but compose file %s is missing", WAF_TEST_COMPOSE_FILE
-        )
+        LOGGER.warning("Requested stack teardown but compose file %s is missing", WAF_TEST_COMPOSE_FILE)
         _COMPOSE_STACK_PROCESS = None
         return
 
@@ -178,9 +139,7 @@ def _teardown_compose_stack(check: bool = True) -> None:
             try:
                 _COMPOSE_STACK_PROCESS.wait(timeout=15)
             except subprocess.TimeoutExpired:
-                LOGGER.warning(
-                    "Compose stack process did not exit in time; terminating forcefully"
-                )
+                LOGGER.warning("Compose stack process did not exit in time; terminating forcefully")
                 _COMPOSE_STACK_PROCESS.kill()
                 _COMPOSE_STACK_PROCESS.wait(timeout=5)
         _COMPOSE_STACK_PROCESS = None
@@ -198,14 +157,9 @@ def _wait_for_crowdsec_ready(timeout: int = 90) -> None:
                 _COMPOSE_STACK_PROCESS = None
                 logs = _collect_compose_logs(["crowdsec", "nginx", "backend"])
                 log_section = f"\n\nService logs:\n{logs}" if logs else ""
-                raise RuntimeError(
-                    "WAF stack exited while waiting for CrowdSec to become ready"
-                    f" (exit code {exit_code}).{log_section}"
-                )
+                raise RuntimeError(f"WAF stack exited while waiting for CrowdSec to become ready (exit code {exit_code}).{log_section}")
         try:
-            result = _run_compose_exec(
-                ["crowdsec", "cscli", "lapi", "status"], capture_output=True, check=False
-            )
+            result = _run_compose_exec(["crowdsec", "cscli", "lapi", "status"], capture_output=True, check=False)
             if isinstance(result, subprocess.CompletedProcess) and result.returncode == 0:
                 LOGGER.info("CrowdSec API is ready")
                 return
@@ -217,7 +171,111 @@ def _wait_for_crowdsec_ready(timeout: int = 90) -> None:
     raise RuntimeError("CrowdSec local API did not become ready in time")
 
 
-def _start_waf_test_stack(rule_yaml: str) -> Tuple[Optional[str], Optional[str]]:
+def _run_nuclei_container(
+    workspace: Path,
+    template_path: Path,
+    *,
+    nuclei_image: str,
+    target_url: str,
+    nuclei_args: list[str] | None = None,
+    timeout: int = 180,
+) -> tuple[bool, str]:
+    """Run the provided nuclei template inside a disposable docker container."""
+    rel_template = template_path.relative_to(workspace)
+    container_template_path = f"/nuclei/{rel_template.as_posix()}"
+
+    ensure_docker_cli()
+
+    command = [
+        "docker",
+        "run",
+        "--rm",
+        "--network",
+        WAF_TEST_NETWORK_NAME,
+        "-v",
+        f"{workspace}:/nuclei",
+        nuclei_image,
+        "-t",
+        container_template_path,
+        "-u",
+        target_url,
+        "-jsonl",
+        "-silent",
+    ]
+    if nuclei_args:
+        command.extend(str(arg) for arg in nuclei_args)
+
+    LOGGER.info("Executing nuclei container: %s", " ".join(command))
+
+    try:
+        result = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        LOGGER.error("Nuclei container timed out after %s seconds", timeout)
+        return (
+            False,
+            "Nuclei execution timed out. Consider simplifying the template or increasing the timeout.",
+        )
+
+    stdout = (result.stdout or "").strip()
+    stderr = (result.stderr or "").strip()
+    details: list[str] = []
+    if stdout:
+        details.append(f"stdout:\n{stdout}")
+    if stderr:
+        details.append(f"stderr:\n{stderr}")
+    detail_text = "\n\n".join(details)
+
+    if result.returncode != 0:
+        LOGGER.error("Nuclei container exited with code %s", result.returncode)
+        failure = f"Nuclei container exited with status {result.returncode}." + (f"\n\n{detail_text}" if detail_text else "")
+        return (False, failure)
+
+    matches: list[dict[str, Any]] = []
+    unmatched_lines: list[str] = []
+    for line in stdout.splitlines():
+        if not line.strip():
+            continue
+        try:
+            payload = json.loads(line)
+            if isinstance(payload, dict):
+                matches.append(payload)
+            else:
+                unmatched_lines.append(line)
+        except json.JSONDecodeError:
+            unmatched_lines.append(line)
+
+    if not matches:
+        LOGGER.warning("Nuclei execution completed but no matches were reported")
+        info_lines = []
+        if unmatched_lines:
+            info_lines.append("Nuclei produced output but no matches were recorded:\n" + "\n".join(unmatched_lines))
+        else:
+            info_lines.append("Nuclei completed successfully but reported zero matches. The WAF rule likely did not block the request (missing HTTP 403).")
+        if stderr:
+            info_lines.append(f"stderr:\n{stderr}")
+        return (False, "\n\n".join(info_lines))
+
+    summary_lines = [
+        f"Nuclei reported {len(matches)} match(es) using template {rel_template.name}.",
+    ]
+    for match in matches:
+        template_id = match.get("template-id") or match.get("templateID") or rel_template.stem
+        url = match.get("matched-at") or match.get("matchedAt") or target_url
+        summary_lines.append(f" - {template_id} matched at {url}")
+    if unmatched_lines:
+        summary_lines.append("Additional nuclei output:\n" + "\n".join(unmatched_lines))
+    if stderr:
+        summary_lines.append(f"stderr:\n{stderr}")
+    return (True, "\n".join(summary_lines))
+
+
+def _start_waf_test_stack(rule_yaml: str) -> tuple[str | None, str | None]:
     global _COMPOSE_STACK_PROCESS
     LOGGER.info("Starting WAF test stack")
     if not WAF_TEST_COMPOSE_FILE.exists():
@@ -289,7 +347,7 @@ def _start_waf_test_stack(rule_yaml: str) -> Tuple[Optional[str], Optional[str]]
         _teardown_compose_stack(check=False)
         return (None, f"{error}{log_section}")
 
-    compose_base = _detect_compose_command() + [
+    compose_base = ensure_docker_compose_cli() + [
         "-p",
         WAF_TEST_PROJECT_NAME,
         "-f",
@@ -306,11 +364,12 @@ def _start_waf_test_stack(rule_yaml: str) -> Tuple[Optional[str], Optional[str]]
             stdout=subprocess.DEVNULL,
             stderr=subprocess.STDOUT,
         )
-    except FileNotFoundError:
+        LOGGER.info("Launched docker compose process with PID %s", process.pid)
+    except (FileNotFoundError, PermissionError):
         LOGGER.error("Failed to launch docker compose process")
         return (
             None,
-            "Docker Compose is required but could not be executed. Ensure Docker is installed and available.",
+            "Docker Compose is required but could not be executed. Ensure Docker is installed and the current user can run Docker commands.",
         )
 
     _COMPOSE_STACK_PROCESS = process
@@ -336,226 +395,206 @@ def _stop_waf_test_stack() -> None:
     _teardown_compose_stack(check=True)
 
 
-def _validate_waf_rule(rule_yaml: str) -> List[types.TextContent]:
+def _validate_waf_rule(rule_yaml: str) -> list[types.TextContent]:
     """Validate that a CrowdSec WAF rule YAML conforms to the schema."""
     LOGGER.info("Validating WAF rule YAML (size=%s bytes)", len(rule_yaml.encode("utf-8")))
-    try:
-        if not WAF_SCHEMA_FILE.exists():
-            LOGGER.error("Schema file missing at %s", WAF_SCHEMA_FILE)
-            return [
-                types.TextContent(
-                    type="text",
-                    text=f"❌ VALIDATION FAILED: Schema file {WAF_SCHEMA_FILE} not found",
-                )
-            ]
+    if not WAF_SCHEMA_FILE.exists():
+        LOGGER.error("Schema file missing at %s", WAF_SCHEMA_FILE)
+        raise FileNotFoundError(f"Schema file {WAF_SCHEMA_FILE} not found")
 
+    try:
         schema = yaml.safe_load(WAF_SCHEMA_FILE.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        LOGGER.error("Failed to parse WAF schema YAML: %s", exc)
+        raise ValueError(f"Unable to parse WAF schema YAML: {exc!s}") from exc
+
+    try:
         parsed = yaml.safe_load(rule_yaml)
+    except yaml.YAMLError as exc:
+        LOGGER.error("YAML syntax error during validation: %s", exc)
+        raise ValueError(f"YAML syntax error: {exc!s}") from exc
 
-        if parsed is None:
-            LOGGER.warning("Validation request received empty YAML content")
-            return [
-                types.TextContent(
-                    type="text",
-                    text="❌ VALIDATION FAILED: Empty or invalid YAML content",
-                )
-            ]
+    if parsed is None:
+        LOGGER.warning("Validation request received empty YAML content")
+        raise ValueError("Empty or invalid YAML content")
 
-        if not isinstance(parsed, dict):
-            return [
-                types.TextContent(
-                    type="text",
-                    text="❌ VALIDATION FAILED: YAML must be a dictionary/object",
-                )
-            ]
+    if not isinstance(parsed, dict):
+        raise ValueError("YAML must be a dictionary/object")
 
+    try:
         jsonschema.validate(instance=parsed, schema=schema)
+    except jsonschema.ValidationError as exc:
+        error_path = " -> ".join(str(p) for p in exc.absolute_path) if exc.absolute_path else "root"
+        LOGGER.warning("Schema validation error at %s: %s", error_path, exc.message)
+        raise ValueError(f"Schema validation error at {error_path}: {exc.message}") from exc
+    except jsonschema.SchemaError as exc:
+        LOGGER.error("Invalid schema encountered: %s", exc)
+        raise RuntimeError(f"Invalid schema: {exc!s}") from exc
+
+    LOGGER.info("WAF rule validation passed")
+    return [
+        types.TextContent(
+            type="text",
+            text="✅ VALIDATION PASSED: Rule conforms to CrowdSec AppSec schema",
+        )
+    ]
 
-        LOGGER.info("WAF rule validation passed")
-        return [
-            types.TextContent(
-                type="text",
-                text="✅ VALIDATION PASSED: Rule conforms to CrowdSec AppSec schema",
-            )
-        ]
 
-    except yaml.YAMLError as e:
-        LOGGER.error("YAML syntax error during validation: %s", e)
-        return [
-            types.TextContent(
-                type="text",
-                text=f"❌ VALIDATION FAILED: YAML syntax error: {str(e)}",
-            )
-        ]
-    except jsonschema.ValidationError as e:
-        error_path = " -> ".join(str(p) for p in e.absolute_path) if e.absolute_path else "root"
-        LOGGER.warning("Schema validation error at %s: %s", error_path, e.message)
-        return [
-            types.TextContent(
-                type="text",
-                text=f"❌ VALIDATION FAILED: Schema validation error at {error_path}: {e.message}",
-            )
-        ]
-    except jsonschema.SchemaError as e:
-        LOGGER.error("Invalid schema encountered: %s", e)
-        return [
-            types.TextContent(
-                type="text",
-                text=f"❌ VALIDATION FAILED: Invalid schema: {str(e)}",
+def _analyze_rule_item(rule_item: Any, rule_path: str, warnings: list[str]) -> tuple[bool, bool]:
+    """Recursively inspect rule items, track operator usage, and record warnings."""
+    if not isinstance(rule_item, dict):
+        return (False, False)
+
+    location = f"rules{rule_path}" if rule_path else "rules"
+    has_and = "and" in rule_item
+    has_or = "or" in rule_item
+    contains_and = has_and
+    contains_or = has_or
+
+    if has_and and has_or:
+        warnings.append(f"{location} mixes 'and' and 'or' operators at the same level; split them into separate nested blocks")
+
+    if has_and:
+        for i, sub_rule in enumerate(rule_item["and"]):
+            child_and, child_or = _analyze_rule_item(
+                sub_rule,
+                f"{rule_path}.and[{i}]",
+                warnings,
             )
-        ]
-    except Exception as e:
-        LOGGER.error("Unexpected validation error: %s", e)
-        return [
-            types.TextContent(
-                type="text",
-                text=f"❌ VALIDATION FAILED: Unexpected error: {str(e)}",
+            contains_and = contains_and or child_and
+            contains_or = contains_or or child_or
+
+    if has_or:
+        for i, sub_rule in enumerate(rule_item["or"]):
+            child_and, child_or = _analyze_rule_item(
+                sub_rule,
+                f"{rule_path}.or[{i}]",
+                warnings,
             )
-        ]
+            contains_and = contains_and or child_and
+            contains_or = contains_or or child_or
 
+    if "match" in rule_item and not (has_and or has_or):
+        match = rule_item["match"]
+        if isinstance(match, dict):
+            match_type = match.get("type", "")
+            match_value = match.get("value", "")
 
-def _lint_waf_rule(rule_yaml: str) -> List[types.TextContent]:
+            if match_type in CASE_SENSITIVE_MATCH_TYPES and isinstance(match_value, str) and any(c.isupper() for c in match_value):
+                transforms = rule_item.get("transform", [])
+                has_lowercase = "lowercase" in transforms if isinstance(transforms, list) else False
+
+                if not has_lowercase:
+                    warnings.append(
+                        f"Match at {location} uses '{match_type}' with uppercase letters but no 'lowercase' transform - consider adding lowercase transform for case-insensitive matching"
+                    )
+
+            if isinstance(match_value, str):
+                lower_value = match_value.lower()
+                sql_keywords = [kw for kw in SQL_KEYWORD_INDICATORS if kw in lower_value]
+                if sql_keywords:
+                    keywords_str = ", ".join(sorted(set(sql_keywords)))
+                    warnings.append(f"Match at {location} contains SQL keyword(s) ({keywords_str}); instead of keyword blacklisting, detect escaping characters like quotes or semicolons")
+
+                transforms = rule_item.get("transform", [])
+                if isinstance(transforms, list) and "urldecode" in transforms:
+                    if "%" in match_value:
+                        warnings.append(
+                            f"Match at {location} applies 'urldecode' but still contains percent-encoded characters; ensure the value is properly decoded or add another urldecode pass."
+                        )
+
+    return (contains_and, contains_or)
+
+
+def lint_waf_rule(rule_yaml: str) -> list[types.TextContent]:
     """Lint a CrowdSec WAF rule and provide warnings/hints for improvement."""
     LOGGER.info("Linting WAF rule YAML (size=%s bytes)", len(rule_yaml.encode("utf-8")))
     try:
         parsed = yaml.safe_load(rule_yaml)
+    except yaml.YAMLError as exc:
+        LOGGER.error("Lint failed due to YAML error: %s", exc)
+        raise ValueError(f"Cannot lint invalid YAML: {exc!s}") from exc
 
-        if parsed is None:
-            LOGGER.warning("Lint request failed: YAML content was empty or invalid")
-            return [
-                types.TextContent(
-                    type="text",
-                    text="❌ LINT ERROR: Cannot lint empty or invalid YAML",
-                )
-            ]
-
-        warnings: List[str] = []
-        hints: List[str] = []
+    if parsed is None:
+        LOGGER.warning("Lint request failed: YAML content was empty or invalid")
+        raise ValueError("Cannot lint empty or invalid YAML")
 
-        if not isinstance(parsed, dict):
-            warnings.append("Rule should be a YAML dictionary")
+    warnings: list[str] = []
+    hints: list[str] = []
 
-        if "name" not in parsed:
-            warnings.append("Missing 'name' field")
+    if not isinstance(parsed, dict):
+        warnings.append("Rule should be a YAML dictionary")
 
-        if "rules" not in parsed:
-            warnings.append("Missing 'rules' field")
+    if "name" not in parsed:
+        warnings.append("Missing 'name' field")
 
-        if "labels" not in parsed:
-            warnings.append("Missing 'labels' field")
+    if "rules" not in parsed:
+        warnings.append("Missing 'rules' field")
 
-        if "name" in parsed:
-            name = parsed.get("name", "")
-            if isinstance(name, str):
-                if name.startswith("crowdsecurity/"):
-                    warnings.append(
-                        "Rule name starts with 'crowdsecurity/' which is reserved for official CrowdSec rules; consider using your own namespace"
-                    )
-            else:
-                warnings.append("Field 'name' should be a string")
-
-        def check_rule_item(rule_item: Any, rule_path: str = "") -> None:
-            """Recursively check rule items for case sensitivity issues."""
-            if not isinstance(rule_item, dict):
-                return
-
-            if "and" in rule_item:
-                for i, sub_rule in enumerate(rule_item["and"]):
-                    check_rule_item(sub_rule, f"{rule_path}.and[{i}]")
-            elif "or" in rule_item:
-                for i, sub_rule in enumerate(rule_item["or"]):
-                    check_rule_item(sub_rule, f"{rule_path}.or[{i}]")
-            elif "match" in rule_item:
-                match = rule_item["match"]
-                if isinstance(match, dict):
-                    match_type = match.get("type", "")
-                    match_value = match.get("value", "")
-
-                    if (
-                        match_type in CASE_SENSITIVE_MATCH_TYPES
-                        and isinstance(match_value, str)
-                        and any(c.isupper() for c in match_value)
-                    ):
-                        transforms = rule_item.get("transform", [])
-                        has_lowercase = (
-                            "lowercase" in transforms if isinstance(transforms, list) else False
-                        )
+    if "labels" not in parsed:
+        warnings.append("Missing 'labels' field")
 
-                        if not has_lowercase:
-                            location = f"rules{rule_path}" if rule_path else "rules"
-                            warnings.append(
-                                f"Match at {location} uses '{match_type}' with uppercase letters "
-                                f"but no 'lowercase' transform - consider adding lowercase transform for case-insensitive matching"
-                            )
-
-                    if isinstance(match_value, str):
-                        lower_value = match_value.lower()
-                        sql_keywords = [kw for kw in SQL_KEYWORD_INDICATORS if kw in lower_value]
-                        if sql_keywords:
-                            location = f"rules{rule_path}" if rule_path else "rules"
-                            keywords_str = ", ".join(sorted(set(sql_keywords)))
-                            warnings.append(
-                                f"Match at {location} contains SQL keyword(s) ({keywords_str}); instead of keyword blacklisting, detect escaping characters like quotes or semicolons"
-                            )
-
-                        transforms = rule_item.get("transform", [])
-                        if isinstance(transforms, list) and "urldecode" in transforms:
-                            if "%" in match_value:
-                                location = f"rules{rule_path}" if rule_path else "rules"
-                                warnings.append(
-                                    f"Match at {location} applies 'urldecode' but still contains percent-encoded characters; ensure the value is properly decoded or add another urldecode pass."
-                                )
-
-        if "rules" in parsed and isinstance(parsed["rules"], list):
-            for i, rule in enumerate(parsed["rules"]):
-                check_rule_item(rule, f"[{i}]")
-
-        result_lines: List[str] = []
-
-        if not warnings and not hints:
-            result_lines.append("✅ LINT PASSED: No issues found")
-            LOGGER.info("Lint completed with no findings")
+    if "name" in parsed:
+        name = parsed.get("name", "")
+        if isinstance(name, str):
+            if name.startswith("crowdsecurity/"):
+                warnings.append("Rule name starts with 'crowdsecurity/' which is reserved for official CrowdSec rules; consider using your own namespace")
         else:
+            warnings.append("Field 'name' should be a string")
+
+    if "rules" in parsed and isinstance(parsed["rules"], list):
+        for i, rule in enumerate(parsed["rules"]):
+            rule_has_and, rule_has_or = _analyze_rule_item(rule, f"[{i}]", warnings)
+            if rule_has_and and rule_has_or:
+                warnings.append(f"rules[{i}] uses both 'and' and 'or' operators somewhere in the block; CrowdSec cannot mix them in one rule, split the logic into separate rules")
+
+    result_lines: list[str] = []
+
+    if not warnings and not hints:
+        result_lines.append("✅ LINT PASSED: No issues found")
+        LOGGER.info("Lint completed with no findings")
+    else:
+        if warnings:
+            result_lines.append("⚠️  WARNINGS:")
+            for warning in warnings:
+                result_lines.append(f"  - {warning}")
+            LOGGER.warning("Lint completed with %s warning(s)", len(warnings))
+
+        if hints:
             if warnings:
-                result_lines.append("⚠️  WARNINGS:")
-                for warning in warnings:
-                    result_lines.append(f"  - {warning}")
-                LOGGER.warning("Lint completed with %s warning(s)", len(warnings))
-
-            if hints:
-                if warnings:
-                    result_lines.append("")
-                result_lines.append("💡 HINTS:")
-                for hint in hints:
-                    result_lines.append(f"  - {hint}")
-                LOGGER.info("Lint completed with %s hint(s)", len(hints))
+                result_lines.append("")
+            result_lines.append("💡 HINTS:")
+            for hint in hints:
+                result_lines.append(f"  - {hint}")
+            LOGGER.info("Lint completed with %s hint(s)", len(hints))
+
+    return [
+        types.TextContent(
+            type="text",
+            text="\n".join(result_lines),
+        )
+    ]
 
-        return [
-            types.TextContent(
-                type="text",
-                text="\n".join(result_lines),
-            )
-        ]
 
-    except yaml.YAMLError as e:
-        LOGGER.error("Lint failed due to YAML error: %s", e)
-        return [
-            types.TextContent(
-                type="text",
-                text=f"❌ LINT ERROR: Cannot lint invalid YAML: {str(e)}",
-            )
-        ]
-    except Exception as e:
-        LOGGER.error("Unexpected lint error: %s", e)
+def _tool_get_waf_top_level_prompt(_: dict[str, Any] | None) -> list[types.TextContent]:
+    try:
+        LOGGER.info("Serving WAF top-level orchestration prompt content")
+        prompt_content = WAF_TOP_LEVEL_PROMPT_FILE.read_text(encoding="utf-8")
         return [
             types.TextContent(
                 type="text",
-                text=f"❌ LINT ERROR: Unexpected error: {str(e)}",
+                text=prompt_content,
             )
         ]
+    except FileNotFoundError as exc:
+        LOGGER.error("WAF top-level prompt file not found at %s", WAF_TOP_LEVEL_PROMPT_FILE)
+        raise FileNotFoundError(f"WAF top-level prompt file not found at {WAF_TOP_LEVEL_PROMPT_FILE}") from exc
+    except Exception as exc:
+        LOGGER.error("Error loading WAF top-level prompt: %s", exc)
+        raise RuntimeError(f"Error reading WAF top-level prompt file: {exc!s}") from exc
 
 
-def _tool_get_waf_prompt(_: Optional[Dict[str, Any]]) -> List[types.TextContent]:
+def _tool_get_waf_prompt(_: dict[str, Any] | None) -> list[types.TextContent]:
     try:
         LOGGER.info("Serving WAF prompt content")
         prompt_content = WAF_PROMPT_FILE.read_text(encoding="utf-8")
@@ -565,25 +604,15 @@ def _tool_get_waf_prompt(_: Optional[Dict[str, Any]]) -> List[types.TextContent]
                 text=prompt_content,
             )
         ]
-    except FileNotFoundError:
+    except FileNotFoundError as exc:
         LOGGER.error("WAF prompt file not found at %s", WAF_PROMPT_FILE)
-        return [
-            types.TextContent(
-                type="text",
-                text="Error: WAF prompt file not found.",
-            )
-        ]
+        raise FileNotFoundError(f"WAF prompt file not found at {WAF_PROMPT_FILE}") from exc
     except Exception as exc:
         LOGGER.error("Error loading WAF prompt: %s", exc)
-        return [
-            types.TextContent(
-                type="text",
-                text=f"Error reading WAF prompt file: {str(exc)}",
-            )
-        ]
+        raise RuntimeError(f"Error reading WAF prompt file: {exc!s}") from exc
 
 
-def _tool_get_waf_examples(_: Optional[Dict[str, Any]]) -> List[types.TextContent]:
+def _tool_get_waf_examples(_: dict[str, Any] | None) -> list[types.TextContent]:
     try:
         LOGGER.info("Serving WAF examples content")
         examples_content = WAF_EXAMPLES_FILE.read_text(encoding="utf-8")
@@ -593,25 +622,15 @@ def _tool_get_waf_examples(_: Optional[Dict[str, Any]]) -> List[types.TextConten
                 text=examples_content,
             )
         ]
-    except FileNotFoundError:
+    except FileNotFoundError as exc:
         LOGGER.error("WAF examples file not found at %s", WAF_EXAMPLES_FILE)
-        return [
-            types.TextContent(
-                type="text",
-                text="Error: WAF examples file not found.",
-            )
-        ]
+        raise FileNotFoundError(f"WAF examples file not found at {WAF_EXAMPLES_FILE}") from exc
     except Exception as exc:
         LOGGER.error("Error loading WAF examples: %s", exc)
-        return [
-            types.TextContent(
-                type="text",
-                text=f"Error reading WAF examples file: {str(exc)}",
-            )
-        ]
+        raise RuntimeError(f"Error reading WAF examples file: {exc!s}") from exc
 
 
-def _tool_generate_waf_rule(arguments: Optional[Dict[str, Any]]) -> List[types.TextContent]:
+def _tool_generate_waf_rule(arguments: dict[str, Any] | None) -> list[types.TextContent]:
     try:
         main_prompt = WAF_PROMPT_FILE.read_text(encoding="utf-8")
         examples_prompt = WAF_EXAMPLES_FILE.read_text(encoding="utf-8")
@@ -624,10 +643,7 @@ def _tool_generate_waf_rule(arguments: Optional[Dict[str, Any]]) -> List[types.T
             bool(nuclei_template),
         )
         if nuclei_template:
-            combined_prompt += (
-                "\n\n### Input Nuclei Template to Process:\n"
-                f"```yaml\n{nuclei_template}\n```"
-            )
+            combined_prompt += f"\n\n### Input Nuclei Template to Process:\n```yaml\n{nuclei_template}\n```"
 
         return [
             types.TextContent(
@@ -637,53 +653,86 @@ def _tool_generate_waf_rule(arguments: Optional[Dict[str, Any]]) -> List[types.T
         ]
     except FileNotFoundError as exc:
         LOGGER.error("Prompt generation failed due to missing file: %s", exc)
-        return [
-            types.TextContent(
-                type="text",
-                text=f"Error: Prompt file not found: {str(exc)}",
-            )
-        ]
+        raise FileNotFoundError(f"Prompt file not found: {exc!s}") from exc
     except Exception as exc:
         LOGGER.error("Unexpected error generating WAF prompt: %s", exc)
+        raise RuntimeError(f"Error generating WAF rule prompt: {exc!s}") from exc
+
+
+def _tool_generate_waf_tests(arguments: dict[str, Any] | None) -> list[types.TextContent]:
+    try:
+        tests_prompt = WAF_TESTS_PROMPT_FILE.read_text(encoding="utf-8")
+        nuclei_template = arguments.get("nuclei_template") if arguments else None
+        rule_filename = arguments.get("rule_filename") if arguments else None
+
+        LOGGER.info(
+            "Generating WAF test prompt (nuclei_template_present=%s, rule_filename_present=%s)",
+            bool(nuclei_template),
+            bool(rule_filename),
+        )
+
+        combined_prompt = tests_prompt
+
+        if rule_filename:
+            combined_prompt += f"\n\n### Rule Under Test\nThe detection rule produced earlier is stored at: {rule_filename}\nUse this exact path in the config.yaml `appsec-rules` list."
+
+        if nuclei_template:
+            combined_prompt += f"\n\n### Input Nuclei Template to Adapt:\n```yaml\n{nuclei_template}\n```"
+
         return [
             types.TextContent(
                 type="text",
-                text=f"Error generating WAF rule prompt: {str(exc)}",
+                text=combined_prompt,
             )
         ]
+    except FileNotFoundError as exc:
+        LOGGER.error("WAF test prompt missing: %s", exc)
+        raise FileNotFoundError(f"WAF test prompt file not found: {exc!s}") from exc
+    except Exception as exc:
+        LOGGER.error("Unexpected error generating WAF test prompt: %s", exc)
+        raise RuntimeError(f"Error generating WAF test prompt: {exc!s}") from exc
 
 
-def _tool_validate_waf_rule(arguments: Optional[Dict[str, Any]]) -> List[types.TextContent]:
+def _tool_get_waf_pr_prompt(_: dict[str, Any] | None) -> list[types.TextContent]:
+    try:
+        LOGGER.info("Serving WAF PR prompt content")
+        prompt_content = WAF_PR_PROMPT_FILE.read_text(encoding="utf-8")
+        return [types.TextContent(type="text", text=prompt_content)]
+    except FileNotFoundError as exc:
+        LOGGER.error("WAF PR prompt file not found at %s", WAF_PR_PROMPT_FILE)
+        raise FileNotFoundError(f"WAF PR prompt file not found at {WAF_PR_PROMPT_FILE}") from exc
+    except Exception as exc:
+        LOGGER.error("Error reading WAF PR prompt: %s", exc)
+        raise RuntimeError(f"Error reading WAF PR prompt: {exc!s}") from exc
+
+
+def _tool_validate_waf_rule(arguments: dict[str, Any] | None) -> list[types.TextContent]:
     if not arguments or "rule_yaml" not in arguments:
         LOGGER.warning("Validation request missing 'rule_yaml' argument")
-        return [
-            types.TextContent(
-                type="text",
-                text="Error: rule_yaml parameter is required",
-            )
-        ]
+        raise ValueError("rule_yaml parameter is required")
 
     rule_yaml = arguments["rule_yaml"]
+    if not isinstance(rule_yaml, str):
+        raise TypeError("rule_yaml must be provided as a string")
+
     LOGGER.info("Received validation request for WAF rule")
     return _validate_waf_rule(rule_yaml)
 
 
-def _tool_lint_waf_rule(arguments: Optional[Dict[str, Any]]) -> List[types.TextContent]:
+def _tool_lint_waf_rule(arguments: dict[str, Any] | None) -> list[types.TextContent]:
     if not arguments or "rule_yaml" not in arguments:
         LOGGER.warning("Lint request missing 'rule_yaml' argument")
-        return [
-            types.TextContent(
-                type="text",
-                text="Error: rule_yaml parameter is required",
-            )
-        ]
+        raise ValueError("rule_yaml parameter is required")
 
     rule_yaml = arguments["rule_yaml"]
+    if not isinstance(rule_yaml, str):
+        raise TypeError("rule_yaml must be provided as a string")
+
     LOGGER.info("Received lint request for WAF rule")
-    return _lint_waf_rule(rule_yaml)
+    return lint_waf_rule(rule_yaml)
 
 
-def _tool_deploy_waf_rule(_: Optional[Dict[str, Any]]) -> List[types.TextContent]:
+def _tool_deploy_waf_rule(_: dict[str, Any] | None) -> list[types.TextContent]:
     try:
         LOGGER.info("Serving WAF deployment guide content")
         deploy_content = WAF_DEPLOY_FILE.read_text(encoding="utf-8")
@@ -693,25 +742,165 @@ def _tool_deploy_waf_rule(_: Optional[Dict[str, Any]]) -> List[types.TextContent
                 text=deploy_content,
             )
         ]
-    except FileNotFoundError:
+    except FileNotFoundError as exc:
         LOGGER.error("WAF deployment guide missing at %s", WAF_DEPLOY_FILE)
-        return [
-            types.TextContent(
-                type="text",
-                text="Error: WAF deployment guide file not found.",
-            )
-        ]
+        raise FileNotFoundError(f"WAF deployment guide file not found at {WAF_DEPLOY_FILE}") from exc
     except Exception as exc:
         LOGGER.error("Error loading WAF deployment guide: %s", exc)
-        return [
-            types.TextContent(
-                type="text",
-                text=f"Error reading WAF deployment guide: {str(exc)}",
-            )
-        ]
+        raise RuntimeError(f"Error reading WAF deployment guide: {exc!s}") from exc
 
 
-def _tool_manage_waf_stack(arguments: Optional[Dict[str, Any]]) -> List[types.TextContent]:
+def _is_relative_to(base: Path, target: Path) -> bool:
+    try:
+        target.relative_to(base)
+    except ValueError:
+        return False
+    return True
+
+def _require_non_empty_str(value: Any, field: str, message: str | None = None) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(message or f"'{field}' must be a non-empty string")
+    return value.strip()
+
+
+def _parse_collection_name(collection_name: str) -> tuple[str, str]:
+    normalized = collection_name.strip().lstrip("/")
+    if normalized.count("/") != 1:
+        raise ValueError("'collection_name' must be in the format 'author/name'")
+    author, name = normalized.split("/", 1)
+    if not author or not name:
+        raise ValueError("'collection_name' must be in the format 'author/name'")
+    return author, name
+
+
+def _load_yaml_mapping(payload: str, error_context: str) -> dict[str, Any]:
+    try:
+        parsed = yaml.safe_load(payload) or {}
+    except yaml.YAMLError as exc:
+        raise RuntimeError(f"Failed to parse {error_context}: {exc}") from exc
+    if not isinstance(parsed, dict):
+        raise RuntimeError(f"{error_context} must be a mapping")
+    return parsed
+
+
+def _update_collection_with_rule(
+    summary_lines: list[str],
+    hub_root: Path,
+    collection_name: str,
+    rule_yaml: str,
+) -> None:
+    author, name = _parse_collection_name(collection_name)
+    collection_file = (hub_root / "collections" / author / f"{name}.yaml").resolve()
+    if not _is_relative_to(hub_root, collection_file):
+        raise ValueError("Resolved collection path escapes the hub directory")
+    if not collection_file.exists():
+        summary_lines.append(f"- Warning: collection file not found at {collection_file}. Add the rule manually.")
+        return
+
+    collection_payload = _load_yaml_mapping(
+        collection_file.read_text(encoding="utf-8"),
+        f"collection YAML at {collection_file}",
+    )
+    appsec_rules = collection_payload.get("appsec-rules")
+    if appsec_rules is None:
+        appsec_rules = []
+        collection_payload["appsec-rules"] = appsec_rules
+    if not isinstance(appsec_rules, list):
+        raise RuntimeError("'appsec-rules' in the collection file must be a list")
+
+    rule_payload = _load_yaml_mapping(rule_yaml, "rule YAML to read the rule name")
+    rule_name = rule_payload.get("name")
+    if not isinstance(rule_name, str) or not rule_name.strip():
+        raise RuntimeError("Rule YAML must include a non-empty 'name' field to update the collection")
+    rule_name = rule_name.strip()
+
+    if rule_name in appsec_rules:
+        summary_lines.append("- Collection already includes the rule; no update needed")
+        return
+
+    appsec_rules.append(rule_name)
+    collection_file.write_text(
+        yaml.safe_dump(collection_payload, sort_keys=False),
+        encoding="utf-8",
+    )
+    summary_lines.append(f"- Updated collection: added {rule_name} to {collection_file}")
+
+def _tool_prepare_waf_pr(arguments: dict[str, Any] | None) -> list[types.TextContent]:
+    if not arguments:
+        LOGGER.warning("prepare_waf_pr called without arguments")
+        raise ValueError("Missing arguments payload")
+
+    hub_dir = _require_non_empty_str(
+        arguments.get("hub_dir"),
+        "hub_dir",
+        "'hub_dir' must be a non-empty string pointing to a local CrowdSec hub clone",
+    )
+    rule_yaml = _require_non_empty_str(
+        arguments.get("rule_yaml"),
+        "rule_yaml",
+        "'rule_yaml' must be a non-empty string containing the WAF rule",
+    )
+    test_config_yaml = _require_non_empty_str(
+        arguments.get("test_config_yaml"),
+        "test_config_yaml",
+        "'test_config_yaml' must be a non-empty string containing the test config.yaml",
+    )
+    test_nuclei_yaml = _require_non_empty_str(
+        arguments.get("test_nuclei_yaml"),
+        "test_nuclei_yaml",
+        "'test_nuclei_yaml' must be a non-empty string containing the adapted nuclei template",
+    )
+    rule_filename = _require_non_empty_str(arguments.get("rule_filename"), "rule_filename")
+    nuclei_filename = _require_non_empty_str(arguments.get("nuclei_filename"), "nuclei_filename")
+    collection_name = arguments.get("collection_name")
+    if collection_name is not None and (not isinstance(collection_name, str) or not collection_name.strip()):
+        raise ValueError("'collection_name' must be a non-empty string when provided")
+
+    hub_path = Path(hub_dir).expanduser()
+    hub_root = hub_path.resolve()
+    if not hub_path.exists() or not hub_path.is_dir():
+        raise ValueError(f"hub_dir does not exist or is not a directory: {hub_path}")
+
+    rule_rel_path = Path(rule_filename.strip())
+
+    rule_path = (hub_path / rule_rel_path).resolve()
+    if not _is_relative_to(hub_root, rule_path):
+        raise ValueError("Resolved rule path escapes the hub directory")
+
+    rule_path.parent.mkdir(parents=True, exist_ok=True)
+    rule_path.write_text(rule_yaml, encoding="utf-8")
+
+    test_dir_name = rule_path.stem
+    tests_root = (hub_path / ".appsec-tests" / test_dir_name).resolve()
+    if not _is_relative_to(hub_root, tests_root):
+        raise ValueError("Resolved test path escapes the hub directory")
+    tests_root.mkdir(parents=True, exist_ok=True)
+
+    nuclei_file = nuclei_filename.strip()
+    if not nuclei_file.endswith(".yaml"):
+        nuclei_file = f"{nuclei_file}.yaml"
+
+    config_path = tests_root / "config.yaml"
+    nuclei_path = tests_root / nuclei_file
+    config_path.write_text(test_config_yaml, encoding="utf-8")
+    nuclei_path.write_text(test_nuclei_yaml, encoding="utf-8")
+
+    summary_lines = [
+        "Prepared PR assets in the hub clone:",
+        f"- Rule: {rule_path}",
+        f"- Test config: {config_path}",
+        f"- Test nuclei: {nuclei_path}",
+    ]
+
+    if collection_name:
+        _update_collection_with_rule(summary_lines, hub_root, collection_name, rule_yaml)
+    else:
+        summary_lines.append("- Warning: rule not added to appsec-virtual-patching collection. Remember to add it before opening the PR.")
+
+    return [types.TextContent(type="text", text="\n".join(summary_lines))]
+
+
+def _tool_manage_waf_stack(arguments: dict[str, Any] | None) -> list[types.TextContent]:
     try:
         if not arguments:
             LOGGER.warning("manage_waf_stack called without arguments")
@@ -732,23 +921,11 @@ def _tool_manage_waf_stack(arguments: Optional[Dict[str, Any]]) -> List[types.Te
             target_url, error_message = _start_waf_test_stack(rule_yaml)
             if error_message:
                 LOGGER.error("Failed to start WAF stack: %s", error_message)
-                return [
-                    types.TextContent(
-                        type="text",
-                        text=f"❌ WAF stack start error: {error_message}",
-                    )
-                ]
+                raise RuntimeError(f"WAF stack start error: {error_message}")
 
             if not target_url:
                 LOGGER.error("WAF stack start returned no target URL and no explicit error")
-                return [
-                    types.TextContent(
-                        type="text",
-                        text=(
-                            "❌ WAF stack start error: stack did not return a service URL but also did not report a specific error."
-                        ),
-                    )
-                ]
+                raise RuntimeError("WAF stack start error: stack did not return a service URL and reported no specific error.")
 
             return [
                 types.TextContent(
@@ -772,19 +949,111 @@ def _tool_manage_waf_stack(arguments: Optional[Dict[str, Any]]) -> List[types.Te
         ]
 
     except Exception as exc:
-        LOGGER.error("manage_waf_stack error: %s", exc)
+        LOGGER.error("manage_waf_stack error: %s", exc, exc_info=True)
+        raise
+
+
+def _tool_run_waf_tests(arguments: dict[str, Any] | None) -> list[types.TextContent]:
+    stack_started_here = False
+    try:
+        if not arguments:
+            LOGGER.warning("run_waf_tests called without arguments")
+            raise ValueError("Missing arguments payload")
+
+        rule_yaml = arguments.get("rule_yaml")
+        nuclei_yaml = arguments.get("nuclei_yaml")
+
+        if not isinstance(rule_yaml, str) or not rule_yaml.strip():
+            raise ValueError("'rule_yaml' must be a non-empty string")
+        if not isinstance(nuclei_yaml, str) or not nuclei_yaml.strip():
+            raise ValueError("'nuclei_yaml' must be a non-empty string")
+
+        LOGGER.info(
+            "Starting WAF stack for nuclei test (image=%s, target_url=%s)",
+            WAF_DEFAULT_NUCLEI_IMAGE,
+            WAF_DEFAULT_TARGET_URL,
+        )
+
+        target_endpoint, stack_error = _start_waf_test_stack(rule_yaml)
+        if stack_error:
+            if "appears to be running already" in stack_error.lower():
+                LOGGER.info("Existing stack detected; attempting restart before running tests")
+                _stop_waf_test_stack()
+                target_endpoint, stack_error = _start_waf_test_stack(rule_yaml)
+            if stack_error:
+                LOGGER.error("Unable to start WAF stack: %s", stack_error)
+                raise RuntimeError(f"Unable to start WAF stack: {stack_error}")
+        stack_started_here = True
+
+        with tempfile.TemporaryDirectory(prefix="waf-test-") as temp_dir:
+            workspace = Path(temp_dir)
+
+            template_path = workspace / "nuclei-template.yaml"
+            template_path.parent.mkdir(parents=True, exist_ok=True)
+            template_path.write_text(nuclei_yaml, encoding="utf-8")
+
+            LOGGER.info(
+                "Running nuclei template against %s (image=%s)",
+                WAF_DEFAULT_TARGET_URL,
+                WAF_DEFAULT_NUCLEI_IMAGE,
+            )
+            success, message = _run_nuclei_container(
+                workspace,
+                template_path,
+                nuclei_image=WAF_DEFAULT_NUCLEI_IMAGE,
+                target_url=WAF_DEFAULT_TARGET_URL,
+            )
+
+        if not success:
+            stack_logs = _collect_compose_logs(["crowdsec", "nginx"])
+            parts = [
+                "❌ Nuclei test failed.",
+                "=== NUCLEI OUTPUT ===",
+                message,
+            ]
+            if stack_logs:
+                parts.append("=== STACK LOGS (crowdsec/nginx) ===")
+                parts.append(stack_logs)
+            joined = "\n\n".join(parts)
+            raise RuntimeError(joined)
+
+        success_sections = [
+            "✅ Nuclei test succeeded.",
+            f"Target endpoint inside the stack: {WAF_DEFAULT_TARGET_URL}",
+            f"Host accessible endpoint: {target_endpoint or 'unknown'}",
+            "=== NUCLEI OUTPUT ===",
+            message,
+        ]
+        stack_logs = _collect_compose_logs(["crowdsec", "nginx"])
+        if stack_logs:
+            success_sections.extend(
+                [
+                    "=== STACK LOGS (crowdsec/nginx) ===",
+                    stack_logs,
+                ]
+            )
         return [
             types.TextContent(
                 type="text",
-                text=f"❌ Stack management error: {str(exc)}",
+                text="\n\n".join(success_sections),
             )
         ]
 
+    except Exception as exc:
+        LOGGER.error("run_waf_tests error: %s", exc, exc_info=True)
+        raise
+    finally:
+        if stack_started_here:
+            try:
+                _stop_waf_test_stack()
+            except Exception as stop_exc:  # pragma: no cover - best effort cleanup
+                LOGGER.warning("Failed to stop WAF stack during cleanup: %s", stop_exc)
 
-def _search_repo_for_cve(repo_path: Path, cve: str) -> List[Path]:
+
+def _search_repo_for_cve(repo_path: Path, cve: str) -> list[Path]:
     """Return files whose name contains the CVE identifier (case-insensitive)."""
     lower_token = cve.lower()
-    matches: List[Path] = []
+    matches: list[Path] = []
 
     for candidate in repo_path.rglob("*"):
         if not candidate.is_file():
@@ -795,7 +1064,7 @@ def _search_repo_for_cve(repo_path: Path, cve: str) -> List[Path]:
     return matches
 
 
-def _tool_fetch_nuclei_exploit(arguments: Optional[Dict[str, Any]]) -> List[types.TextContent]:
+def _tool_fetch_nuclei_exploit(arguments: dict[str, Any] | None) -> list[types.TextContent]:
     try:
         if not arguments:
             LOGGER.warning("fetch_nuclei_exploit called without arguments")
@@ -814,22 +1083,20 @@ def _tool_fetch_nuclei_exploit(arguments: Optional[Dict[str, Any]]) -> List[type
         target_path.mkdir(parents=True, exist_ok=True)
 
         LOGGER.info("Fetching nuclei exploit templates for %s", cve)
-        findings: List[str] = []
-        rendered_templates: List[str] = []
+        findings: list[str] = []
+        rendered_templates: list[str] = []
         total_files = 0
 
         for repo_url in DEFAULT_EXPLOIT_REPOSITORIES:
             cleaned_url = repo_url.rstrip("/")
             repo_name = cleaned_url.split("/")[-1] or "repository"
             if repo_name.endswith(".git"):
-                repo_name = repo_name[:-4]
+                repo_name = repo_name.removesuffix(".git")
             repo_path = target_path / repo_name
 
             if repo_path.exists():
                 if not (repo_path / ".git").exists():
-                    raise RuntimeError(
-                        f"Destination {repo_path} exists but is not a git repository"
-                    )
+                    raise RuntimeError(f"Destination {repo_path} exists but is not a git repository")
                 git_cmd = ["git", "-C", str(repo_path), "pull", "--ff-only"]
             else:
                 git_cmd = ["git", "clone", "--depth", "1", cleaned_url, str(repo_path)]
@@ -863,9 +1130,7 @@ def _tool_fetch_nuclei_exploit(arguments: Optional[Dict[str, Any]]) -> List[type
                 except OSError as read_err:
                     findings.append(f"    (failed to read {relative_path}: {read_err})")
                     continue
-                rendered_templates.append(
-                    f"### {cleaned_url} :: {relative_path}\n```yaml\n{file_contents}\n```"
-                )
+                rendered_templates.append(f"### {cleaned_url} :: {relative_path}\n```yaml\n{file_contents}\n```")
                 total_files += 1
 
         if total_files == 0:
@@ -874,10 +1139,7 @@ def _tool_fetch_nuclei_exploit(arguments: Optional[Dict[str, Any]]) -> List[type
             return [
                 types.TextContent(
                     type="text",
-                    text=(
-                        f"No files containing {cve} were found in the provided repositories."
-                        f"{detail_section}"
-                    ),
+                    text=(f"No files containing {cve} were found in the provided repositories.{detail_section}"),
                 )
             ]
 
@@ -898,16 +1160,11 @@ def _tool_fetch_nuclei_exploit(arguments: Optional[Dict[str, Any]]) -> List[type
         ]
 
     except Exception as exc:
-        LOGGER.error("fetch_nuclei_exploit error: %s", exc)
-        return [
-            types.TextContent(
-                type="text",
-                text=f"❌ fetch nuclei exploit error: {str(exc)}",
-            )
-        ]
+        LOGGER.error("fetch_nuclei_exploit error: %s", exc, exc_info=True)
+        raise
 
 
-def _tool_curl_waf_endpoint(arguments: Optional[Dict[str, Any]]) -> List[types.TextContent]:
+def _tool_curl_waf_endpoint(arguments: dict[str, Any] | None) -> list[types.TextContent]:
     try:
         if not arguments:
             LOGGER.warning("curl_waf_endpoint called without arguments")
@@ -929,9 +1186,7 @@ def _tool_curl_waf_endpoint(arguments: Optional[Dict[str, Any]]) -> List[types.T
         if not path.startswith("/"):
             if "://" in path:
                 parsed = urllib.parse.urlparse(path)
-                path = urllib.parse.urlunparse(
-                    ("", "", parsed.path or "/", parsed.params, parsed.query, parsed.fragment)
-                )
+                path = urllib.parse.urlunparse(("", "", parsed.path or "/", parsed.params, parsed.query, parsed.fragment))
             else:
                 path = "/" + path
 
@@ -939,9 +1194,7 @@ def _tool_curl_waf_endpoint(arguments: Optional[Dict[str, Any]]) -> List[types.T
             LOGGER.warning("curl_waf_endpoint received non-string body payload")
             raise ValueError("'body' must be a string when provided")
 
-        LOGGER.info(
-            "curl_waf_endpoint executing %s request to %s (timeout=%s)", method, path, timeout
-        )
+        LOGGER.info("curl_waf_endpoint executing %s request to %s (timeout=%s)", method, path, timeout)
         try:
             response = requests.request(
                 method=method,
@@ -954,12 +1207,7 @@ def _tool_curl_waf_endpoint(arguments: Optional[Dict[str, Any]]) -> List[types.T
             raise RuntimeError(f"HTTP request failed: {req_err}") from req_err
 
         header_lines = "\n".join(f"{k}: {v}" for k, v in response.headers.items())
-        response_text = (
-            f">>> {method} http://localhost:8081{path}\n"
-            f"Status: {response.status_code}\n"
-            f"Headers:\n{header_lines}\n\n"
-            f"Body:\n{response.text}"
-        )
+        response_text = f">>> {method} http://localhost:8081{path}\nStatus: {response.status_code}\nHeaders:\n{header_lines}\n\nBody:\n{response.text}"
 
         LOGGER.info(
             "curl_waf_endpoint completed with status %s for %s %s",
@@ -975,28 +1223,37 @@ def _tool_curl_waf_endpoint(arguments: Optional[Dict[str, Any]]) -> List[types.T
         ]
 
     except Exception as exc:
-        LOGGER.error("curl_waf_endpoint error: %s", exc)
-        return [
-            types.TextContent(
-                type="text",
-                text=f"❌ curl error: {str(exc)}",
-            )
-        ]
+        LOGGER.error("curl_waf_endpoint error: %s", exc, exc_info=True)
+        raise
 
 
-WAF_TOOL_HANDLERS: Dict[str, ToolHandler] = {
+WAF_TOOL_HANDLERS: dict[str, ToolHandler] = {
+    "get_waf_top_level_prompt": _tool_get_waf_top_level_prompt,
     "get_waf_prompt": _tool_get_waf_prompt,
     "get_waf_examples": _tool_get_waf_examples,
     "generate_waf_rule": _tool_generate_waf_rule,
+    "get_waf_pr_prompt": _tool_get_waf_pr_prompt,
+    "generate_waf_tests": _tool_generate_waf_tests,
     "validate_waf_rule": _tool_validate_waf_rule,
     "lint_waf_rule": _tool_lint_waf_rule,
     "deploy_waf_rule": _tool_deploy_waf_rule,
+    "prepare_waf_pr": _tool_prepare_waf_pr,
     "fetch_nuclei_exploit": _tool_fetch_nuclei_exploit,
     "manage_waf_stack": _tool_manage_waf_stack,
+    "run_waf_tests": _tool_run_waf_tests,
     "curl_waf_endpoint": _tool_curl_waf_endpoint,
 }
 
-WAF_TOOLS: List[types.Tool] = [
+WAF_TOOLS: list[types.Tool] = [
+    types.Tool(
+        name="get_waf_top_level_prompt",
+        description="Get the top-level CrowdSec WAF workflow prompt that explains how to approach rule and test creation",
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+    ),
     types.Tool(
         name="get_waf_prompt",
         description="Get the main WAF rule generation prompt for CrowdSec",
@@ -1029,6 +1286,53 @@ WAF_TOOLS: List[types.Tool] = [
             "additionalProperties": False,
         },
     ),
+    types.Tool(
+        name="generate_waf_tests",
+        description="Get the WAF test generation prompt for producing config.yaml and adapted Nuclei templates",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "nuclei_template": {
+                    "type": "string",
+                    "description": "Optional Nuclei template to include so the assistant can adapt it for testing",
+                },
+                "rule_filename": {
+                    "type": "string",
+                    "description": "Optional path to the generated rule (e.g. ./appsec-rules/crowdsecurity/vpatch-CVE-XXXX-YYYY.yaml)",
+                },
+            },
+            "additionalProperties": False,
+        },
+    ),
+    types.Tool(
+        name="get_waf_pr_prompt",
+        description="Get the WAF PR preparation prompt for writing test assets and drafting a PR comment",
+        inputSchema={
+            "type": "object",
+            "properties": {},
+            "additionalProperties": False,
+        },
+    ),
+    types.Tool(
+        name="run_waf_tests",
+        description="Start the WAF harness and execute the provided nuclei test template against it."
+        " If this action fails because docker isn't present or cannot be run, prompt the user to set it up manually.",
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "rule_yaml": {
+                    "type": "string",
+                    "description": "CrowdSec WAF rule YAML to load into the harness before running tests",
+                },
+                "nuclei_yaml": {
+                    "type": "string",
+                    "description": "Adapted nuclei template YAML that should trigger a block (HTTP 403)",
+                },
+            },
+            "required": ["rule_yaml", "nuclei_yaml"],
+            "additionalProperties": False,
+        },
+    ),
     types.Tool(
         name="validate_waf_rule",
         description="Validate that a CrowdSec WAF rule YAML is syntactically correct",
@@ -1068,6 +1372,52 @@ WAF_TOOLS: List[types.Tool] = [
             "additionalProperties": False,
         },
     ),
+    types.Tool(
+        name="prepare_waf_pr",
+        description=("Help prepare a pull request in a local clone of the CrowdSec hub repository by adding the generated WAF rule and associated test files."),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "hub_dir": {
+                    "type": "string",
+                    "description": "Path to the local clone of the CrowdSec hub repository",
+                },
+                "rule_yaml": {
+                    "type": "string",
+                    "description": "Generated WAF rule YAML content",
+                },
+                "test_config_yaml": {
+                    "type": "string",
+                    "description": "Generated AppSec test config.yaml content",
+                },
+                "test_nuclei_yaml": {
+                    "type": "string",
+                    "description": "Generated adapted nuclei template content",
+                },
+                "rule_filename": {
+                    "type": "string",
+                    "description": "Relative path (from hub root) for the rule file",
+                },
+                "nuclei_filename": {
+                    "type": "string",
+                    "description": "Filename for the nuclei test template",
+                },
+                "collection_name": {
+                    "type": "string",
+                    "description": "Target collection in the format author/name (mapped to collections/author/name.yaml)",
+                },
+            },
+            "required": [
+                "hub_dir",
+                "rule_yaml",
+                "test_config_yaml",
+                "test_nuclei_yaml",
+                "rule_filename",
+                "nuclei_filename",
+            ],
+            "additionalProperties": False,
+        },
+    ),
     types.Tool(
         name="fetch_nuclei_exploit",
         description="Retrieve nuclei templates from the official repository for a CVE to help with generation of WAF rules",
@@ -1085,7 +1435,8 @@ WAF_TOOLS: List[types.Tool] = [
     ),
     types.Tool(
         name="manage_waf_stack",
-        description="Start or stop the Docker-based CrowdSec AppSec test stack so the rule can be exercised with allowed and blocked requests",
+        description="Start or stop the Docker-based CrowdSec AppSec test stack so the rule can be exercised with allowed and blocked requests."
+        " If this action fails because docker isn't present or cannot be run, prompt the user to set it up manually.",
         inputSchema={
             "type": "object",
             "properties": {
@@ -1139,7 +1490,13 @@ WAF_TOOLS: List[types.Tool] = [
     ),
 ]
 
-WAF_RESOURCES: List[types.Resource] = [
+WAF_RESOURCES: list[types.Resource] = [
+    types.Resource(
+        uri="file://prompts/prompt-waf-top-level.txt",
+        name="WAF Top-Level Workflow Prompt",
+        description="High-level guidance for handling CrowdSec WAF rule requests and which tools to use",
+        mimeType="text/plain",
+    ),
     types.Resource(
         uri="file://prompts/prompt-waf.txt",
         name="WAF Rule Generation Prompt",
@@ -1158,12 +1515,27 @@ WAF_RESOURCES: List[types.Resource] = [
         description="Step-by-step guide for deploying CrowdSec WAF rules",
         mimeType="text/plain",
     ),
+    types.Resource(
+        uri="file://prompts/prompt-waf-tests.txt",
+        name="WAF Test Generation Prompt",
+        description="Instructions for producing config.yaml and adapted Nuclei templates for WAF testing",
+        mimeType="text/plain",
+    ),
+    types.Resource(
+        uri="file://prompts/prompt-waf-pr.txt",
+        name="WAF PR Preparation Prompt",
+        description="Short guidance for preparing WAF PR assets and drafting a PR comment",
+        mimeType="text/plain",
+    ),
 ]
 
-WAF_RESOURCE_READERS: Dict[str, Callable[[], str]] = {
+WAF_RESOURCE_READERS: dict[str, Callable[[], str]] = {
+    "file://prompts/prompt-waf-top-level.txt": lambda: WAF_TOP_LEVEL_PROMPT_FILE.read_text(encoding="utf-8"),
     "file://prompts/prompt-waf.txt": lambda: WAF_PROMPT_FILE.read_text(encoding="utf-8"),
     "file://prompts/prompt-waf-examples.txt": lambda: WAF_EXAMPLES_FILE.read_text(encoding="utf-8"),
     "file://prompts/prompt-waf-deploy.txt": lambda: WAF_DEPLOY_FILE.read_text(encoding="utf-8"),
+    "file://prompts/prompt-waf-tests.txt": lambda: WAF_TESTS_PROMPT_FILE.read_text(encoding="utf-8"),
+    "file://prompts/prompt-waf-pr.txt": lambda: WAF_PR_PROMPT_FILE.read_text(encoding="utf-8"),
 }
 
 REGISTRY.register_tools(WAF_TOOL_HANDLERS, WAF_TOOLS)