# FEX Core SDK - Sample Forensic Image

## Overview

This directory contains resources for creating `sample-image.dd`, a sample forensic disk image for testing and evaluating the FEX Core SDK. This image is designed to work with all example applications (Python, C#, C++) without requiring real forensic evidence.

**Note:** Due to filesystem complexity, the sample image must be created using the PowerShell script with Administrator privileges. A Python alternative is provided but requires FAT32 implementation refinement for production use.

## Image Specifications

### Format and Structure

| Property | Value |
|----------|-------|
| **Format** | DD (Raw Disk Image) |
| **Filesystem** | FAT32 (recommended) or FAT16 |
| **Total Size** | 50 MB (52,428,800 bytes) |
| **Sector Size** | 512 bytes |
| **Created** | 2025-11-20 |
| **Purpose** | SDK evaluation and testing |
| **Partition Layout** | Single partition (MBR) |

### Design Principles

- **Self-contained:** Developers can run examples immediately after SDK unzip
- **Realistic:** Represents real-world forensic image structure (not toy data)
- **Diverse:** Multiple file types, sizes, directory depths for thorough testing
- **Safe:** No sensitive, copyrighted, or problematic content (AC-4 compliance)
- **Repeatable:** Automated creation for consistency across SDK versions

## File Inventory

The sample image contains the following test files organized in a realistic directory structure:

### Root Directory

| Path | Size | Type | Description |
|------|------|------|-------------|
| `README.txt` | 1.3 KB | Text | Welcome message and image overview |

### Documents/

| Path | Size | Type | Description |
|------|------|------|-------------|
| `Documents/notes.txt` | 1.1 KB | Text | Meeting notes - small text file for quick testing |
| `Documents/sample-document.txt` | 11 KB | Text | Lorem ipsum text - medium-sized document |
| `Documents/large-text.txt` | 103 KB | Text | System documentation - large text file |
| `Documents/data.csv` | 7.1 KB | CSV | Sample employee data in CSV format |
| `Documents/report.log` | 21 KB | Log | Report generation log with timestamps |

### Pictures/

| Path | Size | Type | Description |
|------|------|------|-------------|
| `Pictures/sample-photo.jpg` | 501 KB | JPEG | Sample photo (binary data with JPEG structure) |
| `Pictures/thumbnail.jpg` | 51 KB | JPEG | Smaller thumbnail image |

### Programs/

| Path | Size | Type | Description |
|------|------|------|-------------|
| `Programs/readme.txt` | 3.4 KB | Text | Explains binary files in this directory |
| `Programs/sample.dll` | 100 KB | Binary (DLL) | Placeholder DLL (non-functional, safe for distribution) |

### Logs/

| Path | Size | Type | Description |
|------|------|------|-------------|
| `Logs/system.log` | 51 KB | Log | System boot and operation logs |
| `Logs/application.log` | 31 KB | Log | Application request/response logs |
| `Logs/debug.log` | 102 KB | Log | Detailed debug traces with timestamps |

### Large Files/

| Path | Size | Type | Description |
|------|------|------|-------------|
| `Large Files/data-1mb.bin` | 1.0 MB | Binary | 1MB binary data file for performance testing |
| `Large Files/data-5mb.bin` | 5.0 MB | Binary | 5MB binary data file for larger dataset testing |

**Total:** 15 files, ~7.9 MB of test data (50 MB including filesystem overhead)

## Creating the Sample Image

### Prerequisites

- Windows 10/11 or Windows Server 2016+
- PowerShell 5.1 or later
- Administrator privileges (for PowerShell method)
- Python 3.14+ (for Python method, optional)
- ~100MB free disk space

### Method 1: PowerShell Script (Recommended - Requires Admin)

This method creates a production-quality FAT32 filesystem image that FEX Core will correctly recognize and parse.

1. **Open PowerShell as Administrator**
   - Right-click PowerShell icon
   - Select "Run as Administrator"

2. **Navigate to sample-data directory**
   ```powershell
   cd "C:\path\to\FEX Core\sample-data"
   ```

3. **Run the creation script**
   ```powershell
   .\create-sample-image.ps1
   ```

4. **Verify output**
   ```powershell
   ls sample-image.dd
   ```

The script will:
- Create a 50MB virtual hard disk (VHDX)
- Initialize with MBR partition table
- Format as FAT32 filesystem
- Copy all test files from `staging/` directory
- Convert to raw DD format
- Validate size and file count

### Method 2: Python Script (Cross-Platform - Experimental)

This method creates a FAT32 image without requiring admin privileges, but the current implementation has limitations.

```bash
python create-sample-image.py
```

**Known Limitations:**
- FAT32 boot sector implementation needs refinement
- FEX Core may detect as FAT16 instead of FAT32
- Directory entries may not enumerate correctly
- **Use PowerShell method for production images**

### Method 3: Manual Creation

For advanced users who want full control:

1. Create virtual disk with `diskpart` or `Disk Management`
2. Format as FAT32
3. Copy files from `staging/` directory
4. Export to raw DD format using `dd` for Windows or similar tool

See `create-sample-image.ps1` for detailed implementation steps.

## Using the Sample Image

The bundled `FexViewer.exe` (C# example) is the easiest way to run the
sample. From the bundle root:

```powershell
$env:FEX_LICENSE_KEY = "FEX2-...your-key..."
.\examples\csharp\bin\Release\net8.0\FexViewer.exe info    --image sample-data\sample-image.dd
.\examples\csharp\bin\Release\net8.0\FexViewer.exe list    --image sample-data\sample-image.dd
.\examples\csharp\bin\Release\net8.0\FexViewer.exe extract --image sample-data\sample-image.dd `
                                                            --path / --out C:\out --dry-run
```

`info` prints metadata as JSON, `list` enumerates the filesystem, and
`extract` writes file content to disk. See
[Quick Start (C#)](../docs/quick-start-csharp.html) in the bundled
documentation for the full walk-through.

## License Keys

A license key issued by GetData is required. The pre-built
`FexViewer.exe` in this bundle ships with the recipient customer's key
embedded, so it runs without any environment configuration. To override
or use a different key, set `FEX_LICENSE_KEY` in your shell or pass
`--license <key>` on the command line.

### For Production

Contact GetData for a production SDK license:
- **Email:** support@getdata.com
- **Website:** https://www.getdataforensics.com

## Troubleshooting

### Image Creation Issues

**Problem:** PowerShell script fails with "Access Denied"
- **Solution:** Ensure you're running PowerShell as Administrator
- **Verification:** Check window title says "Administrator: Windows PowerShell"

**Problem:** Python script creates image but FEX Core shows no files
- **Solution:** Use PowerShell method instead (see Method 1 above)
- **Root Cause:** Python FAT32 implementation needs boot sector refinement

**Problem:** "Cannot find staging directory"
- **Solution:** Ensure all test files were created first
- **Check:** Verify `sample-data/staging/` directory exists with 15 files

### Image Usage Issues

**Problem:** "License key validation failed"
- **Solution:** Verify the key starts with `FEX2-` and was issued by GetData. Legacy GUID keys from pre-1.3.0 are not accepted.
- **Check:** Confirm `FEX_LICENSE_KEY` environment variable is set
- **Expiry:** Ensure the embedded expiry date is in the future

**Problem:** "Image format not supported"
- **Solution:** Verify file extension is `.dd` and file exists
- **Check:** Use absolute path or verify relative path is correct

**Problem:** "No files found" in listing
- **Solution:** Image may not have FAT32 filesystem
- **Fix:** Recreate using PowerShell script (Method 1)

### Platform-Specific Issues

**Windows:**
- Ensure ImageDLL.dll is in same directory as examples
- Verify all dependencies (libcrypto-1_1-x64.dll, etc.) are present

**Linux:**
- Use Wine or native Linux build (if available)
- Check library paths and permissions

## Technical Details

### FAT32 Filesystem Structure

```
Offset   | Size    | Description
---------|---------|----------------------------------
0x0000   | 512 B   | Boot Sector (BPB + FAT32 EBPB)
0x0200   | ~25 KB  | FAT1 (File Allocation Table 1)
0x6400   | ~25 KB  | FAT2 (File Allocation Table 2 - backup)
0xC600   | varies  | Data Area (clusters 2+)
         |         | - Cluster 2: Root Directory
         |         | - Cluster 3+: Files and subdirectories
```

### Disk Layout

```
+------------------+
| MBR (512 bytes)  |  Partition table
+------------------+
| Reserved Sectors |  Boot sector, FSInfo
+------------------+
| FAT1 (copy 1)    |  File allocation table
+------------------+
| FAT2 (copy 2)    |  Backup FAT
+------------------+
| Data Area        |  Root directory + files
|                  |
|   /README.txt    |
|   /Documents/    |
|   /Pictures/     |
|   /Programs/     |
|   /Logs/         |
|   /Large Files/  |
+------------------+
```

### Partition Table (MBR)

- **Partition Type:** 0x0C (FAT32 LBA)
- **Start Sector:** 63 (typical)
- **Total Sectors:** ~97,656 (50MB / 512 bytes)
- **Active:** Yes (bootable flag set)

## Regenerating the Image

The image can be regenerated at any time using the creation scripts. This is useful for:

- Updating test file content
- Changing filesystem parameters
- Adding/removing files
- Creating variants for different test scenarios

To regenerate:

1. Modify files in `staging/` directory
2. Run `create-sample-image.ps1` (or `.py`)
3. Verify output: `sample-image.dd` will be overwritten

**Note:** Image creation is idempotent - running the script multiple times is safe.

## Version Control

### What to Track

- ✅ `staging/` directory with all test files
- ✅ `create-sample-image.ps1` script
- ✅ `create-sample-image.py` script
- ✅ `README.md` (this file)

### What NOT to Track

- ❌ `sample-image.dd` (50MB binary, regenerable from scripts)
- ❌ `temp-image.vhdx` (temporary file created during PowerShell build)

Add to `.gitignore`:
```
sample-data/sample-image.dd
sample-data/*.vhdx
sample-data/*.vhd
```

## Support

For issues with the sample image:

- **Email:** support@getdata.com
- **SDK Documentation:** See `docs/` directory in SDK root
- **Quick Start Guide:** See `docs/quick-start.md`
- **Troubleshooting Guide:** See `docs/troubleshooting.md`

## Safety and Compliance

### No Sensitive Data (AC-4 Compliance)

This image contains **only synthetic test data**:

- ✅ No real investigation data
- ✅ No personally identifiable information (PII)
- ✅ No copyrighted content
- ✅ No sensitive or confidential information
- ✅ Safe for distribution to customers without legal/privacy concerns

All files are self-created or public domain. All names, data, and content are fictional.

### File Content Safety

- **Text files:** Lorem ipsum and generic log entries
- **CSV data:** Fictional employee records with generic names
- **Binary files:** Placeholder data with valid file signatures (JPEG, DLL headers)
- **Images:** Binary data patterns, not real photographs

## Appendix: Complete File Listing

```
sample-data/
├── README.md (this file)
├── create-sample-image.ps1 (PowerShell creation script)
├── create-sample-image.py (Python creation script)
├── sample-image.dd (created by scripts - 50MB)
└── staging/
    ├── README.txt
    ├── Documents/
    │   ├── data.csv
    │   ├── large-text.txt
    │   ├── notes.txt
    │   ├── report.log
    │   └── sample-document.txt
    ├── Pictures/
    │   ├── sample-photo.jpg
    │   └── thumbnail.jpg
    ├── Programs/
    │   ├── readme.txt
    │   └── sample.dll
    ├── Logs/
    │   ├── application.log
    │   ├── debug.log
    │   └── system.log
    └── Large Files/
        ├── data-1mb.bin
        └── data-5mb.bin
```

---

**Last Updated:** 2025-11-20
**Version:** 1.0
**Epic:** 6 (SDK Package & Distribution)
**Story:** 6.1 (Sample Forensic Image Creation)
