# Takumi Guard が Go モジュールに対応

Takumi Guard が npm・PyPI・RubyGems に加えて **Go モジュール** に対応しました。

Go プロジェクトで `go get`・`go mod download`・`go build` を Takumi Guard 経由でルーティングすることで、CI や開発環境に届く前に悪性モジュールをブロックできるようになりました。

![Takumi Guard が Go モジュールに対応](/docs/ja/_md-assets/bca5338806-eyecatch.png)

## 概要 {#overview}

Takumi Guard は、パッケージマネージャーと上流レジストリの間に位置するセキュリティプロキシです。すべてのインストールリクエストを GMO Flatt Security の脅威データベースと照合し、悪性パッケージをブロックします。

今回のリリースにより、npm・Python・Ruby のユーザーが利用していた保護機能が Go エコシステムでも利用可能になりました。

- **[パッケージブロック](/docs/ja/t/guard/features/package-blocking)**: 悪性モジュールをコードの取得前にブロック
- **[ダウンロード追跡](/docs/ja/t/guard/features/installation-logs)**: 認証済みユーザーのインストール履歴を記録
- **[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications)**: ダウンロードしたモジュールが後から悪性であると判明した際に通知

Takumi Guard は標準の [GOPROXY プロトコル](https://go.dev/ref/mod#goproxy-protocol)に対応しているため、ツールチェーン側の変更は不要で、`GOPROXY` を Takumi Guard に向けるだけで利用できます。

## 利用開始 {#getting-started}

以下の手順は匿名で利用できます。アカウント登録は不要です。

### Go ツールチェーン

すべてのモジュール取得を Takumi Guard 経由にルーティングするには、環境変数を 1 行設定するだけです。

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

モジュールメタデータはブロックリスト適用のため Takumi Guard を経由しますが、モジュールアーティファクト（`.zip`）のダウンロードは `proxy.golang.org` に透過的にリダイレクトされるため、ダウンロード速度に影響はありません。

:::warning フォールバックは付けない（URL のみ）
`GOPROXY` には `https://golang.flatt.tech` のみを指定してください。`,direct` や `|direct` は付けないでください。どちらのフォールバックも、プロキシがエラーを返した際に Go ツールチェーンが直接 VCS から取得する動作を有効にします。これにより、まだインデックスされていないモジュール（`404`）や、`|direct` の場合は明示的にブロック対象となっているモジュール（`403`）まで Takumi Guard を回避してしまいます。URL のみを指定する構成が、ブロックリストの完全な適用条件です。
:::

### GitHub Actions

[`flatt-security/setup-takumi-guard-golang`](https://github.com/flatt-security/setup-takumi-guard-golang) Action を利用してください。ブロックのみであればアカウントもトークンも不要です。

```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
      - run: go build ./...
```

組織レベルのダウンロード追跡と[感染可能性の通知](/docs/ja/t/guard/features/breach-notifications)を利用する場合は、`bot-id` を追加し `id-token: write` 権限を付与してください。Action が OIDC → 短期トークン交換を自動で行うため、CI に長期シークレットを保存する必要はありません。詳細は [Go モジュールのクイックスタート](/docs/ja/t/guard/quickstart/golang#setup-ci)を参照してください。

## 動作確認 {#verify}

セットアップ後、ブロック対象として用意してある無害なテストモジュール `github.com/flatt-security/hola-takumi-go` のバージョン `v0.1.0` をインストールしてみてください。

```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
```

:::note
`hola-takumi-go v0.1.0` がすでにモジュールキャッシュに残っている場合は、`rm -rf "$(go env GOMODCACHE)/github.com/flatt-security/hola-takumi-go@v0.1.0"` で該当キャッシュを削除してから再実行してください。
:::

詳しくは、[Go モジュールクイックスタートの「動作確認」](/docs/ja/t/guard/quickstart/golang#verify-setup)を参照してください。

## ユーザー登録で更に多くの機能を（無料） {#email-registration}

メールアドレスを登録すると、ダウンロードしたモジュールが後から悪性であると判明した際に通知が届くようになります。無料で利用できます。

:::info
npm・PyPI・RubyGems で組織ユーザートークンまたはメール認証トークンを取得済みの場合は、再登録は不要です。同じトークンをそのまま Go モジュールで利用できます。
:::

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

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

**ステップ 2:** ウェルカムメール本文に直接記載された API キーを確認します。リンクのクリックは不要です。

**ステップ 3:** トークンを `~/.netrc` に追記して、Go ツールチェーンが取得時に認証情報を送るようにします。

```bash
echo "machine golang.flatt.tech login token password tg_anon_xxxxxx" >> ~/.netrc
chmod 600 ~/.netrc
```

Go ツールチェーンは GOPROXY サーバーに対して `.netrc` 経由の HTTP Basic 認証を使います。ユーザー名は無視され、トークンはパスワード欄に記述します。これでインストール履歴が記録され、ダウンロードしたモジュールが後から悪性であると判明した際に通知が届くようになります。

## プライベートモジュール {#private-modules}

公開モジュールは Takumi Guard 経由で取得し、プライベートモジュール（社内 GitHub Organization など）は Takumi Guard を経由せず VCS から直接取得する構成を推奨します。Go 標準の `GOPRIVATE` 環境変数を使ってください。

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

`GOPRIVATE` にマッチしたモジュールは、既存の `git` 認証情報で VCS から直接取得され、プロキシを経由しません。詳しくは [Go モジュールクイックスタート](/docs/ja/t/guard/quickstart/golang#private-modules) を参照してください。

## 組織全体での運用 {#organization-setup}

チームで Takumi Guard を運用する場合、[インストール履歴の検索](/docs/ja/t/guard/features/installation-logs)、[組織ユーザートークンの一元管理](/docs/ja/t/guard/features/token-management)、[感染可能性通知の Webhook 配信](/docs/ja/t/guard/features/breach-notifications) などの組織向け機能が利用できます。Guard を有効化した Takumi サブスクリプションでご利用ください。

1. [https://cloud.shisho.dev/hello/takumi](https://cloud.shisho.dev/hello/takumi) にアクセスしてサインインします。
2. 組織を登録し、Takumi のサブスクリプションを開始します。
3. サイドバーから **Guard** > **Settings** に移動します。
4. 「Enable」をクリックして Guard を有効化します。

![Guard 設定画面](/docs/ja/_md-assets/fdf50fa5dd-ui-guard-settings.png)

Guard を有効化したら、[Go モジュールクイックスタート](/docs/ja/t/guard/quickstart/golang) に従って CI や開発者端末を設定してください。

GitHub Actions から[長期の組織ユーザートークン](/docs/ja/t/guard/quickstart/golang#setup-org-user-token)のみを利用する場合は、**お支払いの登録は不要**です。組織登録時にお支払い画面が表示されますが、スキップして問題ありません。Guard ページから GitHub Organization を登録するだけで、組織ユーザートークンを発行できます。