Skip to content

README.md

Latest commit

 

History

History
163 lines (118 loc) · 5.52 KB

README.md

File metadata and controls

163 lines (118 loc) · 5.52 KB

File Metadata Preservation Scripts for macOS

macOS-optimized scripts to preserve file modification timestamps while editing.

These scripts help you edit files while maintaining their original "Modified" date in Finder. This is useful when you need to preserve the appearance of when a file was last modified, even after editing it.

Primary Use Cases

🔴 Red Team Operations & Bait File Creation

These scripts were developed for red teaming and security testing purposes. They enable security professionals to:

  • Create Authentic Bait Files: Generate files that appear to have been created or modified at specific historical dates, making them more convincing for honeypots and deception operations
  • Maintain Operational Security: Edit files during red team exercises without leaving obvious traces of recent modification timestamps
  • Test Security Controls: Evaluate how security tools and analysts respond to files with manipulated timestamps
  • Simulate Historical Artifacts: Create files that blend into existing file systems by matching modification dates of surrounding files

Ethical Use: These scripts are intended for authorized security testing, red team exercises, and legitimate security research only. Unauthorized use to deceive or harm is strictly prohibited.

Supported File Types

The scripts work with any file type:

  • Office documents (.docx, .xlsx, .pptx, etc.)
  • Text files (.txt, .md, .json, etc.)
  • Images, videos, PDFs
  • Any file you can edit with applications

Scripts Overview

Universal Scripts (Recommended)

These scripts automatically detect macOS and use appropriate commands:

1. preserve_metadata.sh - Automated workflow

Monitors file changes and automatically restores timestamp after saving.

2. capture_timestamp.sh - Manual workflow step 1

Captures the current timestamp before editing.

3. restore_timestamp.sh - Manual workflow step 2

Restores the timestamp after editing.

Usage

Automated workflow (Recommended):

./preserve_metadata.sh yourfile.ext

This script will:

  1. Capture the current modification time
  2. Open the file in your default application
  3. Monitor for changes and automatically restore the timestamp when you save

Manual workflow:

# Step 1: Capture timestamp before editing
./capture_timestamp.sh yourfile.ext

# Step 2: Edit file normally, then save

# Step 3: Restore timestamp after editing
./restore_timestamp.sh yourfile.ext

Using a Reference File:

If you have a backup with the desired timestamp:

./restore_timestamp.sh yourfile.ext reference_file.ext

Setup

  1. Make the scripts executable:

    chmod +x *.sh

  2. The scripts automatically detect macOS and use:

    • stat -f %m <file> - Get modification time
    • touch -mt <YYYYMMDDHHMM.SS> <file> - Set modification time
    • open <file> - Open in default application

How It Works

The scripts use macOS system tools to:

  1. Capture the original file modification time using stat -f %m
  2. Allow normal editing - file content updates normally
  3. Restore the original filesystem timestamp using touch -mt

Red Team Considerations

When using these scripts for red team operations:

  • Forensic Detection: Advanced forensic tools may detect timestamp manipulation through:

    • File system journal analysis
    • MAC (Modified, Accessed, Created) time inconsistencies
    • Application-level metadata (e.g., Office document properties)
    • File content hash changes without timestamp updates

  • Best Practices:

    • Use reference files from the target environment when possible
    • Test timestamp restoration on similar systems before operations
    • Consider application-specific metadata that may reveal manipulation
    • Document timestamp changes for post-operation analysis

Limitations

  • File Content Changes: File content updates normally - only filesystem timestamp is preserved
  • File Permissions: Scripts need read/write access to files
  • Monitoring Accuracy: Automated script monitors file size changes
  • Application Internal Metadata: Some applications maintain internal metadata that cannot be preserved while saving changes
  • Forensic Detection: These scripts only modify filesystem timestamps. Advanced forensic analysis may still detect manipulation

Troubleshooting

"Permission denied"

Ensure you have write permissions to the file and directory.

"Command not found"

Ensure the scripts are executable: chmod +x *.sh

Timestamp not restored

Check file permissions and ensure no other processes are accessing the file.

File doesn't open

The open command may not work in all environments. Open files manually.

Examples

Red Team: Create bait file matching existing file timestamp:

# Capture timestamp from a legitimate file in the target directory
./capture_timestamp.sh ~/Documents/legitimate_document.docx

# Create/edit your bait file, then restore using the captured timestamp
./restore_timestamp.sh bait_file.docx ~/Documents/legitimate_document.docx

Preserve Excel file timestamp:

./preserve_metadata.sh report.xlsx
# Edit in Excel, save, timestamp automatically restored

Preserve document timestamp:

./capture_timestamp.sh thesis.docx
# Edit document...
./restore_timestamp.sh thesis.docx

Batch processing:

for file in *.pdf; do
    ./capture_timestamp.sh "$file"
    # Edit files...
    ./restore_timestamp.sh "$file"
done

License

These scripts are provided as-is for educational and practical use.