# Go モジュール {#golang}

Takumi Guard は [GOPROXY プロトコル](https://go.dev/ref/mod#goproxy-protocol)に対応しているため、企業内 Go モジュールプロキシと同じ要領で `go get`・`go mod download`・`go build` を経由させることができます。このページでは、ローカル開発環境と CI の両方について、それぞれの利用方法を説明します。

## 設定方法 {#setup}

Takumi Guard には3つの利用方法があります。

- **[匿名で利用する](#setup-anonymous)**：トークン不要。`GOPROXY` を設定するだけでパッケージブロックが有効になります。
- **[ユーザー登録して利用する](#setup-email-verified)**：メール認証トークン（`tg_anon_…`）を使い、ダウンロード追跡と感染可能性の通知を有効にします。
- **[組織ユーザートークンで利用する](#setup-org-user-token)**：組織ユーザートークン（`tg_org_…`）を使い、組織全体のインストール状況を追跡できます。

:::info 有料機能
組織ユーザートークンを利用するには、Guard を有効化した基本サブスクリプションが必要です。詳しくは[料金と請求](/docs/ja/t/guard/billing/index.md)を参照してください。
:::

### 匿名で利用する {#setup-anonymous}

認証なしで Takumi Guard のパッケージブロック機能を利用できます。`GOPROXY` 環境変数を設定するだけで、すべてのモジュール取得がプロキシ経由になります。

```bash
go env -w GOPROXY=https://golang.flatt.tech
```

以上です。`go mod download`・`go get`・`go build` のメタデータ取得はすべて Takumi Guard 経由になり、アーティファクト（`.zip`）のダウンロードは `proxy.golang.org` に透過的にリダイレクトされるため、ダウンロード速度に影響はありません。

`GOPROXY` には URL のみを指定し、`,direct` や `|direct` のフォールバックは付けないでください。付けると Takumi Guard が回避される場合があります。詳しくは[こちら](#goproxy-no-fallback)をご覧ください。

:::tip ツールチェーンの互換性
Takumi Guard は Go 1.21 以上のツールチェーンに対応しています。それより古いバージョンでは GOPROXY プロトコルの仕様が緩く、動作検証も行っていません。
:::

### ユーザー登録して利用する {#setup-email-verified}

メールアドレスを登録すると、匿名利用のパッケージブロックに加えて、ダウンロード追跡と[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications.md)が利用可能になります。ダウンロードしたモジュールが後から悪性であると判明した場合、登録したメールアドレスに通知が届きます。Shisho Cloud アカウントは不要で、無料で利用できます。

:::info 別のエコシステムで `tg_anon_` トークンを取得済みの場合
お持ちの `tg_anon_` トークンは、そのまま npm / PyPI / RubyGems / Go モジュールいずれのエコシステムでも利用できます。再登録は不要で、下記の **ステップ 3** から進めてください。
:::

**ステップ 1: メールアドレスを登録する**

```bash
curl -X POST https://golang.flatt.tech/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "language": "ja"}'
```

`language` フィールドは省略可能で、デフォルトは `"en"`（英語）です。`"ja"` を指定すると、確認メールや感染可能性の通知を含むすべてのメールが日本語で届きます。この設定はトークンに保存され、以降のメールすべてに適用されます。

数秒以内にウェルカムメールが届きます。

**ステップ 2: メールに記載された API キーを確認する**

API キーはウェルカムメール本文に直接記載されています。リンクのクリックは不要で、そのまま利用できます。

:::warning
このキーは安全な場所に保管してください。再発行が必要な場合は次のコマンドでいつでも再生成できます。

```bash
curl -X POST -H 'Authorization: Bearer tg_anon_xxxxxx' \
  https://golang.flatt.tech/api/v1/tokens/regenerate
```

:::

**ステップ 3: Go ツールチェーンにトークンを設定する**

Go ツールチェーンは GOPROXY サーバーに対して `.netrc` 経由の HTTP Basic 認証でトークンを送信します。ユーザー名は無視され、トークンはパスワード欄に書き込みます。

```bash
# 1. ~/.netrc に追記
echo "machine golang.flatt.tech login token password tg_anon_xxxxxx" >> ~/.netrc
chmod 600 ~/.netrc

# 2. GOPROXY を Takumi Guard に向ける（未設定の場合）
go env -w GOPROXY=https://golang.flatt.tech
```

これで以降のモジュール取得はすべて `tg_anon_` トークンで認証され、ダウンロード追跡と感染可能性の通知が有効になります。なお `GOPROXY` には URL のみを指定し、`,direct` や `|direct` のフォールバックは付けないでください。詳しくは[こちら](#goproxy-no-fallback)をご覧ください。

### 組織ユーザートークンで利用する {#setup-org-user-token}

組織ユーザートークン（`tg_org_…`）は、Takumi / Shisho Cloud コンソールから発行するか、Bot 経由で Guard API から発行できます。発行手順の詳細は[トークンの管理](/docs/ja/t/guard/features/token-management.md#user-tokens)を参照してください。

:::info
1 つの `tg_org_` トークンは、Takumi Guard の全エコシステム（npm・PyPI・RubyGems・Go）で共通して利用できます。他のエコシステムですでにトークンを発行済みの場合は、そのトークンをそのまま利用できます。
:::

トークンを取得したら、`~/.netrc` に書き込み、`GOPROXY` を設定します。

```bash
echo "machine golang.flatt.tech login token password tg_org_xxxxxx" >> ~/.netrc
chmod 600 ~/.netrc
go env -w GOPROXY=https://golang.flatt.tech
```

これで `go mod download` は組織ユーザートークンで認証され、[組織全体のインストール追跡](/docs/ja/t/guard/features/installation-logs.md)と組織レベルの感染可能性通知（Slack・Webhook など）が有効になります。なお `GOPROXY` には URL のみを指定し、`,direct` や `|direct` のフォールバックは付けないでください。詳しくは[こちら](#goproxy-no-fallback)をご覧ください。

### `GOPROXY` による設定について {#goproxy-no-fallback}

どの利用方法でも、`go env -w GOPROXY=https://golang.flatt.tech` を使用して同じプロキシ URL を設定します。設定にあたっては、以下の 2 点にご留意ください。

#### フォールバックを指定しない

`GOPROXY` には `https://golang.flatt.tech` のみを指定してください。`,direct` や `|direct` は追加しないでください。

これらのフォールバックを指定すると、プロキシがエラーを返した際に、Go ツールチェーンが VCS から**モジュールを直接取得する動作が有効**になります。その結果、まだインデックスされていないモジュール（`404`）や、`|direct` を指定した場合には明示的にブロック対象となっているモジュール（`403`）についても、**Takumi Guard を経由せず**取得できてしまいます。

ブロックリストを完全に適用するには、`GOPROXY` にプロキシ URL のみを指定する必要があります。

なお、自社のプライベートモジュールは、このプロキシ経由ではなく、[プライベートモジュールと併用する](#private-modules)で説明している `GOPRIVATE` を使用して除外してください。

#### 設定の永続化

`go env -w` で設定した `GOPROXY` は `$(go env GOENV)`（通常は `~/.config/go/env`）に書き込まれるため、シェルをまたいでも、再起動後も保持されます。

現在のシェルセッションでのみ有効にしたい場合は、代わりに `export GOPROXY=…` を使用してください。

### GitHub Actions {#setup-ci}

GitHub Actions ワークフローに Takumi Guard を統合する場合は、`flatt-security/setup-takumi-guard-golang` GitHub Action を利用してください。匿名モードと組織連携モードの両方に対応しています。

#### 匿名モード {#setup-ci-anonymous}

Shisho Cloud アカウントがまだない場合でも、パッケージブロックのみであれば CI で Takumi Guard を利用できます。`bot-id` 入力を省略してください。

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: "1.23"

      - uses: flatt-security/setup-takumi-guard-golang@v1
        # bot-id を指定しない → 匿名モード（ブロックのみ）

      - run: go build ./...
      - run: go test ./...
```

匿名モードでは、Action は `GOPROXY=https://golang.flatt.tech` を設定するだけです。ブロック対象モジュールは `403` で拒否されますが、ダウンロード追跡と[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications.md)は利用できません。

#### Shisho Cloud 組織と連携する {#setup-ci-org}

Shisho Cloud 組織と連携することで、組織レベルのダウンロード追跡と Webhook 経由の[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications.md)が利用できます。**CI 環境に長期シークレットを保存する必要はありません。** 認証は GitHub OIDC トークンを Shisho Cloud の STS サービスで短期アクセストークンに交換することで安全に行われます。

**前提条件:**

1. Shisho Cloud に登録された Bot アイデンティティ。Shisho Cloud コンソールのレジストリ設定ページから **Bot ID** をコピーしてください。
2. ワークフロージョブに `id-token: write` と `contents: read` の権限を付与すること。

**ステップ 1: Action をワークフローに追加する**

```yaml
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # OIDC トークン交換に必須
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: "1.23"

      - uses: flatt-security/setup-takumi-guard-golang@v1
        with:
          bot-id: "BT01EXAMPLE..." # Shisho Cloud コンソールからコピー

      - run: go build ./...
      - run: go test ./...
```

Action は OIDC 交換を自動で処理します。

1. GitHub OIDC トークンを取得（レジストリホストを audience として指定）
2. STS サービス経由で短期の Takumi Guard アクセストークンに交換
3. トークンを mode `0600` で `~/.netrc` に書き込み、`GOPROXY=https://golang.flatt.tech` を設定

:::info
Bot ID はシークレットではありません。トークン交換時に許可リストを参照するための公開された識別子であり、ワークフローファイルに直接コミットして問題ありません。Shisho Cloud コンソールでは Bot ID 込みのワークフロースニペットをコピーできます。
:::

アクセストークンの有効期限はデフォルトで 30 分です（`expires-in` 入力で最大 24 時間まで延長可能）。認証に失敗した場合（`bot-id` が不正、OIDC 権限が不足、STS が到達不能など）はステップが明確なエラーメッセージとともに失敗し、匿名モードへの暗黙のフォールバックは行いません。

#### Action の入力リファレンス {#action-inputs}

| 入力           | 必須   | デフォルト                     | 説明                                                                      |
| -------------- | ------ | ------------------------------ | ------------------------------------------------------------------------- |
| `bot-id`       | いいえ | —                              | Shisho Cloud の Bot ID。省略すると匿名モード（ブロックのみ）になります。  |
| `set-goproxy`  | いいえ | `true`                         | `GOPROXY` を自分で管理する場合は `false` にしてください。                 |
| `registry-url` | いいえ | `https://golang.flatt.tech`    | カスタムレジストリ URL。Shisho Cloud サポートからの指示時のみ変更します。 |
| `sts-url`      | いいえ | `https://sts.cloud.shisho.dev` | OIDC → アクセストークン交換に利用する STS サービスの URL。                |
| `expires-in`   | いいえ | `1800`（秒）                   | アクセストークンの有効期限（秒）。最大 `86400`（24 時間）。               |

入出力の全リストは、[Action のリポジトリ](https://github.com/flatt-security/setup-takumi-guard-golang)を参照してください。

## プライベートモジュールと併用する {#private-modules}

Takumi Guard は公開モジュール向けの読み取り専用セキュリティプロキシです。社内 GitHub Organization のプライベートモジュールに依存している場合は、プライベートモジュールは Takumi Guard を経由せず VCS から直接取得するように設定してください。

### `GOPRIVATE` {#private-modules-goprivate}

Go ツールチェーンには専用の環境変数があります。`GOPRIVATE` はカンマ区切りの glob パターンで、マッチしたモジュールパスは VCS から直接（既存の `git` 認証情報で）取得され、プロキシも `sum.golang.org` も経由しません。

```bash
go env -w GOPROXY=https://golang.flatt.tech
go env -w GOPRIVATE=github.com/your-org/*,*.internal.your-corp.com
```

この設定で、ツールチェーンは次のように振り分けます。

- `github.com/spf13/cobra`（公開モジュール）→ Takumi Guard 経由で取得
- `github.com/your-org/private-repo`（`GOPRIVATE` にマッチ）→ `git` で VCS から直接取得し、Takumi Guard を経由しない
- `internal.your-corp.com/team/lib`（`GOPRIVATE` にマッチ）→ 同様に VCS から直接取得

:::tip
Takumi Guard の URL や API キーを `go.mod` や `go.sum` に書き込む必要はありません。認証は `.netrc` で完結し、プライベートモジュールのパスは `GOPRIVATE` でプロキシから完全に除外できます。
:::

:::warning
VCS から直接取得するプライベートモジュールは、Takumi Guard のセキュリティスキャン対象外になります。自社製モジュールについては許容できますが、これらのモジュールはブロックリストとの照合も `sum.golang.org` での検証も行われない点にご注意ください。
:::

## 動作確認 {#verify-setup}

Takumi Guard が正しく動作しているかを確認するには、ブロック対象として用意してある無害なテストモジュール `github.com/flatt-security/hola-takumi-go` のバージョン `v0.1.0` をインストールしてみてください。`hola-takumi-go` は GMO Flatt Security が Takumi Guard の動作確認用に公開している無害なモジュールです。

```bash
cd $(mktemp -d) && go mod init verify-takumi-guard && go get github.com/flatt-security/hola-takumi-go@v0.1.0
```

Takumi Guard が正しく設定されていれば、プロキシがこのバージョンをフィルタリングし、`go get` は次のエラーで失敗します。

```
go: github.com/flatt-security/hola-takumi-go@v0.1.0: reading https://golang.flatt.tech/github.com/flatt-security/hola-takumi-go/@v/v0.1.0.info: 403 Forbidden
	server response: Forbidden
```

:::note
`hola-takumi-go v0.1.0` がすでにモジュールキャッシュに残っている場合、ツールチェーンはキャッシュを再利用してプロキシに問い合わせません。該当キャッシュを削除して再実行してください。

```bash
go clean -modcache  # キャッシュ全削除（影響範囲大）
# または特定エントリのみ削除:
rm -rf "$(go env GOMODCACHE)/github.com/flatt-security/hola-takumi-go@v0.1.0"
```

:::

## モジュールの公開 {#publishing}

Takumi Guard は読み取り専用のセキュリティプロキシです。Go モジュールは npm パッケージのように中央レジストリに「公開」する仕組みではなく、`proxy.golang.org` が公開 VCS の任意のタグ付きコミットをインデックスする方式のため、Takumi Guard はモジュールのリリースに影響しません。これまでどおり VCS にタグを切って push してください。

## 利用を停止する {#uninstall}

Takumi Guard の利用を停止する場合は、`GOPROXY` 設定を元に戻します。

### ローカル環境 {#uninstall-local}

```bash
# 1. GOPROXY を既定値に戻す
go env -u GOPROXY                      # または: go env -w GOPROXY=https://proxy.golang.org,direct

# 2. ~/.netrc から Takumi Guard のエントリを削除
sed -i.bak '/^machine golang\.flatt\.tech /d' ~/.netrc
```

### GitHub Actions {#uninstall-ci}

ワークフローから `GOPROXY` 環境変数と `.netrc` 設定ステップを削除してください。

```yaml
# 以下を削除:
# env:
#   GOPROXY: https://golang.flatt.tech
# - name: Takumi Guard のトークンを設定
#   run: echo "machine golang.flatt.tech ..." > ~/.netrc
```

:::info
これらを削除すると、`go build` は既定の `https://proxy.golang.org,direct` を利用するようになります。`go.mod` や `go.sum` の変更は不要です。
:::

### 組織ユーザートークンの失効 {#uninstall-org-token}

組織ユーザートークン（`tg_org_…`）を利用している場合は、`.netrc` の更新に加えて、Shisho Cloud コンソールの **Guard** > **Tokens** からトークンを失効させてください。失効するまでは課金対象として扱われます。詳しくは[料金](/docs/ja/t/guard/billing/pricing.md)を参照してください。

## クイックリファレンス {#quick-reference}

各利用ティアでの最小構成です。`tg_anon_xxxxxx` / `tg_org_xxxxxx` は実際のトークンに置き換えてください。

### 匿名 {#quick-reference-anonymous}

```bash
go env -w GOPROXY=https://golang.flatt.tech
```

### ユーザー登録（メール認証） {#quick-reference-email}

```bash
echo "machine golang.flatt.tech login token password tg_anon_xxxxxx" >> ~/.netrc
chmod 600 ~/.netrc
go env -w GOPROXY=https://golang.flatt.tech
```

### 組織 {#quick-reference-org}

```bash
echo "machine golang.flatt.tech login token password tg_org_xxxxxx" >> ~/.netrc
chmod 600 ~/.netrc
go env -w GOPROXY=https://golang.flatt.tech
```

### プライベートモジュール併用 {#quick-reference-private}

```bash
echo "machine golang.flatt.tech login token password tg_org_xxxxxx" >> ~/.netrc
chmod 600 ~/.netrc
go env -w GOPROXY=https://golang.flatt.tech
go env -w GOPRIVATE=github.com/your-org/*,*.internal.your-corp.com
```