Lua で SFTP による安全なファイル転送
SSH 対応の libcurl と Lua-cURL を使い、SFTP ディレクトリの一覧を取得して、名前を指定した単一のファイルをダウンロードします。この例では、サーバーのホスト鍵を検証し、転送にシェルを呼び出すことなく、バイナリファイルや空ファイルを保存します。LuaSocket の
socket.ftp は、SFTP とは異なるプロトコルである平文の FTP を実装しています。
セキュリティ上の考慮事項
既存の SFTP アカウントを用意し、管理者からホスト名、ポート、ユーザー名、アカウントの chroot 内でのディレクトリパスを入手します。インポーターを実行する前に、送信者がそのディレクトリにファイルを配置する必要があります。クライアントの公開鍵を登録した専用の読み取り専用アカウントを使用してください。この無人実行の例では、非公開で管理する、暗号化されていないクライアント秘密鍵を使用します。
認証済みの経路でサーバーの公開ホスト鍵を取得し、非公開の OpenSSH 形式の
known_hosts ファイルを用意します。スキャンだけでは信頼性を確立できません。libcurl のホスト鍵の検証は、このファイルが設定されている場合、未知の鍵や一致しない鍵を拒否します。
このクライアントは、名前に含まれるパストラバーサルを拒否し、ファイル名をコマンドとして評価することはありません。ただし、この字句チェックでは、サーバーがシンボリックリンクをディレクトリの外部へ解決することは防げません。サーバー側には、対象データのみを含む chrootを必須としてください。chroot によるアクセス範囲の限定は、設定したサブディレクトリ単位ではなく chroot のツリー全体単位です。エントリ名に改行を含まない、信頼できるサーバーディレクトリを使用してください。libcurl の名前のみの一覧は改行区切りのため、改行を含むファイル名を曖昧さなく表現できません。
SFTP 転送環境のセットアップ
以下のセットアップは、Bash、LuaJIT 2.1、LuaRocks、C コンパイラー、make、curl、unzip、pkg-config を備えた Linux を対象とします。まず LuaJIT と libcurl の開発用ファイルをインストールしてください。pkg-config が luajit と、libssh2 および SFTP 対応でビルドされた libcurl の両方を検出できる必要があります。また、動的ローダーがそれらの共有ライブラリを読み込める必要があります。libcurl のインストール先プレフィックスを独自に指定する場合は、セットアップの実行前に、そのインストール先に合わせて PKG_CONFIG_PATH とライブラリローダーを設定してください。
テスト済みのバージョンは、LuaJIT 2.1、LuaRocks 3.8 および 3.13、Lua-cURL 0.3.13-1、LuaFileSystem 1.8.0-1、libcurl 8.21.0 および 8.22.0、libssh2 1.11.1 です。これらはテストした構成の記録です。ディストリビューションのセキュリティ更新は適用してください。固定している Lua-cURL のリリースは古いバインディングなので、変更する際は互換性を確認してください。このセットアップでは、pkg-config を通じて開発用パスを選択し、すべてのヘッダーが /usr/include 直下にあるとは仮定しません。
これを setup.sh として、新しい lua-sftp ディレクトリを作成したい親ディレクトリに保存してください。バージョンを固定した Lua-cURL rock と LuaFileSystem を、グローバルな LuaRocks ツリーではなく、そのディレクトリにインストールします。
#!/usr/bin/env bash
set -euo pipefail
unset LUA_PATH LUA_CPATH
for tool in luajit luarocks cc make curl unzip pkg-config; do
command -v "$tool" >/dev/null || { printf 'Missing prerequisite: %s\n' "$tool" >&2; exit 1; }
done
pkg-config --print-errors --exists luajit libcurl
lua_binary=$(command -v luajit)
c_compiler=$(command -v cc)
lua_include=$(pkg-config --variable=includedir luajit)
curl_include=$(pkg-config --variable=includedir libcurl)
curl_library=$(pkg-config --variable=libdir libcurl)
umask 077
mkdir lua-sftp
cd lua-sftp
curl -fsSLo lua-curl-0.3.13-1.src.rock https://luarocks.org/lua-curl-0.3.13-1.src.rock
curl -fsSLo luafilesystem-1.8.0-1.src.rock https://luarocks.org/luafilesystem-1.8.0-1.src.rock
luarocks --lua-version=5.1 --tree="$PWD/rocks" install \
lua-curl-0.3.13-1.src.rock \
LUA="$lua_binary" LUA_INCDIR="$lua_include" CC="$c_compiler" \
CURL_INCDIR="$curl_include" CURL_LIBDIR="$curl_library"
luarocks --lua-version=5.1 --tree="$PWD/rocks" install \
luafilesystem-1.8.0-1.src.rock \
LUA="$lua_binary" LUA_INCDIR="$lua_include" CC="$c_compiler"
mkdir private-imports
LUA_PATH='./rocks/share/lua/5.1/?.lua;./rocks/share/lua/5.1/?/init.lua' \
LUA_CPATH='./rocks/lib/lua/5.1/?.so' \
luajit -e 'local c=require("lcurl.safe"); print(c.version()); assert(c.version_info("protocols").SFTP, "libcurl lacks SFTP support"); assert(c.version():find("libssh2/", 1, true), "Use libcurl built with libssh2")'
bash setup.sh
lua-sftp ディレクトリがすでに存在する場合、セットアップはインストール前に停止します。インストールに失敗した場合はエラーを調べ、前提条件の問題を修正してから、新しい親ディレクトリでスクリプトを再実行してください。失敗したディレクトリは調査用に残ります。最後の検査では、Lua-cURL が使用する libcurl を報告し、SFTP 対応を確認します。システムの curl 実行ファイルは、別のライブラリを使用している場合があります。
SFTP サーバーへの接続
以下の完全なモジュールを lua-sftp/sftp_import.lua として保存してください。接続設定は信頼できる設定情報から取得します。root は、サーバーのホストファイルシステム上のパスではなく、/exports のような、SFTP から見える絶対ディレクトリパスです。クライアントの公開鍵ファイルと秘密鍵ファイルは、対応するペアである必要があります。
local curl = require("lcurl.safe")
local lfs = require("lfs")
local M = {}
local function name_ok(name)
return type(name) == "string" and #name <= 255 and name ~= "." and name ~= ".."
and name:match("^[A-Za-z0-9][A-Za-z0-9._ -]*$") ~= nil
end
local function encode(path)
return (path:gsub("([^A-Za-z0-9/_.~-])", function(byte)
return string.format("%%%02X", byte:byte())
end))
end
function M.remote_path(root, name)
assert(type(root) == "string" and root:sub(1, 1) == "/", "Absolute remote root required")
assert(not root:find("//", 1, true), "Invalid remote root")
for part in root:gmatch("[^/]+") do assert(name_ok(part), "Invalid remote root component") end
if name ~= nil then assert(name_ok(name), "Unsafe remote name") end
local prefix = root:gsub("/+$", "") .. "/"
return prefix .. (name or "")
end
local function transfer(config, path, listing, sink)
assert(config.host:match("^[A-Za-z0-9.-]+$"), "Invalid SSH hostname")
local port = config.port or 22
assert(type(port) == "number" and port == math.floor(port) and port > 0 and port < 65536, "Invalid SSH port")
local handle = assert(curl.easy({
url = "sftp://" .. config.host .. ":" .. port .. encode(path),
protocols = curl.PROTO_SFTP,
proxy = "",
username = assert(config.user),
ssh_auth_types = curl.SSH_AUTH_PUBLICKEY,
ssh_knownhosts = assert(config.known_hosts),
ssh_private_keyfile = assert(config.private_key),
ssh_public_keyfile = assert(config.public_key),
connecttimeout = 10,
timeout = 60,
dirlistonly = listing,
writefunction = sink
}))
local ok, result = pcall(function() return handle:perform() end)
handle:close()
if not ok or not result then return nil, "SFTP transfer failed" end
return true
end
function M.list_directory(config)
local chunks, length = {}, 0
local ok, err = transfer(config, M.remote_path(config.root), true, function(chunk)
length = length + #chunk
if length > 1024 * 1024 then return 0 end
chunks[#chunks + 1] = chunk
return #chunk
end)
if not ok then return nil, err end
local entries = {}
for name in table.concat(chunks):gmatch("([^\n]+)") do
if name ~= "." and name ~= ".." then
if not name_ok(name) then return nil, "Unsupported directory entry" end
entries[#entries + 1] = name
end
end
table.sort(entries)
return entries
end
function M.download(config, name, output_directory)
local remote = M.remote_path(config.root, name)
-- An exclusive directory prevents overwriting an existing file or following its symlink.
assert(lfs.mkdir(output_directory), "Output directory must be new, beneath a private parent")
local destination = output_directory .. "/" .. name
local temporary = output_directory .. "/.download.part"
local file = io.open(temporary, "wb")
if not file then return nil, "Could not create download" end
local size = 0
local called, ok, err = pcall(transfer, config, remote, false, function(chunk)
size = size + #chunk
if size > 64 * 1024 * 1024 then return 0 end
if not file:write(chunk) then return 0 end
return #chunk
end)
local closed = file:close()
if not called or not ok or not closed then
os.remove(temporary)
return nil, "Could not complete download"
end
if not os.rename(temporary, destination) then
os.remove(temporary)
return nil, "Could not publish download"
end
return destination
end
return M
ファイルとディレクトリの一覧取得
list_directory() は libcurl の名前のみのディレクトリ一覧を使用します。返されるのは名前のみで、ファイル名の場合もディレクトリ名の場合もあります。Unix の ls -l 出力を解析することも、すべてのエントリをファイルと仮定することも、一覧取得の成功をもってすべてをダウンロードする権限があると判断することもありません。
名前の制限ポリシーでは、スペース、ドット、アンダースコア、ハイフンを含む ASCII 名を許可します。スラッシュ、バックスラッシュ、制御文字、パーセントエスケープ、および
. と .. は拒否します。このポリシーを拡張する場合は、対応するエンコードとパスの範囲制限のテストも必ず追加してください。未対応の一覧エントリがある場合、list_directory() は
nil と Unsupported directory entry を返し、部分的な結果は返しません。
SFTP サーバーからのファイルのダウンロード
この呼び出し側のコードを lua-sftp/import.lua として保存してください。設定したディレクトリの一覧を取得し、操作者が指定した名前と完全に一致するファイルのみをダウンロードします。出力先の親ディレクトリは、あらかじめ非公開にし、アプリケーションが所有している必要があります。新しい子ディレクトリとそのファイルには、以下の制限的な
umask が適用されます。
local sftp = require("sftp_import")
local config = {
host = assert(os.getenv("SFTP_HOST")),
port = tonumber(os.getenv("SFTP_PORT") or "22"),
user = assert(os.getenv("SFTP_USER")),
known_hosts = assert(os.getenv("SFTP_KNOWN_HOSTS")),
private_key = assert(os.getenv("SFTP_PRIVATE_KEY")),
public_key = assert(os.getenv("SFTP_PUBLIC_KEY")),
root = assert(os.getenv("SFTP_ROOT"))
}
local wanted = assert(arg[1], "remote filename required")
local entries, err = sftp.list_directory(config)
assert(entries, err)
local found = false
for _, name in ipairs(entries) do
print(name)
if name == wanted then found = true end
end
assert(found, "Requested entry is not in the directory")
local saved, failure = sftp.download(config, wanted, assert(arg[2], "new output directory required"))
assert(saved, failure)
print("Download complete")
(
cd lua-sftp || exit 1
umask 077
export SFTP_HOST='sftp.example.com' SFTP_PORT='22' SFTP_USER='import-reader'
export SFTP_ROOT='/exports'
export SFTP_KNOWN_HOSTS='/path/to/verified_known_hosts'
export SFTP_PRIVATE_KEY='/path/to/import-key' SFTP_PUBLIC_KEY='/path/to/import-key.pub'
LUA_PATH='./rocks/share/lua/5.1/?.lua;./rocks/share/lua/5.1/?/init.lua;./?.lua' \
LUA_CPATH='./rocks/lib/lua/5.1/?.so' \
luajit import.lua 'report September.csv' private-imports/job-001
)
接続値と鍵のパスを、アカウント用に提供された値に置き換えてください。成功時の出力にはディレクトリ内の名前が表示され、最後に Download complete が出力されます。その時点で、ファイルは lua-sftp/private-imports/job-001/report September.csv にあります。バイト列またはチェックサムを送信者の元ファイルと比較して、結果を検証してください。ゼロバイトのファイルも、正常なダウンロード結果として有効です。
一覧取得は受信する名前のデータ量が 1 MiB まで、各ダウンロードは 64 MiB までに制限されます。各操作には接続時間の上限 10 秒と、接続時間を含む全体の制限時間 60 秒があります。そのため、低速な転送はサイズ上限に達する前に失敗することがあります。アクセスを拒否されたファイル、ディレクトリ、接続切断、上限超過は失敗となり、ステージングファイルが削除されます。新しいジョブディレクトリは残るため、再試行時には新しいジョブ名を使用してください。既存のジョブディレクトリは拒否され、その中のファイルは置き換えられません。
最終ファイル名が現れるのは、転送が成功してファイルが閉じられた後だけです。公開前にプロセスが中断または強制終了されると、.download.part が残る場合がありますが、最終ファイル名は現れません。ジョブの停止を確認してから、そのステージングファイルを調査または削除してください。利用側では、返された最終パスのみを使用してください。この公開処理は、マシンのクラッシュをまたいだストレージの永続性を保証するものではありません。
SFTP ファイルインポートの自動化
明示的なファイル名と新しいジョブディレクトリを指定し、スケジューラーから同じモジュールを呼び出します。対象にするエントリはアプリケーションコードで判断してください。名前のみの一覧には、ファイル種別やシンボリックリンクの情報がありません。一覧取得とダウンロードは別の操作なので、その間にサーバー上のファイルが変更される可能性があります。ファイルを変更不可にするか、サーバー側でアトミックに公開する運用を送信者と調整してください。
エラー処理とベストプラクティス
呼び出し側は、失敗すると非ゼロのステータスで終了します。認証に失敗した場合は、アカウント設定と登録済みのクライアント鍵を確認してください。ホスト鍵が変わった場合は、管理者と確認して問題を解決してから
known_hosts を更新してください。ローカルへの書き込みに失敗した場合は、非公開の出力先親ディレクトリの空き容量と権限を確認してください。鍵とログは非公開で管理し、ダウンロードを再試行するときは新しいジョブディレクトリを使用してください。
安全な転送の代替手段
引数配列を受け取る API 経由で呼び出す場合は、OpenSSH の
sftp クライアントも選択肢になります。os.execute() や io.popen() にファイル名を埋め込まないでください。HTTPS は、取得元が認証付きの HTTPS ダウンロードサービスを提供している場合に限り、別の選択肢になります。
マネージドなインポートについては、Transloadit の 🤖 /sftp/import Robot を参照してください。
