How silverhack/monkey365 works
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: azure Azure collectors · entraid Entra collectors · microsoft365 M365 collectors · monkeyruleset Rules engine
Components 23
Entry & packaging
PowerShell module entrypoints and packaging surfaces.
- Invoke-Monkey365 · Primary scan entry script.
Invoke-Monkey365.ps1 - monkey365 · PowerShell module manifest and exported entrypoints.
monkey365.psm1
Scan engine
Initialization, orchestration, runspaces, and collector dispatch.
- Scan runners · Azure, Entra ID, and Microsoft 365 scan dispatchers.
core/scan - Scan tasks · Scan initialization and scanner coordination.
core/tasks - Runspaces · Runspace pool and background job execution.
core/runspace_init - Collector core · Collector discovery, metadata, and service selection.
core/collector
Auth & connections
Token acquisition and endpoint connection helpers.
Collectors
Service-specific collection adapters by cloud boundary.
- Azure collectors · Azure Resource Manager and security collection adapters.
collectors/azure - Entra collectors · Microsoft Entra ID and portal collection adapters.
collectors/entraid - M365 collectors · Exchange, SharePoint, Teams, Purview, Fabric, and admin portal collectors.
collectors/microsoft365
API & normalization
Reusable API clients and object builders.
Rules & findings
Rule definitions and evaluation.
- Rule sets · CIS and service-specific rule definitions.
rules/rulesets - Rules engine · Parses rulesets, builds queries, and evaluates datasets into findings.
core/modules/monkeyruleset
Output & reporting
Export, report generation, and telemetry.
- Output core · Shapes findings and writes export artifacts.
core/output - Output module · Generic output conversion and OCSF mapping.
core/modules/monkeyoutput - HTML reports · Dashboard-style report generation.
core/modules/monkeyhtml - Logger · File and webhook logging to Slack and Teams.
core/modules/monkeylogger
Shared modules
Cross-cutting utilities and support libraries.
- Shared utils · Common conversion, URL, tenant, and environment helpers.
core/modules/monkeyutils - Cloud utils · Tenant, environment, and service URL helpers.
core/modules/monkeycloudutils
Delivery
Docs, Docker, and CI/CD automation.
- Docs & CI · MkDocs site, GitHub workflows, and Docker packaging.
docs
Connections 32
- 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.