file_timestamps¶

Status:: ● Tested
Category:: File System
Function Name:: file_timestamps

Tests file timestamps with various comparison types and formats.

This test function provides comprehensive timestamp validation for files, supporting multiple timestamp types, comparison operations, and flexible date/time formats. It’s crucial for forensic analysis and system behavior validation.

Parameters¶

Parameter	Type	Description
`dst`	string	Required. The file path to examine. Supports glob patterns for dynamic path resolution.
`timestamp_type`	string	Optional. Type of timestamp to check. Default: “modified”. Options: “modified”, “accessed”, “created”.
`comparison_type`	string	Optional. How to compare timestamps. Default: “equals”. Options: “equals”, “before”, “after”, “between”, “within_last”.
`expected_time`	string/number	Optional. Expected timestamp for “equals”, “before”, “after” comparisons.
`time_format`	string	Optional. strptime format for parsing timestamp strings.
`tolerance_seconds`	integer	Optional. Tolerance in seconds for “equals” comparison.
`start_time`	string/number	Optional. Start time for “between” comparison.
`end_time`	string/number	Optional. End time for “between” comparison.
`within_duration`	string	Optional. Duration string for “within_last” comparison (e.g., “1h”, “30m”, “2d”).

Usage Examples¶

File Modification Time¶

tests:
  - name: verify_recent_modification
    function: file_timestamps
    parameter:
      dst: "/var/log/application.log"
      timestamp_type: "modified"
      comparison_type: "within_last"
      within_duration: "1h"
    description: "Verify log file was modified within the last hour"

Exact Timestamp Verification¶

tests:
  - name: verify_creation_time
    function: file_timestamps
    parameter:
      dst: "/tmp/generated_file.txt"
      timestamp_type: "created"
      comparison_type: "equals"
      expected_time: "2024-01-15 14:30:00"
      time_format: "%Y-%m-%d %H:%M:%S"
      tolerance_seconds: 30
    description: "Verify file was created at expected time (±30s)"

Time Range Validation¶

tests:
  - name: verify_access_window
    function: file_timestamps
    parameter:
      dst: "/home/user/document.pdf"
      timestamp_type: "accessed"
      comparison_type: "between"
      start_time: "2024-01-15 09:00:00"
      end_time: "2024-01-15 17:00:00"
      time_format: "%Y-%m-%d %H:%M:%S"
    description: "Verify file was accessed during business hours"

Timestamp Types¶

Type	Description	Platform Notes
`modified`	File modification time	Available on all platforms
`accessed`	File access time	May not be updated on all filesystems
`created`	File creation time	Windows: true creation time; Unix: change time or birth time

Comparison Types¶

Type	Parameters Required	Description
`equals`	`expected_time`	Timestamp equals expected time (within tolerance)
`before`	`expected_time`	Timestamp is before expected time
`after`	`expected_time`	Timestamp is after expected time
`between`	`start_time`, `end_time`	Timestamp is between start and end times
`within_last`	`within_duration`	Timestamp is within specified duration from now

Time Format Support¶

Unix Timestamps

Numeric timestamps (seconds since epoch):

expected_time: 1705334400  # Unix timestamp

ISO Format

Standard ISO date/time formats:

expected_time: "2024-01-15T14:30:00"
expected_time: "2024-01-15T14:30:00Z"

Custom Formats

Use time_format for custom parsing:

expected_time: "15/01/2024 2:30 PM"
time_format: "%d/%m/%Y %I:%M %p"

Common Formats

Built-in support for common formats:

%Y-%m-%d %H:%M:%S - “2024-01-15 14:30:00”
%Y-%m-%d - “2024-01-15”
%m/%d/%Y %H:%M:%S - “01/15/2024 14:30:00”

Duration Formats¶

For within_last comparisons, use these duration formats:

Unit	Format	Examples
Seconds	`Ns`	`30s`, `120s`
Minutes	`Nm`	`5m`, `45m`
Hours	`Nh`	`2h`, `24h`
Days	`Nd`	`1d`, `7d`, `30d`

Common Use Cases¶

Log File Monitoring: Verify log files are being updated regularly
File Creation Tracking: Confirm files are created at expected times during processes
Access Pattern Analysis: Monitor when files are accessed for security analysis
Backup Verification: Ensure backup files have expected timestamps
Process Timing Validation: Verify automated processes complete within expected timeframes
Forensic Analysis: Analyze file timeline for investigation purposes

Return Values¶

Success

Returns success when timestamp comparison passes

Failure

Returns failure when timestamp comparison fails, showing expected vs actual times

Execution Error

Returns execution error when:

File cannot be found or accessed
Invalid timestamp format or comparison type
Permission denied accessing file metadata
Path resolution fails

Example Results¶

# Success case
result: success
details:
  - "modified timestamp is within last 1h"

# Failure case
result: failed
details:
  - "modified timestamp mismatch. Expected: 2024-01-15 14:30:00, Got: 2024-01-15 15:45:00"

# Execution error case
result: execution_error
error: "ValueError: Cannot parse timestamp: invalid_date"
context: "Timestamp parsing/comparison error"