# vjeroen/purplecrew architecture

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

- Interactive diagram: https://gitdiagram.com/vjeroen/purplecrew
- Repository: https://github.com/vjeroen/purplecrew

## Overview

##### Project type and purpose
- PurpleCrew is a security-automation full-stack application that leverages AI agents (via CrewAI) to orchestrate Red Team, Blue Team, and IT Ops activities.
- The “crew-api.py” (FastAPI) serves as the HTTP entry point, while the “src/purplecrew” directory contains the core engine, individual crew implementations, and tool integrations.

##### File structure
- Top-level:
- crew-api.py (HTTP/REST API)
- index.html (optional simple UI)
- EmulationSummary.md, FullSummaryReport.md (output reports)
- pyproject.toml, uv.lock (build/config)
- src/purplecrew/main.py – boots the CrewAI flow and loads crews.
- src/purplecrew/crews/[redteamcrew|blueteamcrew|itopscrew] – each crew module implements a specialized agent workflow, backed by YAML configurations (agents.yaml, tasks.yaml).
- src/purplecrew/tools – collection of custom tool wrappers (Caldera, Azure Sentinel, MITRE, Terraform, etc.), plus HTML/JSON/Jinja2 templates.

##### README insights
- Emphasizes a modular architecture: agents, tools, task definitions are pluggable.

- Configuration files (YAML) feeding into each crew module.
- Data flow end-to-end: request → crew selection → task execution → external API → response/report.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI["Browser UI"]:::white
        click UI "https://github.com/vjeroen/purplecrew/blob/main/index.html"
        CLI["CLI (crewai flow run)"]:::white
    end

    %% API Layer
    subgraph "API Layer"
        API["FastAPI Server\ncrew-api.py"]:::white
        click API "https://github.com/vjeroen/purplecrew/blob/main/crew-api.py"
    end

    %% Core Engine
    subgraph "Core Engine"
        Engine["PurpleCrew Flow\n(src/purplecrew/main.py)"]:::white
        click Engine "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/main.py"
    end

    %% Crew Modules
    subgraph "Crew Modules"
        subgraph "RedTeamCrew"
            RTCode["redteamcrew.py"]:::red
            click RTCode "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/crews/redteamcrew/redteamcrew.py"
            RTAgents["agents.yaml"]:::red
            click RTAgents "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/crews/redteamcrew/config/agents.yaml"
            RTTasks["tasks.yaml"]:::red
            click RTTasks "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/crews/redteamcrew/config/tasks.yaml"
        end
        subgraph "BlueTeamCrew"
            BTCode["blueteamcrew.py"]:::blue
            click BTCode "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/crews/blueteamcrew/blueteamcrew.py"
            BTAgents["agents.yaml"]:::blue
            click BTAgents "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/crews/blueteamcrew/config/agents.yaml"
            BTTasks["tasks.yaml"]:::blue
            click BTTasks "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/crews/blueteamcrew/config/tasks.yaml"
        end
        subgraph "ITOpsCrew"
            IOCode["itopscrew.py"]:::gray
            click IOCode "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/crews/itopscrew/itopscrew.py"
            IOAgents["agents.yaml"]:::gray
            click IOAgents "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/crews/itopscrew/config/agents.yaml"
            IOTasks["tasks.yaml"]:::gray
            click IOTasks "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/crews/itopscrew/config/tasks.yaml"
        end
    end

    %% Tools Integrations
    subgraph "Tools Integrations"
        AZ["Azure Sentinel Wrapper"]:::white
        click AZ "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/az_sentinel.py"
        Caldera["Caldera Connector"]:::white
        click Caldera "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/caldera_tool.py"
        CustomTool["Custom Tool"]:::white
        click CustomTool "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/custom_tool.py"
        Terraform["Terraform Wrapper"]:::white
        click Terraform "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/terraform_tool.py"
        TFTemplate["main.tf.j2"]:::white
        click TFTemplate "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/templates/main.tf.j2"
        MitreJSON["enterprise-attack.json"]:::white
        click MitreJSON "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/templates/enterprise-attack.json"
        PDFExtractor["MITRE PDF Extractor"]:::white
        click PDFExtractor "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/mitre_pdf_extractor_tool.py"
        MatrixTool["MITRE Matrix Wrapper"]:::white
        click MatrixTool "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/mitre_matrix_tool.py"
        Serper["Serper Search"]:::white
        click Serper "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/serper_check.py"
        Summarize["Ability Summarization"]:::white
        click Summarize "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/summarize_abilities.py"
        AnalyticRule["Analytic Rule Generator"]:::white
        click AnalyticRule "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/generate_analytic_rule.py"
    end

    %% Reporting & Logging
    subgraph "Reporting & Logging"
        OpsLog["agentops.log"]:::white
        click OpsLog "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/agentops.log"
        ER["EmulationSummary.md"]:::white
        click ER "https://github.com/vjeroen/purplecrew/blob/main/EmulationSummary.md"
        FR["FullSummaryReport.md"]:::white
        click FR "https://github.com/vjeroen/purplecrew/blob/main/FullSummaryReport.md"
        HtmlTemplate["EmulationReportSummary.html"]:::white
        click HtmlTemplate "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/templates/EmulationReportSummary.html"
        JSONTemplate["Sentinel Analytics JSON"]:::white
        click JSONTemplate "https://github.com/vjeroen/purplecrew/blob/main/src/purplecrew/tools/templates/Sentinel_Analytics_Template.json"
    end

    %% External Services
    subgraph "External Services"
        ExtCaldera["Caldera Server"]:::green
        AzureAPIs["Azure APIs"]:::green
        TerraformCloud["Terraform Cloud"]:::green
        GitHub["GitHub"]:::green
        SERPERAPI["Serper API"]:::green
        OpenAI["OpenAI"]:::green
    end

    %% Data Flows
    UI -->|"HTTP Request"| API
    CLI -->|"Invoke CLI"| Engine
    API -->|"invoke"| Engine
    Engine -->|"load agents"| RTCode
    Engine -->|"load agents"| BTCode
    Engine -->|"load agents"| IOCode
    RTCode -->|"use config"| RTAgents
    RTCode -->|"use config"| RTTasks
    BTCode -->|"use config"| BTAgents
    BTCode -->|"use config"| BTTasks
    IOCode -->|"use config"| IOAgents
    IOCode -->|"use config"| IOTasks
    RTCode -->|"call tool"| Caldera
    RTCode -->|"call tool"| AZ
    BTCode -->|"call tool"| Serper
    IOCode -->|"call tool"| Terraform
    CustomTool -->|"helper"| RTCode
    Summarize -->|"generate abilities"| BTCode
    AnalyticRule -->|"generate rules"| IOCode
    Caldera -->|"API call"| ExtCaldera
    AZ -->|"REST API"| AzureAPIs
    Terraform -->|"SDK/API"| TerraformCloud
    Serper -->|"HTTP API"| SERPERAPI
    Summarize -->|"API call"| OpenAI
    MatrixTool -->|"process JSON"| MitreJSON
    PDFExtractor -->|"extract"| MitreJSON
    RTCode -->|"write report"| ER
    BTCode -->|"write report"| FR
    IOCode -->|"write report"| ER
    RTCode -->|"log"| OpsLog
    BTCode -->|"log"| OpsLog
    IOCode -->|"log"| OpsLog
    ER -->|"view via UI/API"| UI
    FR -->|"view via UI/API"| UI

    %% Styles
    classDef red fill:#ffe6e6,stroke:#ff4d4d,stroke-width:1px;
    classDef blue fill:#e6f0ff,stroke:#3399ff,stroke-width:1px;
    classDef gray fill:#f2f2f2,stroke:#a6a6a6,stroke-width:1px;
    classDef green fill:#e6ffe6,stroke:#33cc33,stroke-width:1px;
    classDef white fill:#ffffff,stroke:#cccccc,stroke-width:1px;
```
