Skip to main content
View as Markdown

RubyGems

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

Takumi Guard setup varies depending on your environment and the features you need. This page covers setup for both local development and GitHub Actions.

Setup​

Takumi Guard offers three ways to get started:

  • Anonymous — No token required. Set the mirror URL to enable package blocking.
  • Email-Verified — Use an email-verified token (tg_anon_…) for download tracking and breach notifications.
  • Org User Token — Use an org user token (tg_org_…) to track installations across your organization.

Both email-verified and org user tokens use the same package manager configuration.

Paid Feature

Org user tokens require an active Takumi subscription with Guard enabled. See Pricing & Billing for details.

Anonymous Usage​

You can use Takumi Guard's package blocking without authentication. Simply set the mirror URL to enable malicious package blocking. Download tracking and breach notifications are not available, but this is the easiest way to get started.

Configure Bundler with the mirror URL:

bundle config set --global mirror.https://rubygems.org https://rubygems.flatt.tech/

That's it. All bundle install commands now route through Takumi Guard.

Package Manager Compatibility

Takumi Guard supports Bundler. Bundler reads the mirror config from ~/.bundle/config, so no Gemfile change is needed.

Email-Verified Access​

Registering your email address enables download tracking and breach notifications in addition to package blocking. If a security advisory is published for a package you previously downloaded, a notification is sent to your registered email address. No Shisho Cloud account is required, and this is free of charge.

info

If you already have an org user token or email-verified token from using Takumi Guard with npm or PyPI, you don't need to register again — the same token works for RubyGems.

Step 1: Register your email

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

The language field is optional and defaults to "en". Set it to "ja" to receive emails in Japanese. This preference is stored with your token and applies to all future emails, including breach notifications.

You'll receive a welcome email within a few seconds.

Step 2: Get your API key from the email

Your API key is included directly in the welcome email. The key is ready to use immediately — no link to click.

warning

Save this key somewhere secure. If you need a new one, you can regenerate it anytime: curl -X POST -H 'Authorization: Bearer tg_anon_xxxxxx' https://rubygems.flatt.tech/api/v1/tokens/regenerate

Once you have a token, proceed to "Configure Bundler" below.

Org User Tokens​

Org user tokens (tg_org_…) can be issued from the Takumi / Shisho Cloud console, or by a bot via the Guard API. See Token Management for details on issuing tokens.

Once you have a token, proceed to "Configure Bundler" below.

Configure Bundler​

Configure Bundler with your token. This is the recommended and primary setup method:

bundle config set --global mirror.https://rubygems.org https://token:YOUR_API_KEY@rubygems.flatt.tech/

This redirects all bundle install calls transparently through Takumi Guard. No changes to your Gemfile are needed — Bundler automatically applies the mirror configuration.

Your bundle install commands now authenticate with your token, enabling download tracking and breach notifications.

GitHub Actions​

To integrate Takumi Guard into your GitHub Actions workflow, use the flatt-security/setup-takumi-guard-rubygems GitHub Action. You can use it anonymously or linked to an organization.

Anonymous Mode​

If you don't have a Shisho Cloud account yet, you can still use Takumi Guard in CI for package blocking. Omit the bot-id input:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.3"

      - uses: flatt-security/setup-takumi-guard-rubygems@v1
        # No bot-id — anonymous mode, blocking only

      - run: bundle install
      - run: bundle exec rspec

In anonymous mode, the action only configures the Bundler mirror for rubygems.org. Blocked packages are still rejected with a 403 error, but download tracking and breach notifications are not available.

With Shisho Cloud Organization​

Linking to a Shisho Cloud organization enables organization-level download tracking and breach notifications (via webhook). No long-lived secrets need to be stored in your CI environment. Authentication is performed securely by exchanging a GitHub OIDC token for a short-lived access token via the Shisho Cloud STS service.

Prerequisites:

  1. A bot identity registered in Shisho Cloud. Copy the Bot ID from the registry settings page in the Shisho Cloud console.
  2. The id-token: write and contents: read permissions in your workflow job.

Step 1: Add the action to your workflow

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write # Required for OIDC token exchange
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3.3"

      - uses: flatt-security/setup-takumi-guard-rubygems@v1
        with:
          bot-id: "BT01EXAMPLE..." # Copy from Shisho Cloud console

      - run: bundle install
      - run: bundle exec rspec

The action handles the full OIDC exchange automatically:

  1. Requests a GitHub OIDC token (with the registry host as audience)
  2. Exchanges it for a short-lived Takumi Guard access token via the STS service
  3. Configures the Bundler mirror for rubygems.org to use the Takumi Guard registry with that token
info

The Bot ID is not a secret — it is a public reference key used to look up the allowlist during token exchange. You can commit it directly in your workflow file. The Shisho Cloud console provides a ready-to-copy workflow snippet with the Bot ID pre-filled.

The access token expires after 30 minutes by default (configurable up to 24 hours via the expires-in input).

Action Inputs Reference​

InputRequiredDefaultDescription
bot-idNo—Bot ID from Shisho Cloud. Omit for anonymous blocking-only mode.
set-mirrorNotrueSet to false if you manage the Bundler mirror yourself.
registry-urlNohttps://rubygems.flatt.techCustom registry URL. Override only if directed by Shisho Cloud support.
sts-urlNohttps://sts.cloud.shisho.devSTS service URL used for the OIDC → access-token exchange.
expires-inNo1800 (seconds)Access token lifetime in seconds. Maximum 86400 (24 hours).

For the full list of inputs and outputs, see the action repository.

Using with Private Gems​

Takumi Guard is a read-only security proxy for public gems. If your project depends on private gems, you need to configure your Gemfile so that private gems bypass Takumi Guard and are fetched directly from their registry.

Gemfile Source Block​

Bundler supports per-source registry routing via the source block in your Gemfile. By adding a source block for your private registry, you can route private gems directly while public gems continue to go through Takumi Guard.

For example, if your organization hosts private gems on a custom gem server:

Keep pointing at rubygems.org in your Gemfile — the bundle config mirror setting above redirects requests to Takumi Guard automatically. Only the private registry needs an explicit source block.

# Public gems → redirected to Takumi Guard by the bundle config mirror
source 'https://rubygems.org' do
  gem 'rails', '~> 7.1'
  gem 'bundler', '~> 2.4'
end

# Private gems → bypass Takumi Guard, fetch directly
source 'https://gem-server.your-company.com/' do
  gem 'your-company-utils'
  gem 'your-company-auth'
end

With this configuration, Bundler routes requests as follows:

  • gem 'rails' → fetched via Takumi Guard (redirected by the mirror config, security scanning applied)
  • gem 'your-company-utils' → fetched directly from your private registry (bypasses Takumi Guard)
tip

You do not need to put the Takumi Guard URL or API key directly in your Gemfile. With bundle config mirror configured, your Gemfile can keep pointing at rubygems.org — this way your token is never committed to version control.

warning

Private gems routed to a different registry bypass Takumi Guard's security scanning. This is acceptable for your organization's own packages, but be aware that those packages will not be checked against the blocklist.

Verify Your Setup​

To confirm that Takumi Guard is working, try installing the harmless test gem hola-takumi at the blocked version 0.1.0. hola-takumi is a harmless test gem published by GMO Flatt Security for verifying Takumi Guard's behavior.

cd $(mktemp -d) && printf 'source "https://rubygems.org"\ngem "hola-takumi", "0.1.0"\n' > Gemfile && bundle install

If Takumi Guard is configured correctly, the proxy filters out this version and Bundler fails with the following error:

Fetching gem metadata from https://rubygems.flatt.tech/.
Could not find gem 'hola-takumi (= 0.1.0)' in rubygems repository
https://rubygems.org/ or installed locally.
note

If hola-takumi 0.1.0 is already installed in your local gem environment, Bundler uses the local copy instead of fetching from the proxy — the command then succeeds with Using hola-takumi 0.1.0 instead of failing. Remove it first and re-run:

gem uninstall hola-takumi --all --force

Publishing​

Takumi Guard is a read-only security proxy. Publishing packages is not affected because gem push and similar tools communicate directly with https://rubygems.org, not through the mirror URL.

gem push your-gem-1.0.0.gem

No changes to your publishing workflow are needed.

Uninstall​

To stop using Takumi Guard, revert your mirror settings.

Local Environment​

Remove the Takumi Guard mirror configuration from Bundler:

bundle config unset --global mirror.https://rubygems.org

GitHub Actions​

Remove the Takumi Guard action from your workflow file:

# Remove the following step
- uses: flatt-security/setup-takumi-guard-rubygems@v1
info

Once the action is removed, bundle install will access the public RubyGems registry directly. No lockfile changes are required.

Last updated on