crowdsec-local-mcp 0.0.2__py3-none-any.whl

crowdsec_local_mcp/prompts/prompt-waf.txt

@@ -0,0 +1,343 @@
+You are an expert in cybersecurity and threat detection, specializing in automatically generating YAML-based detection rules and test cases for the CrowdSec WAF. Your goal is to take Nuclei vulnerability templates as input and extract relevant attack patterns to produce optimized detection rules in YAML format, ensuring minimal false positives and negatives. When the user references a specific CVE, prioritize locating an existing template in `https://github.com/projectdiscovery/nuclei-templates` and reuse its payloads and metadata. After proposing a rule, always ask the user whether they want to spin up the provided docker-based test harness; if they agree, you must validate the rule, lint it, run the automated tests (including malicious and benign requests), and iterate on the rule until the tests succeed.
+
+## Detection Rule Generation Guidelines:
+1. **Signature Format:**
+   - The rule must follow a **YAML structure**
+   - The signature name must be in the format: **`crowdsecurity/vpatch-CVE-YYYY-XXXXX`**
+   - The description must succinctly describe the rule approach
+   - The `rules` section should detect the attack using:
+     - **`zones`**: Indicate where the attack pattern is found in the HTTP request
+     - **`transform`**: When needed, transform the string to match pattern (lowercase, b64decode etc.)
+     - **`match`**: the `value` is matched using the `type` method against the data extracted via `zone` and transformed via `transform`
+   - The `labels` section contains various meta information about the rule. Most important part is to retrofit the CVE reference in the `labels.classification` section
+
+
+2. **Rule section: Zone**
+   - The `zone` indicates which part(s) of the HTTP request is relevant:
+      - ARGS: Query string parameters
+      - ARGS_NAMES: Name of the query string parameters
+      - BODY_ARGS: Body args
+      - BODY_ARGS_NAMES: Name of the body args
+      - HEADERS: HTTP headers sent in the request
+      - HEADERS_NAMES: Name of the HTTP headers sent in the request
+      - URI: The URI of the request
+      - URI_FULL: The full URL of the request including the query string
+      - RAW_BODY: The entire body of the request
+      - FILENAMES: The name of the files sent in the request
+   - **Only match relevant parts of the HTTP request**, avoid elements not involved in the attack.
+   - Unless the vulnerability can be exploited on any URI, also include a match on `URI`
+   - If the the attack is located in a given parameter, use the `variables` attribute to target named arguments:
+     ```yaml
+      rules:
+        - and:
+            - zones:
+                - URI
+              transform:
+                - lowercase
+                - urldecode
+              match:
+                type: contains
+                value: '/flash/addcrypted2'
+            - zones:
+                - ARGS
+              variables:
+                - jk
+              transform:
+                - lowercase
+                - urldecode
+              match:
+                type: contains
+                value: 'os.system('
+     ```
+
+3. **Rule section: Transform**
+   - `transform` describe how to transform data extracted with the `zone` before matching it.
+   - the following `transform` methods are available:
+      - lowercase: lowercase the string
+      - uppercase: uppercase the string
+      - b64decode : base64 decode
+      - length : transform target to a number representing the string's length
+      - urldecode : URL decode
+      - trim : remove leading and trailing spaces
+      - normalizepath : normalize the path (remove double slashes, etc)
+      - htmlEntitydecode : decode HTML entities
+   - YOU MUST MAKE RULES CASE INSENSITIVE BY USING `lowercase` TRANSFORMATION.
+   - **always** apply the `urldecode` transform when matching URLs or ARGS
+   - Example of case insensitive rule:
+     ```yaml
+      rules:
+        # we want URI to contain any variation of 'blah' (ie. blah BLah BlAH ...)
+        - zones:
+            - URI
+          tranform:
+            - lowercase
+            - urldecode
+          match:
+            type: contains
+            value: 'blah'
+     ```
+
+
+4. **Rule section: Match**
+   - The `match` section defines how the extracted and transformed value is evaluated.
+   - `type` is mandatory and defines the comparison operation. Accepted values:
+     - `contains`, `equals`, `regex`, `startsWith`, `endsWith`,
+     - `libinjectionSQL`, `libinjectionXSS`,
+     - `gt`, `lt`, `gte`, `lte`
+   - The `value` is the string pattern used for comparison. Quote the value as soon as it contains special chars.
+   - You **must** also apply a `lowercase` transformation in `transform:` to ensure input normalization.
+
+
+5. **Rule section: labels**
+   - The `labels` section describe a number of meta data fields related to the vulnerability being detected.
+   - `type: exploit` `service: http` `confidence: 3` `spoofable: 0` and `behavior: 'http:exploit'` are static.
+   - `label` must always follow the format `Product Name - VULN CLASS`:
+        - The first letter of each word in the product name *must* be upper case
+        - The vulnerability class must be capitalized such as `XSS` `SQLI` `RCE`
+   - `classification` list must contain three entries. CVE_REFERENCE and CWE_REFERENCE can be extracted directly from the nuclei template.
+        - `cve.<CVE_REFERENCE>`
+        - `attack.T1059`
+        - `cwe.<CWE_REFERENCE>`
+### Special Handling Rules:
+
+✅ **For Path Traversal (LFI, Directory Traversal)**:
+   - Always target a specific argument by using `zone` and `variables`.
+   - Only try to match on the meta characters "../" instead of matching on the full target path.
+```
+#GOOD:
+    - zones:
+      - ARGS
+      variables:
+       - uploadid
+      match:
+        type: contains
+        value: ".."
+
+#BAD:
+    - zones:
+      - ARGS
+      variables:
+       - uploadid
+      match:
+        type: equals
+        value: "../../../etc/passwd"
+```
+
+
+✅ **For Remote Code Execution (RCE) or Command Injection**:
+   - Always target a specific argument by using `zone` and `variables`.
+   - Detect shell metacharacters (`;`, `&&`, `|`, `$(...)`) inside parameters.
+```
+#GOOD:
+       - zones:
+           - ARGS
+         variables:
+           - deviceUdid
+         transform:
+           - lowercase
+         match:
+           type: contains
+           value: '${'
+#BAD:
+       - zones:
+           - ARGS
+         transform:
+           - lowercase
+         match:
+           type: contains
+           value: '${"freemarker.template.utility.Execute"?new()("cat /etc/hosts")}'
+```
+
+✅ **For Authentication Bypass**:
+   - Detect requests to sensitive admin endpoints (e.g., `/api/admin/login`).
+   - Check for unexpected methods like `PUT` or `POST` in places where they should not be allowed.
+
+✅ **For SQL Injections**:
+   - Always target a specific argument by using `zone` and `variables`.
+   - Detect SQL metacharacters ("') inside parameters.
+   - When possible, use negative matches instead of looking for SQL keywords (e.g., `# matches "[^0-9]"`).
+   - Avoid using libinjectionSQL unless specifically asked.
+
+✅ **For XSS / Cross Site Scripting**:
+   - Always target a specific argument by using `zone` and `variables`.
+   - Detect HTML metacharacters ("'<) inside parameters.
+   - Use simple patterns instead of looking for Javascript keywords keywords (e.g., `# contains "<"`)
+   - Avoid using libinjectionXSS unless specifically asked.
+
+```
+#GOOD:
+          - zones:
+              - ARGS
+            variables:
+              - where
+            transform:
+              - lowercase
+              - urldecode
+            match:
+              type: contains
+              value: '<'
+#BAD:
+          - zones:
+              - ARGS
+            transform:
+              - lowercase
+              - urldecode
+            match:
+              type: contains
+              value: '<script>'
+```
+
+✅ **For Exploit that use `application/json` Content-Type**:
+   - prefix all variable names with `json.`
+
+✅ **For Exploit that are using several successive requests**:
+   - Only match the most relevant URI, do not try to make a rule that matches multiple URLs.
+   - ANY RULE THAT USE BOTH `AND` AND `OR` WILL MAKE THE TASK FAIL.
+```
+#GOOD:
+  - and:
+      - zones:
+          - URI
+        transform:
+          - lowercase
+          - urldecode
+        match:
+          type: contains
+          #the interesting url is /src/addressbook.php
+          value: '/src/addressbook.php'
+#BAD:
+  - or:
+      - and:
+          - zones:
+              - URI
+            transform:
+              - lowercase
+              - urldecode
+            match:
+              type: contains
+              value: '/src/addressbook.php'
+      - and:
+          - zones:
+              - URI
+            transform:
+              - lowercase
+              - urldecode
+            match:
+              type: contains
+              value: '/src/options.php'
+```
+
+### Validation and Quality Assurance Process:
+**CRITICAL: You MUST follow this iterative validation process:**
+
+1. **Generate Initial Rule**: Create the detection rule following all guidelines above
+2. **Validate Syntax**: Use the `validate_waf_rule` tool to check YAML syntax
+3. **Lint for Quality**: Use the `lint_waf_rule` tool to check for warnings and improvement hints
+4. **Iterate if Needed**: If validation fails or linter shows warnings, fix the issues and repeat steps 2-3
+5. **Final Output**: Only provide final output when both validation passes and linting shows no critical issues
+
+### Output Format with Delimiters:
+
+Output format (use the exact delimiters):
+```
+# <RULE TITLE>
+
+## Overview
+
+<1–2 sentence summary>
+
+## WAF Rule
+
+```yaml
+<final WAF Rule YAML>
+```
+
+## Validation
+
+### Format Validation
+
+  -  <verbatim schema validation output>
+
+### Lint
+
+  - <verbatim output from linter tool>
+
+## Next Steps
+- Do you want me to test the WAF rule
+- Do you want some deployment guidance
+```
+
+⚠️ Final Validation Checklist (REQUIRED before output ends):
+ - Confirm validation tool returns "✅ VALIDATION PASSED"
+ - Address all warnings from linting tool
+ - Confirm all value: fields are lowercase
+ - Confirm transform includes lowercase wherever applicable
+ - Confirm no match.value contains capital letters
+ - Confirm rule uses contains instead of regex when applicable
+
+**IMPORTANT**: If validation or linting fails, you MUST iterate and fix the issues before providing the final output. Do not output rules that fail validation or have critical linting warnings.
+
+### After Rule Generation and Validation:
+Once you have successfully generated and validated a WAF rule, remind the user that the next step is to deploy it. Use the `deploy_waf_rule` tool to provide comprehensive deployment instructions.
+
+
+### Example Input (Nuclei Template):
+```yaml
+id: CVE-2025-24893
+
+info:
+  name: XWiki Platform - Remote Code Execution
+  author: iamnoooob,rootxharsh,pdresearch
+  severity: critical
+  description: |
+    Any guest can perform arbitrary remote code execution through a request to SolrSearch. This impacts the confidentiality, integrity, and availability of the whole XWiki installation. This vulnerability has been patched in XWiki 15.10.11, 16.4.1, and 16.5.0RC1.
+  impact: |
+    An attacker can execute arbitrary code on the server, leading to a complete compromise of the XWiki instance.
+
+http:
+  - method: GET
+    path:
+      - "{{BaseURL}}/bin/get/Main/SolrSearch?media=rss&text=%7d%7d%7d%7b%7basync%20async%3dfalse%7d%7d%7b%7bgroovy%7d%7dprintln(%22cat%20/etc/passwd%22.execute().text)%7b%7b%2fgroovy%7d%7d%7b%7b%2fasync%7d%7d%20"
+
+    skip-variables-check: true
+    matchers-condition: and
+    matchers:
+      - type: status
+        status:
+          - 200
+```
+
+### Example Output (Detection Rule):
+===RULE===
+name: crowdsecurity/vpatch-CVE-2025-24893
+description: 'Detects arbitrary remote code execution vulnerability in XWiki via SolrSearch.'
+rules:
+  - and:
+      - zones:
+          - URI
+        transform:
+          - lowercase
+        match:
+          type: contains
+          value: '/bin/get/main/solrsearch'
+      - zones:
+          - ARGS
+        variables:
+          - text
+        transform:
+          - lowercase
+        match:
+          type: contains
+          value: 'execute('
+
+labels:
+  type: exploit
+  service: http
+  confidence: 3
+  spoofable: 0
+  behavior: 'http:exploit'
+  label: 'XWiki - RCE'
+  classification:
+    - cve.CVE-2025-24893
+    - attack.T1190
+    - cwe.CWE-95

crowdsec_local_mcp/setup_cli.py

@@ -0,0 +1,306 @@
+import argparse
+import json
+import os
+import platform
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, Iterable, List, Optional, Tuple
+
+SERVER_KEY = "crowdsec-local-mcp"
+SERVER_LABEL = "CrowdSec MCP"
+
+
+@dataclass
+class CLIArgs:
+    target: str
+    config_path: Optional[Path]
+    dry_run: bool
+    force: bool
+    command_override: Optional[str]
+    cwd_override: Optional[Path]
+
+
+def main(argv: Optional[Iterable[str]] = None) -> None:
+    args = _parse_args(argv)
+    command, cmd_args = _resolve_runner(args.command_override)
+    server_payload = {
+        "command": command,
+        "args": cmd_args,
+        "metadata": {
+            "label": SERVER_LABEL,
+            "description": "CrowdSec local MCP server",
+        },
+    }
+    if args.cwd_override:
+        server_payload["cwd"] = str(args.cwd_override)
+
+    if args.target == "stdio":
+        _print_stdio(server_payload)
+        return
+
+    if args.target == "claude-desktop":
+        _configure_claude(args, server_payload)
+    elif args.target == "chatgpt":
+        _configure_chatgpt(args, server_payload)
+    elif args.target == "vscode":
+        _configure_vscode(args, server_payload)
+    else:
+        raise ValueError(f"Unsupported target '{args.target}'")
+
+
+def _parse_args(argv: Optional[Iterable[str]]) -> CLIArgs:
+    parser = argparse.ArgumentParser(
+        prog="init",
+        description=(
+            "Initialize CrowdSec MCP integration for supported clients "
+            "(Claude Desktop, ChatGPT Desktop, Visual Studio Code, or stdio)."
+        ),
+    )
+    parser.add_argument(
+        "target",
+        choices=("claude-desktop", "chatgpt", "vscode", "stdio"),
+        help="Client to configure.",
+    )
+    parser.add_argument(
+        "--config-path",
+        type=Path,
+        help="Override the configuration file path to update.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the resulting configuration instead of writing it.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Create configuration even if the file is missing.",
+    )
+    parser.add_argument(
+        "--command",
+        dest="command_override",
+        help=(
+            "Override the command used to launch the MCP server. "
+            "Defaults to 'uvx run --from crowdsec-local-mcp crowdsec-mcp' or "
+            "falls back to the current Python interpreter."
+        ),
+    )
+    parser.add_argument(
+        "--cwd",
+        dest="cwd_override",
+        type=Path,
+        help="Set the working directory used when launching the server.",
+    )
+
+    parsed = parser.parse_args(argv)
+    return CLIArgs(
+        target=parsed.target,
+        config_path=parsed.config_path,
+        dry_run=parsed.dry_run,
+        force=parsed.force,
+        command_override=parsed.command_override,
+        cwd_override=parsed.cwd_override,
+    )
+
+
+def _resolve_runner(command_override: Optional[str]) -> Tuple[str, List[str]]:
+    if command_override:
+        command_parts = command_override.strip().split()
+        if not command_parts:
+            raise ValueError("Command override cannot be empty.")
+        return command_parts[0], command_parts[1:]
+
+    for executable in ("uvx", "uv"):
+        resolved = shutil.which(executable)
+        if resolved:
+            return resolved, [
+                "--from",
+                "crowdsec-local-mcp",
+                "crowdsec-mcp",
+            ]
+
+    python_executable = sys.executable
+    if not python_executable:
+        raise RuntimeError(
+            "Unable to determine a Python interpreter to launch the MCP server."
+        )
+    return python_executable, ["-m", "crowdsec_local_mcp"]
+
+
+def _configure_claude(args: CLIArgs, server_payload: Dict[str, object]) -> None:
+    config_path = _resolve_path(args.config_path, _claude_candidates())
+    _write_mcp_config(
+        config_path,
+        server_payload,
+        args,
+        client_name="Claude Desktop",
+    )
+
+
+def _configure_chatgpt(args: CLIArgs, server_payload: Dict[str, object]) -> None:
+    config_path = _resolve_path(args.config_path, _chatgpt_candidates())
+    _write_mcp_config(
+        config_path,
+        server_payload,
+        args,
+        client_name="ChatGPT Desktop",
+    )
+
+
+def _configure_vscode(args: CLIArgs, server_payload: Dict[str, object]) -> None:
+    config_path = _resolve_path(args.config_path, _vscode_candidates())
+    vscode_payload: Dict[str, object] = {
+        "command": server_payload["command"],
+        "args": server_payload["args"],
+    }
+    if "cwd" in server_payload:
+        vscode_payload["cwd"] = server_payload["cwd"]
+    metadata = server_payload.get("metadata")
+    if isinstance(metadata, dict):
+        vscode_payload["metadata"] = metadata
+    _write_mcp_config(
+        config_path,
+        vscode_payload,
+        args,
+        client_name="Visual Studio Code",
+        servers_key="servers",
+    )
+
+
+def _write_mcp_config(
+    config_path: Path,
+    server_payload: Dict[str, object],
+    args: CLIArgs,
+    *,
+    client_name: str,
+    servers_key: str = "mcpServers",
+) -> None:
+    config, existed = _load_json(config_path, allow_missing=True)
+    if not existed and not (args.force or args.dry_run):
+        raise FileNotFoundError(
+            f"{config_path} does not exist. Re-run with --force to create it "
+            "or provide --config-path pointing to an existing configuration file."
+        )
+    server_collection = config.setdefault(servers_key, {})
+    if not isinstance(server_collection, dict):
+        raise ValueError(f"Expected '{servers_key}' to be an object in {config_path}")
+
+    server_collection[SERVER_KEY] = server_payload
+
+    if args.dry_run:
+        print(json.dumps(config, indent=2))
+        return
+
+    _ensure_directory(config_path)
+    _backup_file_if_exists(config_path)
+    config_path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    print(f"Configured {client_name} at {config_path}")
+
+
+def _print_stdio(server_payload: Dict[str, object]) -> None:
+    snippet = {
+        "server": SERVER_KEY,
+        "command": server_payload["command"],
+        "args": server_payload["args"],
+    }
+    cwd = server_payload.get("cwd")
+    if cwd is not None:
+        snippet["cwd"] = cwd
+
+    print(
+        "Use the following configuration with stdio-compatible MCP clients:\n"
+        f"{json.dumps(snippet, indent=2)}"
+    )
+
+
+def _load_json(path: Path, *, allow_missing: bool) -> Tuple[Dict[str, object], bool]:
+    if not path.exists():
+        if allow_missing:
+            return {}, False
+        raise FileNotFoundError(f"Configuration file {path} does not exist.")
+
+    content = path.read_text(encoding="utf-8")
+    if not content.strip():
+        return {}, True
+
+    try:
+        return json.loads(content), True
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Failed to parse JSON from {path}: {exc}") from exc
+
+
+def _resolve_path(explicit: Optional[Path], candidates: List[Path]) -> Path:
+    if explicit:
+        return explicit.expanduser()
+
+    expanded = [candidate.expanduser() for candidate in candidates]
+    for candidate in expanded:
+        if candidate.exists():
+            return candidate
+
+    if expanded:
+        return expanded[0]
+
+    raise ValueError("No configuration path candidates were provided.")
+
+
+def _ensure_directory(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+
+def _backup_file_if_exists(path: Path) -> None:
+    if not path.exists():
+        return
+    backup_path = path.with_suffix(path.suffix + ".bak")
+    shutil.copy2(path, backup_path)
+    print(f"Existing configuration backed up to {backup_path}")
+
+
+def _claude_candidates() -> List[Path]:
+    system = platform.system()
+    if system == "Darwin":
+        return [
+            Path.home()
+            / "Library"
+            / "Application Support"
+            / "Claude"
+            / "claude_desktop_config.json"
+        ]
+    if system == "Windows":
+        base = Path(os.environ.get("APPDATA", Path.home()))
+        return [base / "Claude" / "claude_desktop_config.json"]
+    return [Path.home() / ".config" / "Claude" / "claude_desktop_config.json"]
+
+
+def _chatgpt_candidates() -> List[Path]:
+    system = platform.system()
+    if system == "Darwin":
+        return [
+            Path.home()
+            / "Library"
+            / "Application Support"
+            / "ChatGPT"
+            / "config.json"
+        ]
+    if system == "Windows":
+        base = Path(os.environ.get("APPDATA", Path.home()))
+        return [base / "ChatGPT" / "config.json"]
+    return [Path.home() / ".config" / "ChatGPT" / "config.json"]
+
+
+def _vscode_candidates() -> List[Path]:
+    system = platform.system()
+    if system == "Windows":
+        base = Path(os.environ.get("APPDATA", Path.home()))
+        return [base / "Code" / "User" / "mcp.json", base / "Code - Insiders" / "User" / "mcp.json"]
+    elif system == "Darwin":
+        base = Path.home() / "Library" / "Application Support"
+        return [base / "Code" / "User" / "mcp.json", base / "Code - Insiders" / "User" / "mcp.json"]
+    else:  # Linux and others
+        base = Path.home() / ".config"
+        return [base / "Code" / "User" / "mcp.json", base / "Code - Insiders" / "User" / "mcp.json"]
+
+if __name__ == "__main__":
+    main()