# falconforceteam/parrotforce architecture

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

- Interactive diagram: https://gitdiagram.com/falconforceteam/parrotforce
- Repository: https://github.com/falconforceteam/parrotforce

## Overview

##### Project Type and Purpose
- Project Type: Infrastructure-as-Code (ARM template + CI/CD) for deploying a serverless Azure Logic App playbook.
- Purpose: Automatically collect forensic evidence (live response) from Windows endpoints by orchestrating calls to Azure Sentinel and Microsoft 365 Defender via a Logic App running on a Consumption plan.

##### File Structure
- azuredeploy.json – ARM template defining Azure resources (Logic App, Managed Identity, roles, connectors).
- .github/workflows/*.yml – CI/CD validations (ARM template linting, PSScriptAnalyzer rules).
- README.md – Describes prerequisites (API permissions), deployment steps, and external tools (trident.ps1, winpmem.exe).

##### Extract Key Architectural Insights from the README
- Components to deploy:
– Azure Logic App (Consumption)
– Managed Identity with API permissions: AdvancedQuery.Read.All, Alert.Read.All, File.Read.All, Machine.LiveResponse, Machine.CollectForensics
– Azure Sentinel workspace connector
– Microsoft 365 Defender REST API connector
- Runtime flow:
– Logic App triggers off Sentinel alerts or manual input
– Calls M365 Defender to start a live-response session
– Executes PowerShell (trident.ps1) or native tool (winpmem.exe) on the target Windows machine
– Collects artifacts and stores them in a storage location (e.g., Azure Storage or Log Analytics)

a. Azure Resource Group
b. Azure Logic App (Consumption)
c. Managed Identity (assigned to Logic App)
d. Azure Sentinel (Log Analytics workspace)
e. Microsoft 365 Defender API
f. Target Windows Endpoints (with MDE agents installed)
g. Artifact Storage (e.g., Storage Account or workspace)
h. CI/CD Pipeline (GitHub Actions for template validation)

##### Relationships & Data Flow
1) Logic App uses its Managed Identity to authenticate against Azure Sentinel and Defender APIs
2) Logic App listens for Sentinel alerts or is triggered manually/in CI
3) Logic App issues a REST call to Microsoft 365 Defender to initiate Live Response
4) MDE Agent on Windows VM establishes a session and runs forensic collection tools (trident.ps1, winpmem.exe)
5) Collected artifacts are uploaded back to Azure (Storage Account or Log Analytics)
6) GitHub Actions workflow checks azuredeploy.json and PowerShell modules before merge

##### Architectural Patterns & Principles
- Serverless, event-driven orchestration (Logic Apps on Consumption)
- Principle of least privilege: Managed Identity scoped to only needed Defender and Sentinel API permissions
- Separation of concerns:
– ARM template for infra
– CI/CD workflows for validation
– External repos for forensic tools

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Resource Group
    subgraph "Resource Group"
        classDef azure fill:#cce5ff,stroke:#0066cc;
        LogicApp["Azure Logic App (Consumption)"]:::azure
        ManagedIdentity["Managed Identity\n(API Permissions)"]:::azure
        SentinelWorkspace["Azure Sentinel\n(Log Analytics Workspace)"]:::azure
        DefenderAPIConnector["M365 Defender API Connector"]:::azure
        StorageAccount["Azure Storage Account"]:::azure
    end

    %% External Services and On-Prem
    classDef external fill:#d4edda,stroke:#155724;
    classDef onprem fill:#f0f0f0,stroke:#8a8a8a;
    Microsoft365DefenderAPI["Microsoft 365 Defender API"]:::external
    WindowsVM["Windows VM\nwith MDE Agent"]:::onprem

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        classDef cicd fill:#e0ccff,stroke:#8000ff;
        GitHub["GitHub Actions"]:::cicd
        Precommit["precommit.yml"]:::cicd
        Psrule["psrule-validations.yml"]:::cicd
        TemplateDeploy["ARM Template Deployment"]:::cicd
        README["README.md"]:::cicd
    end

    %% Triggers and Flows
    SentinelWorkspace -.->|"alert trigger"| LogicApp
    LogicApp -->|"uses Managed Identity"| ManagedIdentity
    LogicApp -->|"calls API Connector"| DefenderAPIConnector
    DefenderAPIConnector -->|"REST API call"| Microsoft365DefenderAPI
    Microsoft365DefenderAPI -->|"live response session"| WindowsVM
    WindowsVM -->|"upload artifacts"| StorageAccount
    LogicApp -->|"store results"| StorageAccount

    %% CI/CD Flow
    GitHub --> Precommit
    GitHub --> Psrule
    Precommit --> TemplateDeploy
    Psrule --> TemplateDeploy
    TemplateDeploy -->|"deploy azuredeploy.json"| LogicApp
    TemplateDeploy -->|"deploy azuredeploy.json"| ManagedIdentity
    TemplateDeploy -->|"deploy azuredeploy.json"| SentinelWorkspace
    TemplateDeploy -->|"deploy azuredeploy.json"| DefenderAPIConnector
    TemplateDeploy -->|"deploy azuredeploy.json"| StorageAccount
    GitHub --> README

    %% Click Events
    click LogicApp "https://github.com/falconforceteam/parrotforce/blob/main/azuredeploy.json"
    click ManagedIdentity "https://github.com/falconforceteam/parrotforce/blob/main/azuredeploy.json"
    click SentinelWorkspace "https://github.com/falconforceteam/parrotforce/blob/main/azuredeploy.json"
    click DefenderAPIConnector "https://github.com/falconforceteam/parrotforce/blob/main/azuredeploy.json"
    click Precommit "https://github.com/falconforceteam/parrotforce/blob/main/.github/workflows/precommit.yml"
    click Psrule "https://github.com/falconforceteam/parrotforce/blob/main/.github/workflows/psrule-validations.yml"
    click README "https://github.com/falconforceteam/parrotforce/blob/main/README.md"

    %% Styles
    class LogicApp,ManagedIdentity,SentinelWorkspace,DefenderAPIConnector,StorageAccount azure
    class Microsoft365DefenderAPI external
    class WindowsVM onprem
    class GitHub,Precommit,Psrule,TemplateDeploy,README cicd
```
