# Takumi Agent の仕組み {#how-it-works}

このページでは、[Takumi Agent](/docs/ja/t/endpoint/index.md) が Mac デバイス上で Takumi Guard を動かす仕組みとして、リクエストの経路、Takumi Agent インストールパッケージの構成要素、設計、デバイスが自身の状態を判定する方法を説明します。

:::warning 変更の可能性について
本ページに記載している挙動は現時点のものです。変更する場合はリリースノートで予告しますが、セキュリティ上の緊急対応などにより、予告なく変更する場合があります。
:::

## リクエストの経路 {#request-flow}

Mac デバイス上のツールが送信したリクエストの経路を、次の図に示します。

```mermaid
flowchart LR
  T["Mac デバイス上のあらゆるツール<br/>npm、pip、gem、go、composer、AI エージェント"] --> X["システム拡張<br/>（対象レジストリへの接続を捕捉）"]
  X --> D["バックグラウンドサービス"]
  D --> G["Takumi Guard<br/>（判定）"]
  G -->|許可| R["公開レジストリ"]
  T -- "直接の接続は<br/>エグレスロックがブロック" --x R
  T -. "復号せずに通過" .-> O["その他のホスト"]
```

## 構成要素 {#components}

Takumi Agent のパッケージをインストールすることで、下記の要素がデバイスに追加されます。

- デバイスの状態を表示し、ほかの要素を有効化するメニューバーのアプリ
- 対象レジストリへの接続を捕捉する macOS のシステム拡張
- Takumi Guard に判定を問い合わせてその結果を中継するバックグラウンドサービス

バックグラウンドサービスは、Mac デバイスの起動時、ユーザーがログインする前に起動します。そのため、保護はユーザーのセッションに依存しません。

## 設計の原則 {#design}

Takumi Agent の設計は、次の原則に従います。

- **扱うのはレジストリの通信のみ**。それ以外の接続はそのまま通し、**復号することはない**
- **デバイスはセキュリティ上の判断をしない**。ブロックリストとポリシーは Takumi Guard 側で管理され、アプリを更新しなくても保護は最新に保たれる
- **フェイルクローズ**。Guard に到達できない場合、捕捉したリクエストは公開レジストリに流さずに拒否する
- **デバイスごとの認証局**。レジストリの通信を読むため、エージェントはデバイス上で認証局を生成する。秘密鍵は Mac デバイスの外に出ることがなく、対象レジストリの通信にのみ使われる
- **エグレスロック**。ネットワークフィルタが対象レジストリへの直接の接続をブロックし、Takumi Guard を迂回できないようにする

## デバイスの認証局 {#device-ca}

デバイスの認証局はインストール時に Mac デバイス上で生成され、その秘密鍵が Mac デバイスの外に出ることはありません。macOS がこの認証局を信頼するには管理者の直接の承認が必要なため、インストーラーが代わりに行うことはできません（[クイックスタートのステップ 5](/docs/ja/t/endpoint/quickstart.md#trust-ca)を参照）。信頼されるまで、捕捉対象となるパッケージのダウンロード通信はブロックされます。独自の証明書ストアを持つツールは、Takumi Agent のトラストバンドルを参照し、証明書を読み込みます（[Takumi Agent を使った開発](/docs/ja/t/endpoint/development.md#host-tools)を参照）。アンインストール時には秘密鍵が削除され、証明書もシステムキーチェーンから削除されます（[アンインストール](/docs/ja/t/endpoint/features/uninstall.md)を参照）。

## 判定の仕組み {#verdict-model}

デバイスは、ヘルスチェックごとの状態から自身の判定を導きます。

- **キャプチャ**：システム拡張がインストール・有効化され、ネットワークプロキシが有効になっており、バックグラウンドサービスが起動して接続を待ち受けている
- **デバイスCA**：デバイス証明書が存在し、システムキーチェーンで信頼されており、有効期限が近づいていない
- **エグレスロック**：ネットワークフィルタが有効になっている
- **キャプチャ対象**：対象レジストリのホスト名が捕捉されている
- **クレデンシャル**：デバイスが登録済みで、有効な Guard 認証情報を持っている
- **ランタイム信頼**：トラストバンドルが設置され、独自の証明書ストアを持つツールがデバイス証明書を信頼している。デバイス証明書を拒否するコンテナは欠陥ではなく注記として扱う

その規則は次のとおりです。

- 赤のヘルスチェックが 1 つでもあれば **保護なし**、そうでなければオレンジが 1 つでもあれば **一部低下**、どちらもなければ **保護中** になる
- **確認できないものはオレンジとして扱う**。状態を確認できないヘルスチェックはオレンジとして扱う。観測できなかったことは「問題なし」を意味しないためである。このバージョンのエージェントが認識できない要因も同じくオレンジとして扱うため、未知の要因だけでデバイス全体が赤に変わることはなく、判定から黙って消えることもない
- **ポリシーで無効なものは欠陥ではない**。組織が保護対象としていないエコシステムは判定に影響しない
- **ブロックは迂回ではない**。デバイス証明書を拒否したコンテナはレジストリに到達しないため、欠陥ではなく注記として扱う
- **一時的な状態がオレンジのまま残り続けることはない**。自動的に解消する見込みの状態は、解消しなければ赤に変わる。人の操作を待つ状態はオレンジのままになる

管理コンソールの表示がデバイス自身の判定より良くなることはありませんが、悪くなることはあります。オフライン、削除済み、改ざんの痕跡は、いずれもデバイスの報告より優先されます（[デバイスの状態](/docs/ja/t/endpoint/features/states.md#fleet-states)を参照）。

## 改ざんの痕跡 {#tamper}

改ざんの痕跡が検知されたデバイスについては、管理コンソールでは管理下の Mac デバイスの状態を記録しており、**健全**状態の報告が後に発生しても、**改ざんの痕跡**状態が解除されることはありません。これは、仮にデバイス上で root 権限を持つ攻撃者がシステム拡張を無効化し、その後**健全**状態の報告を Mac デバイスから送らせて、検知を回避する、などの行為を防止するために必要な挙動です。

管理者が[痕跡を承認する](/docs/ja/t/endpoint/features/managing-devices.md#acknowledge)まで、デバイスは保護なしと表示されます。

誤検知の場合は、デコミッションや再登録をせずに承認することで解除できます。承認によって行われるのは、記録された痕跡の解除のみです。デバイスが再び改ざんを報告すると、痕跡は **最初に検知** の日時が新しくなった状態で再び記録され、以前の承認はその下に表示されたまま残ります。