diff --git a/docs/about.md b/docs/about.md new file mode 100644 index 00000000..198c9612 --- /dev/null +++ b/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. diff --git a/docs/assets/css/extra.css b/docs/assets/css/extra.css new file mode 100644 index 00000000..8b2b122e --- /dev/null +++ b/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; + } \ No newline at end of file diff --git a/docs/assets/images/MonkeyLogo.png b/docs/assets/images/MonkeyLogo.png new file mode 100644 index 00000000..e832810b Binary files /dev/null and b/docs/assets/images/MonkeyLogo.png differ diff --git a/docs/assets/images/NormalTable.png b/docs/assets/images/NormalTable.png new file mode 100644 index 00000000..bf153783 Binary files /dev/null and b/docs/assets/images/NormalTable.png differ diff --git a/docs/assets/images/directLinkButton.png b/docs/assets/images/directLinkButton.png new file mode 100644 index 00000000..c41a0d97 Binary files /dev/null and b/docs/assets/images/directLinkButton.png differ diff --git a/docs/assets/images/favicon.ico b/docs/assets/images/favicon.ico new file mode 100644 index 00000000..97a403cf Binary files /dev/null and b/docs/assets/images/favicon.ico differ diff --git a/docs/assets/images/htmlreport.png b/docs/assets/images/htmlreport.png new file mode 100644 index 00000000..ab0e90f8 Binary files /dev/null and b/docs/assets/images/htmlreport.png differ diff --git a/docs/assets/images/modalButton.png b/docs/assets/images/modalButton.png new file mode 100644 index 00000000..8b3ccc37 Binary files /dev/null and b/docs/assets/images/modalButton.png differ diff --git a/docs/assets/images/monkey365.png b/docs/assets/images/monkey365.png new file mode 100644 index 00000000..36a16136 Binary files /dev/null and b/docs/assets/images/monkey365.png differ diff --git a/docs/assets/images/subscription.png b/docs/assets/images/subscription.png new file mode 100644 index 00000000..b97b30bc Binary files /dev/null and b/docs/assets/images/subscription.png differ diff --git a/docs/assets/images/tableAsList.png b/docs/assets/images/tableAsList.png new file mode 100644 index 00000000..15bca5b8 Binary files /dev/null and b/docs/assets/images/tableAsList.png differ diff --git a/docs/authentication.md b/docs/authentication.md new file mode 100644 index 00000000..f40972a4 --- /dev/null +++ b/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. + diff --git a/docs/basic-usage.md b/docs/basic-usage.md new file mode 100644 index 00000000..7e6bf46b --- /dev/null +++ b/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 +``` \ No newline at end of file diff --git a/docs/configuration/azure-options.md b/docs/configuration/azure-options.md new file mode 100644 index 00000000..bcd2acaf --- /dev/null +++ b/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 +``` diff --git a/docs/configuration/configuration-file.md b/docs/configuration/configuration-file.md new file mode 100644 index 00000000..7d6839d4 --- /dev/null +++ b/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" + ] +} +``` diff --git a/docs/configuration/general-options.md b/docs/configuration/general-options.md new file mode 100644 index 00000000..45e1b6d1 --- /dev/null +++ b/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.
Same as ```--PromptBehavior Always``` + +```--RuleSet``` + +Specifies the path to JSON rules file. \ No newline at end of file diff --git a/docs/configuration/microsoft365-options.md b/docs/configuration/microsoft365-options.md new file mode 100644 index 00000000..fa124c62 --- /dev/null +++ b/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 | diff --git a/docs/configuration/rate-limit.md b/docs/configuration/rate-limit.md new file mode 100644 index 00000000..24434830 --- /dev/null +++ b/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: + +Connect to Exchange Online PowerShell \ No newline at end of file diff --git a/docs/disclaimer.md b/docs/disclaimer.md new file mode 100644 index 00000000..0ee95b1c --- /dev/null +++ b/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 Microsoft Cloud Unified Penetration Testing Rules of Engagement + +- 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. + diff --git a/docs/docker/docker.md b/docs/docker/docker.md new file mode 100644 index 00000000..d92327d6 --- /dev/null +++ b/docs/docker/docker.md @@ -0,0 +1,53 @@ +--- +author: Juan Garrido +--- + +# Overview + +The docker image is an Ubuntu for Linux and Windows Server Core for Windows that comes with all pre-requisite components required to run Monkey365. These are non-root container images. + +# Running the Container + +To run this image, use the ```build.ps1``` script located in the root folder: + +``` powershell +.\build.ps1 -Name monkey365 -version latest -Path .\docker\Dockerfile_linux +``` + +This will create a new Monkey365 Docker image based on Ubuntu for Linux. + +The following command can be used to create a Windows-based container: + +``` powershell +.\build.ps1 -Name monkey365 -version latest -Path .\docker\Dockerfile_windows +``` + +Once container is created, you can run monkey365 container using ```docker run -it monkey365``` + +# Supported environment variables + +The following environment variables are supported: + +* MONKEY_ENV_MONKEY_USER +* MONKEY_ENV_MONKEY_PASSWORD +* MONKEY_ENV_TENANT_ID +* MONKEY_ENV_SUBSCRIPTIONS +* MONKEY_ENV_ANALYSIS +* MONKEY_ENV_EXPORT_TO +* MONKEY_ENV_WRITELOG +* MONKEY_ENV_VERBOSE +* MONKEY_ENV_DEBUG + +You can also use the -e, --env, and --env-file flags to set simple environment variables in the container. + +``` bash +docker run -it --env-file monkey.env monkey365 pwsh "/home/monkey365/monkey365/monkey365.ps1" +``` + +In case you want to map a directory to a docker container directory, you can use the --volume flag, as shown below: + +``` bash +docker run -it --env-file monkey.env ` + -volume=C:\temp:/home/monkey365/monkey365/monkey-reports ` + monkey365 pwsh "/home/monkey365/monkey365/monkey365.ps1" +``` \ No newline at end of file diff --git a/docs/exporting/export-excel.md b/docs/exporting/export-excel.md new file mode 100644 index 00000000..99fabdcf --- /dev/null +++ b/docs/exporting/export-excel.md @@ -0,0 +1,21 @@ +--- +author: Juan Garrido +--- + +Although there is already support for a variety of file formats (CSV, JSON), there is also support for exporting all data to an EXCEL spreadsheet. Currently, it supports style modification, chart creation, company logo or independent language support. At the moment Office Excel 2010/2013/2016 are supported by Monkey365. The following example can be used to export all data to an Excel file. + +``` powershell +$param = @{ + Instance = 'Azure'; + Analysis = 'All'; + PromptBehavior = 'SelectAccount'; + all_subscriptions = $true; + TenantID = '00000000-0000-0000-0000-000000000000'; + ExportTo = 'EXCEL'; +} +$assets = Invoke-Monkey365 @param +``` + +Please, note that the EXCEL application must be installed on the OS, as the script will create the Excel file by using the EXCEL COM interface. + +Please, also note that the EXCEL output is maintained only for legacy purposes, and it will be retired at some future. diff --git a/docs/exporting/export-html.md b/docs/exporting/export-html.md new file mode 100644 index 00000000..af7b83b3 --- /dev/null +++ b/docs/exporting/export-html.md @@ -0,0 +1,150 @@ +--- +author: Juan Garrido +--- + +Monkey365 provides an internal module which provides methods to convert internal data to HTML format. Also, internal module adds additional support to Markdown syntax with Markdig. + +![](../assets/images/htmlreport.png) + +The following example can be used to export all data to an HTML file. + +``` powershell +$param = @{ + Instance = 'Azure'; + Analysis = 'All'; + PromptBehavior = 'SelectAccount'; + all_subscriptions = $true; + TenantID = '00000000-0000-0000-0000-000000000000'; + ExportTo = 'HTML'; +} +$assets = Invoke-Monkey365 @param +``` + +## Customize HTML + +A Monkey365 report uses JSON configuration files to visualize data in a variety of ways. This approach makes it easy to modify and combine tables, style them, and make them interactive with buttons. You can use your favorite text editor in order to modify these configuration files. + +## HTML Configuration Files Location + +All the table formats are stored under ```Monkey365/core/html/htmlconf```. Internal data is rendered with ```JQuery DataTables```. Basic table and table ```as list ``` are the available formats. Please, note that not all features of HTML tables are supported. + +## HTML Table examples + +### Table As List + +For example, table elements for Azure app services can be formatted to display complex structured data in the ``app_services.json`` file. + +``` json +{ + "app_service_missing_identity": [ + { + "translate": { + "name": "Application Name", + "kind": "Kind", + "location": "Location", + "properties.defaultHostName": "HostName", + "properties.httpsOnly": "Https Only", + "identity.principalId": "Principal ID", + "configuration.properties.ftpsState": "SSL FTP", + "configuration.properties.minTlsVersion": "TLS Version", + "configuration.properties.siteAuthSettings.Enabled": "Site Auth Enabled" + }, + "table": "asList", + "emphasis": ["Principal ID"] + } + ] +} +``` + +In the above example, this will result in the data being rendered in a single table formatted ```as list```. + +![](../assets/images/tableAsList.png) + +### Normal Table + +In this example, table elements for Storage accounts missing key rotation can be formatted to display complex structured data in the ``storage.json`` file. + +``` json +{ + "storage_accounts_https_traffic_disabled": [ + { + "translate": { + "name": "Name", + "CreationTime": "Creation Time", + "location": "Location", + "supportsHttpsTrafficOnly": "Https Only" + }, + "table": "Normal" + } + ], +} +``` +The above example will result in the data being rendered in a single table formatted as normal table. + +![](../assets/images/NormalTable.png) + +### Add Raw data button + +Table elements can be configured to show raw data on Bootstrap Modal. In order to route for showing raw data with modals, the ```showModalButton``` should be set to ```True```, as shown below: + +``` json +{ + "storage_accounts_missing_key_rotation": [ + { + "translate": { + "name": "Name", + "location": "Location", + "ResourceGroupName": "ResourceGroupName", + "isKeyRotated": "Key Rotated" + }, + "table": "Normal", + "actions":{ + "objectData":{ + "expand": ["*"], + "format": "json" + }, + "showGoToButton":"True", + "showModalButton":"True" + } + } + ] +} +``` +The above example will result in the data being rendered in a single table formatted as normal table, and a modal button in last column. + +![](../assets/images/modalButton.png) + +**Note** This feature is only supported in tables formatted as a ```Normal``` table. + +### Add direct link button + +Table elements can be configured to add a direct link to the Azure console section associated with the finding in the report. In order to route for showing raw data with modals, the ```showGoToButton``` should be set to ```True``` along with the ```actions```, as shown below: + +``` json +{ + "storage_accounts_missing_key_rotation": [ + { + "translate": { + "name": "Name", + "location": "Location", + "ResourceGroupName": "ResourceGroupName", + "isKeyRotated": "Key Rotated" + }, + "table": "Normal", + "actions":{ + "objectData":{ + "expand": ["*"], + "format": "json" + }, + "showGoToButton":"True", + "showModalButton":"True" + } + } + ] +} +``` +The above example will result in the data being rendered in a single table formatted as normal table, and a direct link button in last column. + +![](../assets/images/directLinkButton.png) + +**Note** This feature is only supported in tables formatted as a ```Normal``` table. Please, also note that since this feature is experimental, we welcome your feedback. \ No newline at end of file diff --git a/docs/exporting/exporting-data.md b/docs/exporting/exporting-data.md new file mode 100644 index 00000000..9afb8b4e --- /dev/null +++ b/docs/exporting/exporting-data.md @@ -0,0 +1,35 @@ +--- +author: Juan Garrido +--- + + +Monkey365 has built-in support for exporting data to a large variety of formats, including CSV and JSON. For example, the CSV output format is a comma-separated output that can be imported into i.e., Excel spreadsheets. The JSON format is pretty similar to JavaScript object, so it can be used as a data format by any programming language. This section page documents how Monkey365's data may be exported to these formats. + +## Data Location + +Depending on what format you are exporting to, the ```-ExportTo``` parameter presents you with slightly different options. Once Monkey365 has finished running, all the exported data are stored under Monkey365/monkey-reports/$GUID/$FORMAT/$FILE. The following demonstrates some examples in which the data may be programmatically accessed using various common languages. + +### Import JSON data in Python + +The following code snippet illustrates how one may load the Monkey365 data in a Python script (assuming that report data was previously exported to JSON format): + +``` json +import json + +file = 'C:/temp/monkey365/monkey-reports/00000000-0000-0000-0000-000000000000/json/aad_domain_users.json' + +with open(file) as f: + + json_data = json.load(f) + + return json_data +``` + +### Import JSON data in PowerShell + +The following code snippet illustrates how one may load the Monkey365 data in a PowerShell script (assuming that report data was previously exported to JSON format): + +``` powershell +PS C:\temp\monkey365> $json_data = (Get-Content -Raw .\monkey-reports\00000000-0000-0000-0000-000000000000\json\aad_domain_users.json) | ConvertFrom-Json +``` + diff --git a/docs/helo.md b/docs/helo.md new file mode 100644 index 00000000..0e20de14 --- /dev/null +++ b/docs/helo.md @@ -0,0 +1,41 @@ +## Welcome to GitHub Pages + +🚀 🐼 + +yes + +You can use the [editor on GitHub](https://github.com/pmarsceill/test-jtd/edit/master/README.md) to maintain and preview the content for your website in Markdown files. + +Whenever you commit to this repository, GitHub Pages will run [Jekyll](https://jekyllrb.com/) to rebuild the pages in your site, from the content in your Markdown files. + +### Markdown + +Markdown is a lightweight and easy-to-use syntax for styling your writing. It includes conventions for + +```markdown +Syntax highlighted code block + +# Header 1 +## Header 2 +### Header 3 + +- Bulleted +- List + +1. Numbered +2. List + +**Bold** and _Italic_ and `Code` text + +[Link](url) and ![Image](src) +``` + +For more details see [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/). + +### Jekyll Themes + +Your Pages site will use the layout and styles from the Jekyll theme you have selected in your [repository settings](https://github.com/pmarsceill/test-jtd/settings). The name of this theme is saved in the Jekyll `_config.yml` configuration file. + +### Support or Contact + +Having trouble with Pages? Check out our [documentation](https://help.github.com/categories/github-pages-basics/) or [contact support](https://github.com/contact) and we’ll help you sort it out. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..6bdf5d0d --- /dev/null +++ b/docs/index.md @@ -0,0 +1,23 @@ +--- +author: Juan Garrido +--- + +# Monkey365 + +
+ +
+ + +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. + +# Architecture + +Monkey365 works in three phases. In the first phase, plugins will issue queries against the multiple data sources to retrieve the desired metadata about targeted tenant or subscription, and then will collect information. Once all the necessary metadata is collected, the result is passed to an internal module in order to start the verifying phase, in which the tool uses the data collected in first phase to perform query search with a default set of rules, as a mechanism to evaluate the configuration and to search for potential misconfigurations and security issues. The third phase starts to generate reports, such as an Excel spreadsheet containing raw data, or a more intuitive HTML report containing structured data for quick checking and verification of the results. \ No newline at end of file diff --git a/docs/install-instructions.md b/docs/install-instructions.md new file mode 100644 index 00000000..103956f0 --- /dev/null +++ b/docs/install-instructions.md @@ -0,0 +1,77 @@ +--- +author: Juan Garrido +--- + +This section covers the process of installing Monkey365 module from GitHub using PowerShell. + +## Operating System Support + +The Monkey365 codebase was upgraded to support PowerShell Core and MSAL, which is the new authentication platform library for both Azure and Microsoft 365. These new features make the code OS independent. It has been tested on Windows, Linux (Ubuntu, Debian), as well as on Ubuntu-On-Windows. + +The following platforms are supported: + +* Windows PowerShell 5.1 with .NET Framework 4.7.2 or greater +* PowerShell 7.1 or greater on Linux and Windows + +## Prerequisites + +Monkey365 works out of the box with PowerShell. You can check your PowerShell version executing the command ```$PsVersionTable``` + +```PowerShell +PS C:\Users\monkeyuser> $PSVersionTable + +Name Value +---- ----- +PSVersion 7.2.4 +PSEdition Core +GitCommitId 7.2.4 +OS Microsoft Windows 10.0.19044 +Platform Win32NT +PSCompatibleVersions {1.0, 2.0, 3.0, 4.0…} +PSRemotingProtocolVersion 2.3 +SerializationVersion 1.1.0.1 +WSManStackVersion 3.0 +``` + +### Install PowerShell on non-Windows platforms + +PowerShell 7.x can be installed on macOS, Linux, and Windows but is not installed by default. For installation on non-Windows systems (i.e., Linux or macOS) please refer to the installation notes on Microsoft: + +Get PowerShell + +## Install Monkey365 + +### Git + +``` powershell +# change path to Module directory +PS C:\Users\monkeyuser> Push-Location ~\Documents\WindowsPowerShell\Modules + +# clone repository +PS C:\Users\monkeyuser\Documents\WindowsPowerShell\Modules> git clone https://github.com/silverhack/monkey365.git + +# return to original location +PS C:\Users\monkeyuser\Documents\WindowsPowerShell\Modules> Pop-Location +``` + +### Manual +You can download the latest zip by clicking [here](https://github.com/silverhack/monkey365/archive/refs/heads/main.zip). Once downloaded, you must extract the file and extract the files to a suitable directory. + +Once you have unzipped the zip file, you can use the PowerShell V3 Unblock-File cmdlet to unblock files + +``` powershell +Get-ChildItem -Recurse c:\monkey365 | Unblock-File +``` +## Import module +Once you have installed the monkey365 module on your system, you will likely want to import the module with the Import-Module cmdlet. Assuming that monkey365 is located in the ```PSModulePath```, PowerShell would load monkey365 into active memory: +``` powershell +Import-Module monkey365 +``` +If monkey365 is not located on a ```PSModulePath``` path, you can use an explicit path to import: +``` powershell +Import-Module C:\temp\monkey365 +``` +You can also use the ```Force``` parameter in case you want to reimport the monkey365 module into the same session +``` powershell +Import-Module C:\temp\monkey365 -Force +``` \ No newline at end of file diff --git a/docs/license-contributing.md b/docs/license-contributing.md new file mode 100644 index 00000000..220cffa2 --- /dev/null +++ b/docs/license-contributing.md @@ -0,0 +1,36 @@ +--- +author: Juan Garrido +--- + +Monkey365 is licensed as Apache License 2.0 as specified in each PS1 file. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 + +Additionaly, the following components are used in order to generate the HTML report: + +- Bootstrap, MIT License - https://getbootstrap.com/docs/5.2/about/license/ +- DataTables, MIT License - https://www.datatables.net/license/mit +- MarkDig, BSD-2-Clause license - https://github.com/xoofx/markdig/blob/master/license.txt +- JQuery, MIT License - https://github.com/jquery/jquery/blob/main/LICENSE.txt +- Fontawesome, CC BY 4.0 License - https://fontawesome.com/license/free +- ChartJs, MIT License - https://github.com/chartjs/Chart.js/blob/master/LICENSE.md +- highlight.js, BSD 3-Clause license - https://github.com/highlightjs/highlight.js/blob/main/LICENSE +- Azure icons, Microsoft license - https://docs.microsoft.com/en-us/azure/architecture/icons/ +- Microsoft 365 icons, Microsoft license + +Monkey365 welcomes all types of contributions that will help us to refine the tool. Testing and feedback on different PowerShell modules and plugins are ways everyone can help in addition to module features or bug fixes, so any support would be much appreciated. + +If you are interested in contributing directly to Monkey365, here is how you can get started: + +* Report issues +* Improve documentation +* Contribute code + +If you have what looks like a bug, or you would like to make a feature request, feel free to open a ticket on the Monkey365 repository on GitHub, but please, you should keep a few things in mind: + +* Before you file an issue, please search existing issues to see if it is already covered +* Please include detailed information about how to reproduce the problem + +## Thank you + +Thank you in advance for your contribution! + +For any questions or concerns feel free to contact me! Follow me on Twitter. Absolutely my DMs are open ;) \ No newline at end of file diff --git a/docs/logging/File.md b/docs/logging/File.md new file mode 100644 index 00000000..c6591f26 --- /dev/null +++ b/docs/logging/File.md @@ -0,0 +1,49 @@ +--- +author: Juan Garrido +--- + +# File logger + +The File plugin writes log events to a file. It supports which ```eventType``` can be written to a file. + +# Example + +``` json +"logging": { + "default":[ + { + "name": "File", + "type": "File", + "configuration": { + "filename": "monkey365_yyyyMMddhhmmss.log", + "includeExceptions": false, + "includeDebug": false, + "includeVerbose": false, + "includeError": false + } + } + ], + "loggers":[ + { + "name": "File", + "type": "File", + "configuration": { + "filename": "monkey365_exceptions_yyyyMMddhhmmss.log", + "includeExceptions": true, + "includeDebug": true, + "includeVerbose": true, + "includeInfo": false + } + } + ] + } +``` + +# Configuration +* name - Channel name +* type - File +* filename - The path of the file where logs will be written +* includeExceptions - whether or no exception streams will be written to file +* includeDebug - whether or no debug streams will be written to file +* includeVerbose - whether or no verbose streams will be written to file +* includeInfo - whether or no information streams will be written to file \ No newline at end of file diff --git a/docs/logging/Slack.md b/docs/logging/Slack.md new file mode 100644 index 00000000..11741662 --- /dev/null +++ b/docs/logging/Slack.md @@ -0,0 +1,49 @@ +--- +author: Juan Garrido +--- + +# Slack logger + +The Slack plugin sends log events to a ```slack``` channel. + +# Example + +``` json +"logging": { + "default":[ + { + "name": "File", + "type": "File", + "configuration": { + "filename": "monkey365_yyyyMMddhhmmss.log", + "includeExceptions": false, + "includeDebug": false, + "includeVerbose": false, + "includeError": false + } + } + ], + "loggers":[ + { + "name": "Slack", + "type": "Slack", + "configuration": { + "webHook": "https://hooks.slack.com/services/00000000000/00000000000/00000000000000000", + "icon_emoji": ":ghost:", + "username": "monkey365", + "channel": "#monkey365", + "onlyExceptions": true + } + } + ] + } +``` + +# Configuration +* name - Channel name +* type - File +* webHook - your Slack WebHook See the slack web api docs +* icon_emoji - the icon to use for the message +* username - the username to display with the message +* channel - the channel to send log messages +* onlyExceptions - Set to true in order to send only exceptions streams to Slack \ No newline at end of file diff --git a/docs/logging/channels.md b/docs/logging/channels.md new file mode 100644 index 00000000..36878c44 --- /dev/null +++ b/docs/logging/channels.md @@ -0,0 +1,54 @@ +--- +author: Juan Garrido +--- + +# Channels + +Channels serialise PowerShell log events to some form of output. Channels can be configured to write stream data to files, send emails, send data over the network, etc... For example: + +# Example + +``` json +"logging": { + "default":[ + { + "name": "File", + "type": "File", + "configuration": { + "filename": "monkey365_yyyyMMddhhmmss.log", + "includeExceptions": false, + "includeDebug": false, + "includeVerbose": false, + "includeError": false + } + } + ], + "loggers":[ + { + "name": "File", + "type": "File", + "configuration": { + "filename": "monkey365_exceptions_yyyyMMddhhmmss.log", + "includeExceptions": true, + "includeDebug": true, + "includeVerbose": true, + "includeInfo": false + } + }, + { + "name": "Slack", + "type": "Slack", + "configuration": { + "webHook": "https://hooks.slack.com/services/00000000000/00000000000/00000000000000000", + "as_user": "false", + "icon_emoji": ":ghost:", + "username": "monkey365", + "channel": "#monkey365", + "onlyExceptions": true + } + } + ] + } +``` + +In the above example, configuration file defines two channels named ```File``` and ```Slack```. \ No newline at end of file diff --git a/docs/logging/introduction.md b/docs/logging/introduction.md new file mode 100644 index 00000000..8db08ecc --- /dev/null +++ b/docs/logging/introduction.md @@ -0,0 +1,35 @@ +--- +author: Juan Garrido +--- + +# Introduction + +The internal logging module provides a multi-channel logger which is used internally. The logger module is inspired by the excellent project Powershell Logging Module. This section outlines how to configure it. + +The internal module intercepts the Write-Information, Write-Warning, Write-Verbose, Write-Debug and Write-Error cmdlets by using proxy functions to first send messages to custom channels before sending stream data to their original commands from the Microsoft.PowerShell.Utility module. + +The ```MonkeyLogger``` will send stream data to enabled channels, which needs to be configured prior using. Each of these listeners will receive each of the stream data and then will be sent to some form of output. + +The easiest way to configure ```MonkeyLogger``` is to have configured listeners in the ```logging``` section within the ```monkey365/config/monkey_365.config``` file. See below for a practical example. + +# Example + +``` json +"logging": { + "default":[ + { + "name": "File", + "type": "File", + "configuration": { + "filename": "monkey365_yyyyMMddhhmmss.log", + "includeExceptions": false, + "includeDebug": false, + "includeVerbose": false, + "includeError": false + } + } + ] +} +``` + +In the above example, configuration file defines one type named ```File```. \ No newline at end of file diff --git a/docs/permissions.md b/docs/permissions.md new file mode 100644 index 00000000..0726b1eb --- /dev/null +++ b/docs/permissions.md @@ -0,0 +1,13 @@ +--- +author: Juan Garrido +--- + +The module will not change or modify any assets deployed in an Azure subscription. Monkey365's only perform read-only access operations. Monkey365 cannot manipulate or change data and cannot influence the resources within Azure or Microsoft 365. + +Depending on what workloads you are trying to connect, Monkey365 will require that the provided identity have the following roles according to the principle of least privilege: + +* Azure AD and Azure environments + * **Global Reader** and **Security Reader** roles in all the subscriptions to assess +* Microsoft 365 environments + * Grant the given identity the role of **Global Reader** + * For SharePoint Online, grant the given identity the role of **Sharepoint Administrator**. Please note that Global Reader role can't access to SharePoint admin features as a reader using PowerShell. Please refer to the Global Reader notes on Microsoft. diff --git a/docs/support.md b/docs/support.md new file mode 100644 index 00000000..683859c8 --- /dev/null +++ b/docs/support.md @@ -0,0 +1,13 @@ +# Support + +Monkey365 uses GitHub Issues to track bugs and feature requests. + +Before you fill an issue, please search the existing issues to avoid duplicates. + +- For new issues, file your bug or feature request as a new [issue]. +- For help, discussion, and support questions about using this project, join or start a [discussion]. + +Support for Monkey365 is limited to the resources listed above. + +[issue]: https://github.com/silverhack/monkey365/issues +[discussion]: https://github.com/silverhack/monkey365/discussions diff --git a/images/MonkeyLogo.png b/images/MonkeyLogo.png new file mode 100644 index 00000000..941d3061 Binary files /dev/null and b/images/MonkeyLogo.png differ