UI-1: Add Additional Command Line Parameters

[jonnybottles]

Proposed Solution

Add consistent command line parameters to both investigation commands (Start-HawkTenantInvestigation and Start-HawkUserInvestigation) that allow specifying all configuration options currently handled through interactive prompts.

Parameters to add to both commands:

• SkipUpdate (switch)
• DaysToLookBack (integer, 1-365)
• StartDate (datetime)
• EndDate (datetime)
• FilePath (string path)

Technical Requirements

Parameter Implementation:

• Use standard PowerShell parameter attributes and validation.
• Maintain backward compatibility with existing interactive prompts when parameters aren't specified.
• Parameters should pass through to Initialize-HawkGlobalObject.

Input Validation Requirements:

• DaysToLookBack: Must be between 1-365 days.
• StartDate/EndDate:
  • Must be valid datetime objects.
  • StartDate must be before EndDate.
  • Date range cannot exceed 365 days.
• FilePath:
  • Must be a valid file system path.

Parameter Priority Logic:

• If both DaysToLookBack and StartDate are specified, StartDate takes precedence.
• If EndDate is specified, but StartDate or DaysToLookBack is not specified, present an error or message to teh user
• If no date parameters are specified, default to a 90-day lookback, with message presented to user
• If EndDate is not specified, default to the current date.
• if FilePath is not passed, present error or message specifying that the user must specify a filepath when running in non-interactive mode
• Either all requierd paramters are specified or it doesnt work, if no parameters are specified, it drops to interactive mode.

Help Documentation:

• Update command help documentation to include new parameters.
• Add examples showing parameter usage.
• Document parameter validation rules.

---

Implementation Approach

1. Add Parameter Validation:

   • Implement internal parameter validation functions for each parameter passed
   • Implement a larger parameter validation function that calls the smaller more fine grained parameter validation functions
   • Implement validation for all parameters.
   • Create clear error messages for validation failures.
   • Handle edge cases appropriately.

2. Update Both Investigation Commands:

   • Add new parameters.
   • Calls the larger internal parameter validation function
   • Pass validated parameters to Initialize-HawkGlobalObject.
   • Maintain existing interactive prompts as a fallback.

3. ** Implement DaysToLookBack to startdate / enddate internal function

• DaysToLookBack is not referenced by other commands throughout hawk for timeline constraints, instead startdate and enddate are. As such the hawkglobalbject variables of StartDate and EndDate need to be populated by converting the DaysToLookBack into the appropriate startdate and enddate

3. **Update Initialize-HawkGlobaObject

• populate command line passed parameters as early in initalizehawkglobal object as possible or where it makes the most sense
• Do not detect license type if StartDate, EndDate or DaysToLookBack are not null
• Do not check for most recent version of hawk or attempt to update hawk if SkipUpdate is passed
• Do note prompt user for startdate or enddate if startdate and endate are null

5. Add Logging:
   • Log parameter values used.
   • Log validation failures.
   • Log parameter priority decisions.

---

Acceptance Criteria

• Both commands accept all listed parameters.
• All parameter validation rules are enforced.
• Parameters correctly pass through to Initialize-HawkGlobalObject.
• Interactive prompts still work when parameters are not specified.
• Help documentation is updated.
• Existing functionality is maintained when no parameters are used.

---

Dependencies

• Existing Initialize-HawkGlobalObject parameter handling.

---

Impact

This change will:

• Improve automation capabilities.
• Reduce manual intervention needed.
• Maintain backward compatibility.
• Add consistent parameter handling across commands.
• Improve validation and error handling.

[jonnybottles]

Implementation Plan is below:

This implementation aims to enhance Hawk's tenant and user investigation commands by adding non-interactive parameter support while maintaining backward compatibility with existing interactive functionality. The primary goal is to enable automated execution through command-line parameters without requiring user interaction.
Key Requirements and Design Decisions
Parameter Implementation:
We will add the following parameters to both Start-HawkTenantInvestigation and Start-HawkUserInvestigation:

StartDate: Specifies investigation start date
EndDate: Specifies investigation end date
DaysToLookBack: Alternative to date range, specifies lookback period from current date
FilePath: Output location for investigation results
SkipUpdate: Bypasses update checks
NonInteractive: Enforces parameter validation requirements

Validation Requirements:
The implementation requires comprehensive parameter validation when running in non-interactive mode. Key validation rules include:

FilePath must be specified in non-interactive mode
Either DaysToLookBack OR both StartDate and EndDate must be provided
DaysToLookBack must be between 1-365 days
StartDate must precede EndDate
Date range cannot exceed 365 days
All parameters must be validated before processing begins

Error Handling:
We decided to implement error handling using PSFramework's built-in capabilities for consistent error reporting. In non-interactive mode, validation failures will throw terminating errors rather than falling back to prompts.
Update Checking:
The SkipUpdate parameter will take precedence over existing update check functionality, while maintaining current behavior when not specified. The system will log when update checks are skipped due to this parameter.
Implementation Structure:
The solution uses a two-stage validation approach:

Early Parameter Validation:

Occurs immediately when commands run
Validates parameter presence and basic validity
Checks parameter interdependencies
Enforces date range constraints
Uses PSFramework for validation and error handling

Detailed Processing:

Maintains existing Initialize-HawkGlobalObject logic
Preserves current logging infrastructure
Modifies behavior based on NonInteractive parameter
Converts DaysToLookBack to appropriate StartDate/EndDate values

Default Behavior:

Interactive mode remains default when no parameters specified
Non-interactive mode enforces strict parameter requirements
All datetime operations use UTC consistently
Existing logging patterns maintained for troubleshooting

Technical Implementation:
The implementation includes:

New parameter validation function in internal/functions
Modifications to Initialize-HawkGlobalObject
Updated help documentation
Enhanced error handling using PSFramework
Parameter validation before processing begins
DaysToLookBack conversion to StartDate/EndDate