Cyberdrain Automatic Documentation Scripts to Hudu
So a few things happened in the last week. Firstly I ended up working over last weekend resolving an emergency for a customer, so had some time built up that I won’t feel bad for taking during the week. I also had a chunk of time booked out for attending Microsoft Ignite events, where I could have sessions on in the background while doing some coding. Finally IT Glue decided to charge us for another month after confirming the cancellation of our account. This by itself wouldn’t be too bad but I had seen numerous reports of them playing silly buggers with pretty much everyone who tries to cancel recently, so it really irritated me. Due to this I reached out to Kelvin from Cyberdrain to get the OK for me to rewrite his IT-Glue automatic documentation scripts for Hudu. Originally I had just planned to rewrite a few of them down the road but instead I have rewritten of the ones from Kelvin’s GitHub account now.
You can find the rewritten scripts here, you will need to make sure you update to version 1.12 of my HuduAPI Powershell module for them to all work:
https://github.com/lwhitelock/HuduAutomation/tree/main/CyberdrainRewrite
I also ran into a bug with being able to tag multiple other assets using an AssetLink field through the API, so the Hudu-ADGroups-Documentation.ps1 will not work until 2.1.5.4 of Hudu is released.
The main problem I ran into was getting tables to display in a readable way. I tried numerous things like switching between RichText and Embed. Trying to manually inject formatting. Doing inline styles in Embeds and a million other things. In the end I realised I could just take advantage of Hudu’s Custom CSS and fix the problem globally.
Note
These scripts are intended as examples and you should convert them to work with your own RMM or toolset. Primarily do not store any of your API Keys or tokens in the script itself and leave them sitting on desktops or servers.
The original script links, link back to the original Cyberdrain blog posts on the scripts where you can see more detail on what is being done.
Get the latest version of Hudu
Hudu have started adding sub version numbers so this makes it a lot easier to check now. You will need to be on version 2.1.5.3 for the majority of these scripts to work. You can check by clicking your name in the top right hand corner. The exception to this is the AD-Groups script which needs version 2.1.5.4 which is still in Beta at the moment. There was a bug with tagging multiple assets which is being fixed in this version, so the Groups script will start working when this is released to latest.
Fix Table Appearance:
If you don’t want your tables to be squished an unreadable go to -> Admin -> Design. Scroll down to your Custom CSS and add in:
.card__item table{
border-collapse: collapse;
margin: 5px 0;
font-size: 0.8em;
font-family: sans-serif;
min-width: 400px;
box-shadow: 0 0 20px rgba(0, 0, 0, 0.15);
}
.card__item h2, p{
font-size: 0.8em;
font-family: sans-serif;
}
.card__item th, td {
padding: 5px 5px;
max-width: 400px;
width:auto;
}
.card__item thead tr {
background-color: #009879;
color: #ffffff;
text-align: left;
}
.card__item tr {
border-bottom: 1px solid #dddddd;
}
.card__item tr:nth-of-type(even) {
background-color: #f3f3f3;
}
Here are details on a a script by script basis.
New Script: Hudu-ADDS-Documentation.ps1
Original Script: IT-Glue-ADDS-Documentation.ps1
Purpose: Gather and sync Active Directory information.
https://github.com/lwhitelock/HuduAutomation/blob/main/CyberdrainRewrite/Hudu-ADDS-Documentation.ps1
This script is pretty much the same as the original. Run it on a domain controller and it will get information about the domain and populate it to an asset. I match the company to create the asset in, on a company name variable set at the start. This can be tweaked to run from an RMM by passing in this value as well as a HuduAPI key scoped to the customer. I am planning on updating some of the scripts shortly to work with Datto RMM and will provide an update if I run into any issues.
New Script: Hudu-ADGroups-Documentation.ps1
Original Script: IT-Glue-ADGroups-Documentation.ps1
Purpose: Gather AD Group information and members and sync to Hudu
This script will document AD Groups. It will Tag users once version 2.1.5.4 is released. Until then it will throw an error as the AssetTag field needed is not in previous versions.
New Script: Hudu-AzureADSettings-Documentation.ps1
Original Script: IT-Glue-AzureADSettings-Documentation.ps1
Purpose: Gathers and syncs details on AzureAD users and settings for all your customers in your partner account.
This script will loop through all your tenants in Microsoft 365 and generates some details. I ran into a few bugs where Microsoft had changed things since the original script was written so I fixed those. I also changed the mapping method to utilise the same search for the default domain under a company in Hudu as my previous M365 script. You can use the same linking script I created before to do this for you https://github.com/lwhitelock/HuduAutomation/blob/main/Hudu-M365-Links.ps1
This uses the secure application model to connect to M365 https://www.cyberdrain.com/connect-to-exchange-online-automated-when-mfa-is-enabled-using-the-secureapp-model/
New Script: Hudu-BitLocker-Documentation.ps1
Original Script: IT-glue-BitLocker-Documentation.ps1
Purpose: Gets the bitlocker key from a machine and stores it as a password in Hudu
This script will document passwords for Bitlocker recovery keys and link them to a matched asset. I take in the company name as a variable rather than just relying on serial number as I found with my home PC if a serial isn’t set in the bios you end up with a lot of machines with the same serial. This also means that if a matching asset isn’t found it should create it under the correct company at least. Rather than just matching on serial like the original script, if it doesn’t find a unique match on serial it will then try to match computer name.
This is a useful script if you want to see a method for finding the asset of the machine you are executing the script on.
New Script: Hudu-Breaches.ps1
Original Script: ITGlue-Breaches.ps1
Purpose: Connects to HaveIBeenPwned and Shodan to check if any users in customers M365 accounts have appeared in a breach. Takes the tenants domains and checks them in Shodan.
https://github.com/lwhitelock/HuduAutomation/blob/main/CyberdrainRewrite/Hudu-Breaches.ps1
Just to note about this script both the original and this version are very slow. This is down to rate limiting at Have I Been Pwned only allowing 1 email to be looked up every 1.5 seconds.
This is the first script I used an embed field instead of a RichText to work around the table issue I applied some styles to it so its easier to read but the limitation is you have to scroll down in the embedded box to view all the entries. Again I am using the default domain website mapping method from Microsoft 365.
This uses the secure application model to connect to M365 https://www.cyberdrain.com/connect-to-exchange-online-automated-when-mfa-is-enabled-using-the-secureapp-model/
New Script: Hudu-Device-AuditLog.ps1
Original Script: IT-Glue-Device-AuditLog.ps1
Purpose: Gathers details on what changes have happened on a device for the last 24 hours. Also audits all software.
https://github.com/lwhitelock/HuduAutomation/blob/main/CyberdrainRewrite/Hudu-Device-AuditLogs.ps1
The first issue I had to solve on this one is the different way Hudu treats devices compared to IT Glue. In IT Glue they are configurations, where as Hudu they can be any custom asset layout people want. In our case we use multiple and split out Desktops/Laptops, Servers, Network Devices etc. The issue comes from when linking to another asset via the AssetLink field you must know it’s type first. The solution I came up with was to create an additional asset layout for the log book, for each asset type used to track Windows devices. The script will grab the name of the computer’s Asset type and create a new one if required.
New Script: Hudu-DHCP-Documentation
Original Script: IT-Glue-DHCP-Documentation.ps1
Purpose: Documents the configuration of a DHCP server.
https://github.com/lwhitelock/HuduAutomation/blob/main/CyberdrainRewrite/Hudu-DHCP-Documentation.ps1
This was a nice and easy one to convert. It took me longer to setup DHCP on my test server than to convert this script.
New Script: Hudu-FileSharePermissions-Documentation.ps1
Original Script: IT-Glue-FileSharePermissions-Documentation.ps1
Purpose: Run on a server to document the file shares present.
This was another straight forward one. I had to remove the CSV upload as that is not currently supported in the Hudu API.
New Script: Hudu-HyperV-Documentation.ps1
Original Script: IT-Glue-HyperV-Documentation.ps1
Purpose: Run on a Hyper-V host to document VMs and Hyper-V settings
This was a straight forward script. Run it on a Hyper-V host and it will grab the details from it.
New Script: Hudu-End-Point-Manager-Application-Documentation.ps1
Original Script: IT-Glue-intuneApplication-Documentation.ps1
Purpose: Go through each M365 tenant and document their Endpoint Manager (Intune )Apps into Hudu
This script gave me some trouble. After doing some debugging in the API I found it was rejecting my requests due to a lack of DeviceManagementApps.Read.All permissions. I searched for my APP ID in App Registrations and added the permission as an application permission and also as a delegated permission and granted admin consent in Azure AD app registrations.
This uses the secure application model to connect to M365 https://www.cyberdrain.com/connect-to-exchange-online-automated-when-mfa-is-enabled-using-the-secureapp-model/
New Script: Hudu-Network-Documentation.ps1
Original Script: IT-Glue-Network-Documentation.ps1
Purpose: This script makes use of powershell nmap to check for devices listening on 80,443,3389,21,22,25,587. It also documents standard information about the network.
This was another straight forward script which didn’t cause any issues.
New Script: Hudu-M365-GuestAccess.ps1
Original Script: IT-Glue-O365-GuestAccess.ps1
Purpose: This will pull Guest activity from M365 and add an asset for each guest in a tenant for all customers you have partner access to.
https://github.com/lwhitelock/HuduAutomation/blob/main/CyberdrainRewrite/Hudu-M365-GuestAccess.ps1
This script I had to strip # from the guest name in the asset name, otherwise when searching Hudu would not find an asset with the name. I also added a remove-pssession at the end which I don’t think was in the original. Make sure you have run my M365 Link script to have mapped your tenants to Hudu Customers.
This uses the secure application model to connect to M365 https://www.cyberdrain.com/connect-to-exchange-online-automated-when-mfa-is-enabled-using-the-secureapp-model/
New Script: Hudu-M365-MailboxPermissions-Documentation.ps1
Original Script: IT-Glue-O365-MailboxPermissions-Documentation.ps1
Purpose: This will loop through all tenants documenting the mailbox permissions on each Mailbox
This was a straight forward M365 Script. Run my mapping script first to map tenants into Hudu.
This uses the secure application model to connect to M365 https://www.cyberdrain.com/connect-to-exchange-online-automated-when-mfa-is-enabled-using-the-secureapp-model/
New Script: Hudu-M365-Teams-Documentation.ps1
Original Script: IT-Glue-O365-Teams-Documentation.ps1
Purpose: This will go through all your tenant’s teams and document their settings them into Hudu
This was a straight forward M365 Script. Run my mapping script first to map tenants into Hudu.
This uses the secure application model to connect to M365 https://www.cyberdrain.com/connect-to-exchange-online-automated-when-mfa-is-enabled-using-the-secureapp-model/
New Script: Hudu-M365-UsageReports-Documentation.ps1
Original Script: IT-Glue-O365-UsageReports-Documentation.ps1
Purpose: This will obtain reports on usage of different M365 services for each tenant and generate a report for them in Hudu.
Make sure you have added the Reports.Read.All permission as set out in the original article https://www.cyberdrain.com/documenting-with-powershell-documenting-office-365-usage-reports/
I had an issue with this script where there were some strange characters being generated in the HTML. I had to strip these out after generation otherwise the postgres database insert would fail. Once this was done the insert was successful.
New Script: Hudu-Server-Documentation.ps1
Original Script: IT-Glue-Server-Documentation.ps1
Purpose: This will grab some details on a server and document them in Hudu. Most of the time Hudu’s RMM integration will grab this data and more. So this only has a limited use case.
New Script: Hudu-SQL-Documentation.ps1
Original Script: IT-Glue-SQL-Documentation.ps1
Purpose: This will document SQL Server databases and their configuration
https://github.com/lwhitelock/HuduAutomation/blob/main/CyberdrainRewrite/Hudu-SQL-Documentation.ps1
This is a simple script. I create a hypertext link to the Host asset if it is found in Hudu.
New Script: Hudu-Unifi-Documentation.ps1
Original Script: IT-Glue-Unifi-Documentation.ps1
Purpose: This will talk to your Unifi controller and pull out details for each site, match to customers and populate Hudu.
For this script I took a new approach to matching than Kelvin did. To map sites first run the script one time. This will make sure the Asset Layout is created. The script will try to match any sites it can to a matching company name. If this fails it will output the site name to the console. If you then copy that site name and create a blank “Unifi – AutoDoc” asset using the site name as the asset name, the script will then pick that up on the next run. You don’t have to set anything other than the name, the script will do it on the next run.
New Script: Hudu-Unifi-Device-Documentation.ps1
Original Script: ITGlue-DeviceSync.ps1
Purpose: This will sync individual device details into Hudu from Unifi for each site
This is the first script I essentially did a full rewrite of. You will need to make sure you have run the Hudu-Unifi-Documentation.ps1 script first and mapped your sites. This will only match to existing sites. I am grabbing some more information than the original script and linking it to the site documentation in Hudu.
New Script: Hudu-LAPSAlternative-Documentation.ps1
Original Script: IT-Glue-LAPSAlternative-Documentation.ps1
Purpose: This will rename the local Administrator account, reset its password and document to Hudu.
This is a simple script that will let you rename / reset the local admin password of the machine it is run on and then document that to Hudu. To use it in the real world I would probably add a check to make sure the password is saved to Hudu before you do the actual change.
New Script: Hudu-Azure-VirtualMachines.ps1
Original Script: IT-Glue-Azure-VirtualMachines.ps1
Purpose: This will loop through all your customers in M365 and document their Azure VMs.
I have not been able to fully test this script. We don’t use Azure to host our virtual machines. In theory it should work. You will need to setup lighthouse delegation as set out in the original Cyberdrain article: https://www.cyberdrain.com/documenting-with-powershell-documenting-azure-vms-and-lighthouse-setup/