q-ring

q-ring

MCP 経由で、AI コーディングエージェントに OS のキーチェーンシークレットを提供します。

平文の .env ファイルに API キーを貼り付けたり、扱いにくいシークレットマネージャーに手間取ったりするのはもうやめましょう。q-ring は認証情報を OS 標準の保管庫（macOS Keychain、Linux Secret Service、Windows Credential Vault）に安全に格納し、量子物理学の仕組みに着想を得た機能でさらに強化します。

📖 公式ドキュメントを見る：CLI リファレンス、MCP プロンプトのクックブック、アーキテクチャの詳細を網羅しています。

q-ring を選ぶ理由

• 重ね合わせ： 1 つのキーに複数の状態（dev/staging/prod）を保存し、コンテキストに応じて切り替えられます。
• 量子もつれ： プロジェクト間でキーをリンクすると、1 つをローテーションした際に、リンク先もすべて自動で更新されます。
• トンネル効果： 指定した時間または読み取り回数が経過すると自動消去される、一時的なメモリ内シークレットを作成できます。
• テレポーテーション： AES-256-GCM で暗号化したシークレットバンドルを安全にまとめて共有できます。
• シームレスな AI 統合： Cursor、Kiro、Claude Code でネイティブに使える、46 種類の組み込み MCP ツールを搭載しています。

🚀 インストール

q-ring はグローバルにインストールすることで、ターミナルのどこからでも使えるように設計されています。お好みのパッケージマネージャーを選んでください。

# pnpm (recommended)
pnpm add -g @i4ctime/q-ring

# npm
npm install -g @i4ctime/q-ring

# yarn
yarn global add @i4ctime/q-ring

# Homebrew (macOS / Linux)
brew install i4ctime/tap/qring

Docker（MCP サーバー）

リポジトリには、MCP サーバーをビルドして mcp-proxy 経由で公開する Dockerfile が含まれています。Glama などでのホスト型 MCP デプロイや、サーバーをホストから完全に切り離す場合に便利です。

git clone https://github.com/I4cTime/q-ring.git
cd q-ring
docker build -t qring-mcp .
docker run --rm -p 8080:8080 qring-mcp

注：コンテナ内には OS キーチェーン（GNOME Keyring / macOS Keychain）がないため、この方法は MCP プロトコルの利用、一時的な使用、CI の実験向けです。永続的なローカルシークレットの保存には適していません。日常的に使用する場合は、上記のパッケージマネージャーのいずれかを使って CLI をネイティブにインストールしてください。

⚡ クイックスタート

# 1️⃣ Store a secret (prompts securely if value is omitted)
qring set OPENAI_API_KEY sk-...

# 2️⃣ Retrieve it anytime
qring get OPENAI_API_KEY

# 3️⃣ List all keys (values are never shown)
qring list

# 4️⃣ Generate a cryptographic secret and save it
qring generate --format api-key --prefix "sk-" --save MY_KEY

# 5️⃣ Run a full health scan
qring health

# Something not working? Diagnose the install (keyring, audit, MCP wiring)
qring doctor

# Tab completion for your shell
qring completion zsh > ~/.zsh/completions/_qring   # also: bash, fish

量子機能

重ね合わせ — 1 つのキーで複数の環境に対応

1 つのシークレットに、開発環境、ステージング環境、本番環境それぞれの値を同時に保持できます。現在のコンテキストに応じて、適切な値が解決されます。

# Set environment-specific values
qring set API_KEY "sk-dev-123" --env dev
qring set API_KEY "sk-stg-456" --env staging
qring set API_KEY "sk-prod-789" --env prod

# Value resolves based on context
QRING_ENV=prod qring get API_KEY   # → sk-prod-789
QRING_ENV=dev  qring get API_KEY   # → sk-dev-123

# Inspect the quantum state
qring inspect API_KEY

環境の昇格 — 差分を確認してから昇格

シークレットが環境ごとの状態を持つようになると、昇格によってコピー＆ペーストが不要になります。2 つの環境をキーごとに比較し（値ではなくステータスのみを確認します）、一方の状態からもう一方へ値をコピーします。diff は差異がある場合に終了コード 1 を返すため、CI のゲートとしても機能します。promote は、明示的に許可しない限り、値が異なる対象を上書きしません。

# What differs between staging and prod? (same / different / missing on one side)
qring diff staging prod

# Make prod match staging for one key (asks before overwriting a different value)
qring promote DATABASE_URL --from staging --to prod

# Non-interactive, e.g. in a release script
qring promote DATABASE_URL --from staging --to prod --force --json

MCP エージェントでも、diff_environments と promote_secret として同じ 2 つの操作を利用できます。

波動関数の収縮 — 環境のスマート検出

q-ring は、明示的なフラグを指定しなくても環境を自動検出します。解決順序は次のとおりです。

1. --env フラグ
2. QRING_ENV 環境変数
3. NODE_ENV 環境変数
4. Git ブランチのヒューリスティック（main／master → 本番環境、develop → 開発環境）
5. .q-ring.json プロジェクト設定
6. シークレットのデフォルト環境

# See what environment q-ring detects
qring env

# Project config (.q-ring.json)
echo '{"env": "staging", "branchMap": {"release/*": "staging"}}' > .q-ring.json

量子崩壊 — TTL 付きシークレット

シークレットには有効期間を設定できます。期限切れのシークレットは読み取りがブロックされます。古くなったシークレット（有効期間の 75％以上が経過）は警告を発します。

# Set a secret that expires in 1 hour
qring set SESSION_TOKEN "tok-..." --ttl 3600

# Set with explicit expiry
qring set CERT_KEY "..." --expires "2026-06-01T00:00:00Z"

# Health check shows decay status
qring health

観測者効果 — すべてを監査

シークレットの読み取り、書き込み、削除はすべて、改ざんを検知できるハッシュチェーンとともに記録されます。異常検知のため、アクセスパターンも追跡されます。

# View audit log
qring audit
qring audit --key OPENAI_KEY --limit 50

# Detect anomalies (burst access, unusual hours, chain tampering)
qring audit --anomalies

# Verify audit chain integrity
qring audit:verify

# Export audit log
qring audit:export --format json --since 2026-03-01
qring audit:export --format csv --output audit-report.csv

量子ノイズ — シークレットの生成

一般的な形式で、暗号学的に強度の高いシークレットを生成します。

qring generate                          # API key (default)
qring generate --format password -l 32  # Strong password
qring generate --format uuid            # UUID v4
qring generate --format token           # Base64url token
qring generate --format hex -l 64       # 64-byte hex
qring generate --format api-key --prefix "sk-live-" --save STRIPE_KEY

エンタングルメント — シークレットのリンク

プロジェクト間でシークレットをリンクします。1 つをローテーションすると、もつれたすべてのコピーが自動的に更新されます。

# Entangle two secrets
qring entangle API_KEY API_KEY_BACKUP

# Now updating API_KEY also updates API_KEY_BACKUP
qring set API_KEY "new-value"

# Unlink entangled secrets
qring disentangle API_KEY API_KEY_BACKUP

トンネリング — エフェメラルシークレット

メモリ上にのみ存在するシークレットを作成します。ディスクに書き込まれることはありません。オプションで TTL と、読み取り回数の上限に達した際の自己破壊を設定できます。

# Create an ephemeral secret (returns tunnel ID)
qring tunnel create "temporary-token-xyz" --ttl 300 --max-reads 1

# Read it (self-destructs after this read)
qring tunnel read tun_abc123

# List active tunnels
qring tunnel list

テレポーテーション — 暗号化共有

シークレットを AES-256-GCM で暗号化されたバンドルにまとめ、マシン間で安全に転送します。バンドルをロックする方法は 2 つあります。

• パスフレーズ（v1）：PBKDF2-HMAC-SHA512（210 000 回の反復）でキーを導出します。各バンドルに反復回数が記録されるため、古いバンドルも引き続き展開できます。
• 受信者（v2、0.18）：各チームメイトが qring teleport keygen を一度実行し、受信者文字列（qring1…。X25519 公開鍵で、秘密鍵は各自の OS キーリングに保存されます）を共有します。pack --to は、一時的な X25519 鍵合意による HKDF-SHA256 を使って新しいコンテンツキーを各受信者向けに暗号化します。処理全体で AES-256-GCM を使用し、node:crypto のみを利用するため、バンドルと一緒に秘密情報が送られることはなく、パスフレーズを声に出して伝える必要もありません。

# Passphrase bundle (prompts)
qring teleport pack --keys "API_KEY,DB_PASS" > bundle.txt
cat bundle.txt | qring teleport unpack

# Recipient bundle: teammates publish their recipient once…
qring teleport keygen            # → qring1a3F…  (share this; keep the keyring)
qring teleport identity          # print it again later

# …then you address the pack to them (repeatable or comma-separated)
qring teleport pack --keys "API_KEY,DB_PASS" --to qring1a3F… --to qring1Zz9… > bundle.txt

# They unpack with the identity in their keyring — no passphrase
cat bundle.txt | qring teleport unpack

# Preview: who it's addressed to, whether that's you, and what's inside
qring teleport unpack <bundle> --dry-run

インポート — シークレットの一括取り込み

.env ファイルから q-ring にシークレットを直接インポートします。コメント、引用符で囲まれた値、エスケープシーケンスなど、標準の dotenv 構文に対応しています。CLI ではファイルパスと生のコンテンツのどちらも指定できます。import_dotenv MCP ツールが受け付けるのは生のコンテンツのみで（ディスク上のファイルを読み取ることはありません）、エージェントが任意のローカルファイルを読み取るよう強制することはできません。

# Import all secrets from a .env file
qring import .env

# Import to project scope, skipping existing keys
qring import .env --project --skip-existing

# Preview what would be imported
qring import .env --dry-run

選択的エクスポート

キー名またはタグフィルターを使って、必要なシークレットのみをエクスポートします。

# Export specific keys
qring export --keys "API_KEY,DB_PASS,REDIS_URL"

# Export by tag
qring export --tags "backend"

# Combine with format
qring export --keys "API_KEY,DB_PASS" --format json

シークレットの検索とフィルタリング

タグ、有効期限の状態、キーのパターンで qring list の出力をフィルタリングします。

# Filter by tag
qring list --tag backend

# Show only expired secrets
qring list --expired

# Show only stale secrets (75%+ decay)
qring list --stale

# Glob pattern on key name
qring list --filter "API_*"

# Script-friendly existence check (exit 0 if present, 1 if not; decay-aware)
qring has OPENAI_API_KEY --quiet && echo "configured"

プロジェクトシークレットマニフェスト

.q-ring.json で必要なシークレットを宣言し、単一のコマンドでプロジェクトの準備状況を検証します。

# Validate project secrets against the manifest
qring check

# See which secrets are present, missing, expired, or stale
qring check --project-path /path/to/project

環境ファイルの同期

プロジェクトマニフェストから .env ファイルを生成し、環境に応じて重ね合わせを収縮させながら、各キーの値を q-ring から解決します。

# Generate to stdout
qring env:generate

# Write to a file
qring env:generate --output .env

# Force a specific environment
qring env:generate --env staging --output .env.staging

シークレット参照と最小権限での実行

qring:// 参照は、シークレットへのコミット可能なポインターです。値の代わりに .env ファイルに記述します。qring run は起動時に参照とマニフェストキーを解決し、プロジェクトで宣言されたものだけを注入します（スコープ全体を注入する exec とは異なります）。出力は自動的にマスキングされます。

# .env — safe to commit: these are references, not values
DATABASE_URL=qring://project/DATABASE_URL
OPENAI_API_KEY=qring://global/OPENAI_API_KEY
STRIPE_KEY=qring:///STRIPE_KEY            # auto scope: project, then global
SESSION_TTL=3600                          # plain values pass through

# Run with declared secrets injected (manifest + .env refs)
qring run -- pnpm dev

# Preview what would be injected, without running
qring run --dry-run -- pnpm dev

# Pin an environment, use a specific env file, or skip the manifest
qring run --env prod --env-file .env.prod --no-manifest -- ./deploy.sh

キーはホストではなくパスに記述します（qring://project/KEY。qring://KEY ではありません）。URL のホスト名は大文字と小文字を区別しませんが、環境変数のキーは区別します。不正な参照は明示的にエラーとなり、リテラルの qring://… 文字列が子プロセスに漏れることはありません。環境を固定した参照の例：qring://project/DATABASE_URL?env=prod。

エディターの設定

1 つのコマンドで、エディターの MCP 設定に q-ring MCP サーバーを追加できます。他のサーバーを保持したまま非破壊的に統合され、既存の q-ring エントリーは --force を指定した場合にのみ置き換えられます。

qring setup cursor          # .cursor/mcp.json (project) or --global for ~/.cursor
qring setup kiro            # .kiro/settings/mcp.json, with read-only autoApprove list
qring setup claude          # .mcp.json (project scope)

# Preview without writing
qring setup cursor --dry-run

デプロイプラットフォームへのプッシュ

GitHub Actions、Vercel、Cloudflare Workers、fly.io、Railway、Netlify には、各プラットフォーム独自の認証済み CLI（gh / vercel / wrangler / flyctl / railway / netlify）を介してマニフェストのシークレットをプッシュします。q-ring がプラットフォームのトークンを保持することはなく、値は標準入力経由で渡されます（Netlify のインポート専用 CLI の場合は、0600 の一時ファイルを使い、直ちに削除します）。値が argv 経由で渡されることはありません。すべてのプッシュは監査チェーンに記録されます。

# Push the .q-ring.json manifest keys to GitHub Actions secrets
qring push github --repo you/your-app

# Push to Vercel environments
qring push vercel --vercel-env production,preview

# Push to Cloudflare Workers secrets
qring push cloudflare

# fly.io (flyctl secrets import over stdin — note flyctl deploys per import), Railway, Netlify
qring push fly --app my-app
qring push railway --service api --railway-env production
qring push netlify --site 1234-abcd

# Explicit keys, preview first
qring push github --keys DATABASE_URL,API_KEY --dry-run

カナリアも同時に登録できます。qring canary plant KEY --format aws --push github は、ローカルでハニートークンを植え付け、値を読み返すことなくプラットフォームにも登録します（Canary Honeytokens を参照）。

シークレットの有効性検証

対象サービスに対してシークレットが実際に有効かどうかをテストします。q-ring はキーのプレフィックス（sk- → OpenAI、ghp_ → GitHub など）からプロバイダーを自動検出するか、明示的なプロバイダー名を受け付けます。

# Validate a single secret
qring validate OPENAI_API_KEY

# Force a specific provider
qring validate SOME_KEY --provider stripe

# Validate all secrets with detectable providers
qring validate --all

# Only validate manifest-declared secrets
qring validate --all --manifest

# List available providers
qring validate --list-providers

組み込みプロバイダー： OpenAI、Anthropic、OpenRouter、Google AI（Gemini）、Groq、Hugging Face、ElevenLabs*、Vercel*、Stripe、GitHub、AWS（形式チェック）、Generic HTTP。キーはヘッダーでのみ送信され、URL に含まれることはありません。（*安全な公開プレフィックスがないため、--provider またはマニフェストの provider フィールドで明示的に選択してください。）

出力：

  ✓ OPENAI_API_KEY   valid    (openai, 342ms)
  ✗ STRIPE_KEY       invalid  (stripe, 128ms) — API key has been revoked
  ⚠ AWS_ACCESS_KEY   error    (aws, 10002ms) — network timeout
  ○ DATABASE_URL     unknown  — no provider detected

フック — シークレット変更時のコールバック

シークレットの作成、更新、削除時に実行される Webhook、シェルコマンド、またはプロセスシグナルを登録します。キーの照合、glob パターン、タグによるフィルタリング、スコープの制約に対応しています。

# Run a shell command when a secret changes
qring hook add --key DB_PASS --exec "docker restart app"

# POST to a webhook on any write/delete
qring hook add --key API_KEY --url "https://hooks.example.com/rotate"

# Trigger on all secrets tagged "backend"
qring hook add --tag backend --exec "pm2 restart all"

# Signal a process when DB secrets change
qring hook add --key-pattern "DB_*" --signal-target "node"

# List all hooks
qring hook list

# Remove a hook
qring hook remove <id>

# Enable/disable
qring hook enable <id>
qring hook disable <id>

# Dry-run test a hook
qring hook test <id>

フックは実行を待たずに処理されるため、フックが失敗してもシークレット操作はブロックされません。フックレジストリーは ~/.config/q-ring/hooks.json に保存されます。

SSRF 対策： プライベート／ループバック IP 範囲（127.0.0.0/8、10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、169.254.0.0/16、::1、fc00::/7）を対象とする HTTP フック URL は、デフォルトでブロックされます。DNS は事前にチェックされ、接続時にも再検証されるため、ホスト名がチェックを通過した後、ソケットが開く前にプライベートアドレスへ再バインドされることはありません。開発中などにローカルサービスを対象とするフックを許可するには、環境変数 Q_RING_ALLOW_PRIVATE_HOOKS=1 を設定してください。

設定可能なローテーション

シークレットごとにローテーション形式を設定すると、エージェントが正しい値の形式で自動ローテーションできるようになります。また、ローテーション間隔を設定すると、認証情報が古くなる前に q-ring がお知らせします。各シークレットには、値が最後に変更された日時（rotatedAt）が記録されます。--rotate-every を指定すると、間隔の最後の 20％（または直近 7 日間のうち短い方）に入った時点で まもなく期限、それを過ぎると 期限切れ になります。これは qring inspect、qring rotate:due、ダッシュボードの「Rotate soon」カード、および inspect_secret ツールに表示されます。

# Store a secret with rotation format metadata
qring set STRIPE_KEY "sk-..." --rotation-format api-key --rotation-prefix "sk-"

# Store a password with password rotation format
qring set DB_PASS "..." --rotation-format password

# Remind me every 90 days
qring set STRIPE_KEY "sk-..." --rotate-every 90

# What needs rotating? (most overdue first; --all lists every scheduled secret)
qring rotate:due
qring rotate:due --json

セキュアな実行と自動マスキング

シークレットを環境変数に安全に注入してコマンドを実行します。既知のシークレット値はすべて標準出力と標準エラーから自動的にマスキングされ、ターミナルログやエージェントのトランスクリプトへの漏えいを防ぎます。実行プロファイルによって、実行可能なコマンドを制限できます。

# Execute a deployment script with secrets injected
qring exec -- npm run deploy

# Inject only specific tags
qring exec --tags backend -- node server.js

# Run with a restricted profile (blocks network tools and interpreters/shells, 30s timeout)
qring exec --profile restricted -- npm test

コードベースのシークレットスキャナー

レガシーなコードベースを移行していますか？正規表現によるヒューリスティックとシャノンエントロピー分析を使って、ディレクトリー内のハードコードされた認証情報をすばやくスキャンできます。

# Scan current directory
qring scan .

出力：

  ✗ src/db/connection.js:12
    Key:     DB_PASSWORD
    Entropy: 4.23
    Context: const DB_PASSWORD = "..."

複合／テンプレート化されたシークレット

他のシークレットを動的に解決する複雑な接続文字列を保存します。DB_PASS がローテーションされても、手動で更新しなくても DB_URL は自動的に正しい値になります。

qring set DB_USER "admin"
qring set DB_PASS "supersecret"
qring set DB_URL "postgres://{{DB_USER}}:{{DB_PASS}}@localhost/mydb"

# Resolves embedded templates automatically
qring get DB_URL 
# Output: postgres://admin:supersecret@localhost/mydb

ユーザー承認（ゼロトラストエージェント）

明示的なユーザー承認なしに、MCP サーバーが機密性の高い本番環境のシークレットを自律的に読み取ることを防ぎます。各承認トークンは HMAC で検証され、スコープが設定され、理由が記録され、有効期間が制限されています。このゲートは一括読み取りにも適用されます。MCP 経由の export_secrets と teleport_pack は、有効な許可がない承認保護対象のキーをスキップします。

# Mark a secret as requiring approval
qring set PROD_DB_URL "..." --requires-approval

# Temporarily grant MCP access for 1 hour with a reason
qring approve PROD_DB_URL --for 3600 --reason "deploying v2.0"

# List all approvals with verification status
qring approvals

# Revoke an approval
qring approve PROD_DB_URL --revoke

エージェントが承認保護対象のキーへのアクセスをブロックされると、q-ring はキー名と正確な qring approve コマンドを示すデスクトップ通知を表示します（Linux では notify-send、macOS では osascript）。キーごとに通知が抑制され、QRING_NOTIFY=off で無効にできます。

カナリア・ハニートークン

本物と見分けがつかず、同じように読み取れる偽の認証情報を仕掛けます。侵害された MCP サーバー、好奇心の強すぎるエージェント、リング内をくまなく調べる流出したツールなど、これに触れたものには、見破られることなく偽の値が返されます。その一方で、q-ring はデスクトップアラートを発し、改ざん検知可能な監査チェーンに canary イベントを書き込みます。

# Plant a canary shaped like a real AWS access key
qring canary plant AWS_SECRET_ACCESS_KEY --format aws

# Other shapes: aws-secret, github, github-pat, openai, openai-project,
# anthropic, stripe, gitlab, slack, google, npm, generic
qring canary plant GHP_BACKUP_TOKEN --format github-pat

# See what's been tripped
qring canary list
qring audit --action canary

値は、プロバイダーの実際のトークン形式に沿った CSPRNG のノイズです（aws のカナリアは AKIA[A-Z0-9]{16} に、anthropic のカナリアは実際の sk-ant-api03-…AA の形式に一致します）。使われてしまうほど本物らしく見えますが、有効ではありません。アラートはキーごとに 30 秒間で 1 回までに制限され、監査証跡にはすべての読み取りが記録されます。

通知を受け取りましょう。 デスクトップ通知は、マシンのそばにいるときにしか役立ちません。Webhook チャネルを登録すれば、トリップが発生するたびにそちらにも通知されます。

qring canary alert add --discord https://discord.com/api/webhooks/…
qring canary alert add --slack   https://hooks.slack.com/services/…
qring canary alert add --ntfy    https://ntfy.sh/my-canaries
qring canary alert add --url     https://example.com/canary   # generic JSON POST
qring canary alert list
qring canary alert test          # send a clearly-labelled drill

チャネルは ~/.config/q-ring/canary-alerts.json に保存されます（モード 0600）。送信は結果を待たずに行われ、フックと同様に SSRF 対策が施され、デスクトップアラートと同じく送信が制限されます。また、偽の値が含まれることはなく、キー、スコープ、送信元、およびアクセスを試みたエージェントのラベルのみが通知されます。

CI にトリップワイヤーを仕掛けましょう。 カナリアを仕掛け、デプロイプラットフォームに一度の手順でプッシュすれば、GitHub Actions／Vercel／Cloudflare の環境変数が漏えいした場合におとりとして機能します。

qring canary plant AWS_SECRET_ACCESS_KEY --format aws-secret --push github --repo you/your-app

正直な注意点として、q-ring が検知できるのは q-ring 経由の読み取りだけです。プラットフォーム側で漏えいした値が直接使われても、ここでは確認できません。その必要がある場合は、プロバイダー独自のアラート機能と併用してください。

カナリアは、存在を悟られないよう設計されています。識別につながる説明は付いていません（必要であれば、--description で無害なカバー説明を追加できます）。フラグが MCP ツールの応答に表示されることもありません。トリップ記録を確認できるのはオペレーターのターミナルだけで、MCP 監査ツールを介してエージェントが見ることはできません。一括 export や delete でも読み取りと同じようにトリップするため、リング内を調べたり、トリップワイヤーを削除したりすると、いずれもアラートが鳴ります。不要になったら、qring canary disarm <key> で通常のシークレットに戻せます（カナリアに対して qring set を実行すると、事前に警告が表示されます。フラグは意図的に上書き後も残り、エージェントがカナリアを消し去ることはできません）。

MCP Airlock

サードパーティ製 MCP サーバーを q-ring の背後で実行します。エアロックはエージェントホストとラップされたサーバーの間に配置され、環境変数を削除した環境（API キーは継承されません。--inherit-env で再び有効にできます）でサーバーを起動します。エアロックを通過するすべてのツール呼び出し、リソースの読み取り、プロンプトの取得を、監査チェーンにセッションごとにグループ化し、呼び出し元のクライアント ID を付けた wrap イベントとして記録し、結果がトランスクリプトに届く前に、既知のシークレット値をすべて削除して、プロジェクトの policy.wrap ルールを適用します。ツールとプロンプトの引数にはシークレットが含まれる可能性があるため、記録されません。

{
  "mcpServers": {
    "some-server": {
      "command": "qring",
      "args": ["mcp", "wrap", "--", "npx", "-y", "some-mcp-server"]
    }
  }
}

ツール、リソース、プロンプトはすべてそのまま通過します（ページネーション、進捗通知、キャンセル、サブスクリプション、list_changed／updated 通知も含みます）。エアロックはラップされたサーバーが持つ機能をそのまま正確に提示します。長時間実行されるツールにはホスト側のタイムアウトが適用され、エアロック側には QRING_WRAP_TIMEOUT_MS で設定できる十分に長い上限時間が設けられています。

# Wrap a remote Streamable HTTP server; the Bearer token comes from q-ring (audited read)
qring mcp wrap --url https://mcp.example.com/mcp --auth-secret EXAMPLE_MCP_TOKEN

# Keep results verbatim (default: known secret values are replaced with [QRING:REDACTED])
qring mcp wrap --no-redact -- npx -y some-mcp-server

ラップポリシー。 .q-ring.json からラップされたサーバーを制御します。同じファイル、同じフェイルクローズ型エンジンを使用します。

{
  "policy": {
    "wrap": {
      "allowTools": ["github_*", "search"],
      "denyTools": ["github_delete_*"],
      "approveTools": ["github_merge_pr"],
      "rateLimit": { "maxCalls": 60, "perSeconds": 60 },
      "toolRateLimits": { "search": { "maxCalls": 5, "perSeconds": 10 } },
      "redactResults": true
    }
  }
}

拒否されたツールは tools/list から隠され、呼び出しも拒否されて policy_deny 監査イベントが記録されます。approveTools は許可されるまで拒否されます。

qring mcp approve github_merge_pr --for 900 --reason "release 1.4"
qring mcp approvals
qring mcp approve github_merge_pr --revoke

エアロックの役割を明確に理解してください。環境変数の削除、通過したすべての操作の改ざん防止記録、ツール境界でのポリシー適用、そしてリングが把握しているシークレットの値のベストエフォートによるマスキングです。サンドボックスではありません。ラップされたプロセスは引き続きユーザー権限で実行され、通常のファイルシステム、ネットワーク、OS キーチェーンにアクセスできます。また、ツールの説明は検査されずにそのまま通過します。実際の境界については docs/threat-model.md を参照してください。

Just-In-Time（JIT）プロビジョニング

静的な認証情報を保存する代わりに、要求時に短期間有効なトークンを動的に生成するよう q-ring を設定します（例：AWS STS、汎用 HTTP エンドポイント）。

# Store the STS role configuration
qring set AWS_TEMP_KEYS '{"roleArn":"arn:aws:iam::123:role/AgentRole", "durationSeconds":3600}' --jit-provider aws-sts

# Resolving the secret automatically assumes the role and caches the temporary token
qring get AWS_TEMP_KEYS

AI エージェント向けプロジェクトコンテキスト

プロジェクトのシークレット、設定、状態を安全にマスキングして概観できます。シークレット値を一切公開せずに AI エージェントのシステムプロンプトに含めることを想定しています。

# Human-readable summary
qring context

# JSON output (for MCP / programmatic use)
qring context --json

シークレット対応リンター

特定のファイルをスキャンして、ハードコードされたシークレットを検出します。自動修正もオプションで利用できます。--fix を使用すると、検出されたシークレットは process.env.KEY 参照に置き換えられ、q-ring に保存されます。

# Lint files for hardcoded secrets
qring lint src/config.ts src/db.ts

# Auto-fix: replace hardcoded values and store in q-ring
qring lint src/config.ts --fix

# Scan entire directory with auto-fix
qring scan . --fix

エージェントメモリ

AI エージェントのセッションをまたいで保持される、暗号化された永続的なキーと値のストアです。ローテーション履歴、プロジェクトの決定事項、コンテキストの記憶に役立ちます。

# Store a memory
qring remember last_rotation "Rotated STRIPE_KEY on 2026-03-21"

# Retrieve it
qring recall last_rotation

# List all memories
qring recall

# Forget
qring forget last_rotation

コミット前のシークレットスキャン

ハードコードされたシークレットを含むコミットを自動的にブロックする Git のコミット前フックをインストールします。

# Install the hook
qring hook:install

# Uninstall
qring hook:uninstall

シークレット分析

使用パターンを分析し、シークレットの最適化に関する提案を取得します。

qring analyze

出力には、最も頻繁にアクセスされたシークレット、未使用または古くなったシークレット、スコープ最適化の提案、ローテーションの推奨事項が含まれます。

サービスセットアップウィザード

1 つのコマンドで、シークレット、マニフェストエントリ、フックを含む新しいサービス連携をすばやく設定します。

# Create secrets for a new Stripe integration
qring wizard stripe --keys STRIPE_KEY,STRIPE_SECRET --provider stripe --tags payment

# With a hook to restart the app on change
qring wizard myservice --hook-exec "pm2 restart app"

ガバナンスポリシー

.q-ring.json でプロジェクトレベルのガバナンスルールを定義し、使用できる MCP ツール、アクセスできるキー、実行できるコマンド、エアロックの背後でラップされた MCP サーバーが実行できる操作を制御します。ポリシーは MCP サーバー、キーリング、エアロックの各レベルで適用されます。

MCP 経由では、ポリシーは呼び出し元が渡す projectPath ではなく、サーバーが起動されたディレクトリから解決されます。そのため、エージェントがポリシーのないディレクトリを指定して制限を回避することはできません。.q-ring.json があるプロジェクトのルートから MCP サーバーを起動してください。.q-ring.json の変更は自動的に反映されます（ファイルが変更されるとポリシーキャッシュが無効になるため、サーバーを再起動する必要はありません）。

ポリシーファイルはスキーマ検証され、フェイルクローズで動作します。無効な policy オブジェクト（たとえば、denytools のようなタイプミス）があると、黙って無視されるのではなく PolicyConfigError が発生するため、不正なルールによってアクセス範囲が拡大することはありません。

# View the active policy
qring policy

# JSON output
qring policy --json

.q-ring.json のポリシー例：

{
  "policy": {
    "mcp": {
      "denyTools": ["delete_secret"],
      "deniedKeys": ["PROD_DB_PASSWORD"],
      "deniedTags": ["production"]
    },
    "exec": {
      "denyCommands": ["curl", "wget", "ssh"],
      "maxRuntimeSeconds": 30
    },
    "secrets": {
      "requireApprovalForTags": ["production"],
      "maxTtlSeconds": 86400
    },
    "wrap": {
      "denyTools": ["*_delete_*"],
      "approveTools": ["deploy_*"],
      "rateLimit": { "maxCalls": 60, "perSeconds": 60 }
    }
  }
}

Exec プロファイル

許可するコマンド、ネットワークアクセス、タイムアウト、環境変数のサニタイズを制御する名前付きプロファイルで、コマンドの実行を制限します。

# Run with the "restricted" profile (blocks network tools and interpreters/shells; 30s timeout)
qring exec --profile restricted -- npm test

# Run with the "ci" profile (5min timeout, allows network)
qring exec --profile ci -- npm run deploy

# Default: unrestricted
qring exec -- echo "hello"

組み込みプロファイル： unrestricted、restricted（ネットワークツールとインタープリター／シェルの両方を拒否します。python -c、node -e、bash などを使って注入されたシークレットを外部に持ち出すことはできません。制限時間は30秒です）、ci（制限時間は5分で、破壊的なコマンドをブロックします）。

改ざん検知可能な監査

すべての監査イベントには直前のイベントの SHA-256 ハッシュが含まれ、改ざんを検知できるチェーンが構築されます。v0.14 以降、チェーンは OS のキーリングに保存されたキー付き HMAC によってもアンカーされるため、qring audit:verify はインプレース編集だけでなく、切り詰めやファイル全体の書き換えも検知します。整合性を検証し、複数の形式でログをエクスポートできます。MCP セッションのイベントには、接続クライアントが自己申告した ID（clientInfo の name@version）も記録されます。この情報は qring audit の出力に表示され、qring audit --agent <label> でフィルタリングできます。これは「どのエージェントが実行したか」を示す監査ラベルであり、クライアントが報告内容を選べるため、認可の境界ではありません。

# Verify the entire audit chain
qring audit:verify

# Export as JSON
qring audit:export --format json --since 2026-03-01

# Export as CSV
qring audit:export --format csv --output audit-report.csv

エージェントセッションのタイムライン

すべての MCP セッションにはクライアントの ID（clientInfo の name@version）が、すべてのエアロックセッションには相関 ID が記録されます。audit:sessions は、フラットな監査フィードをエージェントプロセスごとのタイムラインにまとめ直します。そのため、「そのセッションで Cursor が何をしたか」を確認するのに、grep ではなく1つのコマンドで済みます。

# One block per session: agent, source, window, event + denial counts, keys touched
qring audit:sessions

# Narrow to one client, widen the window, print every event line
qring audit:sessions --agent "[email protected]" --since 7d --verbose

# Machine-readable
qring audit:sessions --json

エアロックセッション（qring mcp wrap）は airlock: <wrapped command> として表示され、プロキシされた各呼び出しが順番に並びます。ステータスダッシュボード（qring status）には、同じデータが展開可能な Agent Sessions (24h) カードとして表示されます。

エージェントは自身の履歴も確認できます。ツールではなく、MCP リソースとして確認します。qring://sessions はセッションの概要を一覧表示し、qring://sessions/{id} は1つのタイムラインを返します（キー名とアクションのみで、値は含まれません）。エージェント側では、次の2つが保証されます。セッションビューで要約が作られる前にカナリアのトリップ情報が取り除かれるため、ハニートークンがセッションビューから見つかることはありません。また、.q-ring.json のポリシーで audit_log ツールを拒否するとリソースも非表示になります。1つの設定で、エージェントからの監査情報の表示を制御できます。

暗号化ファイルバックエンド（ヘッドレス／CI）

OS のキーリングがまったくないホスト（ヘッドレス Linux、コンテナー、CI）では、暗号化ファイルストアを選択できます。シークレット、監査アンカー、エージェントメモリーキーなど、すべてのデータがこのストア経由になります。

export QRING_BACKEND=file
export QRING_FILE_PASSPHRASE="a strong passphrase"   # required — no passphrase, no access
qring set CI_TOKEN

このストアは ~/.config/q-ring/file-backend.enc にある AES-256-GCM で保護されたファイルです（モードは 0600、パスは QRING_FILE_BACKEND_PATH で変更できます）。パスフレーズから PBKDF2 で生成したキーを使用します。これは明示的な選択が必要です。OS のキーリングがない場合でも、暗黙にこのストアへフォールバックすることはありません。また、パスフレーズがない場合はすべての操作がフェイルクローズで失敗します。q-ring がマシン情報から導出できるキーで暗号化することはありません。

チームおよび組織スコープ

global および project スコープに team と org スコープを追加し、グループ間でシークレットを共有できます。解決順序は project → team → org → global で、最も具体的なスコープが優先されます。

# Store a secret in team scope
qring set SHARED_API_KEY "sk-..." --team my-team

# Store in org scope
qring set ORG_LICENSE "lic-..." --org acme-corp

# Resolution cascades: project > team > org > global
qring get API_KEY --team my-team --org acme-corp

発行者ネイティブのローテーション

対応しているプロバイダーではプロバイダー固有のシークレットローテーションを試行し、対応していない場合はローカルでの生成にフォールバックします。

# Rotate via the detected provider
qring rotate STRIPE_KEY

# Force a specific provider
qring rotate API_KEY --provider openai

CI シークレット検証

CI に適したモードで、すべてのシークレットを各プロバイダーに対して一括検証します。構造化された合否レポートを返し、失敗時の終了コードは 1 です。

# Validate all secrets (CI mode)
qring ci:validate

# JSON output for pipeline parsing
qring ci:validate --json

エージェントモード — 自律監視

シークレットの状態を継続的に監視し、異常を検出するとともに、必要に応じて期限切れのシークレットを自動ローテーションするバックグラウンドデーモンです。

# Start the agent
qring agent --interval 60 --verbose

# With auto-rotation of expired secrets
qring agent --auto-rotate

# Single scan (for CI/cron)
qring agent --once

Quantum ステータスダッシュボード — ライブ監視

ブラウザーでリアルタイムダッシュボードを起動し、Quantum サブシステム全体を一目で把握できるページに表示します。ローカルで配信される単一の自己完結型 HTML ページで、クラウド不要、設定不要、完全オフラインです。Preact + htm アプリとして構築されており、ランタイムはバンドルされ、インライン化されています。Server-Sent Events を介して 5 秒ごとに更新を配信し、DOM をその場で差分更新するため、データ更新のたびに表示アニメーションが再実行されることはありません。また、検索入力、カーソル位置、スクロール位置も更新後に保持されます。

表示される内容：

• KPI ストリップ — シークレットの総数、検出された環境、保護された件数、有効な承認数、フック数、過去 24 時間の読み取り数、現在の異常数。
• 健全性の概要 — 正常／古い／期限切れ／減衰なしのシークレットを示すドーナツグラフと、スコープ別（グローバル／プロジェクト／チーム／組織）の件数。
• 環境 — 波動関数の収縮に関する詳細（検出された環境、ソース、ブランチ、プロジェクトコンテキスト）。
• マニフェスト — .q-ring.json の概要。宣言済み／必須／不足／期限切れ／古いキーを表示します。
• ポリシー — MCP、exec、シークレットの各ポリシーをひと目で確認できます（許可／拒否するツール、拒否するキー／タグ、許可／拒否するコマンド、承認とローテーションの要件）。
• シークレットテーブル — すべてのシークレットを検索・並べ替えできる一覧（キー、スコープ、環境、種類、減衰、タグ、最終読み取り日時）。expired、stale、protected フィルター用のクイックチップもあります。/ キーを押すと検索ボックスにフォーカスします。
• Quantum カード — 減衰タイマー、重ね合わせ状態、エンタングルメントのペア、有効な量子トンネル。
• 承認とフック — 有効な（および改ざんされた）承認許可のライブ一覧と、登録済みのすべてのフックおよびその一致概要。
• エージェントセッション（24 時間） — MCP クライアントまたはエアロックセッションごとに展開可能な行を表示します。エージェントラベル、ソース、期間、イベント数と拒否数、最近のイベントを確認できます。
• エージェントメモリ — ~/.config/q-ring/agent-memory.enc に永続化された暗号化メモリキーの数。
• 異常アラート — 読み取りの急増、時間外アクセス、改ざんされた監査チェーン、その他の不審なパターン。
• 監査ログ（24 時間） — アクションチップ（read／write／delete／export）、ソースチップ（cli／mcp／hook／agent）、フリーテキストフィルターで絞り込めるフィード。

トップバーのコントロールから、SSE 更新の一時停止（監査フィードを読むときに便利です）、必要に応じた更新、または未加工の JSON スナップショット /api/status への移動ができます。キーボードショートカット：/ シークレット検索にフォーカス · P 一時停止 · R 更新。

ダッシュボードは 127.0.0.1 のみにバインドされ、シークレットの値を公開することは決してありませんが、キー名、監査ログ、承認許可は表示されます。そのため、すべてのルートは起動ごとにランダムに生成されるトークンで保護されています。qring status を実行すると、?token=… を含む完全な URL が表示され、ブラウザーで開きます。トークンなしのリクエストには 403 が返されます。サーバーを停止すると、トークンは無効になります。

# Open the dashboard (auto-launches your browser at http://127.0.0.1:9876/?token=…)
qring status

# Specify a custom port
qring status --port 4200

# Don't auto-open the browser (copy the printed tokenized URL yourself)
qring status --no-open

MCP サーバー

q-ring には、AI エージェント連携用の 46 個のツールを備えたフル機能の MCP サーバーが含まれています。

コアツール

ツール	説明
get_secret	シークレットの値を読み取ります（重ね合わせ状態を収束させ、読み取りを監査します）
list_secrets	スコープ内のキーとメタデータを一覧表示します（値は公開されません）。タグ、有効期限、glob で絞り込めます
set_secret	オプションの TTL、環境ごとの状態、タグ、ローテーション形式を指定して、単一のシークレットを作成または上書きします
promote_secret	ある環境状態から別の環境状態へ、シークレットの値をコピーします（値が等しい場合は何もせず、異なる値のターゲットを上書きするには force を指定します）
diff_environments	2 つの環境をキーごとに比較します（一致／不一致／a のみ／b のみ／収束済み）。ステータスのみを返し、値は返しません
delete_secret	シークレットの値を完全に削除します（q-ring から元に戻すことはできません）
has_secret	減衰を考慮したブール値の存在確認を行います（読み取り監査は行いません）
export_secrets	1 回限りのエクスポート用に、複数のシークレットを .env または JSON 形式で出力します（許可がない場合、承認保護されたキーはスキップします）
import_dotenv	.env テキストを解析し、すべてのキーと値のペアを一括保存します（生のコンテンツのみ受け付け、ファイルは読み取りません）
check_project	.q-ring.json マニフェストとキーリングを比較し、不足、期限切れ、古いキーを検出します
env_generate	プロジェクトマニフェストから完全な .env の内容を出力し、不足項目について警告します

量子ツール

ツール	説明
inspect_secret	値を公開せずに、1 つのキーのメタデータ（状態、減衰、エンタングルメント、アクセス回数）を表示します
detect_environment	現在のコンテキストで重ね合わせ状態の収束を左右する環境スラッグを特定します
generate_secret	選択した形式で CSPRNG に基づく値を生成し、オプションで保存します
entangle_secrets	2 つのキーをリンクし、以降の書き込み／ローテーションで同じ値が伝播するようにします
disentangle_secrets	2 つのキー間の同期リンクを解除します（値は削除されません）

トンネリングツール

ツール	説明
tunnel_create	値をプロセスメモリに一時保存し、不透明な ID を返します（ディスクには一切触れません）
tunnel_read	ID でトンネリングされた値を取得します（読み取り時に自動消去される場合があります）
tunnel_list	残りの読み取り可能回数と TTL とともに、アクティブなトンネルを列挙します（ID のみ）
tunnel_destroy	TTL または読み取り可能回数が尽きる前に、メモリからトンネルを直ちに削除します

テレポーテーションツール

ツール	説明
teleport_pack	選択したシークレットを、パスフレーズで保護された AES-256-GCM バンドルに暗号化します
teleport_unpack	テレポートバンドルを復号し、各シークレットをインポートします（オプションでドライランを実行できます）

検証ツール

ツール	説明
validate_secret	上流サービス（OpenAI／Stripe／GitHub／AWS／HTTP）にアクセスして、単一のキーが現在も有効か確認します
list_providers	組み込みの検証プロバイダーと、自動検出用のプレフィックスを列挙します

フックツール

ツール	説明
register_hook	書き込み／削除／ローテーション時に実行されるシェル／HTTP／シグナルの副作用を登録します
list_hooks	登録済みのすべてのフックを、マッチ条件、種類、有効フラグとともに表示します
remove_hook	シークレットには触れずに、ID を指定して単一のフックを解除します

実行・スキャンツール

ツール	説明
exec_with_secrets	シークレットを環境変数として注入し、漏えいした値を出力からマスキングして、子コマンドを実行します
scan_codebase_for_secrets	ディレクトリツリーを走査し、正規表現とエントロピーのヒューリスティックを使ってハードコードされたシークレットを検出します
lint_files	指定したファイル一覧を調べ、ハードコードされたシークレットを検出します。オプションで process.env.KEY への自動修正も行えます

AI エージェントツール

ツール	説明
get_project_context	秘密情報、環境、マニフェスト、フック、最近の監査アクティビティを含む、秘密情報をマスキングした単一のスナップショット
agent_remember	セッションをまたいで、秘密情報を含まないメモを暗号化されたエージェントメモリに保存します
agent_recall	メモリの値を読み取ります。キーを指定しない場合は、保存されているすべてのキーを一覧表示します
agent_forget	エージェントメモリからキーを完全に削除します
analyze_secrets	使用状況プロファイル：アクセス頻度が最も高いもの、古いもの、未アクセスのもの、ローテーション対象の候補

オブザーバー＆ヘルスツール

ツール	説明
audit_log	キー、アクション、件数で絞り込んで、改ざん検知可能な監査ログを検索します
detect_anomalies	監査履歴から、短時間の大量読み取りや営業時間外のアクティビティを検出します
verify_audit_chain	監査ハッシュチェーンを再計算し、改ざんがあった場合は最初の破損箇所を報告します
export_audit	アーカイブ／SIEM 用に、監査イベントを jsonl、json、または csv 形式でエクスポートします
health_check	読み取り専用のスコープ検査：経過、古いもの、期限切れの件数と現在の異常を表示します
status_dashboard	ライブ KPI、秘密情報、フック、監査フィードを備えたローカル SSE ダッシュボードを起動します（トークンで保護された 127.0.0.1 URL を返します）
agent_scan	複数プロジェクトのヘルスチェックを実行します。期限切れの秘密情報には、オプションで autoRotate を適用できます

ガバナンス＆ポリシーツール

ツール	説明
check_policy	.q-ring.json ポリシーに照らしてツール／キー／exec アクションをドライランし、実際の操作は行いません
get_policy_summary	ポリシールールの件数と承認／ローテーション要件の概要を表示します
rotate_secret	上流プロバイダーに新しい認証情報の発行を依頼し、キーチェーンに保存します
ci_validate_secrets	スコープ内のアクセス可能なすべての秘密情報を一括検証し、構造化された合否レポートを返します

Cursor ／ Kiro の設定

.cursor/mcp.json または .kiro/settings/mcp.json に追加します（または、qring setup cursor ／ qring setup kiro に書き込ませます）。

q-ring がグローバルにインストールされている場合（例：pnpm add -g @i4ctime/q-ring）：

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

ローカルクローンを使用する場合：

{
  "mcpServers": {
    "q-ring": {
      "command": "node",
      "args": ["/path/to/q-ring/dist/mcp.js"]
    }
  }
}

Claude Code の設定

プロジェクトルートの .mcp.json に追加します。または、qring setup claude、あるいは claude mcp add q-ring -- qring-mcp を実行します（claude_desktop_config.json を使用するアプリは Claude Desktop であり、Claude Code ではありません）。

グローバルインストール：

{
  "mcpServers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

ローカルクローン：

{
  "mcpServers": {
    "q-ring": {
      "command": "node",
      "args": ["/path/to/q-ring/dist/mcp.js"]
    }
  }
}

VS Code の設定

VS Code は MCP をネイティブでサポートしています。.vscode/mcp.json に追加します（mcpServers ではなく servers キーを使用します）。

{
  "servers": {
    "q-ring": {
      "command": "qring-mcp"
    }
  }
}

qring setup はまだこのファイルを書き込みません。VS Code は設定のみで使用でき、ファーストパーティのプラグインバンドルはありません。

エディタープラグイン

q-ring リポジトリには、ファーストパーティのエディターパックが 3 つ含まれています。それぞれのパックは、ルール／ステアリング、エージェント、コマンド、スキル、フック、MCP コネクターを対応するエディターに追加します。

プラグイン	エディター	主な機能
cursor-plugin/	Cursor	3 つのルール、5 つのスキル、2 つのエージェント、8 つのスラッシュコマンド、3 つのフック、MCP 自動接続
kiro-plugin/	Kiro	公式の Power レイアウト：POWER.md、ルートの mcp.json、steering/、hooks/。または plugin:sync:kiro でフラット化できます
claude-code-plugin/	Claude Code	CLAUDE.md のメモリ、プロジェクトの .mcp.json、2 つのサブエージェント、8 つのスラッシュコマンド、6 つのスキル、3 つのフックスクリプト

Cursor Plugin

q-ring Cursor Plugin は、ルール、スキル、エージェント、コマンド、フック、組み込みの MCP コネクターを使って、量子秘密管理を IDE に直接導入します。

コンポーネント	機能
3 つのルール	常時適用されるガイダンス：秘密情報をハードコードしない、すべての操作に q-ring を使う、.env ファイルに注意する
5 つのスキル	コンテキストに応じて自動的に起動：秘密情報の管理、スキャン、ローテーション、プロジェクトのオンボーディング、秘密情報を使った実行
2 つのエージェント	security-auditor（プロアクティブな監視）と secret-ops（日常的なアシスタント）
8 つのコマンド	/qring:scan-secrets、/qring:health-check、/qring:rotate-expired、/qring:setup-project、/qring:teleport-secrets、/qring:dashboard、/qring:exec-safe、/qring:analyze
3 つのフック	afterFileEdit（lint スキャン）、sessionStart（プロジェクトのコンテキスト）、beforeShellExecution（.env ガード）
MCP コネクター	stdio 経由で qring-mcp に自動接続し、46 個すべてのツールを利用できます

Cursor マーケットプレイスからインストールするか、手動でセットアップする場合は cursor-plugin/README.md を参照してください。

Kiro Plugin（Power）

kiro-plugin/ ディレクトリは、Create powers に従った Kiro Power です。POWER.md（メタデータ、オンボーディング、steering マップ）、ルートの mcp.json（MCP サーバーは Power 内で参照されるサーバー名と一致している必要があります）、ワークフロー用の steering/ が含まれています。Kiro → Powers → Add power from Local Path からインストールして kiro-plugin を選択するか、フォルダーを GitHub に公開して Add power from GitHub を使用してください。

常時適用される steering は秘密情報のハードコードを防ぎ、すべての処理を q-ring 経由で実行します。manual steering ファイルは、エージェントのペルソナ（#qring-secret-ops、#qring-security-auditor）、スキルパック、スラッシュ形式のコマンド（#qring-cmd-scan-secrets など）として機能します。コピーして .kiro/hooks/ に配置できるオプションのフックは hooks/ にあります。

# Alternative: flatten into ~/.kiro (settings + steering + hooks)
pnpm run plugin:sync:kiro

# Or scope to a single project
pnpm run plugin:sync:kiro -- /path/to/your/project/.kiro

詳しい内容は kiro-plugin/README.md を参照してください。

Claude Code Plugin

Claude Code 向けに、q-ring は CLAUDE.md メモリファイル、プロジェクトスコープの .mcp.json、2 つのサブエージェント（secret-ops、security-auditor）、8 つのスラッシュコマンド（/qring-scan-secrets、/qring-health-check、…）、6 つのスキル、3 つのフック（編集後の lint リマインダー、Bash 実行前の .env ガード、セッション開始時のコンテキスト導入）を提供します。

# Install into the current project ($PWD)
pnpm run plugin:sync:claude

# Install agents/commands/skills/hooks at user scope (~/.claude)
pnpm run plugin:sync:claude -- --user

# Or target a specific project
pnpm run plugin:sync:claude -- /path/to/your/project

既存の CLAUDE.md、.mcp.json、.claude/settings.json ファイルが黙って上書きされることはありません。スクリプトはそれらのファイルの隣に <filename>.qring-template を書き込むため、手動でマージできます。上書きするには --force を渡してください。

詳しい内容は claude-code-plugin/README.md を参照してください。

アーキテクチャ

qring CLI ─────┐
               ├──▶ Core Engine ──▶ @napi-rs/keyring ──▶ OS Keyring
MCP Server ────┘       │
                       ├── Envelope (quantum metadata)
                       ├── Scope Resolver (global / project / team / org)
                       ├── Collapse (env detection + branchMap globs)
                       ├── Observer (tamper-evident audit chain)
                       ├── Policy (governance-as-code engine)
                       ├── Noise (secret generation)
                       ├── Entanglement (cross-secret linking)
                       ├── Validate (provider-based liveness + rotation)
                       ├── Hooks (shell/HTTP/signal callbacks)
                       ├── Import (.env file ingestion)
                       ├── Exec (profile-restricted injection + redaction)
                       ├── Scan (codebase entropy heuristics)
                       ├── Provision (JIT ephemeral credentials)
                       ├── Approval (HMAC-verified zero-trust tokens)
                       ├── Context (safe redacted project view)
                       ├── Linter (secret-aware code scanning)
                       ├── Memory (encrypted agent persistence)
                       ├── Tunnel (ephemeral in-memory)
                       ├── Teleport (encrypted sharing)
                       ├── Agent (autonomous monitor + rotation)
                       └── Dashboard (live status via SSE)

プロジェクト設定（.q-ring.json）

プロジェクトごとに任意で設定できます。

{
  "env": "dev",
  "defaultEnv": "dev",
  "branchMap": {
    "main": "prod",
    "develop": "dev",
    "staging": "staging",
    "release/*": "staging",
    "feature/*": "dev"
  },
  "secrets": {
    "OPENAI_API_KEY": { "required": true, "description": "OpenAI API key", "format": "api-key", "prefix": "sk-", "provider": "openai" },
    "DATABASE_URL": { "required": true, "description": "Postgres connection string", "validationUrl": "https://api.example.com/health" },
    "SENTRY_DSN": { "required": false, "description": "Sentry error tracking" }
  },
  "policy": {
    "mcp": {
      "denyTools": ["delete_secret"],
      "deniedKeys": ["PROD_DB_PASSWORD"],
      "deniedTags": ["production"]
    },
    "exec": {
      "denyCommands": ["curl", "wget"],
      "maxRuntimeSeconds": 60
    }
  }
}

• branchMap は * ワイルドカードを使った glob パターンをサポートします（例：release/* は release/v1.0 に一致します）
• secrets はプロジェクトで必要な秘密情報を宣言します。検証には qring check、.env ファイルの生成には qring env:generate を使用します
• provider は有効性の検証プロバイダーを秘密情報に関連付けます（例："openai"、"stripe"、"github"）。テストには qring validate を使用します
• validationUrl は、カスタム検証用に汎用 HTTP プロバイダーのエンドポイントを設定します
• policy は、MCP ツールのゲーティング、キーアクセス制限、実行許可リスト、秘密情報のライフサイクル要件に関するガバナンスルールを定義します

📚 ドキュメント

• クイックスタート：Claude Code · Cursor · Kiro
• トラブルシューティング — キーリングバックエンド、MCP 接続、承認ゲート、ポリシーのピン留め
• CLI と MCP の同等性 — 各コマンドに対応する MCP ツール
• リリース — タグ主導のリリースフロー

コントリビューション

全ガイド（開発環境、規約、同期が必要なファイル）については、CONTRIBUTING.md を参照してください。概要は次のとおりです。

• PR を作成する前に、pnpm run lint、pnpm run typecheck、pnpm run test:ci を実行してください。
• テストやサンドボックスでは、QRING_AUDIT_DIR を指定して監査ログの保存先を変更できます（ディレクトリが存在しない場合は作成されます）。デフォルトは ~/.config/q-ring/audit.jsonl です。
• 任意のローカルコミット前フック：qring hook:install（qring が PATH にある場合、このパッケージの precommit フックを使用します）。
• エディタープラグインを変更した後：
  • Cursor： pnpm run plugin:sync は cursor-plugin/ を ~/.cursor/plugins/local/my-plugin にコピーします（またはカスタムパスを指定してください）。
  • Kiro： pnpm run plugin:sync:kiro は kiro-plugin/mcp.json を ~/.kiro/settings/mcp.json にコピーし、さらに steering/ と hooks/ もコピーします（またはプロジェクトの .kiro パスを指定してください）。代わりに、Powers パネルから Power として kiro-plugin/ を追加することを推奨します。
  • Claude Code： pnpm run plugin:sync:claude は claude-code-plugin/ を現在のディレクトリにコピーします（またはプロジェクトパスを指定してください。~/.claude/ にインストールするには --user を追加します）。
• docs/cli-mcp-parity.md も参照してください。

🔒 セキュリティ

• ローカルファースト。 コアストレージは OS のキーチェーンです。q-ring のクラウドもアカウントもありません。MCP の機能、監査ログ、エージェントのメモリはマシン上に保存されます（監査ログとメモリのファイルは所有者のみが読み書きできる 0600 で書き込まれます）。
• 文書化された脅威モデル。 q-ring が保護するもの、保護しないもの、残存リスクが存在する箇所については、エージェントによる情報流出の問いへの率直な回答も含めて、docs/threat-model.md をご覧ください。
• 敵対的レビューによる強化。 v0.14.0 では、内部の敵対的監査の結果が反映されました。ポリシー回避、承認範囲、実行プロファイルに関する指摘はすべて修正され、それぞれにリグレッションテストが追加されています。詳細は CHANGELOG の Security セクションをご覧ください（0.12.0 以降のスタイル：先に修正し、その後ここで開示します）。
• 脆弱性の報告。 GitHub の非公開脆弱性報告を利用してください。サポート対象バージョンの表と対応方針（48 時間以内の受領確認、7 日以内の評価）については、SECURITY.md をご覧ください。

📜 ライセンス

AGPL-3.0 - 使用、改変、共有は自由です。派生物やホステッドサービスは、同じライセンスのもとでソースコードを公開する必要があります。