# 📁 パストラバーサル (Path Traversal) 攻撃
> **ファイル名に `../` を入れて、サーバーに置き場の外のファイルを読ませる (書かせる) 攻撃**

![パストラバーサル: 攻撃者がファイル名を ../../app/.env に書き換えると、サーバーは置き場 /srv/uploads のパスにそのままつなぎ、.. をたどって置き場の外の /app/.env を開いて返す。.. は 1 つ上のディレクトリ](path-traversal.svg)

ファイル名を受け取って、置き場 (例: `/srv/uploads`) のファイルを返す機能があります。名前をそのまま置き場のパスにつなぐと、`..` (1 つ上のディレクトリ) をたどって、置き場の外の設定ファイル・秘密鍵・ソースコードまで届きます。

## 📚 攻撃手順
次の 3 つがそろうと成立します。

![パストラバーサルが成立する 3 つの条件: 1. 利用者が、ファイル名を決められる、2. その名前を、そのままパスにつなぐ、3. 置き場の中かを確かめない。どれか 1 つでも欠ければ成立しない](conditions.svg)

```mermaid
sequenceDiagram
    autonumber
    actor Attacker as 👿 攻撃者<br/>ふつうの利用者
    participant App as 🚀 正規サーバー<br/>api.example
    participant FS as 📁 サーバーのファイル<br/>/srv/uploads・/app

    rect rgb(150, 150, 150)
        Note over Attacker,FS: ふだんは /files?name=report.pdf で、置き場の /srv/uploads/report.pdf を取る
    end

    rect rgb(150, 100, 100)
        Note over Attacker,App: ファイル名に ../ を入れて送る
        Attacker->>+App: GET /files?name=../../app/.env
        App->>+FS: /srv/uploads/../../app/.env を開く
        Note right of App: .. を 2 回たどり、置き場の外の /app/.env になる
        FS-->>-App: .env の中身 (DB のパスワード・API キー)
        App-->>-Attacker: 200 OK (ファイルの中身)
    end

    rect rgb(150, 100, 100)
        Note over Attacker,App: ほかのファイルも、名前を変えて読む
        loop name = ../../etc/passwd, ../../app/src/settings.py, ...
            Attacker->>App: GET /files?name=...
            App-->>Attacker: 置き場の外のファイル
        end
    end
```

 - 攻撃者は、ダウンロードというふつうの機能を使うだけです。ログインの確認は通ります
 - 置き場からどれだけ深いかを知らなくても届きます。`/` より上には行けないので、`../` を多めに並べれば (`../../../../../app/.env`) 必ず `/` に着きます
 - 読むだけでなく、書き込みにも起きます。アップロードや ZIP の展開で名前を `../../app/main.py` にされると、置き場の外のファイルを上書きされます

<details><summary>💻 <b>コードで見る: ① の名前はどう開かれるか</b></summary>

② で狙われるサーバーの実装 (FastAPI の例)

```python
from pathlib import Path

from fastapi.responses import FileResponse

# ... ほかの import と、User・current_user の定義 (省く)

UPLOAD_DIR = Path("/srv/uploads")


@app.get("/files")
def download(name: str, user: Annotated[User, Depends(current_user)]) -> FileResponse:
    # 利用者が渡した名前を、そのまま置き場のパスにつなぐ
    return FileResponse(UPLOAD_DIR / name)
```

① で次のリクエストが届くと、② で `/srv/uploads/../../app/.env` を開きます。

```http
GET /files?name=../../app/.env HTTP/1.1
Host: api.example
Authorization: Bearer <攻撃者のトークン>
```

OS は `..` を 1 つ上のディレクトリとしてたどるので、`/srv/uploads` → `/srv` → `/` → `/app/.env` になります。

`../` を文字列で弾いても、同じ名前を別の書き方で渡されます (FastAPI 0.162・uvicorn で確かめた結果)。

| 渡される値 | アプリが受け取る名前・開くパス |
|:--|:--|
| `?name=..%2f..%2fapp%2f.env` | `../../app/.env` (クエリはデコードされて届く) |
| `?name=%2e%2e%2f%2e%2e%2fapp%2f.env` | `../../app/.env` (`.` も `%2e` で書ける) |
| `?name=/app/.env` | `/app/.env`。pathlib の `/` は、右が絶対パスだと左 (置き場) を捨てる |
| `?name=....//....//app/.env` | `"../"` を消す自作の確認 (`replace("../", "")`) の後で、`../../app/.env` になる |
| `?name=..%252f..%252fapp%252f.env` | `..%2f..%2fapp%2f.env`。アプリがもう一度デコード (`unquote`) すると `../../app/.env` |
| `/files/{name:path}` に `/files/..%2f..%2fapp%2f.env` | `../../app/.env` (パスの `%2f` も `/` にデコードされる) |
| `..\..\app\.env` | Windows のサーバーなら、`\` も区切りになる |

 - URL のパスに `../` をそのまま書くと、ブラウザや多くのクライアントは送る前に消します。攻撃者は `curl --path-as-is` などでそのまま送ります (uvicorn は消さずにアプリへ渡します)
 - `:path` の付かない `/files/{name}` は、`/` を含む値 (`%2f` も) に一致せず 404 になります。それでも `/files/%2e%2e` のように `..` 1 つは届きます
 - Python では、`\x00` の入ったパスは `ValueError` になります。ほかの言語のように、後ろに付けた拡張子 (`.pdf`) を `\x00` で切り捨てる手口は効きません。ただし例外を捕まえないと 500 になります

</details>

## 💥 被害例
サーバーのプロセスが読めるファイルは、すべて狙われます。

| 狙われるファイル | 被害 |
|:--|:--|
| 設定ファイル・`.env` | DB のパスワードや API キーを読まれ、DB や外部サービスに入られる |
| 環境変数 (`/proc/self/environ`) | コンテナに渡した秘密 (DB の URL・API キー) を読まれる |
| クラウドの鍵 (サービスアカウントの鍵の JSON など) | クラウドの API を、サーバーの権限で呼ばれる |
| ソースコード | ほかの脆弱性や、書き込まれた秘密を探される |
| ほかの利用者のファイル | 置き場の別の場所 (他人・他社のディレクトリ) を読まれる |
| 書き込み (アップロード・ZIP の展開) | コードや設定を上書きされ、任意のコードを実行される |
| Web サーバーの文書の外 | 例: 2021 年の Apache HTTP Server 2.4.49 (CVE-2021-41773)。`.%2e/` で文書のディレクトリの外を読め、CGI が有効だとコードも実行された |

## 🛡️ 対策
ケースごとに、次の対策を組み合わせます。MUST は必ず、SHOULD は当てはまらない理由が無い限り、WANT は必要なときに実装します。

| ケース | 対策 |
|:--|:--|
| 利用者のファイルを保存する・返す | 🪪 ID で引き、置き場の名前はサーバーが決める |
| 決まったファイルから選ばせる (テンプレート・帳票の種類など) | 🪪 名前ではなくキーで受け、サーバーの表で引く |
| どうしても名前・パスを受け取る | 🧭 正規化してから、置き場の中かを確かめる |
| ZIP・tar を展開する | 📦 展開する前に、置き場の外に出ないかを確かめる |
| どのケースでも | 🔒 プロセスの権限を絞る・🪣 ファイルをアプリのディスクに置かない |

<details><summary>[MUST] 🪪 <b>ID で引く / 置き場の名前はサーバーが決め、利用者の名前をパスに使わない</b></summary>

```python
import uuid
from pathlib import Path

from fastapi import HTTPException, UploadFile
from fastapi.responses import FileResponse
from sqlalchemy import select

# ... ほかの import と、User・current_user・get_session・StoredFile の定義 (省く)

UPLOAD_DIR = Path("/srv/uploads")


@app.post("/files")
def upload(
    file: UploadFile,
    user: Annotated[User, Depends(current_user)],
    session: Annotated[Session, Depends(get_session)],
) -> dict[str, int]:
    # 置き場の名前は、サーバーが作る (推測できず、../ も / も入らない)
    storage_key = uuid.uuid4().hex
    (UPLOAD_DIR / storage_key).write_bytes(file.file.read())  # ... 大きさの上限 (省く)
    # 利用者が付けた名前は、DB に残すだけ
    stored = StoredFile(tenant_id=user.tenant_id, storage_key=storage_key, name=file.filename or "file")
    session.add(stored)
    session.commit()
    return {"id": stored.id}


@app.get("/files/{file_id}")
def download(
    file_id: int,
    user: Annotated[User, Depends(current_user)],
    session: Annotated[Session, Depends(get_session)],
) -> FileResponse:
    # 持ち主で絞って取る (IDOR の対策)
    stored = session.scalar(
        select(StoredFile).where(StoredFile.id == file_id, StoredFile.tenant_id == user.tenant_id)
    )
    if stored is None:
        raise HTTPException(status_code=404)
    # 利用者が付けた名前は、ダウンロードするときのファイル名に使うだけで、パスには使わない
    return FileResponse(UPLOAD_DIR / stored.storage_key, filename=stored.name)
```

① は、名前 (`name`) を受け取らないので起きません。ID が他社のファイルなら 404 です ([IDOR の資料](../IDOR/README.md))。

決まったファイルから選ばせるときも、名前ではなくキーで受け、サーバーの表で引きます。

```python
from enum import StrEnum

TEMPLATE_DIR = Path("/app/templates")


class Report(StrEnum):
    INVOICE = "invoice"
    RECEIPT = "receipt"


# キーと実際のファイルの対応は、サーバーが持つ
TEMPLATES = {Report.INVOICE: "invoice.html", Report.RECEIPT: "receipt.html"}


@app.get("/reports/{report}")
def report(report: Report) -> FileResponse:
    # Report に無い値は、FastAPI が 422 で弾く
    return FileResponse(TEMPLATE_DIR / TEMPLATES[report])
```

 - ⚠️ 利用者が付けた名前を、`Content-Disposition` 以外 (パス・オブジェクトの名前・コマンドの引数) に使わないでください
 - ⚠️ 拡張子を確かめても防げません。`name.endswith(".pdf")` は `../../secret.pdf` を通します

</details>

<details><summary>[MUST] 🧭 <b>正規化してから、置き場の中かを確かめる / 名前を受け取るしかないとき</b></summary>

```python
from pathlib import Path

from fastapi import HTTPException
from fastapi.responses import FileResponse

# ... ほかの import と、User・current_user の定義 (省く)

# 置き場も、先に正規化しておく (シンボリックリンクを解いた実際のパスと比べるため)
UPLOAD_DIR = Path("/srv/uploads").resolve()


def resolve_inside(base: Path, name: str) -> Path | None:
    """name を base につなぎ、base の中のファイルなら、その実際のパスを返す"""
    try:
        # .. とシンボリックリンクを解き、OS が実際に開くパスにする。右が絶対パスでも、ここで外に出たと分かる
        path = (base / name).resolve()
    except ValueError:
        # \x00 の入った名前は、resolve が ValueError を投げる
        return None
    # 置き場の中で、しかもファイルであること。"" や "." は置き場そのもの (ディレクトリ) になる
    if not path.is_relative_to(base) or not path.is_file():
        return None
    return path


@app.get("/files")
def download(name: str, user: Annotated[User, Depends(current_user)]) -> FileResponse:
    path = resolve_inside(UPLOAD_DIR, name)
    if path is None:
        raise HTTPException(status_code=404)
    return FileResponse(path)
```

① の `../../app/.env` は `/app/.env` に解けて、置き場の中ではないので 404 になります。上の表の書き方も、デコードされた後の名前を正規化して比べるので弾かれます。

 - ⚠️ 文字列の先頭で比べないでください。`str(path).startswith("/srv/uploads")` は `/srv/uploads-old/...` を通します。`is_relative_to` はパスの区切りごとに比べます
 - ⚠️ `..` を文字列で消すやり方 (`name.replace("../", "")`) は、`....//` で破られます (消した後に `../` が残る)
 - ⚠️ 正規化した後で、もう一度デコード (`unquote`) しないでください。確かめたものと違うパスを開きます
 - ⚠️ FastAPI (Starlette) の `StaticFiles` は、絶対パスを拒否し、`realpath` で解いて置き場の外なら 404 にします。静的ファイルを配るだけなら、自分で書かずにこれを使います
 - ⚠️ この確認は「置き場の中か」までです。置き場の中の、他人のファイルを開かれるのは防げません。持ち主の確認には 🪪 の形が要ります
 - ⚠️ 確かめた後で `FileResponse` がパスを開き直すまでの間に、置き場に書き込める者が途中のディレクトリや最後の要素をシンボリックリンクに差し替えると、確かめていないパスを開かれます (TOCTOU)。利用者が置き場に書き込めるなら、🪪 の形にします

</details>

<details><summary>[SHOULD] 📦 <b>アーカイブを安全に展開する / ZIP・tar の中の名前で、置き場の外に書かせない (Zip Slip)</b></summary>

ZIP や tar の中のファイル名も、攻撃者が決められます。`../../app/main.py` という名前を入れたアーカイブを展開させると、置き場の外のファイルを上書きされます。

```python
import tarfile
import zipfile
from pathlib import Path


def extract(archive: Path, dest: Path) -> None:
    if zipfile.is_zipfile(archive):
        with zipfile.ZipFile(archive) as zf:
            # extractall は、名前の .. と先頭の / を取り除き、dest の中に展開する
            zf.extractall(dest)
    else:
        with tarfile.open(archive) as tf:
            # filter="data": dest の外に出る名前・外や絶対パスを指すリンク・デバイスファイルを拒否し、先頭の / を取り除く
            # Python 3.14 は既定で "data" だが、意図を残すために書く
            tf.extractall(dest, filter="data")
    # ... 展開する前の、合計の大きさとファイル数の上限 (ZIP 爆弾の対策。パストラバーサル以外なので省く)
```

```python
# ❌ 中の名前を自分でつなぐと、../../evil.txt は dest の外に書かれる
with zipfile.ZipFile(archive) as zf:
    for name in zf.namelist():
        (dest / name).write_bytes(zf.read(name))
```

 - ⚠️ 名前を自分でつなぐ必要があるときは、🧭 の `resolve_inside` と同じく、`(dest / name).resolve()` が `dest` の中にあり `dest` そのものではないことを確かめてから書きます (書き込みなので `is_file()` は外します。親ディレクトリだけを見ると、最後の要素がシンボリックリンクのときに外へ書かれます)
 - ⚠️ tar の `filter` は Python 3.12 で入りました (3.8〜3.11 にも、2023 年のセキュリティ更新で入っています)。`filter` の無い古い Python や、ほかの言語・ライブラリで展開するときは、同じ確認を自分で書きます

</details>

<details><summary>[SHOULD] 🔒 <b>プロセスの権限を絞る / 外に出られても、読めるもの・書けるものを減らす</b></summary>

```dockerfile
# root で動かさない。読めるのは、appuser に許したファイルだけになる
RUN useradd --system --no-create-home appuser
USER appuser
```

 - ⚠️ root でなくても、アプリ自身のソースコードや環境変数 (`/proc/self/environ`) は読めます。秘密はファイルや環境変数に平文で置かず、Secret Manager から必要なときに取ると、読まれる量を減らせます
 - ⚠️ 書き込める場所は、置き場だけにします。ソースコードや設定のディレクトリを、アプリの利用者が書き込めないようにします
 - ⚠️ MUST の対策の代わりにはなりません。被害を小さくするための二段目です

</details>

<details><summary>[WANT] 🪣 <b>(設計) ファイルをアプリのディスクに置かない / Cloud Storage に置き、署名付き URL で配る</b></summary>

```python
import os
from datetime import timedelta

import google.auth
from google.auth.transport.requests import Request
from google.cloud import storage

# ... ほかの import と、User・current_user・get_session・StoredFile の定義 (省く)

# バケット・署名する SA・URL の宛先は、環境ごとの設定 (環境変数) から渡す
bucket = storage.Client().bucket(os.environ["UPLOAD_BUCKET"])
SIGNER = os.environ["SIGNER_SERVICE_ACCOUNT"]
# ローカルのエミュレーターでは、ブラウザから届く宛先を渡す。本番では設定せず、storage.googleapis.com にする
ENDPOINT = os.environ.get("SIGNED_URL_ENDPOINT", "https://storage.googleapis.com")


def signed_download_url(storage_key: str) -> str:
    # Cloud Run の既定の認証情報には秘密鍵が無いので、IAM の signBlob で SIGNER として署名する (トークンを渡す)
    credentials, _ = google.auth.default()
    credentials.refresh(Request())  # ... トークンの使い回し (省く)
    return bucket.blob(storage_key).generate_signed_url(
        version="v4",
        expiration=timedelta(minutes=5),
        method="GET",
        response_disposition="attachment",
        service_account_email=SIGNER,
        access_token=credentials.token,
        api_access_endpoint=ENDPOINT,
    )


@app.get("/files/{file_id}")
def download(
    file_id: int,
    user: Annotated[User, Depends(current_user)],
    session: Annotated[Session, Depends(get_session)],
) -> dict[str, str]:
    stored = session.scalar(
        select(StoredFile).where(StoredFile.id == file_id, StoredFile.tenant_id == user.tenant_id)
    )
    if stored is None:
        raise HTTPException(status_code=404)
    # オブジェクトの名前 (storage_key) も、サーバーが決めた値。利用者の名前で組み立てない
    return {"url": signed_download_url(stored.storage_key)}
```

アプリのディスクにファイルを置かなければ、名前を書き換えられても、アプリのソースコードや設定には届きません。<br/>
バケット・署名する SA・URL の宛先は、本番とローカルで変わるので、設定から渡します (アップロードも署名付き URL で直接上げさせる形は [SSRF の資料](../SSRF/README.md) の 🪪 にあります)。

 - ⚠️ 利用者が決めた名前をそのままオブジェクトの名前にすると、ほかの利用者と同じ名前になって上書きされます。オブジェクトの名前もサーバーが決めます
 - ⚠️ `response_disposition="attachment"` は、HTML や SVG をブラウザで開かせず、保存させるためです ([XSS の資料](../XSS/README.md) の 📄)
 - ⚠️ signBlob で署名するには、実行する SA に、署名する SA (`SIGNER`) への「サービス アカウント トークン作成者」(`roles/iam.serviceAccountTokenCreator`) のロールが要ります。署名付き URL は署名した SA の権限で認可されるので、署名する SA には、バケットのオブジェクトを読む権限 (`storage.objects.get`) も要ります。引数なしの `generate_signed_url()` は、秘密鍵の無い Cloud Run の既定の認証情報では `AttributeError` になります
 - ⚠️ ローカルのエミュレーター (fake-gcs-server など) では IAM の signBlob を使えません。エミュレーターは署名を確かめないので、ローカルでは使い捨ての鍵で署名します (上の例では省く)

</details>

詳しくは [OWASP の Path Traversal](https://community.owasp.org/attacks/Path_Traversal) と [File Upload Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/File_Upload_Cheat_Sheet.html) にまとまっています。
