Merge pull request #23 from A3-N/main

Update README and .psm1 to remove v1/v2 confusion

Images/readme.md

@@ -1 +0,0 @@
-This folder is for image files.

PowerHuntShares.psm1

@@ -4,26 +4,51 @@
 #--------------------------------------
 # Author: Scott Sutherland, 2024 NetSPI
 # License: 3-clause BSD
-# Version: v2.1
+# Version: v2.1.1
 # References: This script includes custom code and code taken and modified from the open source projects PowerView, Invoke-Ping, and Invoke-Parrell. 
 function Invoke-HuntSMBShares
 {    
 	<#
             .SYNOPSIS
-            This function can be used to inventory to SMB shares on the current Active Directory domain and identify potentially high risk exposures.  
+            Inventories SMB shares within the current Active Directory domain, identifies potentially high-risk exposures, 
-			It will automatically generate csv files and html summary report.
+            and generates CSV and HTML summary reports.
+
             .PARAMETER Threads
-            Number of concurrent tasks to run at once.
+                Number of concurrent tasks to run at once. Default is 20.
-            .PARAMETER Output Directory
+
-            File path where all csv and html report will be exported.
+            .PARAMETER OutputDirectory 
+                File path where all CSV files and the HTML summary report will be exported.
+
+            .PARAMETER HostFile
+                Optional file containing a list of target hosts to scan. One host per line.
+
+            .PARAMETER DomainController
+                One or more domain controllers to target for Active Directory enumeration.
+
+            .PARAMETER Credential
+                Optional PSCredential object for alternate domain authentication. If not supplied, the current user context is used.
+
+            .PARAMETER RunSpaceTimeout
+                Timeout value in seconds for threaded runspaces. Default is 30 seconds.
+
             .EXAMPLE
-	        PS C:\temp\test> Invoke-HuntSMBShares -Threads 20 -OutputDirectory c:\temp\test -DomainController 10.1.1.1 -ExportFindings -Username domain\user -Password password
+                # Run with default AD computer discovery using current user credentials
+                PS C:\temp\test> Invoke-HuntSMBShares -Threads 20 OutputDirectory C:\temp\test
+
             .EXAMPLE
+                # Run against a custom list of target hosts
+                PS C:\temp\test> Invoke-HuntSMBShares -Threads 50 -HostFile C:\temp\hosts.txt OutputDirectory C:\temp\test
+
+            .EXAMPLE
+                # Run from a non-domain joined system using alternate credentials
                 C:\temp\test> runas /netonly /user:domain\user PowerShell.exe
-            PS C:\temp\test> Import-Module Invoke-HuntSMBShares.ps1
+                PS C:\temp\test> Import-Module .\PowerHuntShares.psm1
-            PS C:\temp\test> Invoke-HuntSMBShares -Threads 20 -RunSpaceTimeOut 10 -OutputDirectory c:\folder\ -DomainController 10.1.1.1 -ExportFindings -Username domain\user -Password password        
+                PS C:\temp\test> $Cred = Get-Credential
+                PS C:\temp\test> Invoke-HuntSMBShares -Threads 20 OutputDirectory C:\folder\ DomainController 10.1.1.1 -Credential $Cred
+
             .EXAMPLE
-			PS C:\temp\test> Invoke-HuntSMBShares -Threads 20 -ExportFindings -OutputDirectory c:\temp\test
+                # Run and specify a custom runspace timeout
+                PS C:\temp\test> Invoke-HuntSMBShares -Threads 20 RunSpaceTimeout 60 OutputDirectory C:\temp\test
 
              ---------------------------------------------------------------
              INVOKE-HUNTSMBSHARES                                        

Presentations/readme.md

@@ -1 +0,0 @@
-This folder contains related presentations.

README.md

@@ -45,7 +45,7 @@ However, additional exposures may exist that are not called out beyond that.
 
 # Setup Commands
 Below is a list of commands that can be used to load PowerHuntShares into your current PowerShell session. Please note that one of these will have to be run each time you run PowerShell is run.  It is not persistent. 
-<pre>
+```ps1
 # Bypass execution policy restrictions
 Set-ExecutionPolicy -Scope Process Bypass
 
@@ -60,25 +60,25 @@ or
 
 # Download and load PowerHuntShares.psm1 into memory
 IEX(New-Object System.Net.WebClient).DownloadString("https://raw.githubusercontent.com/NetSPI/PowerHuntShares/main/PowerHuntShares.psm1")
-</pre>
+```
-
 # Example Commands
 Important Note: All commands should be run as an unprivileged domain user.
-<pre>
+```ps1
 .EXAMPLE 1: Run from a domain computer. Performs Active Directory computer discovery by default.
 PS C:\temp\test> Invoke-HuntSMBShares -Threads 100 -OutputDirectory c:\temp\test 
 
 .EXAMPLE 2: Run from a domain computer with alternative domain credentials. Performs Active Directory computer discovery by default.
-PS C:\temp\test> Invoke-HuntSMBShares -Threads 100 -OutputDirectory c:\temp\test -Credentials domain\user
+PS C:\temp\test> Invoke-HuntSMBShares -Threads 100 -OutputDirectory c:\temp\test -Credential domain\user
 
 .EXAMPLE 3: Run from a domain computer as current user. Target hosts in a file. One per line.
-PS C:\temp\test> Invoke-HuntSMBShares -Threads 100 -OutputDirectory c:\temp\test  -HostList c:\temp\hosts.txt      
+PS C:\temp\test> Invoke-HuntSMBShares -Threads 100 -OutputDirectory c:\temp\test  -HostFile c:\temp\hosts.txt      
 
 .EXAMPLE 4: Run from a non-domain computer with credential. Performs Active Directory computer discovery by default.
 C:\temp\test> runas /netonly /user:domain\user PowerShell.exe
 PS C:\temp\test> Import-Module PowerHuntShares.psm1
-PS C:\temp\test> Invoke-HuntSMBShares -Threads 100 -RunSpaceTimeOut 10 -OutputDirectory c:\folder\ -DomainController 10.1.1.1 -Credential domain\user 
+PS C:\temp\test> Invoke-HuntSMBShares -Threads 100 -RunSpaceTimeout 10 -OutputDirectory c:\folder\ -DomainController 10.1.1.1 -Credential domain\user 
-
+```
+<pre>
 ===============================================================
 PowerHuntShares
 ===============================================================
@@ -185,16 +185,16 @@ SHARE REPORT SUMMARY
 # HTML Report Examples
 
 ### Summary Report Page
-![HtmlReport1](https://raw.githubusercontent.com/NetSPI/PowerHuntShares/main/Images/v2/1-Dashboard.png)
+![Summary Report Page](Images/1-Dashboard.png)
 
 ### Interesting Files Page
-![HtmlReport2](https://raw.githubusercontent.com/NetSPI/PowerHuntShares/main/Images/v2/11-InterestingFiles.png)
+![Interesting Files Page](Images/11-InterestingFiles.png)
 
 ### Extracted Secrets Page
-![HtmlReport3](https://raw.githubusercontent.com/NetSPI/PowerHuntShares/main/Images/v2/10-ExtractedSecrets.png)
+![Extracted Secrets Page](Images/10-ExtractedSecrets.png)
 
 ### ShareGraph Explorer Page
-![HtmlReport4](https://raw.githubusercontent.com/NetSPI/PowerHuntShares/main/Images/v2/9-ShareGraph.png)
+![ShareGraph Explorer Page](Images/9-ShareGraph.png)
 
 # Credits
 <strong>Author</strong><Br>
@@ -238,14 +238,74 @@ Todos
 * So. Many. Other. Things.
 </pre>
  
+## PowerHuntShares Visual Overview
 
+Below is a visual walkthrough of how **PowerHuntShares** works, what data it extracts, and how it presents actionable results.
 
+### Dashboard
+Provides a high-level view of discovered shares and associated risks.
 
+![Dashboard](Images/1-Dashboard.png)
 
+### Generated Files
+Automatically generated reports for easy analysis and offline review.
 
+![Generated Files](Images/2-Generated-Files.png)
 
+### Share Names
+Detailed mapping of share names and their properties.
 
+![Share Names - Example 1](Images/3-ShareNames-0.png)
+![Share Names - Example 2](Images/3-ShareNames-1.png)
+![Share Names - Example 3](Images/3-ShareNames-2.png)
 
+### Remediation Guidance
+Suggested remediation steps to address identified risks.
 
+![Remediation](Images/4-Remediation.png)
 
+### Timeline View
+Visualization of discovered issues over time.
 
+![Timeline](Images/5-Timeline.png)
+
+### Peer Comparison
+Compares discovered shares and permissions across different systems.
+
+![Peer Comparison](Images/6-PeerComparison.png)
+
+### Folder Groups
+Grouping related folders and shares for better context.
+
+![Folder Groups](Images/7-FolderGroups.png)
+
+### Asset Fingerprinting Exposure
+Shows asset exposure based on discovered fingerprints.
+
+![Asset Fingerprinting Exposure](Images/8-AssetFingerprintingExposure.png)
+
+### Share Graph
+Visual representation of discovered shares and relationships.
+
+![Share Graph](Images/9-ShareGraph.png)
+
+### Extracted Secrets
+Highlights sensitive information and secrets discovered during the scan.
+
+![Extracted Secrets](Images/10-ExtractedSecrets.png)
+
+### Interesting Files
+Lists potentially interesting or high-value files found in shares.
+
+![Interesting Files](Images/11-InterestingFiles.png)
+
+### Data Exposure
+Highlights areas where sensitive data may be exposed.
+
+![Data Exposure](Images/12-DataExposure.png)
+
+### Risk Exposure
+Comprehensive risk exposure views with detailed analysis.
+
+![Risk Exposure](Images/13-RiskExposure.png)
+![Risk Exposure 2](Images/13-RiskExposure2.png)