Skip to content

Latest commit

 

History

History
126 lines (89 loc) · 4.15 KB

README.md

File metadata and controls

126 lines (89 loc) · 4.15 KB

PowerShell-Hunter 🎯

PowerShell-Hunter Logo


Hunt smarter, hunt harder

License PowerShell

Why PowerShell-Hunter?

PowerShell is both a powerful administrative tool and a favorite weapon for attackers. While its extensive logging capabilities are great for security, the sheer volume of logs can be overwhelming. PowerShell-Hunter helps defenders cut through the noise and focus on what matters.

Key Benefits

  • 🔍 Smart Pattern Detection: Pre-configured patterns catch common attack techniques
  • 📊 Risk Scoring: Prioritize investigation with weighted scoring system
  • 🚀 Performance Optimized: Efficiently process thousands of events
  • 📝 Flexible Output: Export to CSV or JSON for further analysis
  • 🛠 Extensible: Easy to add custom detection patterns

Getting Started

Prerequisites

  • PowerShell 5.1 or higher
  • Administrator access (for reading Event Logs)
  • Windows PowerShell Operational Logs enabled

Quick Start

  1. Clone the repository:
git clone https://github.com/MHaggis/PowerShell-Hunter.git
  1. Navigate to the PowerShell-Hunter directory:
cd PowerShell-Hunter
  1. Run the analyzer:
.\Analyze-PowerShellEvents.ps1 -PatternFile "Patterns.csv"

Basic Usage for PowerShell 4104 Hunting

# Analyze last 5000 events and export to CSV
.\Analyze-PowerShellEvents.ps1 -PatternFile "Patterns.csv"

# Export to JSON instead
.\Analyze-PowerShellEvents.ps1 -PatternFile "Patterns.csv" -OutputFormat JSON

# Analyze specific number of events
.\Analyze-PowerShellEvents.ps1 -PatternFile "Patterns.csv" -MaxEvents 1000

How It Works

PowerShell-Hunter analyzes Event ID 4104 (PowerShell script block logging) events using pattern matching and risk scoring:

  1. Event Collection: Retrieves PowerShell script block logging events
  2. Pattern Matching: Checks events against known suspicious patterns
  3. Risk Scoring: Assigns weighted scores based on matched patterns
  4. Result Export: Outputs findings in CSV or JSON format

Sample Output

PS C:\Users\Administrator\test> .\Analyze-PowerShellEvents.ps1 -PatternFile "Patterns.csv" -OutputFormat csv -OutputFile .\mike.json
Starting PowerShell 4104 Event Analysis...
Loading patterns from Patterns.csv...
Analyzing events...
Exporting results to C:\Users\Administrator\test\mike_AR-WIN-5_20241217_173351.csv...
Results exported to CSV: C:\Users\Administrator\test\mike_AR-WIN-5_20241217_173351.csv

Top 5 highest risk events:

timestamp             risk_score detected_patterns
---------             ---------- -----------------
12/16/2024 8:34:55 PM         12 , WebClient, SuspiciousKeyword, Reflection, Compressed
12/16/2024 8:34:54 PM         12 , WebClient, SuspiciousKeyword, Reflection, Compressed
12/16/2024 8:34:56 PM         12 , WebClient, SuspiciousKeyword, Reflection, Compressed
12/16/2024 8:34:57 PM         12 , WebClient, SuspiciousKeyword, Reflection, Compressed
12/16/2024 8:34:55 PM         10 , EncodedCommand, WebClient, SuspiciousKeyword

Pattern Customization

The Patterns.csv file contains detection patterns and their risk scores. Each pattern includes:

  • Category: Pattern classification
  • Pattern: Regular expression for detection
  • Score: Risk score (1-5)

Example pattern:

Category,Pattern,Score
EncodedCommand,"[A-Za-z0-9+/]{44,}([A-Za-z0-9+/]{4}|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{2}==)",4

Roadmap 🗺️

  • Additional event type support
  • Integration with SIEM systems
  • Pattern suggestion based on false positive feedback

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

  • Inspired by the need for unique ways to hunt in event logs
  • Pattern database

Made with ❤️ by defenders for defenders