Go モジュール

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

設定方法

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

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

有料機能

組織ユーザートークンを利用するには、Guard を有効化した基本サブスクリプションが必要です。詳しくは料金と請求を参照してください。

匿名で利用する

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

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 が回避される場合があります。詳しくはこちらをご覧ください。

ツールチェーンの互換性

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

ユーザー登録して利用する

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

別のエコシステムで tg_anon_ トークンを取得済みの場合

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

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

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

警告

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

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

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

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

# 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 のフォールバックは付けないでください。詳しくはこちらをご覧ください。

組織ユーザートークンで利用する

組織ユーザートークン（tg_org_…）は、Takumi / Shisho Cloud コンソールから発行するか、Bot 経由で Guard API から発行できます。発行手順の詳細はトークンの管理を参照してください。

info

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

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

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 は組織ユーザートークンで認証され、組織全体のインストール追跡と組織レベルの感染可能性通知（Slack・Webhook など）が有効になります。なお GOPROXY には URL のみを指定し、,direct や |direct のフォールバックは付けないでください。詳しくはこちらをご覧ください。

`GOPROXY` による設定について

どの利用方法でも、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 のみを指定する必要があります。

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

設定の永続化

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

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

CI/CD で利用する

GitHub Actions
GitLab CI/CD

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

匿名で利用する

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

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 で拒否されますが、ダウンロード追跡と感染可能性の通知は利用できません。

組織に紐づけて利用する

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

前提条件:

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

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

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 交換を自動で処理します。

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

info

Bot ID はシークレットではありません。サインインするボットを指定するための公開された識別子で、認証は OIDC トークンとボットの信頼条件の照合によって行われます。ワークフローファイルに直接コミットできます。Shisho Cloud コンソールでは Bot ID 込みのワークフロースニペットをコピーできます。

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

参考：Action 入力パラメータ

入力	必須	デフォルト	説明
`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 のリポジトリを参照してください。

GitLab CI/CD では、ジョブの before_script で Go の接続先を Takumi Guard に設定します。匿名で利用する方法と、組織に紐づけて利用する方法があります。

匿名で利用する

Shisho Cloud アカウントがなくても、パッケージブロックのために CI で Takumi Guard を利用できます。ジョブに、レジストリの設定を追加してください。

build:
  image: golang:1.23-bookworm
  before_script:
    # Go の接続先を Takumi Guard にする
    - go env -w GOPROXY=https://golang.flatt.tech
  script:
    - go build ./...
    - go test ./...

匿名で利用する場合、ブロック済みパッケージは引き続き拒否されますが、ダウンロード追跡と感染可能性の通知は利用できません。

組織に紐づけて利用する

GitLab.com の GitLab CI/CD で Takumi Guard を利用するには、OIDC でボットとして Shisho Cloud に認証し、取得したアクセストークンを Go に設定します。CI 環境に長期有効なシークレットを保存する必要はなく、GitHub Actions と同様に、パッケージのダウンロード履歴が組織に記録されます。

前提条件:

Shisho Cloud に、対象プロジェクトの GitLab CI/CD の信頼条件を設定したボットが作成されていること。信頼条件の設定方法はボットの認証を参照してください。また、作成したボットの Bot ID を控えてください。
curl と bash が使え、shishoctl の Linux 版（glibc、x86_64 または aarch64）が動作するコンテナイメージを使用すること。Debian ベースの公式イメージ（-slim 版を除く）などが該当します。Alpine ベースのイメージには対応していません。arm64 のランナーでは、shishoctl の URL の x86_64 を aarch64 に置き換えてください。

.gitlab-ci.yml に、以下のようなジョブを追加してください。

build:
  image: golang:1.23-bookworm
  id_tokens:
    ID_TOKEN:
      aud: https://gitlab.com
  variables:
    SHISHOCLOUD_BOT_ID: "BT01EXAMPLE..." # Shisho Cloud コンソールからコピー
  before_script:
    # shishoctl をインストールする
    - SHISHOCTL_URL="https://shisho.dev/releases/shishoctl-0.15.0-x86_64-unknown-linux-gnu"
    - curl -L $SHISHOCTL_URL -o /usr/local/bin/shishoctl
    - chmod +x /usr/local/bin/shishoctl

    # ボットとしてサインインし、アクセストークンを取得する
    - shishoctl auth signin:bot
      --bot ${SHISHOCLOUD_BOT_ID}
      <<< ${ID_TOKEN}
      --expires-in-minutes 30 # 既定は 30 分（最大 1440 分）。ジョブに合わせて調整する
    - export ACCESS_TOKEN="$(shishoctl auth print-access-token)"

    # アクセストークンを Go に設定する
    - echo "machine golang.flatt.tech login token password ${ACCESS_TOKEN}" >> ~/.netrc
    - chmod 600 ~/.netrc
    - go env -w GOPROXY=https://golang.flatt.tech
  script:
    - go build ./...
    - go test ./...

アクセストークンのデフォルト有効期限は 30 分です（--expires-in-minutes で最大 24 時間まで設定可能です）。

プライベートモジュールと併用する

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

`GOPRIVATE`

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

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 でプロキシから完全に除外できます。

警告

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

セットアップの確認

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

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 がすでにモジュールキャッシュに残っている場合、ツールチェーンはキャッシュを再利用してプロキシに問い合わせません。該当キャッシュを削除して再実行してください。

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

モジュールの公開

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

アンインストール

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

ローカル環境

# 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

CI/CD

GitHub Actions
GitLab CI/CD

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

# 以下を削除:
# 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 の変更は不要です。

.gitlab-ci.yml の before_script から、Go を Takumi Guard に向ける設定の行を削除してください。組織に紐づけて利用している場合は、shishoctl の行も削除してください。

組織ユーザートークンの失効

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

クイックリファレンス

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

匿名

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

ユーザー登録（メール認証）

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

組織

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

プライベートモジュール併用

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

設定方法​

匿名で利用する​

ユーザー登録して利用する​

組織ユーザートークンで利用する​

GOPROXY による設定について​

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

設定の永続化​

CI/CD で利用する​

匿名で利用する​

組織に紐づけて利用する​

参考：Action 入力パラメータ​

匿名で利用する​

組織に紐づけて利用する​

プライベートモジュールと併用する​

GOPRIVATE​

セットアップの確認​

モジュールの公開​

アンインストール​

ローカル環境​

CI/CD​

組織ユーザートークンの失効​

クイックリファレンス​

匿名​

ユーザー登録（メール認証）​

組織​

プライベートモジュール併用​

設定方法

匿名で利用する

ユーザー登録して利用する

組織ユーザートークンで利用する

`GOPROXY` による設定について

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

設定の永続化

CI/CD で利用する

匿名で利用する

組織に紐づけて利用する

参考：Action 入力パラメータ

匿名で利用する

組織に紐づけて利用する

プライベートモジュールと併用する

`GOPRIVATE`

セットアップの確認

モジュールの公開

アンインストール

ローカル環境

CI/CD

組織ユーザートークンの失効

クイックリファレンス

匿名

ユーザー登録（メール認証）

組織

プライベートモジュール併用