# 👑 権限昇格 (Privilege Escalation)
> **利用者が、自分のロールに許されていない操作を、API を直接呼んで実行したり、自分のロールを上げたりできてしまう脆弱性**

![権限昇格: 一般のメンバー (member) の画面には、ロールを変えるボタンが出ない。攻撃者は画面を通さず PATCH /members/7 に {"role": "owner"} を送り、自分をオーナーにする。サーバーはログインしているかだけを確かめ、ロールを変えてよいかを確かめていない](privilege-escalation.svg)

画面は、利用者のロールに合わせてボタンやメニューを隠します。けれども API は、画面を通さなくても curl や開発者ツールで呼べます。サーバーが操作ごとに権限を確かめていないと、一般の利用者が管理者の操作をしたり、自分のロールを上げたりできます。<br/>
OWASP Top 10:2025 の A01 (アクセス制御の不備) に入る攻撃です。ここでは、自分のテナントの中で、ロールに許されていない操作に届く攻撃 (縦の昇格) を扱います。他のテナントのデータに届く攻撃 (横) は [IDOR の資料](../IDOR/README.md) にまとめています。

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

![権限昇格が成立する 3 つの条件: 1. 権限の要る操作を、API で受け付ける、2. 攻撃者が、その API の呼び方を知る、3. サーバーが、操作してよいかを確かめない。どれか 1 つでも欠ければ成立しない](conditions.svg)

2 は防ぎ切れません。API の呼び方は、画面の JS・API クライアントの型・推測 (`/admin` など) から分かります。確実に欠けさせられるのは 3 です。

```mermaid
sequenceDiagram
    autonumber
    actor Attacker as 👿 攻撃者<br/>一般のメンバー (member)
    participant App as 🚀 正規サーバー<br/>api.example
    participant DB as 🐘 DB<br/>メンバーのテーブル

    rect rgb(150, 150, 150)
        Note over Attacker,App: ふだんの画面には、ロールを変えるボタンが出ない (member なので)
    end

    rect rgb(150, 100, 100)
        Note over Attacker,DB: 画面を通さず、API を直接呼ぶ
        Attacker->>+App: PATCH /members/7 {"role": "owner"}
        Note right of Attacker: Authorization: Bearer 🔑 (自分のトークン)<br/>7 は自分のメンバー ID
        App->>+DB: UPDATE memberships SET role = 'owner'<br/>WHERE id = 7 AND tenant_id = (自分のテナント)
        Note right of App: ログインとテナントは確かめるが、<br/>ロールを変えてよいかは確かめない
        DB-->>-App: 1 行を更新
        App-->>-Attacker: 200 OK (role: owner)
    end

    rect rgb(150, 100, 100)
        Note over Attacker,App: オーナーとして、何でもできる
        Attacker->>+App: DELETE /members/1 (本当のオーナーを外す)
        App-->>-Attacker: 204 No Content
    end
```

 - トークンは本物で、テナントでも絞っています (IDOR は防げている)。止められるのは、「この人がロールを変えてよいか」の確認 (認可) だけです
 - 縦の昇格には 2 つの形があります。操作の権限を見ない形 (member がロールを変える・メンバーを外す) と、付けるロールの上限を見ない形 (ロールを変えられる admin が、自分をオーナーにする) です
 - 画面にリンクの無い管理画面や API を直接開く (強制ブラウジング、CWE-425) も同じです。`/admin`・`/internal/export` などは推測で試されます

<details><summary>💻 <b>コードで見る: ① の PATCH はどう通ってしまうか</b></summary>

画面は、ロールを変える権限が無い人にはボタンを出しません。

```tsx
// 画面: ロールを変える権限が無ければ、ボタンを出さない。隠すのは見た目だけで、API はそのまま呼べる
{me.permissions.includes("membership.change_role") && <ChangeRoleButton memberId={member.id} />}
```

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

```python
# ... import と、User・current_user・get_session・Member・MemberJson・Role の定義 (省く)


class ChangeRoleJson(BaseModel):
    role: Role


@app.patch("/members/{member_id}")
def change_role(
    member_id: int,
    body: ChangeRoleJson,
    user: Annotated[User, Depends(current_user)],  # ログインしているかは確かめる (認証)
    session: Annotated[Session, Depends(get_session)],
) -> MemberJson:
    # 自分のテナントのメンバーに絞っている (IDOR は防げている)
    member = session.scalar(select(Member).where(Member.id == member_id, Member.tenant_id == user.tenant_id))
    if member is None:
        raise HTTPException(status_code=404)
    member.role = body.role  # 変える人 (user) が、ロールを変えてよいかを見ていない (認可が無い)
    session.commit()
    return MemberJson.model_validate(member, from_attributes=True)
```

① で次のリクエストが届くと、② で自分の行のロールを owner に変えます。

```http
PATCH /members/7 HTTP/1.1
Host: api.example
Authorization: Bearer <攻撃者のトークン>
Content-Type: application/json

{"role": "owner"}
```

画面にボタンが無くても、開発者ツールで別の画面のリクエストを見たり、画面の JS から API の呼び方を読んだりすれば、このリクエストは作れます。

ロールを上げる道は、ロールの変更の API だけではありません。

| 穴 | 何をされるか | 例 |
|:--|:--|:--|
| 操作の権限を確かめない (上の例) | 一般の利用者が、管理者の操作をする | member が `DELETE /members/1` を送る |
| 付けるロールの上限を確かめない | ロールを変えられる人が、自分や仲間を、自分より権限の多いロールにする | admin が `PATCH /members/7 {"role": "owner"}` を送る |
| 招待で上げる | 自分が持たない権限のロールで招待し、別のアカウントで承諾する | admin が owner で招待する |
| 強制ブラウジング (CWE-425) | 画面にリンクの無い管理画面・API を直接開く | `/admin`・`/internal/export` |
| Mass Assignment (OWASP では A08) | 自分の情報の更新に `role` を混ぜる | `PATCH /me {"name": "...", "role": "owner"}` |

</details>

## 💥 被害例
ロールを上げられると、そのロールに許された操作が、すべて攻撃者の手に渡ります。

| 狙われる操作 | 被害 |
|:--|:--|
| ロールの変更 | 自分をオーナーにして、テナントを乗っ取る。本当のオーナーを外して、取り戻せなくする |
| メンバーの招待・削除 | 外部の人を招待して、データを持ち出させる。社員を外して、仕事を止める |
| テナントの設定・削除 | SSO などの設定を変えられる。テナントごとデータを消される |
| 課金 | プランを変えられる・請求の情報を見られる |
| 運営向けの管理機能 | 全テナントのデータを見られる・利用者を消される |
| 本文に混ぜたロール (Mass Assignment) | 自分の情報の更新に項目を混ぜて、権限を得る (例: 2012 年の GitHub。更新に項目を混ぜて、自分の公開鍵を他人の組織に登録し、rails/rails に commit を push できた) |

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

| ケース | 対策 |
|:--|:--|
| 特定のロールにだけ許す操作 (管理・メンバー・課金) | 👔 操作ごとに権限を確かめる |
| ロールを付ける・変える・招待する・外す | 🪜 自分が持たない権限のロールを扱わせない |
| どのルートも (画面にリンクの無いルートも) | 🚪 既定で拒否 |
| 本文で項目を受け取る | 📝 受け取る項目をモデルで決める |
| どのケースでも | 🧪 ロールと操作の組み合わせのテスト |
| 運営 (社内) 向けの管理機能 | 🏝️ 利用者向けのアプリと分ける |
| 他のテナントのデータに届く (横) | [IDOR の資料](../IDOR/README.md) |

<details><summary>[MUST] 👔 <b>操作ごとに権限を確かめる / ロールではなく操作 (権限) で確かめ、画面で隠すだけにしない</b></summary>

```python
# ... import と、User・current_user・get_session・Permission・ChangeRoleJson・MemberJson の定義 (省く)


class RequirePermission:
    """ルートに要る操作 (権限) を宣言する門。ロールではなく、操作で確かめる"""

    def __init__(self, permission: Permission) -> None:
        self.permission = permission

    def __call__(self, user: Annotated[User, Depends(current_user)]) -> User:
        if not user.role.can(self.permission):
            raise HTTPException(status_code=403)
        return user


@app.patch("/members/{member_id}")
def change_role(
    member_id: int,
    body: ChangeRoleJson,
    user: Annotated[User, Depends(RequirePermission(Permission.MEMBERSHIP_CHANGE_ROLE))],
    session: Annotated[Session, Depends(get_session)],
) -> MemberJson:
    # ... メンバーは user のテナントで絞って取り (IDOR の対策)、付けるロールも 🪜 で確かめる
    ...
```

① は、member が `MEMBERSHIP_CHANGE_ROLE` の権限を持たないので 403 になります。<br/>
「管理者か」(`user.role == Role.ADMIN`) のようにロールで確かめると、ロールを足すたびにルートを直すことになります (経理だけ・閲覧だけのロールなど)。ルートは要る操作 (権限) を宣言し、どのロールにどの操作を許すかは 1 か所にまとめます。

この資料の例では、ロールに許す操作を `Role` にまとめ、`Role.can` で確かめます。member は管理の操作を 1 つも持たず、admin はテナントの削除と課金の管理を持たないとします。

 - ⚠️ 画面でボタンを隠す・メニューから外すのは、使いやすさのためです。守るのはサーバーです
 - ⚠️ 上の例では、権限の確認 (403) が、テナントで絞った取得 (404) より先に動きます。権限が無ければ ID に関係なく 403 なので、他のテナントのリソースがあるかは漏れません。権限がある人が他のテナントの ID を送ると、テナントで絞って取るので 404 になります
 - ⚠️ API 以外の入口 (MCP のツール・バッチなど) にも、同じ確認を入れます

</details>

<details><summary>[MUST] 🪜 <b>自分が持たない権限のロールを扱わせない / ロールを変えられる人に、自分や仲間を上げさせない</b></summary>

```python
# ... import と、Permission・Member・User・app の定義 (省く)


class Role(Enum):
    # ... OWNER・ADMIN・MEMBER と、それぞれに許す操作 (permissions)

    def can(self, permission: Permission) -> bool:
        return permission in self.permissions

    def covers(self, other: Role) -> bool:
        """other の権限をすべて持つか"""
        return other.permissions <= self.permissions


class PermissionDenied(Exception):
    """操作してよい権限が無い。ドメインは HTTP を知らないので、API の層で 403 に変える"""


def change_role(member: Member, new_role: Role, changed_by: User) -> None:
    # 今のロールと新しいロールの両方で、変える人が「ロールを変える権限」と「そのロールの権限すべて」を持つかを確かめる。
    # 持たない権限を含むロールに上げることも、自分より権限の多い人を下げることもさせない
    for role in (member.role, new_role):
        if not changed_by.role.can(Permission.MEMBERSHIP_CHANGE_ROLE) or not changed_by.role.covers(role):
            raise PermissionDenied
    member.role = new_role


# API の層: ドメインの例外を 403 に変える (MCP やバッチの入口では、それぞれの形のエラーに変える)
@app.exception_handler(PermissionDenied)
async def permission_denied(request: Request, exc: PermissionDenied) -> JSONResponse:
    return JSONResponse(status_code=403, content={"detail": "permission denied"})
```

admin が `PATCH /members/7 {"role": "owner"}` を送ると、admin はテナントの削除と課金の管理を持たないので (`ADMIN.covers(OWNER)` が False)、403 になります。admin が member を admin にするのは通ります (自分と同じ権限までは付けられる)。

テナント・操作の権限・相手のロールの 3 つを確かめる処理は、ドメインのモデル (メンバーシップなど) の 1 か所にまとめます。ロールの変更 (今のロールと新しいロールの両方)・メンバーを外す・招待・招待の取り消しのどれも、この確認を通します。

 - ⚠️ ロールに順位 (owner > admin > member) を付けて比べず、権限の集合を含むかで比べます。順位で表せないロール (経理だけ・閲覧だけ) を足しても、正しく比べられます
 - ⚠️ 招待でも同じ確認が要ります。持たない権限のロールで招待し、別のアカウントで承諾すれば、同じように上げられます
 - ⚠️ 自分自身のロールの変更も、同じ確認を通します

</details>

<details><summary>[MUST] 🚪 <b>既定で拒否 / 門を付け忘れたルートを、公開しない (強制ブラウジング)</b></summary>

```python
# ... import と、User・current_user・RequirePermission・Permission の定義 (省く)

# ログインの要るルートは、門 (current_user) を付けたルーターに載せる。公開するルートだけを、別のルーターに分ける
public = APIRouter()
private = APIRouter(dependencies=[Depends(current_user)])


@public.get("/health/check")
def health_check() -> dict[str, bool]:
    return {"health": True}


@private.delete("/members/{member_id}", status_code=204)
def remove_member(
    member_id: int,
    # ルーターの dependencies は、門の戻り値を捨てる。テナントで絞るルートや、権限を確かめるルートは、引数でも門を受け取る。
    # FastAPI は同じリクエストの中で依存の結果をキャッシュするので、current_user は二度は呼ばれない
    user: Annotated[User, Depends(RequirePermission(Permission.MEMBERSHIP_REMOVE))],
) -> None:
    # ... 外す相手は user のテナントで絞って取り (IDOR の対策)、相手のロールも 🪜 で確かめる
    ...


app.include_router(public)
app.include_router(private)
```

付け忘れは、全ルートを並べて呼ぶテストで見つけます。

```python
# test/test_route_auth.py: トークン無しで呼ぶと、公開するルート以外はすべて 401 になるかを確かめる
import re

from fastapi.testclient import TestClient

from api import app

PUBLIC = {("get", "/health/check")}


def test_公開するルート以外はログインが要る() -> None:
    with TestClient(app) as client:
        # 全ルートを、API の仕様書 (OpenAPI) から並べる。仕様書を公開しない設定 (openapi_url=None) でも作れる
        for path, operations in app.openapi()["paths"].items():
            for method in operations:
                if (method, path) in PUBLIC:
                    continue
                # パスの変数はダミーの値で埋める。FastAPI は依存 (current_user) を、パスや本文の検査より先に解くので、401 で止まる
                response = client.request(method, re.sub(r"\{[^}]+\}", "1", path))
                assert response.status_code == 401, f"{method} {path}"
```

ルートを足すと、このテストが公開するかどうかを聞いてきます (`PUBLIC` に足すか、門を付ける)。

 - ⚠️ ここで確かめるのは「ログインが要るか」までです。操作の権限 (👔) は、ルートごとに宣言します
 - ⚠️ `include_in_schema=False` のルート・`app.mount()` したアプリ・Starlette の `Route` は仕様書に載らないので、このテストから漏れます。マウントしたアプリには、それぞれで同じ門とテストを用意します
 - ⚠️ 画面 (Next.js) の管理ページも、表示する前にサーバーで権限を確かめます。漏れても、データは API が権限を確かめてから返すので、中身は渡りません

</details>

<details><summary>[SHOULD] 📝 <b>受け取る項目をモデルで決める / 本文に role を混ぜられても、入れない (Mass Assignment)</b></summary>

```python
from pydantic import BaseModel, ConfigDict

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


class UpdateProfileJson(BaseModel):
    # 利用者が自分で変えてよい項目だけを書く。role・tenant_id は書かない
    model_config = ConfigDict(extra="forbid")  # 知らない項目 (role など) が来たら 422 にする
    name: str


@app.patch("/me")
def update_profile(
    body: UpdateProfileJson,
    user: Annotated[User, Depends(current_user)],
    session: Annotated[Session, Depends(get_session)],
) -> UserJson:
    user.name = body.name  # 1 項目ずつ入れる
    session.commit()
    return UserJson.model_validate(user, from_attributes=True)
```

```python
# ❌ 本文の項目を、すべてそのまま入れる。{"name": "...", "role": "owner"} で自分をオーナーにできる
for key, value in body.items():
    setattr(user, key, value)
```

Pydantic の既定 (`extra="ignore"`) でも、モデルに無い項目は捨てられます。`extra="forbid"` にすると、混ぜられたことに 422 で気づけます。<br/>
Mass Assignment は、OWASP Top 10:2025 では A08 (ソフトウェアやデータの完全性の不備) に入ります ([一覧](../README.md))。

 - ⚠️ DB のモデル (SQLAlchemy) を、入力のモデルに使いません。DB にある項目を、すべて書き換えられます
 - ⚠️ ロールを変えるのは、👔 と 🪜 を通す専用の API だけにします

</details>

<details><summary>[SHOULD] 🧪 <b>ロールと操作の組み合わせのテスト / 拒否される側も、表にしてテストする</b></summary>

```python
# ... import と、fixture (client・login_as)・テストデータを作る関数 (add_member) の定義 (省く)


@pytest.mark.parametrize(
    ("role", "status"),
    [(Role.OWNER, 204), (Role.ADMIN, 204), (Role.MEMBER, 403)],
)
def test_メンバーを外せるのはオーナーと管理者だけ(
    client: TestClient, login_as: LoginAs, role: Role, status: int
) -> None:
    member_id = add_member("a-corp", Role.MEMBER)
    response = client.delete(f"/members/{member_id}", headers=login_as("a-corp", role))
    assert response.status_code == status


@pytest.mark.parametrize(
    ("changed_by", "target", "new_role", "status"),
    [
        (Role.OWNER, Role.MEMBER, Role.OWNER, 200),
        (Role.ADMIN, Role.MEMBER, Role.ADMIN, 200),
        (Role.ADMIN, Role.MEMBER, Role.OWNER, 403),  # 自分が持たない権限 (テナントの削除・課金) を含むロールには上げられない
        (Role.ADMIN, Role.OWNER, Role.MEMBER, 403),  # 自分より権限の多い人 (今のロール) は下げられない
        (Role.MEMBER, Role.MEMBER, Role.ADMIN, 403),  # ロールを変える権限が無い
    ],
)
def test_ロールを変えられる範囲(
    client: TestClient, login_as: LoginAs, changed_by: Role, target: Role, new_role: Role, status: int
) -> None:
    member_id = add_member("a-corp", target)
    response = client.patch(
        f"/members/{member_id}", json={"role": new_role.value}, headers=login_as("a-corp", changed_by)
    )
    assert response.status_code == status
```

権限昇格は、自分のロールで許された操作をするふだんのテストでは見つかりません。ロールと操作の組み合わせを表にして、拒否される側もテストします。<br/>
API のテストに加えて、ドメインのテストでも、ロールごとの操作や「管理者がメンバーをオーナーにすると拒否する」などの組み合わせを確かめます。

 - ⚠️ 操作 (Permission) を足したら、表にも足します。`list(Permission)` で parametrize すると、足した操作が漏れません

</details>

<details><summary>[WANT] 🏝️ <b>(設計) 運営向けの管理機能を、利用者向けのアプリと分ける / 利用者の API から、運営の操作に届かせない</b></summary>

```mermaid
flowchart LR
  user["🥸 利用者"] --> app["🚀 app.example<br/>利用者向け"]
  staff["🧑‍💼 運営"] --> gate["🔐 社内の ID・端末で絞る<br/>Identity-Aware Proxy など"]
  gate --> admin["🛠️ admin.example<br/>運営向け"]
  user -.-x admin
```

全テナントを見る・利用者を消すといった運営の操作を、利用者向けの API に混ぜると、権限の確認が 1 つ漏れただけで、利用者が運営の操作をできます。<br/>
運営向けは別のサービス・別のドメインにし、手前で社内の ID と端末に絞ります。利用者向けの API には、運営の操作を置きません。

 - ⚠️ 分けても、運営向けのサービスの中で、操作ごとの権限 (👔) は要ります (サポート担当・経理など)
 - ⚠️ 運営の操作は、誰が・いつ・どのテナントに何をしたかを記録に残します

</details>

詳しくは [OWASP の Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html) と [Mass Assignment Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Mass_Assignment_Cheat_Sheet.html) にまとまっています。
