# microsoft/pyrit-ship architecture

> Architecture diagram of the GitHub repository microsoft/pyrit-ship, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/pyrit-ship
- Repository: https://github.com/microsoft/pyrit-ship

## Overview

##### Project type and purpose
- This is a dual-component integration prototype (“full-stack” in a broad sense):
a. A Python Flask-based microservice (“PyRIT Ship”) exposing parts of the PyRIT toolkit as HTTP APIs (prompt generation, scoring).
b. A Java extension for PortSwigger’s Burp Suite that calls those HTTP APIs from the Intruder module.
- Purpose: Let red-teamers plug into PyRIT’s AI-driven payload generation/scoring from within Burp Suite (and potentially other tooling).

##### File structure
- Top-level folders:
- pyritship/ — Python Flask app and helper scripts (app.py, request_tester.py)
- burp_extension/pyritship/ — Java Gradle project implementing the Burp Suite extension
- docs/ — Markdown docs (setup, workflows, demos)
- Key configuration and build files:
- build.gradle & settings.gradle define the Java plugin’s build lifecycle
- .env likely holds Python environment/API keys
- Patterns:
- Separation of concerns: Python side = API service; Java side = Burp UI integration.

##### README for additional insights
- Confirms Python Flask server exposing “prompt generator” and “scoring” endpoints.
- Confirms Java extension registers HTTP handlers and payload generators/processors inside Burp Intruder.
- Mentions future Docker container, Entra ID auth, alternate endpoints—external service integration is a concern.

1. Burp Suite Intruder UI (user interface)
2. Java Extension (PyRITShipHttpHandler, PayloadGenerator/Provider/Processor)
3. HTTP Client within the extension
4. PyRITShip Flask API Server
5. PyRIT core library (invoked by app.py)
6. External AI Service (Azure OpenAI API)
7. (Optional future) Docker Host / Container
- User → Intruder UI → invokes Java Extension
- Java Extension → HTTP Client → PyRITShip Flask API
- Flask API → PyRIT core → calls Azure OpenAI → gets response → returns to Extension
- Extension → Intruder → actual attack requests
c. Architectural patterns & principles:
- Microservice style: Python API is decoupled from UX (Burp)
- Plugin architecture: Java implements providers/processors per Burp extension API
- External service integration: API key, auth handled by Flask service
d. Key technologies & frameworks:
- Python: Flask, PyRIT toolkit
- Java: JUnit/Gradle, Burp Suite Extender API
- External: Azure OpenAI REST endpoints
- (Future) Docker for containerization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Burp Suite UI
    UI["Burp Suite Intruder UI"]:::ui

    %% Java Extension
    subgraph "Java Extension"
        EXT_CORE["Java Extension (Core)"]:::java
        ENTRY["PyRITShip.java"]:::java
        HANDLER["PyRITShipHttpHandler"]:::java
        GEN["PyRITShipPayloadGenerator"]:::java
        PROVIDER["PyRITShipPayloadGeneratorProvider"]:::java
        PROCESSOR["PyRITShipPayloadProcessor"]:::java
        BUILD_GRADLE["build.gradle"]:::java
        SETTINGS_GRADLE["settings.gradle"]:::java
    end

    %% Python Flask Service
    subgraph "PyRITShip API Server"
        FLASK["PyRITShip Flask API (Flask)"]:::python
        CORE["PyRIT core library"]:::python
        ENV[".env"]:::config
        TESTER["Python CLI Tester"]:::python
    end

    %% External Service
    AZURE["Azure OpenAI API"]:::external

    %% Documentation
    subgraph "Documentation"
        DOC_EXT["burp_extension.md"]:::docs
        DOC_API["pyritship.md"]:::docs
        DOC_DEMO["burp_gandalf_demo.md"]:::docs
        DOC_IMG["images/"]:::docs
    end

    %% Connections
    UI -->|"triggers extension"| EXT_CORE
    EXT_CORE --> ENTRY
    ENTRY -->|uses| HANDLER
    ENTRY -->|uses| GEN
    ENTRY -->|uses| PROVIDER
    ENTRY -->|uses| PROCESSOR
    HANDLER -->|"HTTP REST"| FLASK
    FLASK -->|invokes| CORE
    CORE -->|"HTTP REST"| AZURE
    AZURE -->|response| CORE
    CORE -->|returns| FLASK
    TESTER -->|"HTTP REST CLI"| FLASK

    %% Click Events
    click EXT_CORE "https://github.com/microsoft/pyrit-ship/tree/main/burp_extension/pyritship/"
    click ENTRY "https://github.com/microsoft/pyrit-ship/blob/main/burp_extension/pyritship/src/main/java/pyritship/PyRITShip.java"
    click HANDLER "https://github.com/microsoft/pyrit-ship/blob/main/burp_extension/pyritship/src/main/java/pyritship/PyRITShipHttpHandler.java"
    click GEN "https://github.com/microsoft/pyrit-ship/blob/main/burp_extension/pyritship/src/main/java/pyritship/PyRITShipPayloadGenerator.java"
    click PROVIDER "https://github.com/microsoft/pyrit-ship/blob/main/burp_extension/pyritship/src/main/java/pyritship/PyRITShipPayloadGeneratorProvider.java"
    click PROCESSOR "https://github.com/microsoft/pyrit-ship/blob/main/burp_extension/pyritship/src/main/java/pyritship/PyRITShipPayloadProcessor.java"
    click BUILD_GRADLE "https://github.com/microsoft/pyrit-ship/blob/main/burp_extension/pyritship/build.gradle"
    click SETTINGS_GRADLE "https://github.com/microsoft/pyrit-ship/blob/main/burp_extension/settings.gradle"
    click FLASK "https://github.com/microsoft/pyrit-ship/blob/main/pyritship/app.py"
    click TESTER "https://github.com/microsoft/pyrit-ship/blob/main/pyritship/request_tester.py"
    click ENV "https://github.com/microsoft/pyrit-ship/blob/main/.env"
    click DOC_EXT "https://github.com/microsoft/pyrit-ship/blob/main/docs/burp_extension.md"
    click DOC_API "https://github.com/microsoft/pyrit-ship/blob/main/docs/pyritship.md"
    click DOC_DEMO "https://github.com/microsoft/pyrit-ship/blob/main/docs/burp_gandalf_demo.md"
    click DOC_IMG "https://github.com/microsoft/pyrit-ship/tree/main/docs/images/"

    %% Styles
    classDef ui fill:#dddddd,stroke:#333,stroke-width:1px;
    classDef java fill:#a0c4ff,stroke:#0366d6,stroke-width:1px;
    classDef python fill:#caffbf,stroke:#33a02c,stroke-width:1px;
    classDef external fill:#bde0fe,stroke:#005b96,stroke-width:1px;
    classDef config fill:#ffe5d9,stroke:#e63946,stroke-width:1px;
    classDef docs fill:#e0e0e0,stroke:#666,stroke-width:1px;
```
