488 lines
20 KiB
PowerShell
488 lines
20 KiB
PowerShell
<#
|
|
.SYNOPSIS
|
|
Transfers files to an SFTP server with filtering and logging.
|
|
|
|
.DESCRIPTION
|
|
Moves or copies files from a local folder to a remote SFTP destination.
|
|
Supports regex/wildcard file filtering, recursive scanning, and secure
|
|
credential storage. Uses the WinSCP .NET assembly for SFTP transport.
|
|
|
|
.PARAMETER LocalPath
|
|
Local source folder to scan for files.
|
|
|
|
.PARAMETER RemotePath
|
|
Remote SFTP destination folder (e.g. /uploads/incoming).
|
|
|
|
.PARAMETER FileFilter
|
|
Regex pattern to match filenames (e.g. '\.csv$' or '^report_\d{8}').
|
|
Default: '.*' (all files).
|
|
|
|
.PARAMETER HostName
|
|
SFTP server hostname or IP.
|
|
|
|
.PARAMETER Port
|
|
SFTP port. Default: 22.
|
|
|
|
.PARAMETER UserName
|
|
SFTP username.
|
|
|
|
.PARAMETER SshHostKeyFingerprint
|
|
SSH host key fingerprint for server verification.
|
|
Use "ssh-rsa 2048 xx:xx:xx..." format, or pass "*" to accept any (NOT recommended for production).
|
|
|
|
.PARAMETER Credential
|
|
PSCredential object. If omitted, you'll be prompted interactively.
|
|
|
|
.PARAMETER CredentialFile
|
|
Path to a saved credential file (Export-Clixml). For scheduled/unattended runs.
|
|
Create one with: Get-Credential | Export-Clixml -Path "C:\secure\sftp_cred.xml"
|
|
|
|
.PARAMETER KeyFilePath
|
|
Path to a private key file for key-based auth (optional).
|
|
|
|
.PARAMETER Recurse
|
|
Scan subdirectories in LocalPath.
|
|
|
|
.PARAMETER RenamePattern
|
|
Regex pattern to match in the filename for renaming before upload.
|
|
Must be used together with -RenameReplacement.
|
|
Supports capture groups (e.g. '(.+)\.csv$' with replacement '$1_processed.csv').
|
|
|
|
.PARAMETER RenameReplacement
|
|
Replacement string for the -RenamePattern match. Supports regex capture groups ($1, ${1}, etc.).
|
|
Use '$0' to reference the full match.
|
|
|
|
.PARAMETER ArchivePath
|
|
Move successfully uploaded files to this local folder instead of leaving them in place.
|
|
The folder will be created if it does not exist.
|
|
Cannot be combined with -DeleteAfterTransfer.
|
|
|
|
.PARAMETER LocalRenamePattern
|
|
Regex pattern to match in the filename when renaming the local file after a successful upload.
|
|
Must be used with -LocalRenameReplacement.
|
|
Works standalone (rename in place) or with -ArchivePath (rename while archiving).
|
|
|
|
.PARAMETER LocalRenameReplacement
|
|
Replacement string for -LocalRenamePattern. Supports regex capture groups ($1, ${1}, etc.).
|
|
|
|
.PARAMETER DeleteAfterTransfer
|
|
Delete local files after successful upload (move behavior).
|
|
Cannot be combined with -ArchivePath.
|
|
|
|
.PARAMETER DryRun
|
|
Show what would be transferred without actually uploading.
|
|
|
|
.PARAMETER LogFile
|
|
Path to a log file. If omitted, logs to console only.
|
|
|
|
.PARAMETER WinScpDllPath
|
|
Path to WinSCPnet.dll. Default: looks in script directory, then common install paths.
|
|
|
|
.EXAMPLE
|
|
# Interactive - transfer all CSVs
|
|
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
|
|
-HostName "sftp.example.com" -UserName "uploader" -FileFilter '\.csv$'
|
|
|
|
.EXAMPLE
|
|
# Rename files by appending today's date before the extension
|
|
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
|
|
-HostName "sftp.example.com" -UserName "uploader" `
|
|
-RenamePattern '^(.+?)(\.[^.]+)$' -RenameReplacement "`$1_$(Get-Date -Format 'yyyyMMdd')`$2"
|
|
|
|
.EXAMPLE
|
|
# Add a prefix to every uploaded file
|
|
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
|
|
-HostName "sftp.example.com" -UserName "uploader" `
|
|
-RenamePattern '^' -RenameReplacement 'processed_'
|
|
|
|
.EXAMPLE
|
|
# Archive files to a local folder after upload
|
|
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
|
|
-HostName "sftp.example.com" -UserName "uploader" `
|
|
-ArchivePath "C:\exports\sent"
|
|
|
|
.EXAMPLE
|
|
# Archive and rename locally (append date) after upload
|
|
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
|
|
-HostName "sftp.example.com" -UserName "uploader" `
|
|
-ArchivePath "C:\exports\sent" `
|
|
-LocalRenamePattern '^(.+?)(\.[^.]+)$' -LocalRenameReplacement "`$1_sent`$2"
|
|
|
|
.EXAMPLE
|
|
# Rename local file in place after upload (no archive)
|
|
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
|
|
-HostName "sftp.example.com" -UserName "uploader" `
|
|
-LocalRenamePattern '^' -LocalRenameReplacement 'done_'
|
|
|
|
.EXAMPLE
|
|
# Unattended with saved credentials and move behavior
|
|
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
|
|
-HostName "sftp.example.com" -UserName "uploader" `
|
|
-CredentialFile "C:\secure\sftp_cred.xml" `
|
|
-FileFilter '^report_\d{8}' -DeleteAfterTransfer -LogFile "C:\logs\sftp.log"
|
|
|
|
.EXAMPLE
|
|
# Dry run to preview what would transfer
|
|
.\Send-FilesToSftp.ps1 -LocalPath "C:\exports" -RemotePath "/incoming" `
|
|
-HostName "sftp.example.com" -UserName "uploader" -DryRun
|
|
|
|
.EXAMPLE
|
|
# Key-based auth, recursive scan
|
|
.\Send-FilesToSftp.ps1 -LocalPath "C:\data" -RemotePath "/archive" `
|
|
-HostName "sftp.example.com" -UserName "svcaccount" `
|
|
-KeyFilePath "C:\keys\id_rsa.ppk" -Recurse
|
|
#>
|
|
|
|
[CmdletBinding(SupportsShouldProcess)]
|
|
param(
|
|
[Parameter(Mandatory)]
|
|
[ValidateScript({ Test-Path $_ -PathType Container })]
|
|
[string]$LocalPath,
|
|
|
|
[Parameter(Mandatory)]
|
|
[string]$RemotePath,
|
|
|
|
[string]$FileFilter = '.*',
|
|
|
|
[Parameter(Mandatory)]
|
|
[string]$HostName,
|
|
|
|
[int]$Port = 22,
|
|
|
|
[Parameter(Mandatory)]
|
|
[string]$UserName,
|
|
|
|
[string]$SshHostKeyFingerprint = $null,
|
|
|
|
[PSCredential]$Credential,
|
|
|
|
[string]$CredentialFile,
|
|
|
|
[string]$KeyFilePath,
|
|
|
|
[string]$RenamePattern,
|
|
|
|
[string]$RenameReplacement,
|
|
|
|
[string]$ArchivePath,
|
|
|
|
[string]$LocalRenamePattern,
|
|
|
|
[string]$LocalRenameReplacement,
|
|
|
|
[switch]$Recurse,
|
|
|
|
[switch]$DeleteAfterTransfer,
|
|
|
|
[switch]$DryRun,
|
|
|
|
[string]$LogFile,
|
|
|
|
[string]$WinScpDllPath
|
|
)
|
|
|
|
# ── Logging ──────────────────────────────────────────────────────────────────
|
|
|
|
function Write-Log {
|
|
param(
|
|
[string]$Message,
|
|
[ValidateSet('INFO','WARN','ERROR','SUCCESS')]
|
|
[string]$Level = 'INFO'
|
|
)
|
|
|
|
$timestamp = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
|
|
$entry = "[$timestamp] [$Level] $Message"
|
|
|
|
switch ($Level) {
|
|
'ERROR' { Write-Host $entry -ForegroundColor Red }
|
|
'WARN' { Write-Host $entry -ForegroundColor Yellow }
|
|
'SUCCESS' { Write-Host $entry -ForegroundColor Green }
|
|
default { Write-Host $entry }
|
|
}
|
|
|
|
if ($LogFile) {
|
|
$entry | Out-File -FilePath $LogFile -Append -Encoding utf8
|
|
}
|
|
}
|
|
|
|
# ── Locate WinSCP .NET Assembly ──────────────────────────────────────────────
|
|
|
|
function Find-WinScpDll {
|
|
$searchPaths = @(
|
|
$WinScpDllPath
|
|
(Join-Path $PSScriptRoot 'WinSCPnet.dll')
|
|
(Join-Path $PSScriptRoot 'lib\WinSCPnet.dll')
|
|
'C:\Program Files (x86)\WinSCP\WinSCPnet.dll'
|
|
'C:\Program Files\WinSCP\WinSCPnet.dll'
|
|
) | Where-Object { $_ }
|
|
|
|
foreach ($path in $searchPaths) {
|
|
if (Test-Path $path) {
|
|
return $path
|
|
}
|
|
}
|
|
|
|
# Try NuGet package in common locations
|
|
$nugetPath = Get-ChildItem -Path "$env:USERPROFILE\.nuget\packages\winscp" -Filter 'WinSCPnet.dll' -Recurse -ErrorAction SilentlyContinue |
|
|
Sort-Object LastWriteTime -Descending | Select-Object -First 1
|
|
if ($nugetPath) { return $nugetPath.FullName }
|
|
|
|
return $null
|
|
}
|
|
|
|
# ── Main ─────────────────────────────────────────────────────────────────────
|
|
|
|
try {
|
|
# ── Validate parameters ──────────────────────────────────────────────
|
|
if (($RenamePattern -and -not $RenameReplacement) -or ($RenameReplacement -and -not $RenamePattern)) {
|
|
Write-Log "-RenamePattern and -RenameReplacement must be used together." -Level ERROR
|
|
exit 1
|
|
}
|
|
if (($LocalRenamePattern -and -not $LocalRenameReplacement) -or ($LocalRenameReplacement -and -not $LocalRenamePattern)) {
|
|
Write-Log "-LocalRenamePattern and -LocalRenameReplacement must be used together." -Level ERROR
|
|
exit 1
|
|
}
|
|
if ($ArchivePath -and $DeleteAfterTransfer) {
|
|
Write-Log "-ArchivePath and -DeleteAfterTransfer cannot be used together." -Level ERROR
|
|
exit 1
|
|
}
|
|
|
|
# ── Create archive folder if needed ─────────────────────────────────
|
|
if ($ArchivePath -and -not (Test-Path $ArchivePath)) {
|
|
New-Item -ItemType Directory -Path $ArchivePath -Force | Out-Null
|
|
Write-Log "Created archive folder: $ArchivePath"
|
|
}
|
|
|
|
Write-Log "═══ SFTP Transfer Starting ═══"
|
|
Write-Log "Local path : $LocalPath"
|
|
Write-Log "Remote path : $RemotePath"
|
|
Write-Log "File filter : $FileFilter"
|
|
Write-Log "Host : ${HostName}:${Port}"
|
|
if ($RenamePattern) { Write-Log "Remote rename : '$RenamePattern' → '$RenameReplacement'" }
|
|
if ($LocalRenamePattern) { Write-Log "Local rename : '$LocalRenamePattern' → '$LocalRenameReplacement'" }
|
|
if ($ArchivePath) { Write-Log "Archive to : $ArchivePath" }
|
|
if ($DryRun) { Write-Log "*** DRY RUN MODE - No files will be transferred ***" -Level WARN }
|
|
|
|
# ── Find and load WinSCP ─────────────────────────────────────────────
|
|
$dllPath = Find-WinScpDll
|
|
if (-not $dllPath) {
|
|
Write-Log "WinSCPnet.dll not found. Install options:" -Level ERROR
|
|
Write-Log " 1) Install-Package WinSCP -Source nuget.org" -Level ERROR
|
|
Write-Log " 2) Download from https://winscp.net/eng/downloads.php (.NET assembly)" -Level ERROR
|
|
Write-Log " 3) Place WinSCPnet.dll in the same folder as this script" -Level ERROR
|
|
exit 1
|
|
}
|
|
Add-Type -Path $dllPath
|
|
Write-Log "Loaded WinSCP from: $dllPath"
|
|
|
|
# ── Resolve credentials ──────────────────────────────────────────────
|
|
$password = $null
|
|
|
|
if ($Credential) {
|
|
$password = $Credential.GetNetworkCredential().Password
|
|
}
|
|
elseif ($CredentialFile) {
|
|
if (-not (Test-Path $CredentialFile)) {
|
|
Write-Log "Credential file not found: $CredentialFile" -Level ERROR
|
|
exit 1
|
|
}
|
|
$savedCred = Import-Clixml -Path $CredentialFile
|
|
$password = $savedCred.GetNetworkCredential().Password
|
|
Write-Log "Loaded credentials from file"
|
|
}
|
|
elseif (-not $KeyFilePath) {
|
|
$promptCred = Get-Credential -UserName $UserName -Message "Enter SFTP password for $HostName"
|
|
if (-not $promptCred) {
|
|
Write-Log "No credentials provided. Aborting." -Level ERROR
|
|
exit 1
|
|
}
|
|
$password = $promptCred.GetNetworkCredential().Password
|
|
}
|
|
|
|
# ── Collect files ────────────────────────────────────────────────────
|
|
$gciParams = @{ Path = $LocalPath; File = $true }
|
|
if ($Recurse) { $gciParams['Recurse'] = $true }
|
|
|
|
$allFiles = Get-ChildItem @gciParams | Where-Object { $_.Name -match $FileFilter }
|
|
|
|
if (-not $allFiles -or $allFiles.Count -eq 0) {
|
|
Write-Log "No files matched filter '$FileFilter' in $LocalPath" -Level WARN
|
|
exit 0
|
|
}
|
|
|
|
Write-Log "Found $($allFiles.Count) file(s) matching filter"
|
|
|
|
if ($DryRun) {
|
|
Write-Log "Files that would be transferred:" -Level INFO
|
|
foreach ($f in $allFiles) {
|
|
$destName = if ($RenamePattern) { $f.Name -replace $RenamePattern, $RenameReplacement } else { $f.Name }
|
|
$localFinalName = if ($LocalRenamePattern) { $f.Name -replace $LocalRenamePattern, $LocalRenameReplacement } else { $f.Name }
|
|
$remoteDir = $RemotePath.TrimEnd('/') + ($f.DirectoryName.Substring($LocalPath.TrimEnd('\').Length) -replace '\\', '/')
|
|
$remoteDest = "$remoteDir/$destName"
|
|
$sizeKB = [math]::Round($f.Length / 1KB, 1)
|
|
$remoteRenameNote = if ($RenamePattern -and $destName -ne $f.Name) { " [remote name: $destName]" } else { '' }
|
|
Write-Log " UPLOAD : $($f.FullName) → $remoteDest (${sizeKB} KB)$remoteRenameNote"
|
|
|
|
if ($DeleteAfterTransfer) {
|
|
Write-Log " LOCAL : DELETE $($f.FullName)"
|
|
}
|
|
elseif ($ArchivePath) {
|
|
$archiveDest = Join-Path $ArchivePath $localFinalName
|
|
$localNote = if ($LocalRenamePattern -and $localFinalName -ne $f.Name) { " [renamed from $($f.Name)]" } else { '' }
|
|
Write-Log " LOCAL : MOVE → $archiveDest$localNote"
|
|
}
|
|
elseif ($LocalRenamePattern -and $localFinalName -ne $f.Name) {
|
|
$renameDest = Join-Path $f.DirectoryName $localFinalName
|
|
Write-Log " LOCAL : RENAME → $renameDest"
|
|
}
|
|
}
|
|
Write-Log "DRY RUN complete. $($allFiles.Count) file(s) would be transferred." -Level SUCCESS
|
|
exit 0
|
|
}
|
|
|
|
# ── Configure session ────────────────────────────────────────────────
|
|
$sessionOptions = New-Object WinSCP.SessionOptions -Property @{
|
|
Protocol = [WinSCP.Protocol]::Sftp
|
|
HostName = $HostName
|
|
PortNumber = $Port
|
|
UserName = $UserName
|
|
}
|
|
|
|
if ($password) {
|
|
$sessionOptions.Password = $password
|
|
}
|
|
|
|
if ($KeyFilePath) {
|
|
if (-not (Test-Path $KeyFilePath)) {
|
|
Write-Log "Private key file not found: $KeyFilePath" -Level ERROR
|
|
exit 1
|
|
}
|
|
$sessionOptions.SshPrivateKeyPath = $KeyFilePath
|
|
Write-Log "Using key-based auth: $KeyFilePath"
|
|
}
|
|
|
|
if ($SshHostKeyFingerprint) {
|
|
if ($SshHostKeyFingerprint -eq '*') {
|
|
Write-Log "Accepting any SSH host key — NOT SAFE FOR PRODUCTION" -Level WARN
|
|
$sessionOptions.GiveUpSecurityAndAcceptAnySshHostKey = $true
|
|
}
|
|
else {
|
|
$sessionOptions.SshHostKeyFingerprint = $SshHostKeyFingerprint
|
|
}
|
|
}
|
|
else {
|
|
Write-Log "No SSH host key fingerprint provided — accepting any key" -Level WARN
|
|
Write-Log " Get your fingerprint with: ssh-keyscan $HostName | ssh-keygen -lf -" -Level WARN
|
|
$sessionOptions.GiveUpSecurityAndAcceptAnySshHostKey = $true
|
|
}
|
|
|
|
# ── Open session and transfer ────────────────────────────────────────
|
|
$session = New-Object WinSCP.Session
|
|
$successCount = 0
|
|
$failCount = 0
|
|
|
|
try {
|
|
$session.Open($sessionOptions)
|
|
Write-Log "Connected to $HostName" -Level SUCCESS
|
|
|
|
# Ensure remote directory exists
|
|
if (-not $session.FileExists($RemotePath)) {
|
|
Write-Log "Creating remote directory: $RemotePath"
|
|
$session.CreateDirectory($RemotePath)
|
|
}
|
|
|
|
foreach ($file in $allFiles) {
|
|
$relativePath = ''
|
|
if ($Recurse) {
|
|
$relativePath = $file.DirectoryName.Substring($LocalPath.TrimEnd('\').Length) -replace '\\', '/'
|
|
}
|
|
|
|
$destName = if ($RenamePattern) { $file.Name -replace $RenamePattern, $RenameReplacement } else { $file.Name }
|
|
$targetDir = $RemotePath.TrimEnd('/') + $relativePath
|
|
$targetPath = "$targetDir/$destName"
|
|
|
|
if ($RenamePattern -and $destName -ne $file.Name) {
|
|
Write-Log "Renaming: $($file.Name) → $destName"
|
|
}
|
|
|
|
try {
|
|
# Ensure subdirectory exists on remote when recursing
|
|
if ($Recurse -and $relativePath -and (-not $session.FileExists($targetDir))) {
|
|
$session.CreateDirectory($targetDir)
|
|
Write-Log "Created remote dir: $targetDir"
|
|
}
|
|
|
|
$transferOptions = New-Object WinSCP.TransferOptions
|
|
$transferOptions.TransferMode = [WinSCP.TransferMode]::Binary
|
|
|
|
# Always upload without auto-delete; handle local disposition ourselves
|
|
$result = $session.PutFiles($file.FullName, $targetPath, $false, $transferOptions)
|
|
$result.Check()
|
|
|
|
$sizeKB = [math]::Round($file.Length / 1KB, 1)
|
|
Write-Log "Transferred: $($file.Name) → $targetPath (${sizeKB} KB)" -Level SUCCESS
|
|
$successCount++
|
|
|
|
# ── Local post-transfer disposition ──────────────────────
|
|
$localFinalName = if ($LocalRenamePattern) { $file.Name -replace $LocalRenamePattern, $LocalRenameReplacement } else { $file.Name }
|
|
|
|
if ($DeleteAfterTransfer) {
|
|
Remove-Item -LiteralPath $file.FullName -Force
|
|
Write-Log "Deleted local: $($file.FullName)"
|
|
}
|
|
elseif ($ArchivePath) {
|
|
# Preserve subdirectory structure when recursing
|
|
$archiveDir = if ($Recurse -and $relativePath) {
|
|
$sub = $file.DirectoryName.Substring($LocalPath.TrimEnd('\').Length).TrimStart('\')
|
|
Join-Path $ArchivePath $sub
|
|
} else { $ArchivePath }
|
|
|
|
if (-not (Test-Path $archiveDir)) {
|
|
New-Item -ItemType Directory -Path $archiveDir -Force | Out-Null
|
|
}
|
|
|
|
$archiveDest = Join-Path $archiveDir $localFinalName
|
|
Move-Item -LiteralPath $file.FullName -Destination $archiveDest -Force
|
|
$archiveNote = if ($localFinalName -ne $file.Name) { " (renamed from $($file.Name))" } else { '' }
|
|
Write-Log "Archived: $($file.FullName) → $archiveDest$archiveNote"
|
|
}
|
|
elseif ($LocalRenamePattern -and $localFinalName -ne $file.Name) {
|
|
$renameDest = Join-Path $file.DirectoryName $localFinalName
|
|
Rename-Item -LiteralPath $file.FullName -NewName $localFinalName -Force
|
|
Write-Log "Renamed local: $($file.Name) → $localFinalName"
|
|
}
|
|
}
|
|
catch {
|
|
Write-Log "FAILED: $($file.Name) — $($_.Exception.Message)" -Level ERROR
|
|
$failCount++
|
|
}
|
|
}
|
|
}
|
|
finally {
|
|
if ($session) { $session.Dispose() }
|
|
}
|
|
|
|
# ── Summary ──────────────────────────────────────────────────────────
|
|
Write-Log "═══ Transfer Complete ═══"
|
|
Write-Log " Succeeded : $successCount"
|
|
if ($failCount -gt 0) {
|
|
Write-Log " Failed : $failCount" -Level ERROR
|
|
}
|
|
if ($DeleteAfterTransfer) {
|
|
Write-Log " Mode : MOVE (source files deleted on success)"
|
|
}
|
|
elseif ($ArchivePath) {
|
|
Write-Log " Mode : ARCHIVE → $ArchivePath"
|
|
}
|
|
else {
|
|
Write-Log " Mode : COPY (source files retained)"
|
|
}
|
|
|
|
if ($failCount -gt 0) { exit 1 }
|
|
}
|
|
catch {
|
|
Write-Log "Fatal error: $($_.Exception.Message)" -Level ERROR
|
|
Write-Log $_.ScriptStackTrace -Level ERROR
|
|
exit 1
|
|
}
|