Thursday, November 17, 2016

Admin Run-As Menu

I found that over the years accessing tools can be time consuming especially when multiple accounts are used for different tools. I developed a PowerShell driven menu (using the latest WPF technology and Mahapps theme) that is highly customizable.

This tool isn't perfect and I'm sure there are many coding flaws with it, but I have tested and implemented it in my IT environment and everyone loves it especially the helpdesk. I designed this tool with one thing in mind: to make a simple push button menu that will launch the tools needed with the appropriate permissions.




When launched you will be presented with 6 tabs (I originally had just one, but found the other shops liked it as well), each tab menu supports a different section. In this screenshot, I have the system admins, Enterprise Admins, SCCM / Automation Team (that's me), Exchange Team and Infrastructure Team. I've added the 6 menu as an Extra Tab for additional tools that are used almost daily.




How it works is when the main PowerShell (AdminMenu.ps1) is called (link from a desktop shortcut), it loads 2 primary functions PowerShell scripts (AdminMenuExtensions.ps1 and ImageBase64Resources.ps1, then it loads 6 more PowerShell scripts for the Tabs (AdminMenu-Tab#.ps1).

However I have added more functionality so in reality it loads a total of 14 ps1 files!

I wrote the UI using Visual Studio 2015 Community Edition so as the Admin Menu launches it loads the XAML form with a XML configuration file.

A new element I've added is, it loads a notification icon and a quick access (always on top) button in the bottom right corner that when clicked it will either hide or open the menu in front of any other window (works most of the time)


Now each button is displayed using a configuration file written in XML. There are also options in the configure file I will get over later. The great thing is this menu is highly customizable because each tab (with exception of Tab 6) can hold 26 configurable buttons.
 


Some of the main buttons on each tab (left column) launches a console specified in the AdminMenu-Tab#.ps1 file. The menu in the right column are scripts or other useful tools an admin uses (mostly scripts). Almost 100% of the scripts it uses are written in PowerShell and are all menu driven scripts. Most of them I got from https://gallery.technet.microsoft.com, others I have found on the net or I write myself. I was only interested in GUI driven menus.

The real drive for this menu was because at work I use three different accounts to access different consoles. I needed a way to temporary store my credentials securely so I can launch any console on the fly. The Credential Management section on the far right does just that. It will store up to three credentials that are selectable. This only stores it for the time the menu is open, however if the menu is closed and reopened it does remember that username and domain entered, but the password has to be re-entered for it to be selectable again.

How this credential system works: when you enter alternate credentials it stores them in a global variable and to an encrypted file. When selected and the user presses a button on a tab, it actually calls a function that launches the exe or bat or vbs or whatnot, with that credential variable using -Credential switch.

...hence the name Admin Run-As Menu

I used FIPS compliance algorithms with encrypted cred file to ensure it was as secure as possible.

Now to make this script easy to use and easy to configure, obviously a lot of complicated scripts must be written to do this, but ultimately there are only a few things to edit to make it customized; the configuration file along with the corresponding tab

Like I mentioned before the Admin Run-As Menu, when launched, reads a configuration file to display the buttons color and name along with other settings:
  • Theme color
  • Accent color
  • Require Privilege Administrator access (UAC)
  • RSAT Check
  • Debug Mode
  • Hide all buttons not used (instead of a gray outline.
  • Hide app if not top window
  • Hide Credential Management feature
  • Load additional PowerShell modules
  • Load additional PowerShell Extension scripts
  • Use remote confit file
Now to control what the button do after editing the xml file:


The corresponding Tab PowerShell script has to be modified to match the process its calling like this:


As you see I designated function section for each button name (eg: Call-btnTab1_01,Call-btnTab1_02, Call-btnTab1_03, etc.)

In each of these function this is where you write the PowerShell code you want it to do. I made this simpler by just using the built-in function: Start-ButtonProcess. This function has many parameters. here is what is wrote as the guide:


USE INTGRATED FUNCTION (EASIEST)
- to log to output box in tab, use -OutputTab switch
- to identify process alias, use -Alias switch, otherwise the button name will be used
- to specify a custom run message use the -CustomRunMsg switch
- to specify a custom error message use the -CustomErrMsg switch (this will only display if errors)
- Auto use credentials feature if selected in menu, you can force it not to by adding -NeverRunAs switch

EXAMPLE (EXE):
Start-ButtonProcess -Alias "$ButtonClicked" -Path "$PSHOME\PowerShell.exe" -WorkingDirectory "$envWinDir\System32" -OutputTab tab1 -WindowStyle Normal

EXAMPLE (EXE) with Parameters:
Start-ButtonProcess -Alias "$ButtonClicked" -Path "$envWinDir\system32\mstsc.exe" -Parameters ("/v:" + $WPFtxtTab1Name1.Text) -OutputTab tab1 -WindowStyle Normal

EXAMPLE (PS1):
Start-ButtonProcess -ProcessCall ps1 -File "Start-PoshPAIG.ps1" -WorkingDirectory "$($scriptRoot + "\Scripts\PoshPAIG_2_1_5")" -CreateNoWindow



Nothing is flawless, there are parts of the code that could have written better. I thought about compiling this into an full executable, but I wanted it highly customizable and easy to update if needed, however I did compile an executable wrapper to call the AdminMenu.ps1 file (source code is below).

If you want to review the source, you can download it from here (GitHub):
Source: Admin Run-As Menu 3.9.9.1 (source)

The installer version is simply a compressed version of the source code that extracts and registers to a windows system that its installed. It will also place a shortcut on the desktop. There are two versions I have, one that used the exe wrapper (not signed) as the entry point, the other is just a shortcut to PowerShell calling a file.

Installer: Admin Run-As Menu 3.9.9.1 (Installer)
(the installer is written with Inno Setup, its source is on GitHub as well).

Installer with no EXE Wrapper: Admin Run-As Menu 3.9.9.1 (No Wrapper)

EXE Source Code: EXE Wrapper

*I also have a full version (it contains 16mb of useful PowerShell driven GUI downloaded all over the internet that are added to the menu which I used to screenshot the above pics. I don't post the full installer due to the sources of the script and copyrights, if you'd like a download link send me a message or email.)


I want to thank all the people on Gallery TechNet for writing wonderful PowerShell GUI scripts. My inspiration comes from here:
https://gallery.technet.microsoft.com/
https://blog.netnerds.net/2016/01/adding-toolbar-icons-to-your-powershell-wpf-guis/
https://foxdeploy.com/2015/04/16/part-ii-deploying-powershell-guis-in-minutes-using-visual-studio/
http://www.systanddeploy.com/2016/01/powershell-gui-add-mahapps-metro-theme.html?m=0
https://psappdeploytoolkit.codeplex.com/

If you work in IT, this menu will help you out. Enjoy 👍

Features I would like to add are (and working on):
  • Run space menu and buttons instead of single threaded
  • Disable buttons if software not installed (prereq check utility)
  • Main option menu (controls paths, themes and other main settings)
  • Quick Menu Option (5 immediate access buttons always on top of screen)

8 comments:

  1. Thanks. Have you tried out the menu?

    ReplyDelete
  2. Very informative and useful

    ReplyDelete
  3. This looks very close to something I've been trying to do for awhile. I have to get my powershell skills up so I can modify this to fit us better, but it's going to be a huge step. Thanks!

    ReplyDelete
  4. This comment has been removed by a blog administrator.

    ReplyDelete
  5. Nice menu, just installed it, and trying out.
    Great work.

    ReplyDelete
  6. Hi, This is a great idea. I stumbled across this page while researching how to make something similar for myself and my colleagues. I would like to get the full version you mention but struggle with sending you a message privately.

    I did find the mmc snapins didnt seem to work properly with elevated user, I found this helped;

    function Call-btnTab2_01{
    $ADMSC = "$envWinDir\system32\mmc.exe"
    If (($AppOptionRSATCheck) -and ($WPFtxtRSAT.Text -eq 'Yes') -or (!$AppOptionRSATCheck)){
    If ($WPFtxtTab2Name2.Text){
    Start-ButtonProcess -Path "$ADMSC" -Parameters ("/server=" + $WPFtxtTab2Name2.Text),"dsa.msc" -CustomRunMsg "Opening [$ButtonClicked] on DC: $($WPFtxtTab2Name2.Text)" -OutputTab Tab2 -WindowStyle Normal
    }
    ElseIf($WPFtxtTab2Name1.Text){
    Start-ButtonProcess -Path "$ADMSC" -Parameters ("/domain=" + $WPFtxtTab2Name1.Text),"dsa.msc" -CustomRunMsg "Opening [$ButtonClicked] for Domain: $($WPFtxtTab2Name1.Text)" -OutputTab Tab2 -WindowStyle Normal
    }..........

    ReplyDelete
  7. Looks sick AF!!
    Im keen to see the Gui PS side of things you mentioned in the full version.
    Please send it to powerfusion1@hotmail.com :)

    ReplyDelete