Private/Test-LocalAdministrator.ps1

<#
.SYNOPSIS
Checks whether the current user is a local administrator and whether the process is elevated.
 
.DESCRIPTION
Inspects the current Windows identity and process token to determine local
administrator status, token elevation, and whether the token is filtered by UAC.
Returns these details together with a human-readable description.
 
.COMPONENT
Category: Sub Function
 
.FUNCTIONALITY
Reports local administrator membership and the current process elevation state.
 
.OUTPUTS
System.Management.Automation.PSCustomObject
 
.EXAMPLE
Test-LocalAdministrator
Returns the current user's local administrator and token elevation status.
 
.NOTES
This function is intended for Windows and does not accept parameters.
#>

function Test-LocalAdministrator {
    [CmdletBinding()]
    param()

    # Load Windows token API once
    if (-not ('AS2Go.NativeToken' -as [type])) {
        Add-Type -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
 
namespace AS2Go
{
    public static class NativeToken
    {
        private const uint TOKEN_QUERY = 0x0008;
        private const int TokenElevationType = 18;
        private const int TokenLinkedToken = 19;
        private const int TokenElevation = 20;
 
        [DllImport("advapi32.dll", SetLastError = true)]
        private static extern bool OpenProcessToken(
            IntPtr ProcessHandle,
            uint DesiredAccess,
            out IntPtr TokenHandle);
 
        [DllImport("advapi32.dll", SetLastError = true)]
        private static extern bool GetTokenInformation(
            IntPtr TokenHandle,
            int TokenInformationClass,
            out int TokenInformation,
            int TokenInformationLength,
            out int ReturnLength);
 
        [DllImport("advapi32.dll", SetLastError = true)]
        private static extern bool GetTokenInformation(
            IntPtr TokenHandle,
            int TokenInformationClass,
            out IntPtr TokenInformation,
            int TokenInformationLength,
            out int ReturnLength);
 
        [DllImport("kernel32.dll")]
        private static extern IntPtr GetCurrentProcess();
 
        [DllImport("kernel32.dll", SetLastError = true)]
        private static extern bool CloseHandle(IntPtr Handle);
 
        private static int ReadInt(IntPtr token, int infoClass)
        {
            int value;
            int length;
 
            if (!GetTokenInformation(
                token, infoClass, out value, sizeof(int),
                out length))
            {
                throw new Win32Exception(
                    Marshal.GetLastWin32Error());
            }
 
            return value;
        }
 
        public static int[] GetStatus()
        {
            IntPtr token = IntPtr.Zero;
 
            if (!OpenProcessToken(
                GetCurrentProcess(), TOKEN_QUERY, out token))
            {
                throw new Win32Exception(
                    Marshal.GetLastWin32Error());
            }
 
            try
            {
                int type = ReadInt(token, TokenElevationType);
                int elevated = ReadInt(token, TokenElevation);
 
                // Limited tokens have a linked elevated token.
                // Full tokens are already elevated.
                // Default tokens require a separate membership check.
                return new int[] { type, elevated };
            }
            finally
            {
                CloseHandle(token);
            }
        }
    }
}
'@
 -ErrorAction Stop
    }


    $Info = Measure-FunctionRuntime -Begin

    $Identity = [System.Security.Principal.WindowsIdentity]::GetCurrent()
    $Principal = [System.Security.Principal.WindowsPrincipal]::new($Identity)

    $TokenStatus = [AS2Go.NativeToken]::GetStatus()

    $ElevationType = switch ($TokenStatus[0]) {
        1 { 'Default' }
        2 { 'Full' }
        3 { 'Limited' }
        default { 'Unknown' }
    }

    $IsElevated = $Principal.IsInRole(
        [System.Security.Principal.WindowsBuiltInRole]::Administrator
    )

    # Full and Limited indicate an administrator split token.
    # Default tokens require an enabled administrator SID check.
    $IsLocalAdmin = if ($ElevationType -in @('Full', 'Limited')) {
        $true
    }
    else {
        $IsElevated
    }

    # Determine administrator status
    $IsUACFiltered = ($ElevationType -eq 'Limited')

    $Description = if ($IsLocalAdmin -and $IsElevated) {
        'Local administrator with elevated privileges (full administrative access).'
    }
    elseif ($IsLocalAdmin -and $IsUACFiltered) {
        'Local administrator running with a UAC-filtered token (elevation required).'
    }
    elseif ($IsLocalAdmin) {
        'Local administrator without active administrative privileges.'
    }
    else {
        'Standard user without local administrator privileges.'
    }


    Measure-FunctionRuntime -End -Details $Info 
    [pscustomobject]@{
        ComputerName  = $env:COMPUTERNAME
        UserName      = $Identity.Name
        IsLocalAdmin  = $IsLocalAdmin
        IsElevated    = $IsElevated
        IsUACFiltered = $IsUACFiltered
        ElevationType = $ElevationType
        Description   = $Description
    }
}