# bishopfox/cloudfox architecture

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

- Interactive diagram: https://gitdiagram.com/bishopfox/cloudfox
- Repository: https://github.com/bishopfox/cloudfox

## Overview

##### Main components
- Command Line Interface (CLI) Layer – Represented by files in the “cli” directory and the main.go file. This is the entry point that parses user input and delegates actions.
- Cloud Provider Modules – Separate major modules exist for each cloud provider:
– AWS – Found in the “aws” directory (including extensive sub-packages like aws/sdk, aws/graph, tests, and various command implementations).
– Azure – Handled in the “azure” directory (with inventory, RBAC, storage, and VM enumeration).
– GCP – Located in the “gcp” folder (commands and services for its multiple cloud operations).
- Shared & Internal Libraries – Items in “globals” and “internal” provide common functionality such as logging, utility functions, caching, output formatting, and internal policies.
- CI/CD and Testing – The “.github” folder (with workflows) indicates established processes for continuous integration, and the presence of test files in virtually every module shows a test-driven approach.
- Miscellaneous Assets – The “misc” directory contains supporting data (e.g., a sample AWS policy) used by the system.

##### Relationships and interactions
- The CLI layer (main.go, cli/aws.go, cli/azure.go, cli/gcp.go) directs control to the respective provider modules based on the user’s input.
- Within each provider module, commands invoke various sub-packages and services. For example, the AWS module calls functions from its “sdk” subdirectory (which wraps external AWS APIs) and uses graph building (found under aws/graph) to analyze relationships.
- Shared components (in “globals” and “internal”) are used across modules to handle tasks like logging, output formatting, and common utility operations.
- External interactions: Each provider module (via its SDK wrappers) communicates with the external cloud provider APIs (AWS, Azure, GCP).
- The testing directories and test-data folders are used to simulate cloud responses, confirming the modular design and verifying behavior.

##### Important architectural patterns
- Modularity – The design clearly decomposes the system into provider-specific modules, allowing each cloud provider’s implementation to be developed and enhanced independently.
- Layered Architecture – There’s a clear separation between the CLI/input handling, business logic (the enumeration commands per provider), and external API integrations.
- SDK Wrapper Pattern – AWS and other providers have dedicated “sdk” packages that encapsulate API communications (with corresponding mocks) to facilitate testing and easy future modifications.
- Use of common internal and global libraries for repeating concerns such as logging, output management, and utility functions.

##### Relevant technologies and frameworks
- Programming Language: Go (with its package/module structure clearly visible)
- CI/CD: GitHub workflows in the “.github/workflows” directory, indicating continuous integration and automated testing.
- Testing: Built-in testing via separate test files (e.g., *_test.go) and test-data directories to simulate API responses.
- External Integration: AWS CLI, Azure CLI, and GCP authentication for cloud API access, as described in the README.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% CLI Layer
    subgraph "CLI Layer"
        mainGo["CLI Entry: main.go"]:::cli
        cliDir["CLI Files: cli/"]:::cli
    end

    %% Provider Modules
    subgraph "Provider Modules"
        %% AWS Module
        subgraph "AWS Module"
            awsModule["AWS Module"]:::module
            awsSdk["SDK Wrapper: aws/sdk/"]:::module
            awsGraph["Graph Engine: aws/graph/"]:::module
            awsTest["Test Data: aws/test-data/"]:::module
            awsModule --> awsSdk
            awsModule --> awsGraph
            awsModule --> awsTest
            awsModule -->|"calls"| awsExt["AWS External API"]:::external
        end

        %% Azure Module
        subgraph "Azure Module"
            azureModule["Azure Module"]:::module
            azureModule -->|"calls"| azureExt["Azure External API"]:::external
        end

        %% GCP Module
        subgraph "GCP Module"
            gcpModule["GCP Module"]:::module
            gcpCommands["Commands: gcp/commands/"]:::module
            gcpServices["Services: gcp/services/"]:::module
            gcpModule --> gcpCommands
            gcpModule --> gcpServices
            gcpModule -->|"calls"| gcpExt["GCP External API"]:::external
        end
    end

    %% Shared & Internal Libraries
    subgraph "Shared & Internal Libraries"
        globals["Globals"]:::shared
        internal["Internal Utilities"]:::shared
    end

    %% CI/CD & Testing
    ciCd["CI/CD Pipeline & Testing (.github/)"]:::cicd

    %% Miscellaneous Assets
    miscAssets["Misc Assets: AWS Policy"]:::misc

    %% External Cloud APIs (Grouped for clarity)
    subgraph "External Cloud APIs"
        awsExt
        azureExt
        gcpExt
    end

    %% Connections from CLI to Provider Modules
    mainGo -->|"dispatches"| awsModule
    mainGo -->|"dispatches"| azureModule
    mainGo -->|"dispatches"| gcpModule
    cliDir  -->|"routes"| awsModule
    cliDir  -->|"routes"| azureModule
    cliDir  -->|"routes"| gcpModule

    %% Providers use shared libraries
    awsModule -->|"uses"| globals
    awsModule -->|"uses"| internal
    azureModule -->|"uses"| globals
    azureModule -->|"uses"| internal
    gcpModule -->|"uses"| globals
    gcpModule -->|"uses"| internal

    %% Modules integrated with CI/CD
    awsModule -->|"tested_by"| ciCd
    azureModule -->|"tested_by"| ciCd
    gcpModule -->|"tested_by"| ciCd
    mainGo -->|"tested_by"| ciCd
    cliDir -->|"tested_by"| ciCd

    %% Misc Assets used by AWS Module
    awsModule -->|"refers_to"| miscAssets

    %% Click Events
    click mainGo "https://github.com/bishopfox/cloudfox/blob/main/main.go"
    click cliDir "https://github.com/bishopfox/cloudfox/tree/main/cli/"
    click awsModule "https://github.com/bishopfox/cloudfox/tree/main/aws/"
    click awsSdk "https://github.com/bishopfox/cloudfox/tree/main/aws/sdk/"
    click awsGraph "https://github.com/bishopfox/cloudfox/tree/main/aws/graph/"
    click awsTest "https://github.com/bishopfox/cloudfox/tree/main/aws/test-data/"
    click azureModule "https://github.com/bishopfox/cloudfox/tree/main/azure/"
    click gcpModule "https://github.com/bishopfox/cloudfox/tree/main/gcp/"
    click gcpCommands "https://github.com/bishopfox/cloudfox/tree/main/gcp/commands/"
    click gcpServices "https://github.com/bishopfox/cloudfox/tree/main/gcp/services/"
    click globals "https://github.com/bishopfox/cloudfox/tree/main/globals/"
    click internal "https://github.com/bishopfox/cloudfox/tree/main/internal/"
    click ciCd "https://github.com/bishopfox/cloudfox/tree/main/.github/"
    click miscAssets "https://github.com/bishopfox/cloudfox/tree/main/misc/aws/"

    %% Styles
    classDef cli fill:#f9c74f,stroke:#000,stroke-width:1px;
    classDef module fill:#90be6d,stroke:#000,stroke-width:1px;
    classDef shared fill:#f9844a,stroke:#000,stroke-width:1px;
    classDef cicd fill:#577590,stroke:#fff,stroke-width:1px;
    classDef external fill:#277da1,stroke:#fff,stroke-width:1px;
    classDef misc fill:#f94144,stroke:#000,stroke-width:1px;
```
