# cobbr/covenant architecture

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

- Interactive diagram: https://gitdiagram.com/cobbr/covenant
- Repository: https://github.com/cobbr/covenant

## Overview

##### Main System Components
- Web Frontend – Represented by the web pages, Razor pages, and Blazor components found in directories such as “Pages” and “Components”. This component provides the user interface for multi‑user collaboration and operation management.
- API Layer – The API controllers (located in “Controllers/ApiControllers”) expose endpoints for operations like user management, credentials, tasks, events, indicators, launchers, listeners, and more. There is also a Swagger UI exposed via the “openapi.json” file.
- Real‑Time Communication – SignalR hubs (in the “Hubs” directory) manage real‑time events such as command outputs, event notifications, and grunt interactions.
- Core Services – The “Core” directory holds business logic already seen in classes like CovenantAPIService, CovenantHubService, and NotificationService. This is where much of the coordination between subsystems happens.
- Dynamic Compilation Module – Note the integration with the Roslyn API used for dynamic C# compilation; these elements (also related to “Data/Tasks”) represent the system’s ability to generate and obfuscate code on the fly.
- Data and Storage – The “Data” directory houses configuration files, download directories, profiles, tasks, reference libraries, and even embedded resources. This is effectively the persistence or configuration storage for many runtime aspects.
- Security and Communication – Encryption, key-exchange logic, and SSL (optional) are implemented in services (see Encryption.cs) which ensure secure communication between the server and implants.
- Implant (Grunt) Communication – This component involves the “Grunt” models and related controllers/logic which handle communication with the remote payloads ("Grunts").

##### Relationships and Interactions
- The Web Frontend interacts with the API controllers via HTTP requests. In parallel, it subscribes to real‑time updates via SignalR hubs.
- API controllers serve as the bridge between frontend user actions and back‑end processing logic contained in the Core services.
- The Core services invoke business logic — including dynamic compilation for generating “Grunt” code – and communicate with the data layer as necessary. They also update the SignalR hubs.
- Data storage is leveraged for configuration (profiles, tasks, listener settings) and logging events, which can be reviewed through the UI.
- The secure encrypted key exchange and other cryptographic operations ensure that messages with implants are protected.
- External integrations, such as a Docker container (using the Dockerfile) and possibly other third‑party libraries (e.g., ConfuserEx for obfuscation), are depicted as external modules or dependencies.

##### Architectural Patterns & Design Principles
- Separation of Concerns – Clear segregation of presentation (Razor components and pages), API (controllers), business logic (Core), and data access.
- API-Driven Design – A RESTful (and Swagger-documented) API layer makes the system extendible and supports multi-user collaboration.
- Real-Time Communication – SignalR hubs promote push notifications and bi‑directional updates, enhancing the responsiveness of the system.
- Dynamic & Modular – Since tasks and code generation/recompilation is handled dynamically through the Roslyn API, illustrate a distinct “Dynamic Compilation” module that feeds into the “Grunt” or implant components.
- Security Focused – Highlight the use of encryption and secure communication strategies between implants and the server.

##### Detailing Technologies and Frameworks
- ASP.NET Core – Foundation for both the API and web frontend.
- Razor/Blazor Components – For interactive UI elements.
- SignalR – For real‑time communication.
- Swagger – As shown by openapi.json for API development.
- Roslyn API – To support dynamic compilation.
- .NET Core Data Structures – Including Entity Framework if used for database access (implied by the data directories and context models).
- Other libraries include ConfuserEx (for obfuscation), and potentially Docker (for container deployment).

– Consider including external elements such as Docker containers and third-party tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actor
    External["Red Team Operators"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer: Web Frontend"
        WP["Web Pages"]:::frontend
        WC["Web Components"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        APICtrl["API Controllers"]:::api
        APIService["OpenAPI Layer"]:::api
        APICtrl -->|"internal"| APIService
    end

    %% Core Services
    subgraph "Business Logic"
        CS["Core Business Logic"]:::core
    end

    %% Dynamic Compilation Module
    subgraph "Dynamic Compilation Module"
        Compiler["Dynamic Compiler"]:::dynamic
        CST["CSharp Task Generation"]:::dynamic
        Compiler -->|"generates"| CST
    end

    %% Data and Storage
    subgraph "Data Storage"
        Data["Configuration & Storage"]:::data
    end

    %% Real‑Time Communication
    subgraph "Real‑Time Communication"
        SignalR["SignalR Hubs"]:::realtime
    end

    %% Security and Communication
    subgraph "Security & Communication"
        Sec["Encryption Services"]:::security
    end

    %% Implant (Grunt) Communication
    subgraph "Implant Communication"
        GruntComp["Grunt Components"]:::implant
        GruntModel["Grunt Models"]:::implant
        GruntComp -->|"interfaces"| GruntModel
    end

    %% Connections
    External -->|"HTTP_Request"| WP
    External -->|"HTTP_Request"| WC

    WP -->|"HTTP_APICalls"| APICtrl
    WC -->|"HTTP_APICalls"| APICtrl

    APICtrl -->|"processes"| CS

    CS -->|"data_ops"| Data
    CS -->|"real-time"| SignalR
    CS -->|"triggers"| Compiler
    CS -->|"secure"| Sec

    CST -->|"feeds_code"| GruntComp

    %% Styling
    classDef external fill:#f9c,stroke:#333,stroke-width:2px
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px
    classDef api fill:#afa,stroke:#333,stroke-width:2px
    classDef core fill:#ff9,stroke:#333,stroke-width:2px
    classDef dynamic fill:#9cf,stroke:#333,stroke-width:2px
    classDef data fill:#fc9,stroke:#333,stroke-width:2px
    classDef realtime fill:#cfc,stroke:#333,stroke-width:2px
    classDef security fill:#fcc,stroke:#333,stroke-width:2px
    classDef implant fill:#cdf,stroke:#333,stroke-width:2px

    %% Click Events
    click WP "https://github.com/cobbr/covenant/tree/master/Covenant/Pages"
    click WC "https://github.com/cobbr/covenant/tree/master/Covenant/Components"
    click APICtrl "https://github.com/cobbr/covenant/tree/master/Covenant/Controllers/ApiControllers"
    click APIService "https://github.com/cobbr/covenant/tree/master/Covenant/API"
    click SignalR "https://github.com/cobbr/covenant/tree/master/Covenant/Hubs"
    click CS "https://github.com/cobbr/covenant/tree/master/Covenant/Core"
    click Compiler "https://github.com/cobbr/covenant/blob/master/Covenant/Core/Compiler.cs"
    click CST "https://github.com/cobbr/covenant/tree/master/Covenant/Data/Tasks/CSharp"
    click Data "https://github.com/cobbr/covenant/tree/master/Covenant/Data"
    click Sec "https://github.com/cobbr/covenant/blob/master/Covenant/Core/Encryption.cs"
    click GruntComp "https://github.com/cobbr/covenant/tree/master/Covenant/Components/Grunts"
    click GruntModel "https://github.com/cobbr/covenant/tree/master/Covenant/Models/Grunts"
```
