How to Intercept Network Traffic in a Chrome Extension Using chrome.debugger API

Overview

The chrome.debugger API allows Chrome extensions to interact with the Chrome DevTools Protocol (CDP), enabling network traffic interception. This is useful for monitoring, logging, or modifying network requests and responses in real-time.

Step-by-Step Tutorial

1. Manifest Permissions

Ensure your manifest.json includes the necessary permissions:

{
  "manifest_version": 3,
  "name": "Network Traffic Interceptor",
  "version": "1.0",
  "permissions": ["debugger", "storage"],
  "host_permissions": ["https://www.google.com/*"],
  "background": {
    "service_worker": "service-worker.js"
  },
  "action": {}
}

2. Attach Debugger to Tab

In your service worker (service-worker.js), attach the debugger to the active tab:

async function attachDebugger(tab) {
  if (!tab || !tab.id) return;
  if (!tab.url.startsWith("http")) {
    console.error("Debugger can only be attached to HTTP/HTTPS pages.");
    return;
  }

  const debuggee_id = { tabId: tab.id };

  try {
    await chrome.debugger.detach(debuggee_id);
  } catch (e) {
    // Ignore if not attached
  }

  try {
    await chrome.debugger.attach(debuggee_id, "1.3"); // https://chromedevtools.github.io/devtools-protocol/
    await chrome.debugger.sendCommand(debuggee_id, "Network.enable", {});
    console.log("Network interception enabled.");
  } catch (error) {
    console.error("Failed to attach debugger:", error);
  }
} // Google's boilerplates: https://github.com/GoogleChrome/chrome-extensions-samples/blob/main/api-samples/

// usage: Attach on action click
chrome.action.onClicked.addListener(async (tab) => {
  await attachDebugger(tab);
});

3. Listen for Network Events

Set up event listeners for network events:

const pending_requests = new Map();

chrome.debugger.onEvent.addListener(function (source, method, params) {
  if (method === "Network.responseReceived") {
    // Store request ID for later retrieval
    pending_requests.set(params.requestId, params.response.url);
  }

  if (method === "Network.loadingFinished") {
    const request_id = params.requestId;
    const url = pending_requests.get(request_id);
    if (!url) return;
    pending_requests.delete(request_id);

    chrome.debugger.sendCommand(
      source,
      "Network.getResponseBody",
      { requestId: request_id },
      function (result) {
        if (chrome.runtime.lastError) {
          console.error(
            `Failed to get response body: ${chrome.runtime.lastError.message}`
          );
          return;
        }
        if (result && result.body) {
          const body = result.base64Encoded ? atob(result.body) : result.body;
          console.log(`Response from ${url}:`, body);
          // Process the response body here
        }
      }
    );
  }
});

Running the Extension

Create a new directory for your extension.
Save the manifest.json and service-worker.js files as shown above.
Load the directory as an unpacked extension in Chrome:
- Open chrome://extensions/.
- Enable "Developer mode".
- Click "Load unpacked" and select your directory.
Navigate to an HTTP/HTTPS webpage (e.g., https://stackoverflow.com/questions).
Click the extension's action button (puzzle piece icon) to attach the debugger.
Open the developer console (F12) to see logged network responses.
Interact with the page to trigger network requests and observe the logs.

Handling the "{"code":-32000,"message":"No resource with given identifier found"}" Error

This error stems from Network.getResponseBody and is symptomatic of the following common causes:

Timing Issues: Network.enable must be called before requests are made. If called after, existing request IDs are invalid.
Buffer Overflow: Chrome's Network domain has memory limits (~10MB per resource, ~100MB total). Old responses are discarded FIFO.
State Reset: Network.enable resets the domain state, invalidating previous IDs.
Incomplete Response: Calling getResponseBody before loadingFinished.

Mitigation:

Best to attach the debugger only once: Implement debugger attachment through a single, controlled mechanism (e.g., via chrome.action.onClicked) to prevent multiple or conflicting Network.enable commands. Each Network.enable resets the Network domain state, clearing buffers and invalidating existing request IDs. Calling it redundantly or out of sequence can cause state resets mid-session, leading to the "No resource" error.
API error handling: CDP APIs do not throw errors; instead, failures are indicated by setting chrome.runtime.lastError
Adjust buffer sizes for large responses: If dealing with large response bodies, configure Network.enable with increased limits, e.g., Network.enable({ maxTotalBufferSize: 200000000, maxResourceBufferSize: 50000000 }), to prevent FIFO eviction of response data before retrieval.

Network Protocols and Event Flow

HTTP Workflow: Client sends request → Server responds → Browser processes response.
CDP Events:
1. Network.requestWillBeSent: Request initiated.
2. Network.responseReceived: Response headers received.
3. Network.dataReceived: Response data chunks (if chunked).
4. Network.loadingFinished: Response fully loaded.
State Changes: Network.enable initializes/reinitializes the domain, clearing buffers and invalidating IDs.

Underlying Changes in Network Domain

The Network domain manages an in-memory buffer for response bodies. Enabling resets this buffer, ensuring fresh state but invalidating old data.

79820438