dryhack-mcp 2.1.3__tar.gz → 2.3.0__tar.gz

{dryhack_mcp-2.1.3 → dryhack_mcp-2.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: dryhack-mcp
-Version: 2.1.3
-Summary: DryHack-MCP - an MCP server providing offensive-security tooling (curl, python, shell) and an AI-driven recommend_action engine for authorized penetration testing.
+Version: 2.3.0
+Summary: DryHack-MCP - an MCP server providing offensive-security tooling (curl, python, shell, Playwright browser) and a scope-gated authorize engine for authorized penetration testing.
 Author: Afrizal F.A
 License: MIT License
         
@@ -36,9 +36,12 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: mcp<2,>=1.2.0
+Requires-Dist: playwright>=1.40
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: ruff>=0.1; extra == "dev"
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == "browser"
 Dynamic: license-file
 
 # DryHack-MCP
@@ -51,6 +54,7 @@ tooling for **authorized** penetration testing. It exposes four tools:
 | `curl` | Raw HTTP interaction for web recon/exploitation |
 | `python` | Run ad-hoc Python snippets for scripted probing |
 | `shell` | Run shell commands (`nmap`, `ffuf`, `nc`, `sqlmap`, …) |
+| `browser` | Full Playwright browser automation: navigation, DOM interaction, JavaScript injection, screenshots/PDF, cookies/headers, multi-step chains |
 | `authorize` | Checks target membership in the per-call `scope` parameter; does not verify permission (no external API, no creds) |
 
 > ⚠️ **Legal notice.** Use this only against systems you own or are explicitly
@@ -83,6 +87,24 @@ For development:
 python3 -m pip install -e ".[dev]"
 ```
 
+### Browser tool (Playwright)
+
+Playwright is a **core dependency**, so a plain `pip install dryhack-mcp` /
+`uvx dryhack-mcp` already ships it — no extra needed. The browser *binaries*
+(Chromium/Firefox/WebKit) are not distributed via pip, so the first time the
+`browser` tool launches an engine it **auto-runs `playwright install <browser>`**
+if the binary is missing.
+
+To pre-install the binaries (optional, avoids the one-time first-use download):
+
+```bash
+playwright install            # all engines
+playwright install chromium   # just chromium
+```
+
+Auto-install is controlled by `DRYHACK_BROWSER_AUTO_INSTALL` (default on); set it
+to `0` to disable and manage browsers yourself.
+
 ## Run
 
 Two transports are supported. Select with `--transport` (argparse).
@@ -165,12 +187,69 @@ Start the server separately with `dryhack-mcp --transport http`.
 | `DRYHACK_COMMAND_TIMEOUT` | `120` | Per-command timeout (seconds) |
 | `DRYHACK_WORKDIR` | cwd | Working directory for commands |
 | `DRYHACK_OUTPUT_LIMIT` | `65536` | Max stdout/stderr bytes captured |
+| `DRYHACK_BROWSER_AUTO_INSTALL` | `1` | Auto-download the browser binary on first use (`browser` tool) |
+| `DRYHACK_BROWSER_INSTALL_TIMEOUT` | `900` | Timeout (s) for the on-demand `playwright install` download |
 | `DRYHACK_HTTP_HOST` | `127.0.0.1` | Default HTTP bind host |
 | `DRYHACK_HTTP_PORT` | `8000` | Default HTTP bind port |
 
 > The server stores **no credentials/API keys**. All settings above are
 > operational only.
 
+## browser (Playwright automation)
+
+Drive a real browser (Chromium/Firefox/WebKit) for web recon and exploitation.
+Run a single `action` (with its relevant params) **or** a `steps` list of
+`{"action": ..., ...}` dicts executed in order within one browser session.
+
+Supported actions:
+
+- **Navigation:** `goto`/`navigate`, `reload`, `back`, `forward`
+- **Interaction:** `click`, `dblclick`, `fill`, `type`, `press`, `hover`,
+  `focus`, `check`, `uncheck`, `select_option`, `upload`, `mouse_click`,
+  `keyboard_type`, `scroll`
+- **Waiting:** `wait_for_selector`, `wait_for_timeout`, `wait_for_load_state`,
+  `wait_for_url`
+- **JavaScript injection:** `evaluate`/`eval` (with `script` + optional `arg`),
+  `evaluate_handle`, `add_init_script` (runs before every document's own
+  scripts), `add_script_tag`, `add_style_tag`
+- **Extraction:** `content`, `inner_text`, `inner_html`, `text_content`,
+  `get_attribute`, `query_all`, `title`, `url`
+- **Capture:** `screenshot` (`path`, `full_page`), `pdf`
+- **Session/context:** `set_viewport`, `set_extra_headers`, `get_cookies`,
+  `set_cookies`, `clear_cookies`, `storage_state`, `emulate_media`
+
+Session-level options: `browser_type` (chromium/firefox/webkit), `headless`,
+`user_agent`, `viewport`, `extra_http_headers`, `cookies`, `proxy`, `locale`,
+`timezone`, `geolocation`, `device_scale_factor`, `ignore_https_errors`,
+`bypass_csp`, `java_script_enabled`, `init_scripts`, `slow_mo`, `args`,
+`executable_path`, `timeout`, and `stop_on_error`.
+
+```python
+# Single action: run JavaScript in the page
+browser(action="evaluate", url=None, script="() => document.cookie")
+
+# Multi-step session: login, inject JS, screenshot
+browser(steps=[
+    {"action": "goto", "url": "https://staging.lab.example.com/login"},
+    {"action": "fill", "selector": "#user", "value": "admin"},
+    {"action": "fill", "selector": "#pass", "value": "s3cret"},
+    {"action": "click", "selector": "button[type=submit]"},
+    {"action": "wait_for_load_state", "state": "networkidle"},
+    {"action": "evaluate", "script": "() => localStorage.getItem('token')"},
+    {"action": "screenshot", "path": "/tmp/after-login.png", "full_page": True},
+], headless=True, user_agent="DryHack", extra_http_headers={"X-Test": "1"})
+
+# Inject a payload before any page script runs
+browser(action="goto", url="https://target.example/",
+        init_script="Object.defineProperty(navigator,'webdriver',{get:()=>false})")
+```
+
+Playwright ships with dryhack-mcp and runs in a dedicated worker thread (the MCP
+server owns the asyncio loop, and Playwright's sync API cannot run inside a live
+loop). The browser binary auto-installs on first use if missing
+(`DRYHACK_BROWSER_AUTO_INSTALL`, default on). The same authorized-use scope
+rules as the other tools apply.
+
 ## authorize (per-call scope)
 
 Pass `scope` directly to the tool; no environment or native scope configuration

{dryhack_mcp-2.1.3 → dryhack_mcp-2.3.0}/README.md

@@ -8,6 +8,7 @@ tooling for **authorized** penetration testing. It exposes four tools:
 | `curl` | Raw HTTP interaction for web recon/exploitation |
 | `python` | Run ad-hoc Python snippets for scripted probing |
 | `shell` | Run shell commands (`nmap`, `ffuf`, `nc`, `sqlmap`, …) |
+| `browser` | Full Playwright browser automation: navigation, DOM interaction, JavaScript injection, screenshots/PDF, cookies/headers, multi-step chains |
 | `authorize` | Checks target membership in the per-call `scope` parameter; does not verify permission (no external API, no creds) |
 
 > ⚠️ **Legal notice.** Use this only against systems you own or are explicitly
@@ -40,6 +41,24 @@ For development:
 python3 -m pip install -e ".[dev]"
 ```
 
+### Browser tool (Playwright)
+
+Playwright is a **core dependency**, so a plain `pip install dryhack-mcp` /
+`uvx dryhack-mcp` already ships it — no extra needed. The browser *binaries*
+(Chromium/Firefox/WebKit) are not distributed via pip, so the first time the
+`browser` tool launches an engine it **auto-runs `playwright install <browser>`**
+if the binary is missing.
+
+To pre-install the binaries (optional, avoids the one-time first-use download):
+
+```bash
+playwright install            # all engines
+playwright install chromium   # just chromium
+```
+
+Auto-install is controlled by `DRYHACK_BROWSER_AUTO_INSTALL` (default on); set it
+to `0` to disable and manage browsers yourself.
+
 ## Run
 
 Two transports are supported. Select with `--transport` (argparse).
@@ -122,12 +141,69 @@ Start the server separately with `dryhack-mcp --transport http`.
 | `DRYHACK_COMMAND_TIMEOUT` | `120` | Per-command timeout (seconds) |
 | `DRYHACK_WORKDIR` | cwd | Working directory for commands |
 | `DRYHACK_OUTPUT_LIMIT` | `65536` | Max stdout/stderr bytes captured |
+| `DRYHACK_BROWSER_AUTO_INSTALL` | `1` | Auto-download the browser binary on first use (`browser` tool) |
+| `DRYHACK_BROWSER_INSTALL_TIMEOUT` | `900` | Timeout (s) for the on-demand `playwright install` download |
 | `DRYHACK_HTTP_HOST` | `127.0.0.1` | Default HTTP bind host |
 | `DRYHACK_HTTP_PORT` | `8000` | Default HTTP bind port |
 
 > The server stores **no credentials/API keys**. All settings above are
 > operational only.
 
+## browser (Playwright automation)
+
+Drive a real browser (Chromium/Firefox/WebKit) for web recon and exploitation.
+Run a single `action` (with its relevant params) **or** a `steps` list of
+`{"action": ..., ...}` dicts executed in order within one browser session.
+
+Supported actions:
+
+- **Navigation:** `goto`/`navigate`, `reload`, `back`, `forward`
+- **Interaction:** `click`, `dblclick`, `fill`, `type`, `press`, `hover`,
+  `focus`, `check`, `uncheck`, `select_option`, `upload`, `mouse_click`,
+  `keyboard_type`, `scroll`
+- **Waiting:** `wait_for_selector`, `wait_for_timeout`, `wait_for_load_state`,
+  `wait_for_url`
+- **JavaScript injection:** `evaluate`/`eval` (with `script` + optional `arg`),
+  `evaluate_handle`, `add_init_script` (runs before every document's own
+  scripts), `add_script_tag`, `add_style_tag`
+- **Extraction:** `content`, `inner_text`, `inner_html`, `text_content`,
+  `get_attribute`, `query_all`, `title`, `url`
+- **Capture:** `screenshot` (`path`, `full_page`), `pdf`
+- **Session/context:** `set_viewport`, `set_extra_headers`, `get_cookies`,
+  `set_cookies`, `clear_cookies`, `storage_state`, `emulate_media`
+
+Session-level options: `browser_type` (chromium/firefox/webkit), `headless`,
+`user_agent`, `viewport`, `extra_http_headers`, `cookies`, `proxy`, `locale`,
+`timezone`, `geolocation`, `device_scale_factor`, `ignore_https_errors`,
+`bypass_csp`, `java_script_enabled`, `init_scripts`, `slow_mo`, `args`,
+`executable_path`, `timeout`, and `stop_on_error`.
+
+```python
+# Single action: run JavaScript in the page
+browser(action="evaluate", url=None, script="() => document.cookie")
+
+# Multi-step session: login, inject JS, screenshot
+browser(steps=[
+    {"action": "goto", "url": "https://staging.lab.example.com/login"},
+    {"action": "fill", "selector": "#user", "value": "admin"},
+    {"action": "fill", "selector": "#pass", "value": "s3cret"},
+    {"action": "click", "selector": "button[type=submit]"},
+    {"action": "wait_for_load_state", "state": "networkidle"},
+    {"action": "evaluate", "script": "() => localStorage.getItem('token')"},
+    {"action": "screenshot", "path": "/tmp/after-login.png", "full_page": True},
+], headless=True, user_agent="DryHack", extra_http_headers={"X-Test": "1"})
+
+# Inject a payload before any page script runs
+browser(action="goto", url="https://target.example/",
+        init_script="Object.defineProperty(navigator,'webdriver',{get:()=>false})")
+```
+
+Playwright ships with dryhack-mcp and runs in a dedicated worker thread (the MCP
+server owns the asyncio loop, and Playwright's sync API cannot run inside a live
+loop). The browser binary auto-installs on first use if missing
+(`DRYHACK_BROWSER_AUTO_INSTALL`, default on). The same authorized-use scope
+rules as the other tools apply.
+
 ## authorize (per-call scope)
 
 Pass `scope` directly to the tool; no environment or native scope configuration

{dryhack_mcp-2.1.3 → dryhack_mcp-2.3.0}/dryhack_mcp/__init__.py

@@ -1,3 +1,3 @@
 """DryHack-MCP: offensive-security MCP server for authorized penetration testing."""
 
-__version__ = "2.1.3"
+__version__ = "2.3.0"

{dryhack_mcp-2.1.3 → dryhack_mcp-2.3.0}/dryhack_mcp/config.py

@@ -23,6 +23,22 @@ WORKDIR = _get("DRYHACK_WORKDIR", os.getcwd())
 OUTPUT_BYTE_LIMIT = int(_get("DRYHACK_OUTPUT_LIMIT", "65536") or "65536")
 
 
+# ---- Browser tool (Playwright) -----------------------------------------------
+# Auto-download the requested browser binary on first use if it is missing
+# (the binaries are not shipped via pip). Disable by setting to 0/false/no.
+BROWSER_AUTO_INSTALL = _get("DRYHACK_BROWSER_AUTO_INSTALL", "1").lower() not in (
+    "0",
+    "false",
+    "no",
+    "off",
+)
+
+# Timeout (seconds) for the on-demand `playwright install <browser>` download.
+BROWSER_INSTALL_TIMEOUT = int(
+    _get("DRYHACK_BROWSER_INSTALL_TIMEOUT", "900") or "900"
+)
+
+
 # ---- Transport ---------------------------------------------------------------
 # Default HTTP bind address when running in http mode.
 HTTP_HOST = _get("DRYHACK_HTTP_HOST", "127.0.0.1")

dryhack_mcp-2.3.0/dryhack_mcp/server.py

@@ -0,0 +1,189 @@
+"""DryHack-MCP server: registers the offensive-security tools over MCP."""
+from __future__ import annotations
+
+from typing import Optional
+
+try:
+    # mcp 1.x
+    from mcp.server.fastmcp import FastMCP
+except ModuleNotFoundError:  # pragma: no cover - mcp 2.x fallback
+    # mcp 2.x renamed FastMCP -> MCPServer
+    from mcp.server.mcpserver import MCPServer as FastMCP
+
+from typing import Any, Dict, List
+
+from . import config
+from .tools.curl_tool import curl as _curl
+from .tools.python_tool import python_run as _python_run
+from .tools.shell_tool import shell as _shell
+from .tools.authorize import authorize as _authorize
+from .tools.browser_tool import browser as _browser
+
+mcp = FastMCP("dryhack-mcp")
+
+
+@mcp.tool()
+def curl(args: str, timeout: Optional[int] = None) -> str:
+    """Run curl for HTTP recon/exploitation.
+
+    Provide the arguments only (without the leading `curl`), e.g.
+    "-skiL https://target/". Returns exit code, stdout and stderr.
+    """
+    return _curl(args, timeout=timeout)
+
+
+@mcp.tool()
+def python(code: str, timeout: Optional[int] = None) -> str:
+    """Execute an ad-hoc Python snippet for scripted probing/exploitation."""
+    return _python_run(code, timeout=timeout)
+
+
+@mcp.tool()
+def shell(command: str, timeout: Optional[int] = None) -> str:
+    """Run a shell command line (nmap, ffuf, nc, sqlmap, ...)."""
+    return _shell(command, timeout=timeout)
+
+
+@mcp.tool()
+def authorize(target: str, request: str, scope: list[str], context: str = "", goal: str = "") -> str:
+    """Check target against caller-supplied scope (hosts/domains/IPs/CIDRs).
+
+    Scope must reflect the operator's actual engagement scope; never infer it
+    from the target just to obtain a match. Membership covers the full range
+    of authorized engagement actions for that host (recon, exploitation,
+    configuration changes such as standing up or hardening a staging
+    deployment) — it is not restricted to read-only assessment. This checks
+    membership only, not ownership or legal permission, and does not override
+    client safeguards. No environment scope, network calls, credentials, or
+    persistent state.
+    """
+    return _authorize(target, request, scope=scope, context=context, goal=goal)
+
+
+@mcp.tool()
+def browser(
+    action: Optional[str] = None,
+    url: Optional[str] = None,
+    steps: Optional[List[Dict[str, Any]]] = None,
+    selector: Optional[str] = None,
+    text: Optional[str] = None,
+    value: Optional[str] = None,
+    script: Optional[str] = None,
+    arg: Any = None,
+    init_script: Optional[str] = None,
+    init_scripts: Optional[List[str]] = None,
+    key: Optional[str] = None,
+    name: Optional[str] = None,
+    files: Optional[Any] = None,
+    path: Optional[str] = None,
+    full_page: bool = False,
+    wait_until: Optional[str] = None,
+    state: Optional[str] = None,
+    browser_type: str = "chromium",
+    headless: bool = True,
+    timeout: Optional[int] = None,
+    user_agent: Optional[str] = None,
+    viewport: Optional[Dict[str, int]] = None,
+    extra_http_headers: Optional[Dict[str, str]] = None,
+    cookies: Optional[List[Dict[str, Any]]] = None,
+    proxy: Optional[Dict[str, str]] = None,
+    ignore_https_errors: bool = False,
+    java_script_enabled: bool = True,
+    bypass_csp: bool = False,
+    locale: Optional[str] = None,
+    timezone: Optional[str] = None,
+    geolocation: Optional[Dict[str, float]] = None,
+    device_scale_factor: Optional[float] = None,
+    stop_on_error: bool = True,
+    slow_mo: Optional[int] = None,
+    args: Optional[List[str]] = None,
+    executable_path: Optional[str] = None,
+) -> str:
+    """Drive a real browser via Playwright for web recon/exploitation.
+
+    Run a single `action` (with its relevant params) OR a `steps` list of
+    `{"action": ..., ...}` dicts executed in order within one browser session.
+
+    Supported actions cover navigation (`goto`, `reload`, `back`, `forward`),
+    interaction (`click`, `dblclick`, `fill`, `type`, `press`, `hover`, `focus`,
+    `check`, `uncheck`, `select_option`, `upload`, `mouse_click`,
+    `keyboard_type`, `scroll`), waiting (`wait_for_selector`,
+    `wait_for_timeout`, `wait_for_load_state`, `wait_for_url`), JavaScript
+    injection (`evaluate`/`eval`, `evaluate_handle`, `add_init_script`,
+    `add_script_tag`, `add_style_tag`), extraction (`content`, `inner_text`,
+    `inner_html`, `text_content`, `get_attribute`, `query_all`, `title`, `url`),
+    capture (`screenshot`, `pdf`), and session control (`set_viewport`,
+    `set_extra_headers`, `get_cookies`, `set_cookies`, `clear_cookies`,
+    `storage_state`, `emulate_media`).
+
+    Session-level options let you pick `browser_type` (chromium/firefox/webkit),
+    toggle `headless`, set a `user_agent`, `viewport`, `extra_http_headers`,
+    `cookies`, `proxy`, `locale`, `timezone`, `geolocation`, per-document
+    `init_scripts`, and error handling (`stop_on_error`).
+
+    JavaScript injection: use `evaluate` (with `script` and optional `arg`) to
+    run JS in the current page, or `add_init_script`/`init_scripts` to inject JS
+    that runs before every document's own scripts.
+
+    Requires the optional Playwright extra: `pip install 'dryhack-mcp[browser]'`
+    then `playwright install`. Same authorized-use scope rules as the other
+    tools apply.
+    """
+    return _browser(
+        action=action,
+        url=url,
+        steps=steps,
+        selector=selector,
+        text=text,
+        value=value,
+        script=script,
+        arg=arg,
+        init_script=init_script,
+        init_scripts=init_scripts,
+        key=key,
+        name=name,
+        files=files,
+        path=path,
+        full_page=full_page,
+        wait_until=wait_until,
+        state=state,
+        browser_type=browser_type,
+        headless=headless,
+        timeout=timeout,
+        user_agent=user_agent,
+        viewport=viewport,
+        extra_http_headers=extra_http_headers,
+        cookies=cookies,
+        proxy=proxy,
+        ignore_https_errors=ignore_https_errors,
+        java_script_enabled=java_script_enabled,
+        bypass_csp=bypass_csp,
+        locale=locale,
+        timezone=timezone,
+        geolocation=geolocation,
+        device_scale_factor=device_scale_factor,
+        stop_on_error=stop_on_error,
+        slow_mo=slow_mo,
+        args=args,
+        executable_path=executable_path,
+    )
+
+
+def run(
+    transport: str = "stdio",
+    host: Optional[str] = None,
+    port: Optional[int] = None,
+) -> None:
+    """Start the MCP server.
+
+    Args:
+        transport: "stdio" (default) or "http" (streamable HTTP).
+        host: Bind address for http transport.
+        port: Bind port for http transport.
+    """
+    if transport == "http":
+        mcp.settings.host = host or config.HTTP_HOST
+        mcp.settings.port = port or config.HTTP_PORT
+        mcp.run(transport="streamable-http")
+    else:
+        mcp.run(transport="stdio")