brokre — AI 안전 자격 증명 브로커

English | 简体中文

brokre는 AI 에이전트와 인간을 위한 로컬 자격 증명 브로커입니다. Cursor, Claude Code, Kimi Code, Trae, OpenClaw, Hermes Agent, ChatClaw 및 기타 MCP 지원 클라이언트와 함께 사용하여 ssh, mysql, psql 등을 실행할 수 있습니다 — 비밀번호는 AI 컨텍스트, 환경 변수 또는 ps 출력에 절대 노출되지 않습니다. PATH에 있는 모든 CLI를 래핑하며 — SSH나 MySQL뿐만 아니라 — 프롬프트에서 저장된 비밀번호를 주입하되 평문을 AI 프로세스, 셸 히스토리 또는 프로세스 환경에 노출하지 않습니다.

Techinone(成都同创合一科技有限公司)이 개발했습니다.

0.2.17의 새로운 기능

0.2.17이 현재 릴리스입니다: SessionRelay 라우팅 SSH 기본 적용, 멀티홉 배스천 라우트, 로컬 전용 목록 기본 적용, 그리고 기존의 원커맨드 npm 설치 / 자동 MCP 등록 / 자동 바이너리 업그레이드 흐름을 포함합니다.

npm — 설치, 자동 업데이트, 자동 MCP 설정

npm install -g brokre          # or: npx -y brokre@latest

권장 MCP 설정(자동 설정에서도 적용):

{ "command": "npx", "args": ["-y", "brokre@latest"] }

배스천 브로커 — 클러스터 관리

배스천 계층을 통해 AI 에이전트는 점프 박스 하나 뒤의 많은 호스트를 운영할 수 있으며, 볼트 비밀번호를 컨텍스트에 복사하거나 노트북에 시크릿을 흩뿌릴 필요가 없습니다.

단일 진입 호스트 뒤의 K8s / DB / 배치 클러스터의 일반적인 흐름:

brokre bastion enable b150
brokre bastion sync b150 --json          # pull inner alias catalog
brokre bastion unlock
brokre list --include-bastions --json    # b150::db, b150::worker-01, …
brokre ssh b150::db systemctl status   # MCP: brokre_exec with routed alias

MCP 동등 표현:

{ "binary": "ssh", "args": ["b150::db", "uname", "-a"] }

게이트 정책(기본 vs 엄격) — 아래 배스천 게이트 정책 참조. 게이트는 brokre bastion set-key 전까지 비활성화됩니다. 이후 기본은 배스천 아웃바운드 경로만 잠금 해제하고, 엄격은 배스천 탐색이 요청되지 않는 한 목록이 로컬 전용으로 유지되는 동안 모든 실행에 잠금 해제가 필요합니다.

설정 세부 사항은 아래 교차 네트워크 목록 상속 및 배스천 프록시를 참조하세요.

Related MCP server: agent-vault

CLI 보안 (핵심)

brokre는 한 가지 규칙을 중심으로 구축되었습니다: 시크릿은 AI의 접근 범위와 관찰 가능한 프로세스 상태에서 벗어나 있어야 합니다.

전체 위협 모델: SECURITY.md, THREAT_MODEL.md.

PATH의 모든 CLI (설계상 범용)

brokre는 고정된 데이터베이스/SSH 래퍼 목록이 아닙니다. 핵심 모델은 다음과 같습니다:

brokre <any-cli-on-PATH> [args...]

첫 연결: 그대로 실행하고, 프롬프트에서 입력한 비밀번호를 캡처한 후 별칭으로 저장할지 제안합니다.
다음부터: brokre <cli> <alias> …가 자동 주입 — AI와 스크립트는 별칭 이름만 볼 수 있습니다.

사전 설정 프롬프트 패턴은 일반적인 도구(ssh, mysql, psql, redis-cli, ftp, clickhouse, git, docker, kubectl, sudo 등)에 포함되어 있습니다. 그 외 모든 것은 일반적인 password: / passphrase: 매처를 사용합니다 — 코드 변경이 필요 없습니다.

brokre gsql prod-cluster -c "SELECT 1"    # any proprietary CLI on PATH
brokre kubectl get pods                   # if your cluster CLI prompts for a password
brokre my-internal-tool --host db.internal

필요할 때 사용자 지정:

• ~/.brokre/prompts.toml — 바이너리별 프롬프트 정규식 재정의

• ~/.brokre/manage.toml — 관리 UI의 사용자 지정 섹션(예: GaussDB, 내부 도구)

기본 제공 관리 UI 탭(바이너리가 설치된 경우)에는 SSH, FTP, MySQL, PostgreSQL, Redis, ClickHouse, MinIO가 포함됩니다 — 편의 기능일 뿐입니다. PTY 래퍼는 모든 CLI에서 작동합니다.

설치 (MCP 우선 — AI에 권장)

npm 패키지 brokre는 Cursor, Claude Code, Kimi Code, Trae, OpenClaw, Windsurf, VS Code 및 기타 MCP 클라이언트를 위해 stdio를 통해 로컬 brokre mcp 서버를 실행합니다.

설치 경로 선택

권장 MCP 항목(자동 설정도 동일하게 작성):

{ "command": "npx", "args": ["-y", "brokre@latest"] }

Node 없음 — MCP를 네이티브 바이너리로 지정: { "command": "brokre", "args": ["mcp"] }.

경로 A — npm 원라이너 (0.2.8+)

npm install -g brokre
# or without global install:
npx -y brokre@latest

npm install 시 세 가지가 자동으로 발생합니다:

1. MCP 런처 — brokre-mcp / npx -y brokre@latest가 brokre mcp를 실행합니다.

2. IDE 자동 등록 — postinstall이 brokre-setup-mcp를 실행: 설치된 IDE만 감지(앱, CLI 또는 실제 사용 아티팩트 — 빈 폴더 아님)하고 위의 MCP 항목을 각 글로벌 설정에 병합합니다. 멱등적이며 다른 MCP 서버를 보존합니다.

3. 바이너리 자동 업그레이드 — 각 MCP 시작 시 PATH 또는 ~/.brokre/bin/brokre가 npm 패키지보다 이전 버전이면 일치하는 GitHub Release가 다운로드됩니다.

자동 설정이 지원하는 IDE

등록 다시 실행(예: brokre를 Cursor보다 먼저 설치한 후 Cursor를 나중에 설치한 경우):

brokre mcp setup              # via CLI — same logic as postinstall
npx brokre-setup-mcp          # via npm
brokre mcp setup --dry-run    # preview only
brokre mcp setup --force      # overwrite existing brokre entry

npm install 시 자동 등록 건너뛰기: BROKRE_MCP_SKIP_SETUP=1. 바이너리 자동 다운로드 비활성화: BROKRE_SKIP_AUTO_INSTALL=1. 바이너리 고정: BROKRE_BIN=/path/to/brokre.

npm 경로에는 **Node.js 18+**가 필요합니다.

경로 B — 네이티브 CLI (install.sh / Homebrew, npm 불필요)

curl -fsSL https://raw.githubusercontent.com/Furowu/brokre/main/install.sh | bash

brew tap Furowu/brokre
brew install brokre

버전 및 업그레이드(CLI에 내장 — npm 불필요):

brokre version                # version, binary path, install type
brokre version --check        # compare with latest GitHub release
brokre version --check --json
brokre upgrade                # download latest release (curl + tar)
brokre upgrade --check        # exit 1 if an update is available
brokre upgrade 0.2.10         # install a specific version
brokre upgrade --force        # reinstall even when up to date

install.sh를 다시 실행하면 최신 릴리스가 있을 때 업그레이드도 수행됩니다.

CLI 설치 후 MCP 등록 (설정 스크립트에 Node 필요, 또는 npx 폴백):

brokre mcp setup

IDE별 수동 설정 (선택 사항)

자동 설정을 건너뛰었거나 프로젝트 범위 설정이 필요한 경우에만 사용하세요.

Cursor — 원클릭 설치, 또는 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "brokre": { "command": "npx", "args": ["-y", "brokre@latest"] }
  }
}

Claude Code — 사용자 범위는 ~/.claude.json 또는 claude mcp add --scope user brokre -- npx -y brokre@latest. 프로젝트 범위: "type": "stdio"가 포함된 .mcp.json.

더 많은 클라이언트 및 환경 변수: packages/brokre-mcp/README.md. MCP Registry ID: io.github.Furowu/brokre.

MCP 도구 및 사용법

MCP vs CLI (AI 에이전트에 필수)

brokre는 ssh / mysql의 대체 도구가 아닙니다 — 볼트 주입을 위해 반드시 brokre 접두사를 붙여야 합니다.

흔한 실수 (AI 에이전트)

원격 SSH의 경우: 별칭 뒤의 토큰은 argv 조각이지 하나의 셸 명령이 아닙니다. 단순 명령에는 분할 토큰을 사용하고, 복잡한 스크립트에는 shell_command를 사용하세요.

MCP 상승 세션 (sudo / su, Unix)

기본적으로 brokre mcp는 (alias, mode, user)별로 백그라운드 상승 셸을 재사용하므로 sudo 비밀번호를 호출할 때마다 다시 묻지 않습니다.

brokre_exec_elevated (권한 상승에 권장):

{
  "alias": "prod",
  "command": "systemctl status nginx",
  "mode": "sudo_login",
  "session": "reuse"
}

세션 풀이 활성화되면 응답에 exit_code / stdout / stderr 외에도 session_reused 및 session_idle_expires_at이 포함됩니다. session_idle_expires_at은 고정 만료 타임스탬프가 아니라 호출마다 갱신되는 롤링 유휴 창 힌트입니다. 풀 경로에서는 stderr가 보통 비어 있습니다. stdout은 원격 명령 출력만 포함합니다 — TTY 에코, __BROKRE_* 프레이밍, 셸 프롬프트는 제거됩니다.

brokre_exec: args에 sudo/su가 포함된 binary=ssh는 동일한 풀을 자동으로 사용합니다(항상 reuse, session=new|close 없음). 예: args=["prod","sudo","whoami"].

원격 스크립트/파일 작성 (shell_command, binary=ssh 전용): args에는 별칭만 전달하고 전체 셸 스크립트는 shell_command에 넣으세요(brokre가 sh -c로 정규화). args에 sh -c '...'를 포함하거나 printf/리다이렉트를 argv 토큰으로 분할하지 마세요. 권한이 필요한 시스템 경로에는 brokre_exec_elevated.command를 사용하세요.

{
  "binary": "ssh",
  "args": ["prod"],
  "shell_command": "cat > /tmp/deploy.sh <<'EOF'\n#!/bin/sh\necho ok\nEOF"
}

배스천 라우트도 동일하게 작동합니다: args=["b150::db"]와 함께 shell_command를 원격 스크립트로 사용.

SessionRelay 터널 (기본값)

brokre ssh b150::db는 기본적으로 SessionRelay 경로를 사용합니다: 노트북이 SSH를 통해 b150에서 brokre tunnel agent --stdio를 시작하고, 에이전트가 배스천에서 brokre ssh db를 실행합니다. 멀티홉 라우트는 에이전트당 한 홉씩 벗겨냅니다(b1::b2::db는 b1에서 시작한 후 b1이 b2::db로 계속 진행). 내부 자격 증명은 배스천 볼트에 유지되고, 노트북은 터미널 바이트만 중계합니다. BROKRE_TUNNEL=0은 비상 롤백을 위한 임시 레거시 탈출구입니다.

brokre tunnel doctor b150
brokre ssh b150::db uname -a

라우팅된 SSH에 대한 MCP brokre_exec 응답에는 tunnel: { mode, active }가 포함됩니다. TcpForward, 엔드포인트 동기화, Manage UI 터널 제어, 영구 tunneld는 이후 단계입니다.

지원되지 않음: 명령 없는 대화형 sudo -i, vim/top, 볼트 password 필드와 다른 sudo 비밀번호. THREAT_MODEL.md T12 참조.

빈 볼트로 처음 연결하면 brokre가 브라우저에서 manage를 엽니다(http://127.0.0.1:56777/?t=…). 세션 토큰은 localhost에만 유지되며 AI에 반환되지 않습니다. 자동 열기를 비활성화하려면 BROKRE_MCP_NO_AUTO_OPEN=1을 설정하세요.

| MCP 도구 | 용도 |

자격 증명 추가

CLI 설치 후, 매니저는 첫 실행 시 열립니다(brokre manage --onboard --open). 또는 언제든지:

brokre manage --open

또는 첫 대화형 연결 시 저장(모든 CLI):

brokre ssh root@10.0.0.1
brokre my-tool --host internal.corp

사용 (AI 안전)

brokre mysql prod-db -e "SHOW TABLES"
brokre ssh prod-bastion uname -a
brokre <your-cli> <alias> [args...]

메타데이터 목록 (AI / 스크립트에 안전)

brokre list --json              # local aliases with reachability status (default probe)
brokre list --no-probe --json   # metadata only, skip TCP/SSH probes
brokre list --reachable-only    # hide unavailable aliases
brokre list --all --json        # compat: show all (same as default unless --reachable-only)
brokre list --no-bastion-discovery   # local only — no bastion SSH discovery

배스천이 등록된 경우 brokre list는 기본적으로 로컬 전용이며 배스천에 SSH를 하거나 배스천 잠금 해제를 트리거하지 않습니다. b150::db와 같은 라우팅된 별칭이 실제로 필요할 때 brokre list --include-bastions(MCP: include_bastions=true)를 사용하세요. 이 원격 발견에는 잠금 해제가 필요할 수 있습니다.

OpenSSH 세션은 기본적으로 ConnectTimeout=5를 주입합니다(BROKRE_SSH_CONNECT_TIMEOUT). -o ConnectTimeout=N 또는 환경 변수로 재정의하세요. 배스천 RPC(brokre list --include-bastions / 원격 목록)는 60초 후 제한시간이 초과됩니다(BROKRE_BASTION_RPC_TIMEOUT). 원격 명령은 ControlPath=none을 사용하므로 ControlPersist mux 마스터에 연결되지 않습니다.

크로스 네트워크 목록 상속 (배스천 브로커)

크로스 네트워크 액세스 — 출장, VPN, 공용 진입점 — 로컬 LAN 별칭이 로컬에서 연결할 수 없지만 brokre를 실행하는 배스천을 통해 연결할 수 있는 경우.

전제 조건

1. 노트북: brokre bastion enable b150 (b150은 저장된 SSH 별칭)

2. 배스천 호스트가 ~/.brokre/bin/brokre(표준 설치 / npx 경로)에서 brokre를 실행하고 내부 별칭이 저장되어 있음(예: db)

라우팅된 목록

brokre bastion unlock            # if bastion key is set
brokre list --include-bastions   # includes b150::db (route=b150, access=via_b150)

크로스 네트워크일 때 라우팅된 별칭이 필요하면 --include-bastions를 사용하세요. 일반 brokre list는 로컬 전용이며 배스천을 잠금 해제하거나 SSH하지 않습니다.

실행

brokre ssh b150::db uname -a
# MCP: brokre_exec binary=ssh, args=["b150::db", "uname", "-a"]

두 경로가 모두 작동하면 목록에 db(direct)와 b150::db(via_b150) 둘 다 표시됩니다 — access로 구분하세요.

배스천 프록시 (크로스 네트워크 / 인트라넷 진입점)

원격 호스트가 brokre를 실행하는 모든 저장된 SSH 별칭을 배스천 브로커로 승격하세요. 비밀은 배스천에 유지되고, 노트북은 메타데이터를 캐시하고 SSH 패스스루로 실행합니다.

brokre bastion enable b150        # register ssh alias b150 as bastion
brokre bastion set-key              # set bastion unlock key (TTY)
brokre bastion unlock               # unlock outbound session (TTL, 30 min idle default)
brokre list --include-bastions --json # discover bastion-routed aliases
brokre ssh b150::db uname -a        # routed exec via b150 remote brokre
brokre bastion sync b150 --json     # fetch alias list from one bastion

• 라우트 구분자 :: (:는 별칭 이름에 사용 불가): db (로컬), b150::db (배스천 경유), b1::b2::inner (멀티홉, 기본 깊이 ≤2).

• 원격 brokre: 라우팅된 실행은 배스천에서 ~/.brokre/bin/brokre를 호출합니다(헤드리스 Linux용 BROKRE_SOFT_MEMLOCK=1, BROKRE_ALLOW_FILE_KEYCHAIN=1, BROKRE_ROUTED_INNER=1 포함). 대화형 명령(예: sudo -i)은 자동으로 -tt를 받습니다.

• 안전장치: 프로브 동시성 상한, ms 제한시간, 짧은 캐시, 루프 감지, 감사 route/bastion (HMAC v4).

• Manage UI: brokre manage Bastion 탭 — 배스천 등록/비활성화, Web 키 설정 및 잠금/잠금 해제, 엄격 모드 토글, 원격 별칭 동기화. 비-TTY에서도 /bastion-auth 자동 열림. 감사 탭은 bastion/source로 필터링하고 라우트 필드를 표시합니다.

배스천 게이트 정책 (기본값 vs 엄격 모드)

The bastion gate is a human unlock step before sensitive operations. It is off until you set a bastion key (brokre bastion set-key). After a key exists, unlock establishes a local TTL session (brokre bastion unlock, TTY passphrase, manage UI /bastion-auth, or MCP browser elicitation).

bastion 게이트는 민감한 작업 전에 사람의 잠금 해제 단계입니다. bastion 키를 설정하기 전까지는 꺼져 있습니다 (brokre bastion set-key). 키가 존재하면 잠금 해제는 로컬 TTL 세션을 설정합니다 (brokre bastion unlock, TTY 패스프레이즈, manage UI /bastion-auth, 또는 MCP 브라우저 유도).

Policy is stored at ~/.brokre/bastion/policy.json (strict_mode, default false).

정책은 ~/.brokre/bastion/policy.json에 저장됩니다 (strict_mode, 기본값 false).

Examples (default mode, key set, session locked)

예시 (기본 모드, 키 설정됨, 세션 잠김)

In strict mode, exec rows require unlock; metadata-only brokre list remains local-only and does not unlock unless --include-bastions is used.

엄격 모드에서는 exec 행에 잠금 해제가 필요합니다. 메타데이터 전용 brokre list는 로컬 전용으로 유지되며 --include-bastions를 사용하지 않는 한 잠금 해제되지 않습니다.

Set gate mode

게이트 모드 설정

brokre bastion strict status    # default | strict
brokre bastion strict on        # strict — all exec gated; list stays local-only unless discovery is requested
brokre bastion strict off       # default — bastion outbound only

MCP read response includes strict_mode, gate_mode, key_set, unlocked. List/exec responses include bastion_gate (required, unlocked_during_call, idle_expires_at).

MCP 읽기 응답에는 strict_mode, gate_mode, key_set, unlocked가 포함됩니다. 목록/exec 응답에는 bastion_gate (required, unlocked_during_call, idle_expires_at)가 포함됩니다.

Unlock session TTL (defaults): 30 min idle (BROKRE_BASTION_IDLE_SECS), 8 h max lifetime (BROKRE_BASTION_MAX_SECS). Idle window renews on each gated call while unlocked (shared across CLI, MCP, and manage UI via ~/.brokre/run/bastion_session.json). Bastion gate auth is independent of manage UI session idle expiry. Disable auto-open browser on MCP unlock: BROKRE_BASTION_NO_AUTO_OPEN=1.

잠금 해제 세션 TTL (기본값): 유휴 30분 (BROKRE_BASTION_IDLE_SECS), 최대 수명 8시간 (BROKRE_BASTION_MAX_SECS). 유휴 창은 잠금 해제 상태에서 각 게이트 호출 시 갱신됩니다 (CLI, MCP, manage UI 간 ~/.brokre/run/bastion_session.json을 통해 공유). Bastion 게이트 인증은 manage UI 세션 유휴 만료와 독립적입니다. MCP 잠금 해제 시 브라우저 자동 열기 비활성화: BROKRE_BASTION_NO_AUTO_OPEN=1.

Reveal / delete (human-only, real TTY)

공개 / 삭제 (사람 전용, 실제 TTY)

brokre reveal mysql prod-db --field password
brokre rm ssh prod-bastion

Audit log (metadata only)

감사 로그 (메타데이터 전용)

brokre audit list --profile ssh --action exec --json
brokre audit verify --json

Events are stored at ~/.brokre/audit/audit.log (HMAC-chained). Command arguments are uniformly redacted as <REDACTED>. New events include a source field (cli, mcp, or manage). The manage UI Audit log tab and MCP brokre_audit_list expose the same metadata.

이벤트는 ~/.brokre/audit/audit.log에 저장됩니다 (HMAC 체인). 명령 인수는 일관되게 <REDACTED>로 마스킹됩니다. 새 이벤트에는 source 필드(cli, mcp 또는 manage)가 포함됩니다. manage UI 감사 로그 탭과 MCP brokre_audit_list는 동일한 메타데이터를 노출합니다.

Manage UI security

Manage UI 보안

• 127.0.0.1 only; session token in terminal

• Passwords: create / rotate only — no read API

• Delete / rotate require reveal passphrase (or YES for auto-saved records)

• 15-minute idle timeout

• 127.0.0.1 전용; 세션 토큰은 터미널에 표시

• 비밀번호: 생성 / 회전만 가능 — 읽기 API 없음

• 삭제 / 회전에는 공개 패스프레이즈 필요 (자동 저장된 레코드의 경우 YES)

• 15분 유휴 제한 시간

Architecture

아키텍처

┌─────────┐     ┌──────────┐     ┌─────────────┐     ┌────────────┐
│ AI/User │────▶│ brokre CLI│────▶│ OS Keychain │────▶│ Vault File │
└─────────┘     └──────────┘     └─────────────┘     └────────────┘
                      │
                      ▼
               ┌─────────────┐
               │  PTY + inj. │──▶ any CLI on PATH (ssh, mysql, gsql, …)
               └─────────────┘

• Double encryption: unique DEK per field; wrapped for exec and reveal separately.

• Vault metadata: profile, name, host_alias, saved_args in cleartext beside ciphertext (THREAT_MODEL.md T3).

• SSH private keys: 0600 temp file + -i for the session (docs/HARDENING.md).

• 이중 암호화: 필드별 고유 DEK; exec와 reveal용으로 별도 래핑.

• Vault 메타데이터: profile, name, host_alias, saved_args는 암호문 옆에 평문으로 저장 (THREAT_MODEL.md T3).

• SSH 개인 키: 0600 임시 파일 + 세션용 -i (docs/HARDENING.md).

Preset manage UI groups

사전 설정 manage UI 그룹

Convenience tabs when the binary is on PATH:

바이너리가 PATH에 있을 때의 편의 탭:

Roadmap

로드맵

Today: generic PTY wrapper + manage.toml groups + prompts.toml overrides.

현재: 일반 PTY 래퍼 + manage.toml 그룹 + prompts.toml 재정의.

Planned: full TOML connector profiles under ~/.brokre/profiles/ with per-tool injection strategies.

계획: ~/.brokre/profiles/ 아래의 전체 TOML 커넥터 프로필과 도구별 주입 전략.

Piped stdin and OpenSSH sharing

파이프된 stdin 및 OpenSSH 공유

• Piped stdin (tar | brokre ssh host 'tar xf -'): pipe data forwards only after injection completes.

• OpenSSH family (ssh, scp, sftp): shared saved credentials when the host matches. Interactive save required first (TTY).

• 파이프된 stdin (tar | brokre ssh host 'tar xf -'): 파이프 데이터는 주입이 완료된 후에만 전달됩니다.

• OpenSSH 계열 (ssh, scp, sftp): 호스트가 일치할 때 저장된 자격 증명을 공유합니다. 먼저 대화형 저장이 필요합니다 (TTY).

Development

개발

cargo test    # unit tests in src/ only (no tests/ integration suite in this repo)
cargo clippy --all-targets --all-features -- -D warnings
cargo build --release   # binary: target/release/brokre

Release version is declared in VERSION (also reflected in Cargo.toml and packages/brokre-mcp/package.json). Official binaries and npm packages are published by TechinOne via GitHub Releases and CI — not part of this open-source tree.

릴리스 버전은 VERSION에 선언되어 있습니다 (Cargo.toml 및 packages/brokre-mcp/package.json에도 반영됨). 공식 바이너리와 npm 패키지는 TechinOne이 GitHub Releases 및 CI를 통해 게시합니다 — 이 오픈소스 트리의 일부가 아닙니다.

License

라이선스

MIT — see LICENSE.

MIT — LICENSE 참조.

Techinone · 成都同创合一科技有限公司