# silverhack/monkey365 architecture

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

- Interactive diagram: https://gitdiagram.com/silverhack/monkey365
- Repository: https://github.com/silverhack/monkey365

## Overview

1. **What this repo is**
   Monkey365 is a PowerShell security assessment module for Microsoft cloud estates. The primary execution path starts from `Invoke-Monkey365.ps1` / `monkey365.psm1`, then fans out into scanners for Azure, Microsoft Entra ID, and Microsoft 365 workloads.

2. **Top-level execution pipeline**
   The architecture is a scan pipeline: initialize runtime and auth settings, select the target services, collect raw tenant/subscription data, normalize it into internal objects, evaluate security rules, and finally export or report the findings. The main orchestration lives under `core/scan`, `core/tasks`, `core/init`, and `core/output`.

3. **Service boundaries**
   The repo is organized by cloud boundary:
   - `core/api/azure` and `collectors/azure`
   - `core/api/entraid` and `collectors/entraid`
   - `core/api/m365` and `collectors/microsoft365`
   
   Each boundary has its own authentication helpers, API wrappers, service-specific collectors, and object builders. That separation is important: Azure Resource Manager, Microsoft Graph, Exchange Online, SharePoint, Teams, and Purview are treated as distinct subsystems.

4. **Authentication and connection layer**
   Authentication is centralized in `core/api/auth` and backed by `core/modules/monkeymsal`. There are separate connection entry points for Azure, Microsoft Graph, Exchange, SharePoint, generic apps, and Microsoft 365. This layer is responsible for acquiring and shaping access tokens and for handling environment-specific endpoints such as Azure Public, China, and US Government clouds.

5. **Collector model**
   The `collectors/` tree contains the service-specific collection entry points. These collectors are essentially adapters that know what to fetch from each platform area and how to invoke the lower-level API helpers. The breadth of collectors shows the tool’s scope: VM, storage, Key Vault, networking, Defender, Conditional Access, groups, applications, Exchange policies, SharePoint sites, Teams policies, Fabric, and more.

6. **API and normalization layer**
   Under `core/api`, the repo holds reusable API clients and helpers for each backend. These helpers retrieve raw objects from provider APIs and transform them into internal PowerShell objects using the `utils/New-Monkey*Object.ps1` files. This normalization boundary is a key architectural feature: collectors should work with a consistent object model rather than raw service responses.

7. **Runspace and parallel execution**
   `core/modules/monkeyjob` plus `core/runspace_init` provide the concurrency model. The repository uses runspace pools and background jobs to collect data in parallel and manage long-running tasks. This affects diagramming because collection is not a single-threaded linear script; it is a job-dispatched scan engine.

8. **Rules engine and compliance checks**
   Security findings are driven by JSON rule definitions in `rules/`. Rule sets such as CIS for Azure, Azure Database Services, and Microsoft 365 are defined separately from the code. `core/modules/monkeyruleset` parses those rules, builds queries, and evaluates datasets to produce findings. In the architecture, this is the policy evaluation boundary: collected data enters the rules engine, and findings come out.

9. **Output, findings, and report generation**
   `core/modules/monkeyoutput`, `core/output`, and `core/modules/monkeyhtml` handle result shaping and presentation. Outputs include JSON, CSV, XML/CLIXML, zipped artifacts, OCSF-formatted objects, and HTML reports. The HTML reporting stack depends on `psmarkdig` and chart/card helpers to build the final dashboard-style report.

10. **Logging and notifications**
    Logging is a separate subsystem in `core/modules/monkeylogger`. It supports file output plus webhook-style integrations for Slack and Teams. This means operational telemetry is emitted independently of scan results, and can be wired to different sinks without changing the collectors.

11. **Shared utilities and metadata**
    `core/modules/monkeyutils`, `core/modules/monkeycloudutils`, and `core/utils` contain shared helpers for URL handling, object conversion, tenant and SKU discovery, licensing, environment detection, and configuration. These modules act as cross-cutting support libraries used by auth, collectors, rules, and output.

12. **External services the architecture depends on**
    The tool integrates materially with Microsoft cloud APIs: Azure Resource Manager, Microsoft Graph, Exchange Online APIs, SharePoint CSOM/REST, Teams, Purview, Fabric/Power BI, and Azure/M365 admin portals. The repository is therefore best diagrammed as a local PowerShell orchestration layer over multiple Microsoft service backends, not as a traditional web application.

13. **Packaging, automation, and delivery**
    The repo is packaged as a PowerShell module and also supports Docker execution via `docker/`. CI/CD in `.github/workflows` covers tests, ScriptAnalyzer, documentation publishing, and PowerShell Gallery publishing. Documentation is generated with MkDocs under `docs/`, which mirrors the module’s scan/auth/export concepts.

Main entry points: [`collectors/azure`](https://github.com/silverhack/monkey365/tree/main/collectors/azure) (Azure collectors), [`collectors/entraid`](https://github.com/silverhack/monkey365/tree/main/collectors/entraid) (Entra collectors), [`collectors/microsoft365`](https://github.com/silverhack/monkey365/tree/main/collectors/microsoft365) (M365 collectors), [`core/modules/monkeyruleset`](https://github.com/silverhack/monkey365/tree/main/core/modules/monkeyruleset) (Rules engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & packaging"]
  node_invoke["Invoke-Monkey365<br/>module entry"]
  node_module["monkey365<br/>module surface<br/>[monkey365.psm1]"]
end

subgraph group_engine["Scan engine"]
  node_scan["Scan runners<br/>orchestration"]
  node_tasks["Scan tasks<br/>lifecycle"]
  node_runspace["Runspaces<br/>concurrency"]
  node_collector_core["Collector core<br/>selection"]
end

subgraph group_auth["Auth & connections"]
  node_auth_core["Auth core<br/>connection layer"]
  node_msal["MSAL<br/>token engine"]
end

subgraph group_collectors["Collectors"]
  node_azure_collectors["Azure collectors<br/>azure boundary"]
  node_entra_collectors["Entra collectors<br/>entra boundary"]
  node_m365_collectors["M365 collectors<br/>m365 boundary"]
end

subgraph group_api["API & normalization"]
  node_azure_api["Azure API<br/>ARM helpers"]
  node_entra_api["Entra API<br/>Graph helpers"]
  node_m365_api["M365 API<br/>service helpers"]
end

subgraph group_policy["Rules & findings"]
  node_rulesets["Rule sets<br/>json rules"]
  node_rules_engine["Rules engine<br/>evaluation"]
end

subgraph group_output["Output & reporting"]
  node_output_core["Output core<br/>export pipeline"]
  node_output_mod["Output module<br/>serialization"]
  node_html["HTML reports<br/>presentation"]
  node_logger["Logger<br/>telemetry"]
end

subgraph group_shared["Shared modules"]
  node_utils["Shared utils<br/>helpers"]
  node_cloudutils["Cloud utils<br/>cloud helpers"]
end

subgraph group_delivery["Delivery"]
  node_docs["Docs & CI<br/>delivery"]
end

node_invoke -->|"loads"| node_module
node_module -->|"starts"| node_scan
node_module -->|"initializes"| node_tasks
node_tasks -->|"dispatches"| node_runspace
node_tasks -->|"selects"| node_collector_core
node_collector_core -->|"routes"| node_azure_collectors
node_collector_core -->|"routes"| node_entra_collectors
node_collector_core -->|"routes"| node_m365_collectors
node_scan -->|"invokes"| node_azure_collectors
node_scan -->|"invokes"| node_entra_collectors
node_scan -->|"invokes"| node_m365_collectors
node_auth_core -->|"uses"| node_msal
node_azure_collectors -->|"calls"| node_azure_api
node_entra_collectors -->|"calls"| node_entra_api
node_m365_collectors -->|"calls"| node_m365_api
node_azure_api -->|"normalizes"| node_utils
node_entra_api -->|"normalizes"| node_utils
node_m365_api -->|"normalizes"| node_utils
node_azure_collectors -.->|"feeds"| node_rules_engine
node_entra_collectors -.->|"feeds"| node_rules_engine
node_m365_collectors -.->|"feeds"| node_rules_engine
node_rulesets -->|"defines"| node_rules_engine
node_rules_engine -->|"produces"| node_output_mod
node_output_mod -->|"exports"| node_output_core
node_output_core -->|"renders"| node_html
node_output_core -->|"emits"| node_logger
node_cloudutils -->|"supports"| node_auth_core
node_cloudutils -.->|"supports"| node_azure_collectors
node_cloudutils -.->|"supports"| node_entra_collectors
node_cloudutils -.->|"supports"| node_m365_collectors
node_docs -.->|"documents"| node_module
node_docs -.->|"documents"| node_output_core

click node_invoke "https://github.com/silverhack/monkey365/blob/main/Invoke-Monkey365.ps1"
click node_module "https://github.com/silverhack/monkey365/blob/main/monkey365.psm1"
click node_scan "https://github.com/silverhack/monkey365/tree/main/core/scan"
click node_tasks "https://github.com/silverhack/monkey365/tree/main/core/tasks"
click node_runspace "https://github.com/silverhack/monkey365/tree/main/core/runspace_init"
click node_collector_core "https://github.com/silverhack/monkey365/tree/main/core/collector"
click node_auth_core "https://github.com/silverhack/monkey365/tree/main/core/api/auth"
click node_msal "https://github.com/silverhack/monkey365/tree/main/core/modules/monkeymsal"
click node_azure_collectors "https://github.com/silverhack/monkey365/tree/main/collectors/azure"
click node_entra_collectors "https://github.com/silverhack/monkey365/tree/main/collectors/entraid"
click node_m365_collectors "https://github.com/silverhack/monkey365/tree/main/collectors/microsoft365"
click node_azure_api "https://github.com/silverhack/monkey365/tree/main/core/api/azure"
click node_entra_api "https://github.com/silverhack/monkey365/tree/main/core/api/entraid"
click node_m365_api "https://github.com/silverhack/monkey365/tree/main/core/api/m365"
click node_rulesets "https://github.com/silverhack/monkey365/tree/main/rules/rulesets"
click node_rules_engine "https://github.com/silverhack/monkey365/tree/main/core/modules/monkeyruleset"
click node_output_core "https://github.com/silverhack/monkey365/tree/main/core/output"
click node_output_mod "https://github.com/silverhack/monkey365/tree/main/core/modules/monkeyoutput"
click node_html "https://github.com/silverhack/monkey365/tree/main/core/modules/monkeyhtml"
click node_logger "https://github.com/silverhack/monkey365/tree/main/core/modules/monkeylogger"
click node_utils "https://github.com/silverhack/monkey365/tree/main/core/modules/monkeyutils"
click node_cloudutils "https://github.com/silverhack/monkey365/tree/main/core/modules/monkeycloudutils"
click node_docs "https://github.com/silverhack/monkey365/tree/main/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_invoke,node_module,node_output_core,node_output_mod,node_html,node_logger toneBlue
class node_scan,node_tasks,node_runspace,node_collector_core,node_utils,node_cloudutils toneAmber
class node_auth_core,node_msal,node_docs toneMint
class node_azure_collectors,node_entra_collectors,node_m365_collectors toneRose
class node_azure_api,node_entra_api,node_m365_api toneIndigo
class node_rulesets,node_rules_engine toneTeal
```

## Components

### Entry & packaging

PowerShell module entrypoints and packaging surfaces.

- [Invoke-Monkey365](https://github.com/silverhack/monkey365/blob/main/Invoke-Monkey365.ps1): module entry · Primary scan entry script. · `Invoke-Monkey365.ps1`
- [monkey365](https://github.com/silverhack/monkey365/blob/main/monkey365.psm1): module surface · PowerShell module manifest and exported entrypoints. · `monkey365.psm1`

### Scan engine

Initialization, orchestration, runspaces, and collector dispatch.

- [Scan runners](https://github.com/silverhack/monkey365/tree/main/core/scan): orchestration · Azure, Entra ID, and Microsoft 365 scan dispatchers. · `core/scan`
- [Scan tasks](https://github.com/silverhack/monkey365/tree/main/core/tasks): lifecycle · Scan initialization and scanner coordination. · `core/tasks`
- [Runspaces](https://github.com/silverhack/monkey365/tree/main/core/runspace_init): concurrency · Runspace pool and background job execution. · `core/runspace_init`
- [Collector core](https://github.com/silverhack/monkey365/tree/main/core/collector): selection · Collector discovery, metadata, and service selection. · `core/collector`

### Auth & connections

Token acquisition and endpoint connection helpers.

- [Auth core](https://github.com/silverhack/monkey365/tree/main/core/api/auth): connection layer · Central authentication and service connection orchestration. · `core/api/auth`
- [MSAL](https://github.com/silverhack/monkey365/tree/main/core/modules/monkeymsal): token engine · Shared token acquisition implementation. · `core/modules/monkeymsal`

### Collectors

Service-specific collection adapters by cloud boundary.

- [Azure collectors](https://github.com/silverhack/monkey365/tree/main/collectors/azure): azure boundary · Azure Resource Manager and security collection adapters. · `collectors/azure`
- [Entra collectors](https://github.com/silverhack/monkey365/tree/main/collectors/entraid): entra boundary · Microsoft Entra ID and portal collection adapters. · `collectors/entraid`
- [M365 collectors](https://github.com/silverhack/monkey365/tree/main/collectors/microsoft365): m365 boundary · Exchange, SharePoint, Teams, Purview, Fabric, and admin portal collectors. · `collectors/microsoft365`

### API & normalization

Reusable API clients and object builders.

- [Azure API](https://github.com/silverhack/monkey365/tree/main/core/api/azure): ARM helpers · Azure API helpers and resource object builders. · `core/api/azure`
- [Entra API](https://github.com/silverhack/monkey365/tree/main/core/api/entraid): Graph helpers · Microsoft Graph, portal, and PIM helpers. · `core/api/entraid`
- [M365 API](https://github.com/silverhack/monkey365/tree/main/core/api/m365): service helpers · Exchange Online, SharePoint, Teams, Purview, Fabric, and admin portal helpers. · `core/api/m365`

### Rules & findings

Rule definitions and evaluation.

- [Rule sets](https://github.com/silverhack/monkey365/tree/main/rules/rulesets): json rules · CIS and service-specific rule definitions. · `rules/rulesets`
- [Rules engine](https://github.com/silverhack/monkey365/tree/main/core/modules/monkeyruleset): evaluation · Parses rulesets, builds queries, and evaluates datasets into findings. · `core/modules/monkeyruleset`

### Output & reporting

Export, report generation, and telemetry.

- [Output core](https://github.com/silverhack/monkey365/tree/main/core/output): export pipeline · Shapes findings and writes export artifacts. · `core/output`
- [Output module](https://github.com/silverhack/monkey365/tree/main/core/modules/monkeyoutput): serialization · Generic output conversion and OCSF mapping. · `core/modules/monkeyoutput`
- [HTML reports](https://github.com/silverhack/monkey365/tree/main/core/modules/monkeyhtml): presentation · Dashboard-style report generation. · `core/modules/monkeyhtml`
- [Logger](https://github.com/silverhack/monkey365/tree/main/core/modules/monkeylogger): telemetry · File and webhook logging to Slack and Teams. · `core/modules/monkeylogger`

### Shared modules

Cross-cutting utilities and support libraries.

- [Shared utils](https://github.com/silverhack/monkey365/tree/main/core/modules/monkeyutils): helpers · Common conversion, URL, tenant, and environment helpers. · `core/modules/monkeyutils`
- [Cloud utils](https://github.com/silverhack/monkey365/tree/main/core/modules/monkeycloudutils): cloud helpers · Tenant, environment, and service URL helpers. · `core/modules/monkeycloudutils`

### Delivery

Docs, Docker, and CI/CD automation.

- [Docs & CI](https://github.com/silverhack/monkey365/tree/main/docs): delivery · MkDocs site, GitHub workflows, and Docker packaging. · `docs`

## Connections

- Invoke-Monkey365 → monkey365: loads · Entry script is exposed through the module surface.
- monkey365 → Scan runners: starts · Module invokes cloud scan runners.
- monkey365 → Scan tasks: initializes · Bootstraps scan lifecycle and orchestration.
- Scan tasks → Runspaces: dispatches · Scans are parallelized through runspaces and jobs.
- Scan tasks → Collector core: selects · Scan initialization chooses supported collectors.
- Collector core → Azure collectors: routes · Collector selection fans out to Azure boundary.
- Collector core → Entra collectors: routes · Collector selection fans out to Entra boundary.
- Collector core → M365 collectors: routes · Collector selection fans out to Microsoft 365 boundary.
- Scan runners → Azure collectors: invokes · Azure scan runner triggers Azure collectors.
- Scan runners → Entra collectors: invokes · Entra scan runner triggers Entra collectors.
- Scan runners → M365 collectors: invokes · M365 scan runner triggers Microsoft 365 collectors.
- Auth core → MSAL: uses · Connection helpers rely on shared MSAL token acquisition.
- Azure collectors → Azure API: calls · Azure collectors use ARM/service helpers and normalization.
- Entra collectors → Entra API: calls · Entra collectors use Graph and portal helpers.
- M365 collectors → M365 API: calls · M365 collectors use service-specific API helpers.
- Azure API → Shared utils: normalizes · Azure API layer emits internal PowerShell objects and uses shared helpers.
- Entra API → Shared utils: normalizes · Entra API layer emits internal PowerShell objects and uses shared helpers.
- M365 API → Shared utils: normalizes · M365 API layer emits internal PowerShell objects and uses shared helpers.
- Azure collectors → Rules engine: feeds · Collected Azure datasets become rule-evaluation input.
- Entra collectors → Rules engine: feeds · Collected Entra datasets become rule-evaluation input.
- M365 collectors → Rules engine: feeds · Collected M365 datasets become rule-evaluation input.
- Rule sets → Rules engine: defines · JSON rulesets drive rule loading and matching.
- Rules engine → Output module: produces · Rule evaluation produces normalized findings objects.
- Output module → Output core: exports · Output module is consumed by export pipeline.
- Output core → HTML reports: renders · HTML reporting is part of the final presentation stack.
- Output core → Logger: emits · Export and scan lifecycle emit operational telemetry.
- Cloud utils → Auth core: supports · Cloud/environment helpers support authentication endpoints and tenant resolution.
- Cloud utils → Azure collectors: supports · Cloud helper functions are reused by Azure collection paths.
- Cloud utils → Entra collectors: supports · Cloud helper functions are reused by Entra collection paths.
- Cloud utils → M365 collectors: supports · Cloud helper functions are reused by Microsoft 365 collection paths.
- Docs & CI → monkey365: documents · Documentation and CI/CD describe and package the module.
- Docs & CI → Output core: documents · Docs cover export and reporting flows.
