FEAT: add WebSocket-based prompt target for Microsoft Copilot

.gitignore

@@ -172,6 +172,7 @@ cython_debug/
 
 # PyRIT secrets file
 .env
+.pyrit_cache/
 
 # Cache for generating docs
 doc/generate_docs/cache/*

doc/_toc.yml

@@ -77,12 +77,13 @@ chapters:
       - file: code/targets/7_http_target
       - file: code/targets/8_openai_responses_target
       - file: code/targets/9_message_normalizer
+      - file: code/targets/10_1_playwright_target
+      - file: code/targets/10_2_playwright_target_copilot
+      - file: code/targets/10_3_websocket_copilot_target
       - file: code/targets/open_ai_completions
-      - file: code/targets/playwright_target
-      - file: code/targets/playwright_target_copilot
       - file: code/targets/prompt_shield_target
-      - file: code/targets/use_huggingface_chat_target
       - file: code/targets/realtime_target
+      - file: code/targets/use_huggingface_chat_target
     - file: code/converters/0_converters
       sections:
         - file: code/converters/1_text_to_text_converters

doc/api.rst

@@ -30,6 +30,8 @@ API Reference
     Authenticator
     AzureAuth
     AzureStorageAuth
+    CopilotAuthenticator
+    ManualCopilotAuthenticator
 
 :py:mod:`pyrit.auxiliary_attacks`
 =================================
@@ -519,6 +521,7 @@ API Reference
     PromptTarget
     RealtimeTarget
     TextTarget
+    WebSocketCopilotTarget
 
 :py:mod:`pyrit.score`
 =====================

doc/code/targets/playwright_target.ipynb → doc/code/targets/10_1_playwright_target.ipynb

@@ -5,7 +5,7 @@
    "id": "0",
    "metadata": {},
    "source": [
-    "# Playwright Target - optional\n",
+    "# 10.1 Generic Playwright Target\n",
     "\n",
     "This notebook demonstrates how to interact with the **Playwright Target** in PyRIT.\n",
     "\n",

doc/code/targets/playwright_target.py → doc/code/targets/10_1_playwright_target.py

@@ -5,15 +5,11 @@
 #       extension: .py
 #       format_name: percent
 #       format_version: '1.3'
-#       jupytext_version: 1.17.2
-#   kernelspec:
-#     display_name: pyrit-dev
-#     language: python
-#     name: python3
+#       jupytext_version: 1.18.1
 # ---
 
 # %% [markdown]
-# # Playwright Target - optional
+# # 10.1 Generic Playwright Target
 #
 # This notebook demonstrates how to interact with the **Playwright Target** in PyRIT.
 #
@@ -158,7 +154,7 @@ async def main(page: Page) -> None:
 
 async def run() -> None:
     async with async_playwright() as playwright:
-        browser = await playwright.chromium.launch(headless=False)
+        browser = await playwright.chromium.launch(headless=True)
         context = await browser.new_context()
         page: Page = await context.new_page()
         await page.goto("http://127.0.0.1:5000")
@@ -169,10 +165,10 @@ async def run() -> None:
 
 # Note in Windows this doesn't run in jupyter notebooks due to playwright limitations
 # https://github.com/microsoft/playwright-python/issues/480
-# await run()
+await run()
 
-if __name__ == "__main__":
-    asyncio.run(run())
+# if __name__ == "__main__":
+#     asyncio.run(run())
 
 
 # %% [markdown]

doc/code/targets/10_3_websocket_copilot_target.py

@@ -0,0 +1,118 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.18.1
+#   kernelspec:
+#     display_name: pyrit (3.13.5)
+#     language: python
+#     name: python3
+# ---
+
+# %% [markdown]
+# # 10.3 WebSocket Copilot Target
+#
+# The `WebSocketCopilotTarget` is an alternative to the `PlaywrightCopilotTarget` that is designed to be more reliable by minimizing dependence on browser automation. Instead of driving the Copilot UI, it communicates directly with Copilot over a WebSocket connection.
+#
+# By default, this target uses automated authentication which requires:
+# - `COPILOT_USERNAME` and `COPILOT_PASSWORD` environment variables
+# - Playwright installed: `pip install playwright && playwright install chromium`
+#
+# Some environments are not suited for automated authentication (e.g. they have security policies with retrieving tokens or have MFA). See the [Alternative Authentication](#alternative-authentication-with-manualcopilotauthenticator) section below.
+
+# %% [markdown]
+# ## Basic Usage with `PromptSendingAttack`
+#
+# The simplest way to interact with the `WebSocketCopilotTarget` is through the `PromptSendingAttack` class.
+
+# %%
+# type: ignore
+from pyrit.executor.attack import ConsoleAttackResultPrinter, PromptSendingAttack
+from pyrit.prompt_target import WebSocketCopilotTarget
+from pyrit.setup import IN_MEMORY, initialize_pyrit_async
+
+await initialize_pyrit_async(memory_db_type=IN_MEMORY, silent=True)
+
+target = WebSocketCopilotTarget()
+attack = PromptSendingAttack(objective_target=target)
+
+objective = "Tell me a joke about AI"
+
+result = await attack.execute_async(objective=objective)
+await ConsoleAttackResultPrinter().print_conversation_async(result=result)
+
+# %% [markdown]
+# ## Multi-Turn Conversations
+#
+# The `WebSocketCopilotTarget` supports multi-turn conversations by leveraging Copilot's server-side conversation management. It automatically generates consistent `session_id` and `conversation_id` values for each PyRIT conversation, enabling Copilot to maintain context across multiple turns.
+#
+# However, this target does not support setting a system prompt nor modifying conversation history. As a result, it cannot be used with attack strategies that require altering prior messages (such as PAIR, TAP, or flip attack) or in contexts where a `PromptChatTarget` is required.
+#
+# Here is a simple multi-turn conversation example:
+
+# %%
+from pyrit.executor.attack import ConsoleAttackResultPrinter, MultiPromptSendingAttack
+from pyrit.models import Message
+from pyrit.prompt_target import WebSocketCopilotTarget
+from pyrit.setup import IN_MEMORY, initialize_pyrit_async
+
+await initialize_pyrit_async(memory_db_type=IN_MEMORY, silent=True)
+
+target = WebSocketCopilotTarget()
+
+prompts = [
+    "I'm thinking of a number between 1 and 10.",
+    "It's greater than 5.",
+    "It's an even number.",
+    "What number am I thinking of?",
+]
+
+messages = [Message.from_prompt(prompt=p, role="user") for p in prompts]
+multi_turn_attack = MultiPromptSendingAttack(objective_target=target)
+
+result = await multi_turn_attack.execute_async(
+    objective="Engage in a multi-turn conversation about a number guessing game",
+    user_messages=messages,
+)
+
+await ConsoleAttackResultPrinter().print_conversation_async(result=result)
+
+# %% [markdown]
+# ## Alternative Authentication with `ManualCopilotAuthenticator`
+#
+# If browser automation is not suitable for your environment, you can use the `ManualCopilotAuthenticator` instead. This authenticator accepts a pre-obtained access token that you can extract from your browser's DevTools.
+#
+# How to obtain the access token:
+#
+# 1. Open the Copilot webapp (e.g., https://m365.cloud.microsoft/chat) in a browser.
+# 2. Open DevTools (F12 or Ctrl+Shift+I).
+# 3. Go to the Network tab.
+# 4. Filter by "Socket" connections or search for "Chathub".
+# 5. Start typing in the chat to initiate a WebSocket connection.
+# 6. Look for the latest WebSocket connection to `substrate.office.com/m365Copilot/Chathub`.
+# 7. You may find the `access_token` in the request URL or in the request payload.
+#
+# You can either pass the token directly or set the `COPILOT_ACCESS_TOKEN` environment variable.
+
+# %%
+from pyrit.auth import ManualCopilotAuthenticator
+from pyrit.executor.attack import ConsoleAttackResultPrinter, PromptSendingAttack
+from pyrit.prompt_target import WebSocketCopilotTarget
+from pyrit.setup import IN_MEMORY, initialize_pyrit_async
+
+await initialize_pyrit_async(memory_db_type=IN_MEMORY, silent=True)
+
+# Option 1: Pass the token directly
+# auth = ManualCopilotAuthenticator(access_token="eyJ0eXAi...")
+
+# Option 2: Use COPILOT_ACCESS_TOKEN environment variable
+auth = ManualCopilotAuthenticator()
+
+target = WebSocketCopilotTarget(authenticator=auth)
+attack_manual = PromptSendingAttack(objective_target=target)
+
+result_manual = await attack_manual.execute_async(objective="Hello! Who are you?")
+await ConsoleAttackResultPrinter().print_conversation_async(result=result_manual)

doc/contributing/1c_install_conda.md

@@ -65,7 +65,7 @@ This is a guide for how to install PyRIT into a `conda` environment.
    ```bash
    pip install -e '.[dev]'
    ```
-   If you plan to use the [Playwright integration](../code/targets/playwright_target.py), install with the playwright extra:
+   If you plan to use the [Playwright integration](../code/targets/10_1_playwright_target.py), install with the playwright extra:
    ```bash
    pip install -e '.[dev,playwright]'
    ```

pyrit/auth/__init__.py

@@ -15,11 +15,15 @@
     get_default_azure_scope,
 )
 from pyrit.auth.azure_storage_auth import AzureStorageAuth
+from pyrit.auth.copilot_authenticator import CopilotAuthenticator
+from pyrit.auth.manual_copilot_authenticator import ManualCopilotAuthenticator
 
 __all__ = [
     "Authenticator",
     "AzureAuth",
     "AzureStorageAuth",
+    "CopilotAuthenticator",
+    "ManualCopilotAuthenticator",
     "TokenProviderCredential",
     "get_azure_token_provider",
     "get_azure_async_token_provider",

pyrit/auth/authenticator.py

@@ -4,30 +4,45 @@
 from __future__ import annotations
 
 import abc
-from abc import abstractmethod
 
 
 class Authenticator(abc.ABC):
     """Abstract base class for authenticators."""
 
     token: str
 
-    @abstractmethod
     def refresh_token(self) -> str:
         """
-        Refresh the authentication token.
+        Refresh the authentication token synchronously.
 
         Returns:
             str: The refreshed authentication token.
         """
-        raise NotImplementedError("refresh_token method not implemented")
+        raise NotImplementedError("Either refresh_token or refresh_token_async method must be implemented")
+
+    async def refresh_token_async(self) -> str:
+        """
+        Refresh the authentication token asynchronously.
+
+        Returns:
+            str: The refreshed authentication token.
+        """
+        raise NotImplementedError("Either refresh_token or refresh_token_async method must be implemented")
 
-    @abstractmethod
     def get_token(self) -> str:
         """
-        Get the current authentication token.
+        Get the current authentication token synchronously.
+
+        Returns:
+            str: The current authentication token.
+        """
+        raise NotImplementedError("Either get_token or get_token_async method must be implemented")
+
+    async def get_token_async(self) -> str:
+        """
+        Get the current authentication token asynchronously.
 
         Returns:
             str: The current authentication token.
         """
-        raise NotImplementedError("get_token method not implemented")
+        raise NotImplementedError("Either get_token or get_token_async method must be implemented")