### APT-Hunter Command-Line Usage Examples

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

These examples demonstrate how to run APT-Hunter from the command line for different threat hunting tasks. Ensure you have the necessary log files and rule files in the specified paths.

```bash
python3 APT-Hunter.py -p /logs/evtx/ -o Project1 -allreport
```

```bash
python3 APT-Hunter.py -p /logs/evtx/ -o Project2 -hunt "psexec" -start 2022-04-03 -end 2022-04-05
```

```bash
python3 APT-Hunter.py -p /logs/evtx/ -o Project3 -sigma -rules rules.json
```

--------------------------------

### Install APT-Hunter Dependencies

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/README.md

Installs the required Python libraries for APT-Hunter using pip.

```bash
python3 -m pip install -r requirements.txt
```

--------------------------------

### Example Usage of Multiprocess

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Demonstrates how to call the multiprocess function with specific parameters for security log analysis. Ensure necessary imports are included.

```python
from lib import EvtxDetection
from pytz import timezone

input_tz = timezone('UTC')
EvtxDetection.multiprocess(
    file_list=['security.evtx'],
    detection_function=EvtxDetection.detect_events_security_log,
    input_timezone=input_tz,
    timestart=None,
    timeend=None,
    objectaccess=True,
    output='/output',
    cpu_cores=4
)
```

--------------------------------

### Bash Example of Invalid Date/Time Argument

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/errors.md

This example demonstrates an invalid command-line argument for the start time, which lacks a day component. The expected output is an error message indicating the correct ISO format.

```bash
# INVALID - missing day
python3 APT-Hunter.py -start "2022-04"

# Output: Error parsing time, please use ISO format...
```

--------------------------------

### Example Usage of Security Log Detection

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Demonstrates how to call the detect_events_security_log function with specific parameters. Ensure necessary imports like 'detect_events_security_log' and 'pytz.timezone' are included.

```python
from lib.EvtxDetection import detect_events_security_log
from pytz import timezone

detect_events_security_log(
    file='Security.evtx',
    input_timezone=timezone('UTC'),
    timestart=1648944000.0,  # 2022-04-03
    timeend=1649203200.0,    # 2022-04-05
    objectaccess=True,
    processexec=True,
    logons=True,
    frequencyanalysis=False,
    allreport=False,
    output='/output',
    cpu_cores=0,
    temp_dir='temp/'
)
```

--------------------------------

### Get Latest Sigma Rules

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/README.md

Downloads the latest Sigma rules and converts them into a format compatible with APT-Hunter. The output is saved to 'rules.json'.

```bash
Get_Latest_Sigma_Rules.sh
```

--------------------------------

### APT-Hunter Analysis with Time Filtering

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/INDEX.md

Perform analysis within a specific date and time range. Ensure ISO 8601 format for start and end times.

```bash
python3 APT-Hunter.py -p /logs -o ProjectName -allreport \
  -start "2024-04-01T00:00:00" -end "2024-04-05T23:59:59"
```

--------------------------------

### Example Sigma Rule for Multiple Failed Logins

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/types.md

An example of a Sigma rule designed to detect multiple failed login attempts by a single user. The query targets the 'UserLoginFailed' operation and groups results by user ID.

```json
{
  "name": "Multiple Failed Logins",
  "severity": "High",
  "query": "SELECT UserId, COUNT(*) as attempts FROM events WHERE Operation = 'UserLoginFailed' GROUP BY UserId HAVING attempts > 10"
}
```

--------------------------------

### Analyze EVTX Files with All Reports

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/README.md

Analyzes EVTX files from a specified directory and generates all reports. Use this to get a comprehensive analysis of the logs.

```bash
python3 APT-Hunter.py    -p /opt/wineventlogs/ -o Project1 -allreport
```

--------------------------------

### SigmaHunter Field Mapping Example

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/modules.md

Illustrates the global 'Alldata' dictionary used to store extracted EVTX event data fields. This dictionary can contain over 200 fields.

```python
Alldata = {
    'Original_Event_Log': [],
    'Channel': [],
    'Computer': [],
    'EventID': [],
    'ProcessName': [],
    'CommandLine': [],
    'TargetFilename': [],
    'SourceIp': [],
    'DestinationIp': [],
    ... (200+ fields)
}
```

--------------------------------

### System Events Structure

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/types.md

Defines the fields for system events, particularly focusing on service installations (Event ID 7045).

```python
System_events = [{
    'Date and Time': list[str],
    'timestamp': list[float],
    'Detection Rule': list[str],
    'Severity': list[str],
    'Detection Domain': list[str],
    'Service Name': list[str],             # Service/driver name
    'Image Path': list[str],               # Full path to executable
    'Event Description': list[str],
    'Event ID': list[str],                 # 7045 (service installed) common
    'Original Event Log': list[str],
    'Computer Name': list[str],
    'Channel': list[str]
}]
```

--------------------------------

### Display APT-Hunter Help

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/README.md

Prints the help message to display available options and usage instructions for APT-Hunter.

```bash
python3 APT-Hunter.py -h
```

--------------------------------

### detect_events_system_log

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/modules.md

Analyzes the Windows System event log for critical events such as service installation and system errors. It detects suspicious service installations and critical system failures.

```APIDOC
## detect_events_system_log(file, ...)

### Description
Analyzes the System event log for service installations and critical errors.

### Parameters
- **file** (string) - Path to the System event log file.
- **...** (any) - Additional arguments.
```

--------------------------------

### APT-Hunter Hunt with File

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/INDEX.md

Utilize a text file containing regex patterns for hunting.

```bash
python3 APT-Hunter.py -p /logs -o ProjectName -huntfile patterns.txt
```

--------------------------------

### Execute Main Entry Point

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Call the main function to initiate the command-line parser and orchestrator for the tool.

```python
main()
```

--------------------------------

### Run APT-Hunter Main Entry Point

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/INDEX.md

Execute the main APT-Hunter script. This function parses command-line arguments for execution.

```python
from APT-Hunter import main
main()  # Parses sys.argv
```

--------------------------------

### Main Entry Point

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

The main function serves as the command-line parser and orchestrator for the APT Hunter tool.

```APIDOC
## main()

### Description
Parses command-line arguments and orchestrates the execution of APT Hunter functionalities.

### Method
N/A (Python function)

### Parameters
N/A (Assumes command-line arguments are handled internally)

### Request Example
```python
main()
```

### Response
N/A (Executes based on command-line input)
```

--------------------------------

### Basic Log Analysis with APT-Hunter

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Perform basic analysis on logs in a specified directory, generating a comprehensive report. Ensure the log directory and output project name are correctly provided.

```bash
python3 APT-Hunter.py -p /logs -o Project1 -allreport
```

--------------------------------

### Basic Analysis with All Reports

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/configuration.md

Run a basic analysis of EVTX logs, generating all available reports and setting the timezone to UTC.

```bash
python3 APT-Hunter.py \
  -p /logs/evtx/ \
  -o Incident_2024_04 \
  -allreport \
  -tz "UTC"
```

--------------------------------

### APT-Hunter Comprehensive Analysis

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/INDEX.md

Run a full analysis on specified logs, generating all reports.

```bash
python3 APT-Hunter.py -p /logs -o ProjectName -allreport
```

--------------------------------

### Get Country from IP Address

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Retrieve the country associated with a given IP address using a GeoLite2 database reader. Requires the IP address and the reader object.

```python
get_country_from_ip(ip, reader)
```

--------------------------------

### Time-Range Specific Log Analysis

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Analyze logs within a specific date range. This is useful for focusing investigations on particular periods. Specify the start and end dates for the analysis.

```bash
python3 APT-Hunter.py -p /logs -o Project2 -allreport -start 2024-04-01 -end 2024-04-05
```

--------------------------------

### APT-Hunter Multicore Processing

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/INDEX.md

Leverage multiple CPU cores for faster analysis. Provide an integer value for the number of cores.

```bash
python3 APT-Hunter.py -p /logs -o ProjectName -allreport -cores 8
```

--------------------------------

### Append Event Data

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

To add new event data to the collections, use the append method on the specific list within the dictionary at index 0. For example, to add an Event ID to Security_events.

```python
Security_events[0]['Event ID'].append('4624')
```

--------------------------------

### Configure CPU Cores for Analysis

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/configuration.md

Specify the number of CPU cores to use for analysis. The default is half of the available cores. This option is useful for balancing resource usage.

```bash
-cores <N>  # Use N CPU cores (default: half of available)
```

--------------------------------

### APT-Hunter Sigma Rule Analysis

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/INDEX.md

Analyze logs using Sigma rules defined in a JSON file. Verify JSON syntax and query validity.

```bash
python3 APT-Hunter.py -p /logs -o ProjectName -sigma -rules rules.json
```

--------------------------------

### Initialize Event Collections

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

These variables are initialized as lists of dictionaries to hold various event data. Each dictionary represents a structured event log.

```python
Sysmon_events = [{'Date and Time': [], 'timestamp': [], 'Detection Rule': [], 
                    'Severity': [], 'Detection Domain': [], 'Event Description': [], 
                    'Event ID': [], 'Original Event Log': [], 'Computer Name': [], 
                    'Channel': []}]

Security_events = [{'Date and Time': [], 'timestamp': [], 'Detection Rule': [], 
                    'Severity': [], 'Detection Domain': [], 'Event Description': [], 
                    'Event ID': [], 'Original Event Log': [], 'Computer Name': [], 
                    'Channel': []}]

Logon_Events = [{'Date and Time': [], 'timestamp': [], 'Event ID': [], 
                 'Account Name': [], 'Account Domain': [], 'Logon Type': [], 
                 'Logon Process': [], 'Source IP': [], 'Workstation Name': [], 
                 'Computer Name': [], 'Channel': [], 'Original Event Log': []}]

Object_Access_Events = [{'Date and Time': [], 'timestamp': [], 'Event ID': [], 
                         'Account Name': [], 'Account Domain': [], 'Object Name': [], 
                         'Object Type': [], 'Process Name': [], 'Computer Name': [], 
                         'Channel': [], 'Original Event Log': []}]
```

--------------------------------

### Hunt File with Multiple Patterns

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/configuration.md

Perform a hunt using a file containing multiple detection patterns, useful for complex threat hunting scenarios.

```bash
python3 APT-Hunter.py \
  -p /logs/evtx/ \
  -o Regex_Hunt \
  -huntfile patterns.txt
```

--------------------------------

### Detect SMB Client Events

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Parses an EVTX file to detect SMB Client related events. All detection functions accept identical parameters for file path, timezone, time range, event tracking options, reporting, and output directories.

```python
def detect_events_SMB_Client_log(file, input_timezone, timestart, timeend, objectaccess,
                                 processexec, logons, frequencyanalysis, allreport, output,
                                 cpu_cores, temp_dir)
```

--------------------------------

### File Existence Check Before Use

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/errors.md

Ensures that a file exists before attempting to use it, preventing potential `FileNotFoundError` exceptions. If the file does not exist, it provides a message and uses a default data structure.

```python
if os.path.exists(file_path):
    # Use file
else:
    print(f"File {file_path} does not exist")
    # Use default/empty data structure
```

--------------------------------

### Basic Log Analysis

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/README.md

Perform a basic analysis of security logs. Specify the path to the logs and an output directory.

```bash
python3 APT-Hunter.py -p /path/to/logs -o OutputProject -allreport
```

--------------------------------

### Hunt Using a File of Regex Patterns

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/README.md

Hunts for patterns defined in a file containing regular expressions. This allows for more complex and flexible hunting queries.

```bash
python3 APT-Hunter.py  -huntfile "huntfile.txt)" -p /opt/wineventlogs/ -o Project2
```

--------------------------------

### Detect SMB Server Events

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Parses an EVTX file to detect SMB Server related events. All detection functions accept identical parameters for file path, timezone, time range, event tracking options, reporting, and output directories.

```python
def detect_events_SMB_Server_log(file, input_timezone, timestart, timeend, objectaccess,
                                 processexec, logons, frequencyanalysis, allreport, output,
                                 cpu_cores, temp_dir)
```

--------------------------------

### SMB Client Events Structure

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/types.md

Defines the structure for SMB client events, including details like share name and accessed file.

```python
SMB_Client_events = [{
    'Date and Time': list[str],
    'timestamp': list[float],
    'Detection Rule': list[str],
    'Severity': list[str],
    'Detection Domain': list[str],
    'Event Description': list[str],
    'Share Name': list[str],               # Connected share
    'File Name': list[str],                # Accessed file
    'Event ID': list[str],
    'Computer Name': list[str],
    'Channel': list[str],
    'Original Event Log': list[str]
}]
```

--------------------------------

### Create SQLite Database from DataFrame

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Create an SQLite database from a pandas DataFrame. Requires the DataFrame and the desired database name.

```python
create_sqlite_db_from_dataframe(dataframe, db_name)
```

--------------------------------

### Sigma Rule Integration for Threat Hunting

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Utilize Sigma rules for threat detection. This command enables APT-Hunter to process Sigma rule files to identify potential threats within the logs.

```bash
python3 APT-Hunter.py -p /logs -o Sigma1 -sigma -rules rules.json
```

--------------------------------

### Try-Except with Specific and General Error Handling

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/errors.md

A common pattern for handling specific errors gracefully while logging detailed information for any other unexpected exceptions.

```python
try:
    # operation
except SpecificError:
    print("Error message")
except Exception as e:
    logging.error(traceback.format_exc())
```

--------------------------------

### APT-Hunter Custom Regex Search

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/INDEX.md

Hunt for specific patterns using a custom regex string.

```bash
python3 APT-Hunter.py -p /logs -o ProjectName -hunt "pattern1|pattern2"
```

--------------------------------

### Targeted Hunting with Time Filter

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/configuration.md

Perform targeted hunting for specific patterns (psexec, mimikatz, procdump) within a defined time range and timezone.

```bash
python3 APT-Hunter.py \
  -p /logs/evtx/ \
  -o Hunting_Campaign \
  -hunt "psexec|mimikatz|procdump" \
  -start "2024-04-01T00:00:00" \
  -end "2024-04-05T23:59:59" \
  -tz "America/New_York"
```

--------------------------------

### Load or Fallback Frequency Analysis Data in Python

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/errors.md

Attempts to load pickled frequency analysis data from a file. If the file does not exist, it prints an error message and falls back to using in-memory summary data.

```python
if os.path.exists(temp_dir + "Powershell_Execution_Events.pickle"):
    with open(temp_dir + "Powershell_Execution_Events.pickle", 'rb') as handle:
        Powershell_Execution_dataframes = pickle.load(handle)
else:
    print(f"{temp_dir + '_Executed_Powershell_report.csv'} does not exist.")
    ExecutedPowershell_Summary = pd.DataFrame(Executed_Powershell_Summary[0])
```

--------------------------------

### Logon Events Summary Structure

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/types.md

Defines the structure for a logon events summary, tracking user logins and their success/failure counts.

```python
Logon_Events_Summary = {
    'User': list[str],
    'Number of Failed Logins': list[int],
    'Number of Successful Logins': list[int]
}
```

--------------------------------

### EvtxHunt: Custom Regex Threat Hunting on EVTX Files

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Use Evtx_hunt for custom regex-based threat hunting on specified EVTX files. It requires a list of files, regex patterns, event ID (optional), input timezone, and an output prefix. Timestamps can be filtered using Unix timestamps.

```python
from lib.EvtxHunt import Evtx_hunt
from pytz import timezone

Evtx_hunt(
    files=['Security.evtx', 'System.evtx'],
    str_regexes=[r'mimikatz', r'psexec', r'procdump'],
    eid='1',  # Process creation events
    input_timezone=timezone('UTC'),
    output='hunt_results',
    timestart=None,
    timeend=None
)
```

--------------------------------

### Generate APT-Hunter Reports

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Call this function to aggregate analysis results and generate comprehensive reports in Excel and CSV formats. The function produces various files detailing timelines, logon events, object access, process execution, and more.

```python
def report()
```

--------------------------------

### Office365 User Operations Summary Query

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/configuration.md

A pre-built SQL query to summarize user operations in Office365, showing the count and list of distinct operations performed by each user.

```sql
SELECT UserId, COUNT(DISTINCT Operation) AS OperationCount,
       GROUP_CONCAT(Operation, ', ') AS UniqueOperations
FROM events
GROUP BY UserId
ORDER BY OperationCount DESC;
```

--------------------------------

### Perform Custom Hunting with Regex

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/INDEX.md

Hunt for specific patterns in event logs using regular expressions. Requires file paths, regex patterns, event IDs, and time range.

```python
from lib.EvtxHunt import Evtx_hunt
Evtx_hunt(files, str_regexes, eid, input_timezone, output, timestart, timeend)
```

--------------------------------

### Multicore Processing for Performance

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Leverage multiple CPU cores to speed up log analysis. Specify the number of cores to use for enhanced performance, especially on large datasets.

```bash
python3 APT-Hunter.py -p /logs -o Project3 -allreport -cores 8
```

--------------------------------

### Analyze Sigma Rules

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/INDEX.md

Analyze log data against Sigma rules. Requires the path to Sigma rules, a rules file, and an output path.

```python
from lib.SigmaHunter import Sigma_Analyze
Sigma_Analyze(path, rules_file, output)
```

--------------------------------

### Logon Events Structure

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/types.md

Defines the structure for logon-related events. Includes details about the account, logon type, and source of the logon.

```python
Logon_Events = [{
    'Date and Time': list[str],
    'timestamp': list[float],
    'Event ID': list[str],
    'Account Name': list[str],            # SAM account name
    'Account Domain': list[str],          # Domain name or computer name
    'Logon Type': list[str],              # Type 2-12 (see Logon Type enumeration)
    'Logon Process': list[str],           # Process name (NtlmSsp, Kerberos, etc.)
    'Source IP': list[str],               # Client IP address
    'Workstation Name': list[str],        # Source computer name
    'Computer Name': list[str],           # Target computer name
    'Channel': list[str],                 # Log channel
    'Original Event Log': list[str]       # Raw event XML
}]
```

--------------------------------

### Hunt Using Sigma Rules

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/README.md

Hunts for threats using Sigma rules specified in a JSON file. This leverages a standardized rule format for threat detection.

```bash
python3 APT-Hunter.py -sigma -rules rules.json -p /opt/wineventlogs/ -o Project2
```

--------------------------------

### APT-Hunter Timezone Conversion

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/INDEX.md

Specify a timezone for log analysis and reporting.

```bash
python3 APT-Hunter.py -p /logs -o ProjectName -allreport -tz "America/New_York"
```

--------------------------------

### APT-Hunter Office365 Hunt

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/INDEX.md

Perform hunting operations on Office365 audit data using specified rules.

```bash
python3 APT-Hunter.py -p /audit -o ProjectName -o365hunt -o365rules o365_rules.json
```

--------------------------------

### multiprocess

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/modules.md

Orchestrates parallel analysis of EVTX files using a specified detection function. This is the main entry point for running multiple detection routines concurrently.

```APIDOC
## multiprocess(file_list, detection_function, ...)

### Description
Orchestrates parallel analysis of EVTX files using specified detection function.

### Parameters
- **file_list** (list) - A list of EVTX file paths to analyze.
- **detection_function** (function) - The function to apply to each file for detection.
- **...** (any) - Additional arguments to pass to the detection function.
```

--------------------------------

### EvtxHunt Functions

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Functions for hunting specific patterns within event log files.

```APIDOC
## EvtxHunt Functions

### Description
Provides functions for hunting specific patterns (regex) within event log files and generating reports.

### Functions
- **Evtx_hunt**: Hunts for specified string regular expressions within a list of event log files.
- **hunt_report**: Generates a report from the hunt results.

### Parameters
- **Evtx_hunt**:
  - **files** (list): A list of paths to the event log files to hunt within.
  - **str_regexes** (list): A list of string regular expressions to search for.
  - **eid** (string): Event ID to filter by.
  - **input_timezone** (string): Timezone of the input logs.
  - **output** (string): Path for the output report.
  - **timestart** (string): Start time for filtering events.
  - **timeend** (string): End time for filtering events.
- **hunt_report**:
  - **output** (string): Path to the hunt results to generate a report from.

### Request Example
```python
Evtx_hunt(files=['evtx_log1.evtx', 'evtx_log2.evtx'], str_regexes=['suspicious_pattern'], eid='1', input_timezone='UTC', output='hunt_results.json', timestart='2023-01-01', timeend='2023-01-31')
hunt_report(output='hunt_results.json')
```

### Response
- **Evtx_hunt**: No direct return value, populates hunt results for `hunt_report`.
- **hunt_report**: Generates a report file at the specified output path.
```

--------------------------------

### Sigma Rule Detection

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/README.md

Integrate Sigma rules for threat detection. Specify the log path, output directory, and the path to the Sigma rules file.

```bash
python3 APT-Hunter.py -p /path/to/logs -o OutputProject -sigma -rules rules.json
```

--------------------------------

### Multiprocessing Error Handling with IOError and General Exceptions

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/errors.md

Handles potential `IOError` during process startup, specifically when a file path is invalid. It also includes a general exception handler for other unexpected issues during multiprocessing.

```python
try:
    process = multiprocessing.Process(target=function, args=args)
    process.start()
    process_list.append(process)
except IOError:
    print("Error: File Path Does Not Exist")
except Exception as e:
    logging.error(traceback.format_exc())
```

--------------------------------

### Handle Missing Sigma Rules Path

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/errors.md

When Sigma mode is enabled without providing a rules file path using the --rules argument, this error message is displayed. The process returns after printing the message.

```bash
python3 APT-Hunter.py --sigma
# Output: Please include rules path ex : --rules rules.json
```

--------------------------------

### Analyze EVTX Files with Time Frame

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/README.md

Analyzes EVTX files within a specific time range, focusing the hunt on a particular timeline. The end time can include hours, minutes, and seconds.

```bash
python3 APT-Hunter.py    -p /opt/wineventlogs/ -o Project1 -allreport -start 2022-04-03 -end 2022-04-05T20:56
```

--------------------------------

### Custom Regex Hunting

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/README.md

Hunt for specific patterns in logs using custom regular expressions. Provide the log path, output directory, and the regex pattern.

```bash
python3 APT-Hunter.py -p /path/to/logs -o OutputProject -hunt "mimikatz|psexec"
```

--------------------------------

### Hunt Using a Specific String

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/README.md

Hunts for a specific string pattern within EVTX files. This is useful for finding known indicators of compromise.

```bash
python3 APT-Hunter.py  -hunt "psexec" -p /opt/wineventlogs/ -o Project2
```

--------------------------------

### detect_events_SMB_Client_log

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Detects events from SMB Client logs. This function processes EVTX files to identify SMB client-related activities.

```APIDOC
## detect_events_SMB_Client_log

### Description
Detects events from SMB Client logs. This function processes EVTX files to identify SMB client-related activities.

### Parameters
All detection functions accept identical parameters:

#### Path Parameters
- **file** (str) - Required - Path to single EVTX file
- **input_timezone** (pytz.timezone) - Required - Timezone for timestamp conversion
- **timestart** (float) - Optional - Unix timestamp for start filter (or None)
- **timeend** (float) - Optional - Unix timestamp for end filter (or None)
- **objectaccess** (bool) - Required - Track object access events (Event ID 4663)
- **processexec** (bool) - Required - Track process execution events (Event ID 1)
- **logons** (bool) - Required - Track logon events (Event IDs 4624, 4625)
- **frequencyanalysis** (bool) - Required - Calculate event ID frequency statistics
- **allreport** (bool) - Required - Generate all optional reports
- **output** (str) - Required - Output directory path
- **cpu_cores** (int) - Required - Reserved for consistency (not used in serial execution)
- **temp_dir** (str) - Required - Directory for temporary CSV files

### Return Type
None (updates module-level globals)
```

--------------------------------

### Detect User Profile Service Events

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Parses an EVTX file to detect User Profile Service related events. All detection functions accept identical parameters for file path, timezone, time range, event tracking options, reporting, and output directories.

```python
def detect_events_UserProfileService_log(file, input_timezone, timestart, timeend,
                                         objectaccess, processexec, logons, frequencyanalysis,
                                         allreport, output, cpu_cores, temp_dir)
```

--------------------------------

### Search Database

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Perform a search query against a database. Requires the query string and the database object.

```python
search_db(query, DB)
```

--------------------------------

### detect_events_SMB_Server_log

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Detects events from SMB Server logs. This function analyzes EVTX files for SMB server-related activities.

```APIDOC
## detect_events_SMB_Server_log

### Description
Detects events from SMB Server logs. This function analyzes EVTX files for SMB server-related activities.

### Parameters
All detection functions accept identical parameters:

#### Path Parameters
- **file** (str) - Required - Path to single EVTX file
- **input_timezone** (pytz.timezone) - Required - Timezone for timestamp conversion
- **timestart** (float) - Optional - Unix timestamp for start filter (or None)
- **timeend** (float) - Optional - Unix timestamp for end filter (or None)
- **objectaccess** (bool) - Required - Track object access events (Event ID 4663)
- **processexec** (bool) - Required - Track process execution events (Event ID 1)
- **logons** (bool) - Required - Track logon events (Event IDs 4624, 4625)
- **frequencyanalysis** (bool) - Required - Calculate event ID frequency statistics
- **allreport** (bool) - Required - Generate all optional reports
- **output** (str) - Required - Output directory path
- **cpu_cores** (int) - Required - Reserved for consistency (not used in serial execution)
- **temp_dir** (str) - Required - Directory for temporary CSV files

### Return Type
None (updates module-level globals)
```

--------------------------------

### Process Execution Summary Structure

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/types.md

Defines the structure for a process execution summary, listing processes and their execution counts.

```python
Executed_Process_Summary = [{
    'Process Name': list[str],
    'Number of Execution': list[int]
}]
```

--------------------------------

### Analyze with Sigma Rules

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Analyze data using Sigma rules. This function takes a path to the data, a Sigma rules file, and an output path.

```python
Sigma_Analyze(path, rules_file, output)
```

--------------------------------

### Suspicious Program Signatures

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/modules.md

Lists of signatures used for detecting malicious tools and commands. Includes executables, PowerShell commands, and arguments.

```python
Suspicious_executables              # ~75 malware tools (mimikatz, psexec, procdump, etc.)
```

```python
Suspicious_powershell_commands      # ~400+ PowerShell exploitation commands
```

```python
Suspicious_powershell_Arguments     # ~1000+ obfuscation/execution patterns
```

```python
critical_services                   # Windows services critical to security
```

--------------------------------

### Handle Invalid Hunt File Path

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/errors.md

This error indicates an issue with the provided hunt file path. Processing halts and returns without generating any output.

```python
# lib/EvtxHunt.py:400-408
# Message: "Issue with the hunt file path"
```

--------------------------------

### detect_events_SMB_Client_log

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/modules.md

Analyzes the SMB Client security log for signs of lateral movement attempts and unusual share connections.

```APIDOC
## detect_events_SMB_Client_log(file, ...)

### Description
Analyzes SMB Client logs for lateral movement attempts and suspicious connections.

### Parameters
- **file** (string) - Path to the SMB Client security log file.
- **...** (any) - Additional arguments.
```

--------------------------------

### SigmaHunter: Sigma Rule-Based Threat Detection for EVTX

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Perform Sigma rule-based threat detection on EVTX files using Sigma_Analyze. Provide the path to the directory containing EVTX files, the Sigma rules file, and the desired output directory for results.

```python
from lib.SigmaHunter import Sigma_Analyze

Sigma_Analyze(
    path='/logs/evtx/',
    rules_file='sigma_rules.json',
    output='/output'
)
```

--------------------------------

### Windows Defender Events Structure

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/types.md

Defines the structure for Windows Defender events, including event IDs for malware detection and scans.

```python
Windows_Defender_events = [{
    'Date and Time': list[str],
    'timestamp': list[float],
    'Detection Rule': list[str],
    'Severity': list[str],
    'Detection Domain': list[str],
    'Event Description': list[str],
    'Event ID': list[str],                 # 1116, 1117, 1118, 1119
    'Original Event Log': list[str],
    'Computer Name': list[str],
    'Channel': list[str]
}]
```

--------------------------------

### Excel Writer Error Handling

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/errors.md

This error occurs when APT-Hunter cannot write an Excel file due to permission issues or a full disk. The process exits with an exception, potentially leading to incomplete reports.

```python
## Excel Writer Errors

**Condition**: Cannot write Excel file (permission denied, disk full)

**Trigger Location**: `APT-Hunter.py:618-640` (pd.ExcelWriter)

**Message**: Standard Python I/O error with file path

**Recovery**: Process exits with exception, reports may be incomplete
```

--------------------------------

### Multicore Processing

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/configuration.md

Optimize analysis performance on large datasets by utilizing multiple CPU cores.

```bash
python3 APT-Hunter.py \
  -p /logs/evtx/ \
  -o Large_Dataset \
  -allreport \
  -cores 8
```

--------------------------------

### Office365 Password Spray Detection Query

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/configuration.md

A pre-built SQL query to detect password spray attacks in Office365 by identifying users with a high number of failed logins from multiple IP addresses within a short period.

```sql
WITH FailedLogins AS (
  SELECT UserId, ClientIP, datetime(CreationTime) AS LoginDate
  FROM events
  WHERE Operation = 'UserLoginFailed'
)
SELECT UserId, GROUP_CONCAT(ClientIP, ', ') AS ClientIPs,
       COUNT(DISTINCT ClientIP) AS UniqueIPCount,
       COUNT(*) AS FailedLoginAttempts, LoginDate
FROM FailedLogins
GROUP BY UserId, strftime('%Y-%m-%d %H', LoginDate)
HAVING COUNT(*) > 5 AND UniqueIPCount > 3
ORDER BY FailedLoginAttempts DESC;
```

--------------------------------

### Sigma_Analyze

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Analyzes EVTX files using Sigma rules for threat detection. It supports various rule features including field matching, regex, hash matching, and multi-field correlation.

```APIDOC
## Sigma_Analyze

### Description
Analyzes EVTX files using Sigma rules for threat detection. It supports various rule features including field matching, regex, hash matching, and multi-field correlation.

### Method
```python
def Sigma_Analyze(path, rules_file, output)
```

### Parameters
#### Path Parameters
- **path** (str) - Yes - Path to directory containing EVTX files
- **rules_file** (str) - Yes - Path to Sigma rules in JSON format
- **output** (str) - Yes - Output directory for detection results

### Response
#### Success Response (None)
Generates a detection report in the specified output directory.

### Request Example
```python
from lib.SigmaHunter import Sigma_Analyze

Sigma_Analyze(
    path='/logs/evtx/',
    rules_file='sigma_rules.json',
    output='/output'
)
```
```

--------------------------------

### EvtxDetection Functions

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Functions for detecting events from various Windows event logs.

```APIDOC
## EvtxDetection Functions

### Description
Provides a suite of functions to detect and analyze events from different Windows Event Log files.

### Functions
- **multiprocess**: Processes a list of files using a specified detection function with multiprocessing.
- **detect_events_security_log**: Detects events from the Security log.
- **detect_events_system_log**: Detects events from the System log.
- **detect_events_powershell_log**: Detects events from the PowerShell log.
- **detect_events_powershell_operational_log**: Detects events from the PowerShell Operational log.
- **detect_events_scheduled_task_log**: Detects events from the Scheduled Task log.
- **detect_events_windows_defender_log**: Detects events from the Windows Defender log.
- **detect_events_TerminalServices_LocalSessionManager_log**: Detects events from the Terminal Services Local Session Manager log.
- **detect_events_TerminalServices_RDPClient_log**: Detects events from the Terminal Services RDP Client log.
- **detect_events_Microsoft_Windows_WinRM**: Detects events from the Microsoft Windows WinRM log.
- **detect_events_Sysmon_log**: Detects events from the Sysmon log.
- **detect_events_group_policy_log**: Detects events from the Group Policy log.
- **detect_events_SMB_Server_log**: Detects events from the SMB Server log.
- **detect_events_SMB_Client_log**: Detects events from the SMB Client log.
- **detect_events_UserProfileService_log**: Detects events from the User Profile Service log.

### Parameters (Common to most detection functions)
- **file** (string): Path to the event log file.
- **input_timezone** (string): Timezone of the input logs.
- **timestart** (string): Start time for filtering events.
- **timeend** (string): End time for filtering events.
- **objectaccess** (bool): Flag to include object access events.
- **processexec** (bool): Flag to include process execution events.
- **logons** (bool): Flag to include logon events.
- **frequencyanalysis** (bool): Flag to perform frequency analysis.
- **allreport** (bool): Flag to generate a comprehensive report.
- **output** (string): Path for the output report.
- **cpu_cores** (int): Number of CPU cores to use for multiprocessing.
- **temp_dir** (string): Temporary directory for processing.

### Request Example
```python
detect_events_security_log(file='security.evtx', input_timezone='UTC', timestart='2023-01-01', timeend='2023-01-31', objectaccess=True, processexec=False, logons=True, frequencyanalysis=False, allreport=True, output='report.json', cpu_cores=4, temp_dir='/tmp')
```

### Response
- **output** (string): Path to the generated report file.
```

--------------------------------

### SMB Server Events Structure

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/types.md

Defines the fields for SMB server events, including client IP, username, share name, and accessed file. Event IDs range from 3000-3063.

```python
SMB_Server_events = [{
    'Date and Time': list[str],
    'timestamp': list[float],
    'Detection Rule': list[str],
    'Severity': list[str],
    'Detection Domain': list[str],
    'Event Description': list[str],
    'Client Address': list[str],           # Client IP address
    'UserName': list[str],                 # Username accessing share
    'Share Name': list[str],               # Share path
    'File Name': list[str],                # Accessed file
    'Event ID': list[str],                 # 3000-3063 range
    'Computer Name': list[str],
    'Channel': list[str],
    'Original Event Log': list[str]
}]
```

--------------------------------

### O365Hunter: Analyze Microsoft Office365 Audit Logs

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/api-reference.md

Analyze O365 audit logs with analyzeoff365 to detect threats and generate reports. Specify the audit file, detection rules, output directory, and timezone. Optionally include flattened data and provide a path to the GeoLite2 database.

```python
from lib.O365Hunter import analyzeoff365
from pytz import timezone

analyzeoff365(
    auditfile='audit_export.csv',
    rule_file='o365_rules.json',
    output='/output/o365_analysis',
    timezone=timezone('UTC'),
    include_flattened_data=False
)
```

--------------------------------

### Terminal Services Summary Structure

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/types.md

Defines the structure for a Terminal Services summary, tracking user logins and their counts.

```python
TerminalServices_Summary = [{
    'User': list[str],
    'Number of Logins': list[int]
}]
```

--------------------------------

### Detect SMB Client Log Events

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/REFERENCE.md

Detect specific events within the Windows SMB Client log. This function requires file path, timezone, time range, and various detection parameters.

```python
detect_events_SMB_Client_log(file, input_timezone, timestart, timeend, objectaccess, 
                            processexec, logons, frequencyanalysis, allreport, 
                            output, cpu_cores, temp_dir)
```

--------------------------------

### detect_events_SMB_Server_log

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/modules.md

Analyzes the SMB Server operational log for share access events. It detects lateral movement via SMB and unauthorized access to sensitive shares.

```APIDOC
## detect_events_SMB_Server_log(file, ...)

### Description
Analyzes SMB Server logs for share access events to detect lateral movement.

### Parameters
- **file** (string) - Path to the SMB Server operational log file.
- **...** (any) - Additional arguments.
```

--------------------------------

### Object Access Events Structure

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/types.md

Defines the structure for object access events, typically related to file or resource access. Captures details about the object, the accessing process, and the account.

```python
Object_Access_Events = [{
    'Date and Time': list[str],
    'timestamp': list[float],
    'Event ID': list[str],                 # Usually 4663
    'Account Name': list[str],
    'Account Domain': list[str],
    'Object Name': list[str],              # File/folder path
    'Object Type': list[str],              # File, Folder, Printer, etc.
    'Process Name': list[str],             # Accessing process name
    'Computer Name': list[str],
    'Channel': list[str],
    'Original Event Log': list[str]
}]
```

--------------------------------

### Suspicious Executables List

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/configuration.md

A list of common suspicious executable names used for process name matching in security logs. These are hardcoded within the EvtxDetection.py script.

```python
Suspicious_executables = [
    "\\mshta.exe", "\\csc.exe", "whoami.exe", "\\pl.exe", "\\nc.exe",
    "nmap.exe", "psexec.exe", "plink.exe", "mimikatz", "procdump.exe",
    "dcom.exe", "Inveigh.exe", "LockLess.exe", "Logger.exe", "PBind.exe",
    "PS.exe", "Rubeus.exe", "RunasCs.exe", "RunAs.exe", "SafetyDump.exe",
    "SafetyKatz.exe", "Seatbelt.exe", "SExec.exe", "SharpApplocker.exe",
    "SharpChrome.exe", "SharpCOM.exe", "SharpDPAPI.exe", "SharpDump.exe",
    "SharpEdge.exe", "SharpEDRChecker.exe", "SharPersist.exe",
    "SharpHound.exe", "SharpLogger.exe", "SharpPrinter.exe", "SharpRoast.exe",
    "SharpSC.exe", "SharpSniper.exe", "SharpSocks.exe", "SharpSSDP.exe",
    "SharpTask.exe", "SharpUp.exe", "SharpView.exe", "SharpWeb.exe",
    "SharpWMI.exe", "Shhmon.exe", "SweetPotato.exe", "Watson.exe",
    "WExec.exe", "7zip.exe"
]
```

--------------------------------

### Enabling Detailed Debug Logging

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/errors.md

Configures the logging module to display DEBUG level messages and provides a specific format for log output, including timestamp, level, and message. This is crucial for detailed error tracing.

```python
import logging
logging.basicConfig(level=logging.DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')
```

--------------------------------

### Set Temporary Directory Path

Source: https://github.com/ahmedkhlief/apt-hunter/blob/main/_autodocs/configuration.md

Configure the temporary directory used for intermediate CSV and pickle files. This variable is set globally in the main script.

```python
temp_dir = "temp/"
```