Add docs

docs/about.md

@@ -0,0 +1,15 @@
+---
+author: Juan Garrido
+---
+
+# Monkey365
+![](assets/images/monkey365.png)
+
+Monkey365 is an Open Source security tool that can be used to easily conduct not only Microsoft 365, but also Azure subscriptions and Azure Active Directory security configuration reviews without the significant overhead of learning tool APIs or complex admin panels from the start.
+
+Monkey365 has been designed to tackle these difficulties and get results fast and without any requirements. The results will be visualised in a simplified HTML report to quickly identify potential issues. As such, security consultants will be able to effectively address issues from a 
+single vulnerability report.
+
+![](../assets/images/htmlreport.png)
+
+To help with this effort, Monkey365 also provides several ways to identify security gaps in the desired tenant setup and configuration. Monkey365 provides valuable recommendations on how to best configure those settings to get the most out of your Microsoft 365 tenant or Azure subscription.

docs/assets/css/extra.css

@@ -0,0 +1,14 @@
+.container {
+    font-family: arial;
+    font-size: 24px;
+    margin: 25px;
+    width: 350px;
+    height: 200px;
+    outline: dashed 1px black;
+  }
+
+  .center {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }

docs/authentication.md

@@ -0,0 +1,26 @@
+---
+author: Juan Garrido
+---
+Monkey365 offers many ways to connect to both Azure and Microsoft 365 environments. This section covers the authentication process against Azure or Microsoft 365, as well as the supported authentication options, including:
+
+* Interactive browser authentication
+* Authentication with a username and password
+* Device Code Authentication
+* Client Credential Authentication
+
+## Interactive browser authentication
+
+Interactive browser authentication enables the monkey 365 PowerShell module for all operations allowed by the interactive login credentials. Please, note that if you are using a user with owner or administrator permissions within the subscription in scope, the monkey365 tool will inherent these permissions to all resources in that subscription without having to assign any specific permissions. Please, see the [permissions](permissions.md) for further details.
+
+## Resource Owner Password Credentials
+
+The Microsoft identity platform supports the OAuth 2.0 Resource Owner Password Credentials (ROPC) grant, which allows an application to sign in the user by directly handling their password. In this flow, client identification (e.g. user's email address) and user's credentials is sent to the identity server, and then a token is received.
+
+## Device code authentication
+
+Interactive authentication with Azure Active Directory requires a web browser. However, in operating systems that do not provide a Web browser, such as containers, command line tools or non-gui systems, Device code flow lets the user use another computer to sign-in interactively. The tokens will be obtained through a two-step process.
+
+## Client credential authentication
+
+This type of grant is commonly used for machine-to-machine interactions that must run in the background, such as daemons, or service accounts. In this case, Azure AD authenticates and authorizes the app rather than a user. During this step, the client has to authenticate itself to Azure AD. The Microsoft identity platform allows the confidential client to authenticate using a shared secret, certificate or federated credential.
+

docs/basic-usage.md

@@ -0,0 +1,72 @@
+---
+author: Juan Garrido
+---
+
+The following command will provide the list of available command line options:
+``` powershell
+Get-Help Invoke-Monkey365
+```
+
+To get a list of examples use:
+``` powershell
+Get-Help Invoke-Monkey365 -Examples
+```
+
+To get a list of all options and examples with detailed info use:
+``` powershell
+Get-Help Invoke-Monkey365 -Detailed
+```
+
+This example retrieves information from Azure AD and SharePoint Online and then print results. If credentials are not supplied, Monkey365 will prompt for credentials.
+``` powershell
+$param = @{
+    Instance = 'Office365';
+    Analysis = 'SharePointOnline';
+    PromptBehavior = 'SelectAccount';
+    IncludeAzureActiveDirectory = $true;
+    ExportTo = 'PRINT';
+}
+$assets = Invoke-Monkey365 @param
+```
+
+This example retrieves information from specific Azure subscription and Tenant and prints results to a local variable. If credentials are not supplied, Monkey365 will prompt for credentials.
+``` powershell
+$param = @{
+    Instance = 'Azure';
+    Analysis = 'All';
+    PromptBehavior = 'SelectAccount';
+    subscriptions = '00000000-0000-0000-0000-000000000000';
+    TenantID = '00000000-0000-0000-0000-000000000000';
+    ExportTo = 'PRINT';
+}
+$assets = Invoke-Monkey365 @param
+```
+
+This example retrieves information from specific Azure subscription and Tenant and will export data driven to CSV, JSON, HTML, XML and Excel format into monkey-reports folder. The script will connect to Azure using the client credential flow.
+``` powershell
+$param = @{
+    ClientId = '00000000-0000-0000-0000-000000000000';
+    ClientSecret = ("MySuperClientSecret" | ConvertTo-SecureString -AsPlainText -Force)
+    Instance = 'Azure';
+    Analysis = 'All';
+    subscriptions = '00000000-0000-0000-0000-000000000000';
+    TenantID = '00000000-0000-0000-0000-000000000000';
+    ExportTo = 'CLIXML,EXCEL,CSV,JSON,HTML';
+}
+$assets = Invoke-Monkey365 @param
+```
+
+This example retrieves information from specific Azure subscription and Tenant and will export data driven to CSV, JSON, HTML, XML and Excel format into monkey-reports folder. The script will connect to Azure using the client credential flow.
+``` powershell
+$param = @{
+    ClientId = '00000000-0000-0000-0000-000000000000';
+    certificate = 'C:\monkey365\testapp.pfx';
+    CertFilePassword = ("MySuperCertSecret" | ConvertTo-SecureString -AsPlainText -Force);
+    Instance = 'Office365';
+    Analysis = 'SharePointOnline';
+    subscriptions = '00000000-0000-0000-0000-000000000000';
+    TenantID = '00000000-0000-0000-0000-000000000000';
+    ExportTo = 'CLIXML,EXCEL,CSV,JSON,HTML';
+}
+$assets = Invoke-Monkey365 @param
+```

docs/configuration/azure-options.md

@@ -0,0 +1,59 @@
+---
+author: Juan Garrido
+---
+
+This section covers the supported options to help customize and automate scans for Azure environments. General options include:
+
+ ```--Analysis```
+
+Select the Azure resources used to gather data. Valid values are:
+
+| Resource        | Value         |
+| --------------- |:-------------|
+| Databases       | Retrieves information from Azure databases, such as Azure SQL, Azure PostgreSQL or MariaDB |
+| virtualmachines | Retrieves information from Azure virtual machines |
+| SecurityAlerts | Retrieves information from security alers      |
+| StorageAccounts | Retrieves information from storage accounts      |
+| SecurityBaseline | Retrieves information from virtual machine's security baseline      |
+| MissingPatches | Retrieves information from potentially virtual machine's missing patches      |
+| SecurityPolicies | Retrieves information from security policy      |
+| AppServices | Retrieves information from App Services      |
+| KeyVaults | Retrieves information from Azure KeyVaults      |
+| roleassignments | Retrieves information from Azure RBAC      |
+| SecurityContacts | Retrieves information from Security Contacts      |
+| All | Retrieves all metadata from Azure subscription      |
+
+## Subscriptions
+
+By default, Monkey365 will show the subscriptions to which the provided identity have access to. A user can select all the subscriptions to which the provided identity have access.
+
+![](../assets/images/subscription.png)
+
+
+The ```-subscriptions``` option can be used to scan a number of subscriptions in one execution.
+
+``` powershell
+$param = @{
+    Instance = 'Azure';
+    Analysis = 'All';
+    PromptBehavior = 'SelectAccount';
+    subscriptions = '00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111';
+    TenantID = '00000000-0000-0000-0000-000000000000';
+    ExportTo = 'PRINT';
+}
+$assets = Invoke-Monkey365 @param
+```
+
+The ```-all_subscriptions``` option can be used to scan all the subscriptions.
+
+``` powershell
+$param = @{
+    Instance = 'Azure';
+    Analysis = 'All';
+    PromptBehavior = 'SelectAccount';
+    all_subscriptions = $true;
+    TenantID = '00000000-0000-0000-0000-000000000000';
+    ExportTo = 'PRINT';
+}
+$assets = Invoke-Monkey365 @param
+```

docs/configuration/configuration-file.md

@@ -0,0 +1,42 @@
+---
+author: Juan Garrido
+---
+
+The Monkey365 configuration file contains settings that are used for managing CLI behavior. The configuration file itself is located at ```$monkey365_DIR/config/monkey_365.config```.
+
+Configuration file is written in the JSON file format. This file format is followed by a list of key-value entries. Also, Boolean is case-insensitive, and is represented by ```True``` (Enabled/must check) and ```False``` (Disabled/not check).
+
+The following is an example of a configuration file that sets up Monkey365 to use the ```1.6``` version of the Azure AD API but is also setting the ```dumpAdUsersWithInternalGraphAPI``` key to ```True```. With this change, Monkey365 will use the internal (1.6-internal) API version to extract information regarding Azure AD users:
+
+```json
+"azuread": {
+    "usemsalAuth": "true",
+    "userFilters": ["*"],
+    "DirectoryRolesFilter": ["*"],
+    "GroupFilter": ["*"],
+    "AuditLogDaysAgo": "-7",
+    "GetManagedApplicationsByPrincipalId": "true",
+    "GetUserDetails": "true",
+    "GetGroupMembers": "true",
+    "useAzurePortalAPI": "true",
+    "dumpAdUsersWithInternalGraphAPI": "true",
+    "api_version": "1.6",
+    "internal_api_version": "1.61-internal",
+    "AuditLogFilter": [
+        "activityType",
+        "correlationId",
+        "tenantId",
+        "activityOperationType",
+        "activity",
+        "activityDate",
+        "actor",
+        "actorType",
+        "targetResourceType",
+        "targetobjectId,targetName",
+        "targetUserPrincipalName",
+        "ChangeAttribute",
+        "OldValue",
+        "NewValue"
+    ]
+}
+```

docs/configuration/general-options.md

@@ -0,0 +1,59 @@
+---
+author: Juan Garrido
+---
+
+Monkey365 supports many options to help customize and automate scans. General options include:
+
+```--Environment```
+
+It can be used to set the environment containing the Azure account. Valid values are:
+
+* AzureChina
+* AzureGermany
+* AzurePublic
+* AzureUSGovernment
+
+**Note**: Default value is ```AzurePublic```
+
+ ```--Instance```
+
+Specifies the cloud provider to use. Valid values are:
+
+* Azure
+* Office365
+
+ ```--TenantID```
+
+It can be used to force Monkey365 to sign in to a tenant
+
+```--ResolveTenantDomainName```
+
+It can be used to resolve the unique ID of the tenant name
+
+```--ResolveTenantUserName```
+
+It can be used to resolve the Tenant ID for a specific user
+
+```--IncludeAzureActiveDirectory```
+
+It can be used to get information from Azure Active Directory
+
+```--SaveProject```
+
+Saves project to a local folder (Default folder is monkey-reports)
+
+```--ImportJob```
+
+Import previously exported jobs
+
+```--PromptBehavior```
+
+Sets the behavior for authentication. Valid values are ```Always```, ```Auto```, ```Never```, ```RefreshSession``` and ```SelectAccount```
+
+```--ForceAuth```
+
+Force the prompt behavior and user will be prompted for credentials. <br /> Same as ```--PromptBehavior Always```
+
+```--RuleSet```
+
+Specifies the path to JSON rules file.

docs/configuration/microsoft365-options.md

@@ -0,0 +1,18 @@
+---
+author: Juan Garrido
+---
+
+This section covers the supported options to help customize and automate scans for Microsoft 365 environments. General options include:
+
+ ```--Analysis```
+
+Select the Microsoft 365 resources used to gather data. Valid values are:
+
+| Resource        | Value         |
+| --------------- |:-------------|
+| ExchangeOnline | Retrieves information from Exchange Online |
+| SharePointOnline | Retrieves information from SharePoint Online, including lists, users, groups, orphaned users, etc.. |
+| PurView | Retrieves information from Microsoft PurView |
+| MicrosoftTeams | Retrieves information from Microsoft Teams      |
+| IRM | Retrieves information regarding rights management in Microsoft 365      |
+| MicrosoftForms | Retrieves basic information from Microsoft Forms     |

docs/configuration/rate-limit.md

@@ -0,0 +1,28 @@
+---
+author: Juan Garrido
+---
+
+The Monkey365 tool runs with 2 threads by default. Additionally, Monkey365 handles rate limiting by implementing a ```MaxQueue``` value that configures the number of worker threads that are available for the tool. When the tool detects that the ```MaxQueue``` limit is reached, the ```Start-Sleep``` command will be used to delay requests for a fixed amount of time. This is often sufficient to complete a run.
+
+In addition to the default execution, the ```Threads``` option can be used to modify the default behavior.
+
+The following example will fetch data from specific Azure subscription and Tenant and then will export results to CSV. If credentials are not supplied, Monkey365 will prompt for credentials. In addition, the ```Threads``` flag is set to ```4```.
+
+``` powershell
+$param = @{
+    Instance = 'Azure';
+    Analysis = 'All';
+    PromptBehavior = 'SelectAccount';
+    subscriptions = '00000000-0000-0000-0000-000000000000';
+    TenantID = '00000000-0000-0000-0000-000000000000';
+    ExportTo = 'CSV';
+    Threads = 4;
+}
+$assets = Invoke-Monkey365 @param
+```
+
+Regarding Exchange Online, and since the maximum number of remote connections allowed is 5, Monkey365 will limit the remote connections to one open remote PowerShell connection, regardless of number of configured threads. This is often enough to complete all jobs.
+
+For information regarding connecting Exchange Online, please refer to the installation notes on Microsoft:
+
+<a href='https://docs.microsoft.com/en-us/powershell/exchange/connect-to-exchange-online-powershell?view=exchange-ps' target='_blank'>Connect to Exchange Online PowerShell</a>

docs/disclaimer.md

@@ -0,0 +1,16 @@
+---
+author: Juan Garrido
+---
+
+## Disclaimers, and the Azure Penetration testing policy
+
+- To the best of our knowledge Monkey365's plugins are compliant with the Azure Penetration testing policy, but as a modular tool, we cannot guarantee this will be the case in every situation. It is entirely your responsibility to ensure that you know such requirements and how you use Monkey365 is compliant with the Azure Penetration testing policy.
+
+- Although notifying Microsoft of pen testing activities is no longer required you must still comply with the <a href='https://www.microsoft.com/msrc/pentest-rules-of-engagement' target='_blank'>Microsoft Cloud Unified Penetration Testing Rules of Engagement</a>
+
+- As with any other security tool, it is your responsibility to get proper authorization before using Monkey365 outside of your tenant/subscription.
+
+- Please note that this PowerShell module was designed to help companies to make both Azure and Microsoft365 more secure and should never be used maliciously. 
+
+- Monkey365 is software that comes with absolutely no warranties, either implied or explicit. By using Monkey365, you take full responsibility with any action taken using this software.
+