filestosftp/README.md

# Send-FilesToSftp.ps1

PowerShell script to transfer files to an SFTP server with regex filtering, secure credential handling, and logging.

## Prerequisites

**WinSCP .NET Assembly** (`WinSCPnet.dll`) is required. Install using one of these methods:

| Method | Steps |
|--------|-------|
| **Drop-in** | Download the [.NET assembly package](https://winscp.net/eng/downloads.php), extract `WinSCPnet.dll` next to the script |
| **NuGet** | `Install-Package WinSCP -Source nuget.org` |
| **WinSCP Installer** | Install WinSCP and check the ".NET assembly" option during setup |

The script auto-searches these locations in order:
1. `-WinScpDllPath` parameter (if provided)
2. Same directory as the script
3. `lib\` subdirectory of the script folder
4. `C:\Program Files (x86)\WinSCP\`
5. `C:\Program Files\WinSCP\`
6. NuGet package cache (`~\.nuget\packages\winscp`)

## Quick Start

```powershell
# Basic usage — prompted for password interactively
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
    -HostName "sftp.example.com" -UserName "uploader"
```

## Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `-LocalPath` | Yes | — | Local source folder to scan |
| `-RemotePath` | Yes | — | Remote SFTP destination folder |
| `-HostName` | Yes | — | SFTP server hostname or IP |
| `-UserName` | Yes | — | SFTP username |
| `-FileFilter` | No | `.*` | Regex pattern to match filenames |
| `-Port` | No | `22` | SFTP port |
| `-Credential` | No | — | `PSCredential` object |
| `-CredentialFile` | No | — | Path to saved credential XML (see below) |
| `-KeyFilePath` | No | — | Path to SSH private key (`.ppk`) |
| `-SshHostKeyFingerprint` | No | — | SSH host key fingerprint for verification |
| `-RenamePattern` | No | — | Regex pattern to match in filename for renaming on the **remote** side before upload |
| `-RenameReplacement` | No | — | Replacement string for `-RenamePattern` (supports capture groups like `$1`) |
| `-ArchivePath` | No | — | Move successfully uploaded files to this local folder (created if missing). Cannot combine with `-DeleteAfterTransfer` |
| `-LocalRenamePattern` | No | — | Regex pattern to rename the **local** file after upload (in place, or into `-ArchivePath`) |
| `-LocalRenameReplacement` | No | — | Replacement string for `-LocalRenamePattern` (supports capture groups like `$1`) |
| `-Recurse` | No | `false` | Scan subdirectories |
| `-DeleteAfterTransfer` | No | `false` | Delete local files after successful upload. Cannot combine with `-ArchivePath` |
| `-DryRun` | No | `false` | Preview transfers without uploading |
| `-LogFile` | No | — | Path to log file (logs to console if omitted) |
| `-WinScpDllPath` | No | — | Explicit path to `WinSCPnet.dll` |

## Authentication

The script supports three auth methods, checked in this order:

### 1. Credential Object (interactive or pipeline)
```powershell
$cred = Get-Credential
.\Send-FilesToSftp.ps1 -LocalPath "C:\data" -RemotePath "/uploads" `
    -HostName "sftp.example.com" -UserName "brad" -Credential $cred
```

### 2. Saved Credential File (unattended / scheduled tasks)
```powershell
# One-time setup — run as the same user that will run the scheduled task
Get-Credential | Export-Clixml -Path "C:\secure\sftp_cred.xml"

# Use in script
.\Send-FilesToSftp.ps1 -LocalPath "C:\data" -RemotePath "/uploads" `
    -HostName "sftp.example.com" -UserName "svc_upload" `
    -CredentialFile "C:\secure\sftp_cred.xml"
```

> **Note:** `Export-Clixml` encrypts credentials using Windows DPAPI, tied to the user account and machine that created the file. Only that same user on that same machine can decrypt it.

### 3. SSH Private Key
```powershell
.\Send-FilesToSftp.ps1 -LocalPath "C:\data" -RemotePath "/uploads" `
    -HostName "sftp.example.com" -UserName "svc_upload" `
    -KeyFilePath "C:\keys\id_rsa.ppk"
```

### 4. Interactive Prompt
If none of the above are provided and no key file is specified, you'll be prompted for a password at runtime.

## File Filtering (Regex)

The `-FileFilter` parameter uses PowerShell regex (case-insensitive by default).

| Filter | Matches |
|--------|---------|
| `'\.csv$'` | All CSV files |
| `'\.xlsx?$'` | `.xls` and `.xlsx` files |
| `'^report_\d{8}'` | Files starting with `report_` + 8 digits (e.g. `report_20260415.csv`) |
| `'(?-i)^Data'` | Files starting with `Data` (case-sensitive) |
| `'badge.*\.xlsx$'` | Excel files with `badge` anywhere in the name |
| `'\.(csv\|txt)$'` | CSV or TXT files |
| `'.*'` | Everything (default) |

## Usage Examples

### Transfer all CSVs
```powershell
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
    -HostName "sftp.example.com" -UserName "uploader" -FileFilter '\.csv$'
```

### Move files (delete after upload) with logging
```powershell
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
    -HostName "sftp.example.com" -UserName "svc_upload" `
    -CredentialFile "C:\secure\cred.xml" `
    -DeleteAfterTransfer -LogFile "C:\logs\sftp_transfer.log"
```

### Dry run — preview without transferring
```powershell
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
    -HostName "sftp.example.com" -UserName "uploader" -DryRun
```

### Recursive with subdirectories
```powershell
.\Send-FilesToSftp.ps1 -LocalPath "C:\data\projects" -RemotePath "/archive" `
    -HostName "sftp.example.com" -UserName "uploader" `
    -Recurse -FileFilter '\.pdf$'
```

## Local Archive & Rename After Upload

After a successful upload you can archive or rename the local source file. These are mutually exclusive with `-DeleteAfterTransfer`.

### Archive to a folder
```powershell
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
    -HostName "sftp.example.com" -UserName "uploader" `
    -ArchivePath "C:\exports\sent"
```

### Archive and rename while archiving (e.g. add `_sent` before extension)
```powershell
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
    -HostName "sftp.example.com" -UserName "uploader" `
    -ArchivePath "C:\exports\sent" `
    -LocalRenamePattern '^(.+?)(\.[^.]+)$' -LocalRenameReplacement '${1}_sent${2}'
```

### Rename local file in place (no archive, no delete)
```powershell
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
    -HostName "sftp.example.com" -UserName "uploader" `
    -LocalRenamePattern '^' -LocalRenameReplacement 'done_'
```

> `-LocalRenamePattern`/`-LocalRenameReplacement` only rename the local file — the remote name is controlled by `-RenamePattern`/`-RenameReplacement`. You can use both together.

## Renaming Files on the Remote Side

Use `-RenamePattern` (regex) and `-RenameReplacement` together to rename files on the remote side without touching the local files.

| Goal | Pattern | Replacement |
|------|---------|-------------|
| Add date before extension | `'^(.+?)(\.[^.]+)$'` | `'${1}_20260416${2}'` |
| Add prefix | `'^'` | `'processed_'` |
| Add suffix before extension | `'^(.+?)(\.[^.]+)$'` | `'${1}_done${2}'` |
| Strip `_draft` from name | `'_draft'` | `''` |
| Replace spaces with underscores | `' '` | `'_'` |

Rename uses PowerShell's `-replace` operator (regex, case-insensitive). The local file is **not** modified — only the remote destination path changes.

### Add today's date to every filename
```powershell
$date = Get-Date -Format 'yyyyMMdd'
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
    -HostName "sftp.example.com" -UserName "uploader" `
    -RenamePattern '^(.+?)(\.[^.]+)$' -RenameReplacement "${date}_`$1`$2"
```

> **Tip:** Use `-DryRun` first to preview the renamed remote paths before committing to the transfer.

## SSH Host Key Fingerprint

For production use, always provide the host key fingerprint to prevent MITM attacks:

```powershell
# Get the fingerprint from the server
ssh-keyscan sftp.example.com | ssh-keygen -lf -

# Use it in the script
.\Send-FilesToSftp.ps1 -LocalPath "C:\data" -RemotePath "/uploads" `
    -HostName "sftp.example.com" -UserName "uploader" `
    -SshHostKeyFingerprint "ssh-rsa 2048 aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99"
```

Pass `"*"` to accept any key (development/testing only — **not recommended for production**).

## Scheduled Task Setup

To run unattended via Windows Task Scheduler:

1. **Save credentials** as the service account user:
   ```powershell
   Get-Credential | Export-Clixml -Path "C:\secure\sftp_cred.xml"
   ```

2. **Create the scheduled task:**
   ```powershell
   $action = New-ScheduledTaskAction `
       -Execute "powershell.exe" `
       -Argument '-NoProfile -ExecutionPolicy Bypass -File "C:\scripts\Send-FilesToSftp.ps1" -LocalPath "C:\exports" -RemotePath "/incoming" -HostName "sftp.example.com" -UserName "svc_upload" -CredentialFile "C:\secure\sftp_cred.xml" -FileFilter "\.csv$" -DeleteAfterTransfer -LogFile "C:\logs\sftp.log"'

   $trigger = New-ScheduledTaskTrigger -Daily -At "2:00AM"

   Register-ScheduledTask -TaskName "SFTP Upload" `
       -Action $action -Trigger $trigger `
       -User "DOMAIN\svc_upload" -Password "****" `
       -RunLevel Highest
   ```

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | All files transferred (or no files matched filter) |
| `1` | One or more failures occurred |

## Log Output

Logs include timestamps and severity levels. Sample output:

```
[2026-04-16 14:30:01] [INFO] ═══ SFTP Transfer Starting ═══
[2026-04-16 14:30:01] [INFO] Local path  : C:\exports
[2026-04-16 14:30:01] [INFO] Remote path : /incoming
[2026-04-16 14:30:01] [INFO] File filter : \.csv$
[2026-04-16 14:30:01] [INFO] Found 3 file(s) matching filter
[2026-04-16 14:30:02] [SUCCESS] Connected to sftp.example.com
[2026-04-16 14:30:03] [SUCCESS] Transferred: report_20260415.csv → /incoming/report_20260415.csv  (42.3 KB)
[2026-04-16 14:30:03] [SUCCESS] Transferred: badges_export.csv → /incoming/badges_export.csv  (18.1 KB)
[2026-04-16 14:30:04] [SUCCESS] Transferred: access_log.csv → /incoming/access_log.csv  (7.8 KB)
[2026-04-16 14:30:04] [INFO] ═══ Transfer Complete ═══
[2026-04-16 14:30:04] [INFO]   Succeeded : 3
[2026-04-16 14:30:04] [INFO]   Mode      : COPY (source files retained)
```