Start or stop the mitmproxy background process. This is the FIRST tool you should call before any proxy/traffic operation.

WORKFLOW:

1. Call manage_proxy(action="start") to start the proxy

2. Then call browser_open(proxy_port=8082) to route browser traffic through it

3. Now all browser traffic is captured — use get_traffic_summary, search_traffic, etc.

To chain through Burp Suite: manage_proxy(action="start", upstream="localhost:8080") To get a web GUI: manage_proxy(action="start", ui=true) — opens mitmweb on port 8081

Args: action: "start" to launch mitmproxy, "stop" to kill it. No other values accepted. port: Proxy listen port (default 8082). Browser must connect to the same port. ui: If true, launches mitmweb (web GUI on port 8081) instead of headless mitmdump. upstream: Forward all traffic to an upstream proxy (e.g. "localhost:8080" for Burp Suite). Leave empty for direct connections.

Limit which domains the proxy records. Call AFTER manage_proxy(action="start").

By default, ALL traffic is recorded. Use this to focus on specific target domains and reduce noise. Static assets (.jpg, .css, .woff, etc.) and OPTIONS requests are always ignored regardless of scope.

Examples:

• set_scope(allowed_domains=["target.com", "api.target.com"]) — only record these domains

• set_scope(allowed_domains=[]) — reset to record everything

Args: allowed_domains: List of domains to record. Subdomains must be listed explicitly. Empty list = record all traffic.

Check if the mitmproxy process is currently running. Returns status, port, and PID.

Call this BEFORE any proxy operation if you're unsure whether the proxy is already running. If status is "not_running", call manage_proxy(action="start") first.

Get a paginated list of all captured HTTP flows. REQUIRES: proxy must be running and traffic must exist.

Returns flow IDs, URLs, methods, status codes, and latency for each flow. Use the returned flow_id values with inspect_flow, replay_flow, extract_from_flow, etc.

WORKFLOW: manage_proxy(start) → browser_open → browser_go → get_traffic_summary → inspect_flow(flow_id)

Args: limit: Maximum number of flows to return (default 20). Use smaller values to save tokens. offset: Number of flows to skip from the start (default 0). Use for pagination: offset=20 gets the next page.

Get full details of a single HTTP flow (request headers, body, response headers, body).

PREREQUISITE: Get flow_id from get_traffic_summary or search_traffic first.

By default returns only metadata (URL, method, status) to save tokens. Add fields to the include list to get headers and bodies.

Args: flow_id: The flow ID from get_traffic_summary or search_traffic results. include: List of fields to include. Options: - "metadata" (default) — URL, method, status code, latency - "requestHeaders" — all request headers - "requestBody" — request body content - "responseHeaders" — all response headers - "responseBody" — response body content Example: ["metadata", "requestHeaders", "responseBody"]

Search captured traffic by keyword, domain, HTTP method, or status code.

PREREQUISITE: Proxy must be running and have captured traffic.

Use this instead of get_traffic_summary when you need to find specific requests. All filters are optional and can be combined (AND logic).

Examples:

• search_traffic(query="password") — find flows containing "password" in URL or body

• search_traffic(domain="api.target.com", method="POST") — find all POSTs to the API

• search_traffic(status_code=401) — find unauthorized responses

Args: query: Keyword to search in URL, request body, and response body domain: Filter by exact domain (e.g. "api.target.com") method: Filter by HTTP method: "GET", "POST", "PUT", "DELETE", etc. status_code: Filter by exact response status code (e.g. 200, 401, 500) limit: Maximum results to return (default 50)

Extract specific data from a flow's response body using JSONPath, CSS selector, or regex.

PREREQUISITE: Get flow_id from get_traffic_summary or search_traffic.

Choose exactly ONE extractor per call:

• json_path: For JSON API responses. Example: "$.data.users[0].id"

• css_selector: For HTML pages. Example: "input[name=csrf]" to find CSRF tokens

• regex: For any text. Example: 'token":"([^"]+)' to capture a token value

To save the extracted value for reuse in replay_flow, use extract_session_variable instead.

Args: flow_id: The flow ID to extract from json_path: JSONPath expression (e.g. "$.data.users[0].id", "$.token") css_selector: CSS selector for HTML (e.g. "input[name=csrf]", "a.secret-link") regex: Regex pattern — use capture groups to extract specific parts (e.g. 'token":"([^"]+)')

Delete all captured traffic from the database. Use when you want a clean slate before a new test.

WARNING: This permanently deletes all recorded flows. Session variables are NOT cleared.

Generate a copy-paste curl command that reproduces a captured HTTP flow.

PREREQUISITE: Get flow_id from get_traffic_summary or search_traffic.

Useful for:

• Exporting requests to share with teammates

• Testing in terminal outside the MCP environment

• Importing into Burp Suite or Postman

Args: flow_id: The flow ID to generate a curl command for

Resend a captured HTTP request with optional modifications (like Burp Repeater).

PREREQUISITE: Get flow_id from get_traffic_summary or search_traffic.

Session variable substitution: Any {{varname}} in URL, headers, or body is automatically replaced with the value saved by extract_session_variable. Use this for token rotation.

Regex replacements: Modify parts of the request using regex find-and-replace. Example: replacements=[{"regex": "user_id=1", "replacement": "user_id=2"}]

TYPICAL IDOR WORKFLOW:

1. search_traffic(query="/api/users/") → get flow_id

2. extract_session_variable(flow_id, regex="Bearer ([\w.-]+)", name="jwt")

3. replay_flow(flow_id, replacements=[{"regex": "/users/1", "replacement": "/users/2"}])

Args: flow_id: The captured flow to replay replacements: List of {"regex": "pattern", "replacement": "value"} objects for partial modification follow_redirects: Follow HTTP 3xx redirects (default true). Set false to inspect redirect targets.

Send a hand-crafted raw HTTP request (like Burp Repeater's raw editor). No proxy required.

REQUIRES: approved=true (human must approve sending potentially destructive requests).

Use this when you need full control over request formatting — multipart uploads, unusual headers, HTTP smuggling payloads, etc. For replaying captured traffic, use replay_flow instead.

Example raw request: POST /api/login HTTP/1.1 Host: target.com Content-Type: application/json

{"username":"admin","password":"test"}

SECURITY: SSRF protection blocks requests to localhost/private IPs.

Args: raw: Complete raw HTTP request text (request line + headers + blank line + body) host: Override the Host header for routing (optional — extracted from Host header if omitted) port: Target port (default: 443 for HTTPS, 80 for HTTP) tls: Use HTTPS (default true). Set false for plain HTTP targets. follow_redirects: Follow HTTP 3xx redirects (default true) approved: MUST be true. Set this ONLY after the human user has explicitly approved this action.

Add a rule that modifies HTTP traffic in real-time as it passes through the mitmproxy.

PREREQUISITE: Proxy must be running (call manage_proxy(action="start") first).

NOTE: These rules apply to ALL traffic through the proxy (browser + code-mode + replay). Rules are cached for ~5 seconds, so changes are not instant. For instant browser-only interception, use browser_intercept_request/response instead.

Available actions:

• "inject_header": Add/override a header. Requires key and value. Example: add_interception_rule(url_pattern=".api.", action="inject_header", key="X-Admin", value="true")

• "replace_body": Find and replace text in the body. Requires search_pattern and value. Example: add_interception_rule(url_pattern=".*", action="replace_body", search_pattern="false", value="true", resource_type="response")

• "block": Block matching requests entirely. Example: add_interception_rule(url_pattern=".analytics.", action="block")

Args: url_pattern: Regex pattern to match URLs (e.g. ".api.target.com.", ".*.js$") action: "inject_header", "replace_body", or "block" resource_type: "request" or "response" (default: "request") key: Header name (required for inject_header only) value: Header value (for inject_header) or replacement text (for replace_body) search_pattern: Regex to find in body (required for replace_body only) method: Only match this HTTP method, e.g. "POST" (optional, matches all methods if omitted)

Remove a proxy interception rule by its ID.

PREREQUISITE: Get rule_id from list_interception_rules or the add_interception_rule response.

Args: rule_id: The rule ID to remove (e.g. "r-abc12345")

List all active proxy interception rules (added via add_interception_rule).

NOTE: These are proxy-level rules only. For browser-level CDP Fetch rules, use browser_list_intercept_rules instead.

Extract a value from a captured flow and save it as a named session variable.

PREREQUISITE: Get flow_id from get_traffic_summary or search_traffic.

Saved variables are automatically substituted in replay_flow: Any {{varname}} in the URL, headers, or body of a replayed request is replaced with the saved value.

TYPICAL AUTH WORKFLOW:

1. search_traffic(query="/login") → find the login response flow_id

2. extract_session_variable(flow_id, regex='token":"([^"]+)', name="jwt", source="response_body")

3. replay_flow(another_flow_id) → {{jwt}} in Authorization header is auto-replaced

Args: flow_id: The flow to extract from regex: Regex with exactly ONE capture group — the captured group becomes the saved value. Example: 'Bearer ([\w.-]+)' captures the token part only. name: Variable name to save as. Used as {{name}} in replay_flow. source: Where to extract from (default: "response_body"): - "response_body" — response body text - "response_header" — response headers (raw text) - "request_header" — request headers (raw text) - "request_body" — request body text

List all saved session variables. These are used as {{name}} placeholders in replay_flow.

Variables are created by extract_session_variable. They persist until the proxy is restarted.

Automatically scan captured traffic to detect authentication mechanisms.

PREREQUISITE: Proxy must be running and have captured traffic (especially login/API flows).

Detects: JWT, Bearer tokens, API keys, session cookies, CSRF tokens, Basic auth, OAuth2 endpoints. Returns which auth types were found and the flow IDs where they appear.

Use this early in a pentest to understand the target's auth model before planning attacks.

Args: flow_ids: Optional comma-separated flow IDs to analyze (e.g. "abc123,def456"). If omitted, scans the 100 most recent flows automatically.

Fuzz a captured HTTP request by injecting payloads and detecting anomalies.

REQUIRES: approved=true (human must approve high-volume fuzzing). PREREQUISITE: Get flow_id from a captured request that contains the target_pattern string.

HOW IT WORKS:

1. Takes the captured request and replaces target_pattern with each payload

2. Sends all modified requests (concurrently for speed)

3. Measures a baseline from the original request

4. Flags anomalies: unexpected status codes, unusual response lengths, latency spikes, error keywords

SETUP: Insert "FUZZ" into the target field before capturing:

• For URL parameter fuzzing: browser_go("https://target.com/api?id=FUZZ")

• For body fuzzing: use replay_flow with replacements first to insert FUZZ, then fuzz

Args: flow_id: The base flow to fuzz. Its URL/headers/body MUST contain the target_pattern string. payloads: List of strings to inject. Example: ["' OR 1=1--", "alert(1)", "../../../etc/passwd"] target_pattern: The placeholder string to replace with each payload (default: "FUZZ") concurrency: Number of simultaneous requests (default 5). Higher = faster but more aggressive. approved: MUST be true. Set this ONLY after the human user has explicitly approved this action.

Launch a new Chrome browser session with anti-bot bypass (nodriver CDP). Call this BEFORE any other browser_* tool.

TYPICAL STARTUP SEQUENCE:

1. manage_proxy(action="start") — start the proxy first

2. browser_open(proxy_port=8082) — launch Chrome routed through proxy

3. browser_go(url="https://target.com") — navigate

Each session is an independent Chrome instance. You can run multiple sessions simultaneously for multi-user testing (e.g. "victim" and "attacker" sessions for IDOR/privilege escalation).

The browser uses nodriver which bypasses Cloudflare, DataDome, and other bot detection automatically.

Args: session_name: Unique name for this session (default: "default"). Use different names for multiple sessions. proxy_port: Route all browser traffic through mitmproxy on this port (default 8082). Must match the port used in manage_proxy. Set to 0 to disable proxy routing. headless: Run Chrome without a visible window (default true). Set false for visual debugging.

Close a browser session and terminate the Chrome process.

Call this when you're done with a browser session to free resources. If session_name is omitted, closes the "default" session.

Args: session_name: Session to close (default: "default")

List all active browser sessions with their status, PID, ports, and uptime.

Use this to check which sessions are running before sending commands. Dead sessions are automatically cleaned up.

List all open tabs in a browser session with their tab IDs and URLs.

PREREQUISITE: browser_open must have been called first.

Use tab_id from the results to target specific tabs in other browser_* tools.

Args: session_name: Browser session to query (default: "default")

Navigate to a URL and wait for the page to load. Returns the page title and any JS dialog messages.

PREREQUISITE: browser_open must have been called first.

For Single Page Applications (SPAs) that load content dynamically after initial page load, use wait_for to specify a CSS selector that indicates the content is ready.

Args: url: Full URL to navigate to (e.g. "https://target.com/login") session_name: Browser session to use (default: "default") tab_id: Target a specific tab (optional — uses active tab if omitted) wait_for: CSS selector to wait for after navigation (e.g. "#main-content", ".login-form"). Use for SPAs.

Navigate back in browser history (like clicking the Back button).

PREREQUISITE: browser_open and browser_go must have been called first.

Args: session_name: Browser session to use (default: "default")

Extract security-relevant DOM structure from the current page. Returns data the PROXY CANNOT SEE.

PREREQUISITE: browser_open and browser_go must have been called first.

Automatically extracts:

• Forms: action URLs, methods, input fields, hidden inputs, CSRF tokens

• Links: all href values

• Scripts: src attributes (for finding JS endpoints)

• Iframes: embedded frame sources

• HTML comments: developers often leave sensitive info in comments

• Event handlers: onclick, onsubmit, etc. (for client-side logic)

• data-* attributes: often contain API endpoints or config values

• Simplified DOM tree (depth-limited)

Use this for initial recon after navigating to a page.

Args: selector: Root element CSS selector to analyze (default: "body" = entire page) max_depth: How deep to traverse the DOM tree (default: 4). Higher = more detail but more tokens. session_name: Browser session to use (default: "default")

Get the visible text content of a specific DOM element.

PREREQUISITE: browser_open and browser_go must have been called first.

Use this to read specific parts of a page (error messages, user info, API responses rendered in HTML). For full DOM analysis, use browser_get_dom instead.

Args: selector: CSS selector for the element (e.g. "#error-message", ".user-name", "h1") session_name: Browser session to use (default: "default")

Dump browser localStorage and/or sessionStorage contents. Returns data the PROXY CANNOT SEE.

PREREQUISITE: browser_open and browser_go must have been called first.

Web apps often store JWT tokens, API keys, user preferences, or feature flags in browser storage. This data never appears in HTTP traffic — it's only accessible client-side.

Args: storage_type: What to read — "local" (localStorage only), "session" (sessionStorage only), or "both" (default) session_name: Browser session to use (default: "default")

Read JavaScript console output from the browser. Returns data the PROXY CANNOT SEE.

PREREQUISITE: browser_open and browser_go must have been called first.

Console messages often contain:

• Stack traces that reveal internal file paths and function names

• Debug messages with internal API URLs or configuration

• Error messages that indicate vulnerability surfaces

• Content Security Policy (CSP) violation reports

Args: level: Filter by message level — "all" (default), "error", or "warning" clear: Clear the console buffer after reading (default false). Set true to avoid re-reading old messages. session_name: Browser session to use (default: "default")

Take a screenshot of the current page (returns base64-encoded PNG).

PREREQUISITE: browser_open and browser_go must have been called first.

Useful for:

• Verifying the page state after navigation (did login succeed?)

• Checking for bot detection challenges (Cloudflare, CAPTCHA)

• Documenting vulnerability evidence

• Visual confirmation before destructive actions

Args: selector: CSS selector to capture a specific element (optional — captures full page if omitted) session_name: Browser session to use (default: "default")

Click an element on the page. Returns any JavaScript alert/confirm/prompt dialog messages triggered.

PREREQUISITE: browser_open and browser_go must have been called first.

Provide EITHER selector OR text (not both):

• selector: CSS selector for the element (e.g. "#login-btn", "button[type=submit]")

• text: Visible text to find and click (uses best match, e.g. "Login", "Submit")

XSS DETECTION: If clicking triggers a JavaScript alert() dialog, the dialog message is returned. This is how you verify reflected/stored XSS — inject a payload, navigate to the page, and check for alerts.

Args: selector: CSS selector to click (e.g. "#submit", "button.login") text: Visible text to find and click (e.g. "Login", "Submit Order") session_name: Browser session to use (default: "default")

Type text into an input field (login forms, search boxes, payload injection).

PREREQUISITE: browser_open and browser_go must have been called first.

TYPICAL LOGIN FLOW:

1. browser_go(url="https://target.com/login")

2. browser_type(selector="#email", text="admin@target.com")

3. browser_type(selector="#password", text="password123")

4. browser_click(selector="#login-btn")

For XSS testing, type payloads directly: browser_type(selector="#search", text='alert(1)')

Args: selector: CSS selector for the input element (e.g. "#email", "input[name=username]", "#search") text: Text to type. Can be any string including XSS/SQLi payloads. clear: Clear existing text before typing (default true). Set false to append. press_enter: Press Enter key after typing (default false). Useful for search forms without a submit button. session_name: Browser session to use (default: "default")

Set a cookie in the browser via CDP. Can set httpOnly cookies (unlike document.cookie in JS).

PREREQUISITE: browser_open and browser_go must have been called first (need a page loaded for domain).

USE CASES:

• IDOR testing: Set another user's session cookie to test access controls

• Session fixation: Pre-set a known session ID

• Testing httpOnly bypass: Inject cookies that JavaScript can't normally set

Args: name: Cookie name (e.g. "session_id", "auth_token") value: Cookie value domain: Cookie domain (default: current page's domain). Must match or be a parent of the page domain. path: Cookie path (default: "/") http_only: Set the HttpOnly flag — makes cookie invisible to document.cookie (default false) secure: Set the Secure flag — cookie only sent over HTTPS (default false) session_name: Browser session to use (default: "default")

Execute arbitrary JavaScript in the browser page context. Returns the expression's result.

PREREQUISITE: browser_open and browser_go must have been called first.

USE CASES:

• Extract CSRF tokens: 'document.querySelector("meta[name=csrf-token]").content'

• Read cookies: 'document.cookie'

• Hook fetch API to monitor requests

• Inspect JavaScript objects and prototypes

• Test DOM-based XSS payloads

• Call internal JavaScript functions

The expression is evaluated in the page's JS context — it has full access to the page's DOM, variables, functions, and APIs.

Args: expression: JavaScript code to evaluate. Can be a single expression or multi-line code. Example: 'document.title' or 'fetch("/api/me").then(r=>r.json())' session_name: Browser session to use (default: "default")

Wait for a DOM element or text to appear on the page. Use for SPAs, AJAX, and dynamic content.

PREREQUISITE: browser_open and browser_go must have been called first.

Use this AFTER browser_go or browser_click when the page loads content asynchronously. Provide EITHER selector OR text (not both).

Args: selector: CSS selector to wait for (e.g. "#dashboard", ".search-results", "table.data") text: Text content to wait for (e.g. "Welcome back", "Results found") timeout: Maximum wait time in seconds (default: 10). Returns error if element doesn't appear. session_name: Browser session to use (default: "default")

Intercept and modify OUTGOING browser requests in real-time via Chrome CDP Fetch API.

PREREQUISITE: browser_open must have been called first.

IMPORTANT — This is DIFFERENT from add_interception_rule (proxy-level):

• browser_intercept_* = instant, browser-only, via Chrome CDP. Changes take effect immediately.

• add_interception_rule = proxy-level, ~5s cache delay, applies to ALL traffic (browser + code-mode).

Available actions:

• "inject_header": Add a custom header to matching requests. Example: browser_intercept_request(url_pattern=".api.", action="inject_header", key="X-Admin", value="true")

• "block": Block matching requests entirely (returns network error to the page). Example: browser_intercept_request(url_pattern=".analytics.", action="block")

Args: url_pattern: Regex pattern to match request URLs (e.g. ".api.target.com.") action: "inject_header" or "block" key: Header name (required for inject_header) value: Header value (required for inject_header) session_name: Browser session to use (default: "default")

Intercept and modify INCOMING browser responses in real-time via Chrome CDP Fetch API.

PREREQUISITE: browser_open must have been called first.

USE CASES:

• CSP bypass testing: Replace Content-Security-Policy headers in responses

• Response tampering: Modify API responses to test client-side validation

• Inject XSS payloads into response bodies

• Remove security headers to test fallback behavior

Available actions:

• "replace_body": Find and replace text in the response body. Example: browser_intercept_response(url_pattern=".api.", action="replace_body", search_pattern='"admin":false', value='"admin":true')

• "block": Block the response entirely.

Args: url_pattern: Regex pattern to match request URLs (e.g. ".api.target.com/me.") action: "replace_body" or "block" search_pattern: Regex to find in the response body (required for replace_body) value: Replacement text (required for replace_body) session_name: Browser session to use (default: "default")

Disable ALL CDP Fetch interception and remove all rules for this browser session.

Call this when you want to stop intercepting and return to normal browsing. This clears both request and response intercept rules.

Args: session_name: Browser session to use (default: "default")

List all active CDP Fetch interception rules for a browser session.

NOTE: These are browser-level rules only (set via browser_intercept_request/response). For proxy-level rules, use list_interception_rules instead.

Args: session_name: Browser session to use (default: "default")

Execute a Python script in an isolated sandbox with full access to all other tools via NdpSDK.

REQUIRES: approved=true (human must approve arbitrary code execution).

WHEN TO USE THIS (instead of individual tools):

• Race conditions / TOCTOU attacks (need precise timing)

• Blind SQL injection (needs hundreds of sequential requests with conditional logic)

• Multi-step exploit chains (login → extract token → IDOR scan → report)

• Heavy loops (brute force, enumeration)

• Complex encoding/decoding chains (double URL encoding, JWT manipulation)

• Custom PoC/exploit generation

HOW TO USE NdpSDK:

from nodriver_proxy_mcp.sdk import NdpSDK
import asyncio

async def main():
    sdk = NdpSDK()  # auto-connects to running proxy and browser sessions

    # All 38 other tools are available as async methods:
    await sdk.manage_proxy("start")
    await sdk.browser_open()
    await sdk.browser_go("https://target.com")
    flows = await sdk.get_traffic_summary()
    result = await sdk.replay_flow(flow_id, replacements=[...])

asyncio.run(main())

RESOURCE LIMITS: 256MB memory, 60s CPU time, 32KB output cap. External packages can be auto-installed via the dependencies parameter.

Args: script_content: Python code to execute. Use NdpSDK to access all proxy/browser tools programmatically. dependencies: Pip packages to install before execution (e.g. ["pyjwt", "pycryptodome", "beautifulsoup4"]). timeout: Maximum wall-clock execution time in seconds (default: 300 = 5 minutes). approved: MUST be true. Set this ONLY after the human user has explicitly approved code execution. bypass_proxy: If true, HTTP requests from the script skip the proxy (for raw speed or avoiding interception loops).