{"id":35098706,"url":"https://github.com/meloncafe/vaultctl","last_synced_at":"2026-04-10T10:31:24.150Z","repository":{"id":331042060,"uuid":"1123516825","full_name":"meloncafe/vaultctl","owner":"meloncafe","description":"A CLI tool for centrally managing Proxmox LXC container passwords/URLs and Docker environment variables with Vault.","archived":false,"fork":false,"pushed_at":"2026-04-08T08:59:52.000Z","size":4385,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T10:31:51.027Z","etag":null,"topics":["docker","env","environment","hashicorp-vault","lxc","proxmox","security","vault"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meloncafe.png","metadata":{"files":{"readme":"README.ko.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-27T03:33:39.000Z","updated_at":"2026-04-08T08:58:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/meloncafe/vaultctl","commit_stats":null,"previous_names":["meloncafe/vaultctl"],"tags_count":64,"template":false,"template_full_name":null,"purl":"pkg:github/meloncafe/vaultctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meloncafe%2Fvaultctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meloncafe%2Fvaultctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meloncafe%2Fvaultctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meloncafe%2Fvaultctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meloncafe","download_url":"https://codeload.github.com/meloncafe/vaultctl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meloncafe%2Fvaultctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31638375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T07:40:12.752Z","status":"ssl_error","status_checked_at":"2026-04-10T07:40:11.664Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","env","environment","hashicorp-vault","lxc","proxmox","security","vault"],"created_at":"2025-12-27T16:11:01.100Z","updated_at":"2026-04-10T10:31:24.133Z","avatar_url":"https://github.com/meloncafe.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vaultctl\n\n[English](README.md) | **한국어**\n\n---\n\nLXC 환경을 위한 간단한 Vault CLI.\n\nProxmox LXC 컨테이너의 시크릿을 HashiCorp Vault로 중앙 관리하는 CLI 도구입니다.\n\n## 목차\n\n- [특징](#특징)\n- [아키텍처](#아키텍처)\n- [설치 방법](#설치-방법)\n- [빠른 시작](#빠른-시작)\n- [명령어 레퍼런스](#명령어-레퍼런스)\n- [Docker Compose 통합](#docker-compose-통합)\n- [확장 명령어](#확장-명령어-teller-스타일)\n- [설정](#설정)\n- [APT 서버 구축](#apt-서버-구축)\n- [패키지 빌드 및 배포](#패키지-빌드-및-배포)\n- [보안 참고사항](#보안-참고사항)\n- [문제 해결](#문제-해결)\n\n---\n\n## 특징\n\n- 🔐 **간단한 설정**: `vaultctl init`으로 AppRole 자격 증명 자동 생성\n- 📦 **시크릿 관리**: LXC별 환경변수 중앙 관리\n- 🐳 **Docker Compose**: .env.secrets 자동 생성 및 compose 파일 업데이트 통합\n- 🔄 **토큰 자동 갱신**: AppRole 토큰 만료 시 자동 재발급\n- 🎯 **단일 바이너리**: Python 의존성 없이 설치 (deb 패키지)\n- 🚀 **프로세스 실행**: 환경변수 주입하며 명령어 실행\n- 🔎 **비밀 스캔**: 코드에서 하드코딩된 비밀 검색 (DevSecOps)\n- 👁️ **변경 감지**: Vault 비밀 변경 시 자동 재시작\n\n---\n\n## 아키텍처\n\n```mermaid\nflowchart TB\n    subgraph admin[\"👨‍💻 관리자 워크스테이션\"]\n        A1[vaultctl admin setup vault]\n        A2[vaultctl admin put 100 DB_HOST=...]\n    end\n\n    subgraph vault[\"🔐 HashiCorp Vault\"]\n        V1[\"kv/data/proxmox/lxc/100\u003cbr/\u003eDB_HOST, DB_PASSWORD, REDIS_URL\"]\n        V2[\"kv/data/proxmox/lxc/101\u003cbr/\u003eAPI_KEY, SECRET_KEY\"]\n        V3[\"kv/data/proxmox/lxc/102\u003cbr/\u003e...\"]\n    end\n\n    subgraph lxc[\"📦 Proxmox LXC 컨테이너\"]\n        L1[\"LXC 100 - n8n\u003cbr/\u003evaultctl compose up 100\"]\n        L2[\"LXC 101 - gitea\u003cbr/\u003evaultctl compose up 101\"]\n        L3[\"LXC 102 - postgres\u003cbr/\u003evaultctl compose up 102\"]\n    end\n\n    admin --\u003e vault\n    V1 --\u003e L1\n    V2 --\u003e L2\n    V3 --\u003e L3\n```\n\n### KV 경로 구조\n\n```mermaid\nflowchart LR\n    A[\"kv_mount\u003cbr/\u003e\u003ccode\u003ekv\u003c/code\u003e\"] --\u003e B[\"data\"] --\u003e C[\"kv_path\u003cbr/\u003e\u003ccode\u003eproxmox/lxc\u003c/code\u003e\"] --\u003e D[\"name\u003cbr/\u003e\u003ccode\u003e100\u003c/code\u003e\"]\n    \n    style A fill:#e1f5fe\n    style C fill:#e8f5e9\n    style D fill:#fff3e0\n```\n\n**전체 경로 예시:** `kv/data/proxmox/lxc/100`\n\n---\n\n## 설치 방법\n\n### 옵션 1: GitHub에서 바로 설치 (권장)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/meloncafe/vaultctl/main/scripts/install.sh | sudo bash\n```\n\n### 옵션 2: 개인 APT 서버에서 설치\n\n```bash\n# 클라이언트 설정 (최초 1회)\ncurl -fsSL https://apt.example.com/setup-client.sh | sudo bash -s -- apt \"password\"\n\n# 설치\nsudo apt update\nsudo apt install vaultctl\n```\n\n### 옵션 3: 소스에서 빌드\n\n```bash\ngit clone https://github.com/YOUR_USERNAME/vaultctl.git\ncd vaultctl\npoetry install\npoetry run vaultctl --help\n```\n\n---\n\n## 빠른 시작\n\n### 1단계: 관리자 설정 (최초 1회, 아무 머신에서나)\n\n```bash\nvaultctl admin setup vault\n```\n\nVault에 Policy와 AppRole을 생성합니다. 입력 항목:\n- Vault 서버 주소\n- Root/Admin 토큰\n- KV 엔진 마운트 (기본: `kv`)\n- 시크릿 베이스 경로 (기본: `proxmox/lxc`)\n\n### 2단계: 시크릿 등록\n\n```bash\n# LXC 100용 시크릿 추가 (경로 자동 생성)\nvaultctl admin put 100 \\\n  DB_HOST=postgres.internal \\\n  DB_PASSWORD=supersecret \\\n  REDIS_URL=redis://redis.internal:6379\n```\n\n### 3단계: 각 LXC에서 초기화\n\n```bash\nvaultctl init\n```\n\n프롬프트에서:\n1. Vault 서버 주소 입력\n2. Admin 토큰 입력 (Secret ID 자동 생성용)\n3. KV 마운트 및 경로 입력\n4. AppRole 이름 (기본: `vaultctl`)\n\n**끝!** 이 머신용 Secret ID가 자동 생성됩니다.\n\n### 4단계: 시크릿 사용\n\n```bash\n# .env 파일 생성\nvaultctl env 100\n\n# 또는 Docker Compose와 함께 사용\nvaultctl compose init 100\nvaultctl compose up 100\n```\n\n---\n\n## 명령어 레퍼런스\n\n### 사용자 명령어\n\n| 명령어 | 설명 |\n|--------|------|\n| `vaultctl init` | 초기 설정 (Secret ID 자동 생성) |\n| `vaultctl env \u003cn\u003e` | .env 파일 생성 |\n| `vaultctl status` | 연결 및 인증 상태 확인 |\n| `vaultctl config` | 현재 설정 출력 |\n| `vaultctl run \u003cn\u003e -- cmd` | 환경변수 주입하여 명령 실행 |\n| `vaultctl sh \u003cn\u003e` | 셸 export 문 생성 |\n| `vaultctl watch \u003cn\u003e -- cmd` | 비밀 변경 시 자동 재시작 |\n| `vaultctl scan` | 코드에서 하드코딩된 비밀 검색 |\n| `vaultctl redact` | 로그에서 비밀 마스킹 |\n\n### 관리자 명령어\n\n| 명령어 | 설명 |\n|--------|------|\n| `vaultctl admin setup vault` | Vault policy, AppRole 생성 |\n| `vaultctl admin credentials` | Role ID 조회 + 새 Secret ID 생성 |\n| `vaultctl admin list` | 시크릿 목록 |\n| `vaultctl admin get \u003cn\u003e` | 시크릿 상세 조회 |\n| `vaultctl admin put \u003cn\u003e K=V...` | 시크릿 저장 (경로 자동 생성) |\n| `vaultctl admin delete \u003cn\u003e` | 시크릿 삭제 |\n| `vaultctl admin import \u003cfile\u003e` | JSON에서 일괄 가져오기 |\n| `vaultctl admin export` | JSON으로 내보내기 |\n| `vaultctl admin token status` | 토큰 상태 확인 |\n| `vaultctl admin token renew` | 토큰 갱신 |\n\n### Docker Compose 명령어\n\n| 명령어 | 설명 |\n|--------|------|\n| `vaultctl compose init \u003cn\u003e` | compose + 시크릿 설정 |\n| `vaultctl compose up \u003cn\u003e` | 시크릿 동기화 \u0026 시작 |\n| `vaultctl compose down` | 컨테이너 중지 |\n| `vaultctl compose restart \u003cn\u003e` | 동기화 \u0026 재시작 |\n| `vaultctl compose status` | 상태 확인 |\n| `vaultctl compose sync \u003cn\u003e` | 시크릿만 동기화 |\n\n---\n\n## 상세 사용법\n\n### vaultctl init\n\n이 머신용 AppRole 자격 증명을 자동 생성합니다.\n\n```bash\n$ vaultctl init\n\n🔐 Setup\n╭──────────────────────────────────────────╮\n│ vaultctl Initial Setup                   │\n│                                          │\n│ Vault에 연결하고 AppRole 자격 증명을      │\n│ 생성합니다. Admin 토큰이 필요합니다.      │\n╰──────────────────────────────────────────╯\n\nVault server address: https://vault.example.com\n✓ Connection successful\n\nAdmin Authentication\nAdmin/Root token: ********\n✓ Admin authentication successful\n\nKV Secret Path\nKV engine mount [kv]: kv\nSecret path [proxmox/lxc]: proxmox/lxc\n\nAppRole\nAppRole name [vaultctl]: vaultctl\n\nChecking AppRole 'vaultctl'...\n✓ AppRole found: vaultctl\n   Policies: vaultctl\n✓ Role ID retrieved\n\nGenerating Secret ID for lxc-100...\n✓ Secret ID generated\n\nTesting AppRole authentication...\n✓ AppRole authentication successful\n   Policies: vaultctl, default\n   TTL: 1 hour\n\n✓ Configuration saved: ~/.config/vaultctl/\n```\n\n### vaultctl admin credentials\n\n전체 init 없이 자격 증명 생성 (스크립팅에 유용):\n\n```bash\n# 새 LXC용 자격 증명 생성\nvaultctl admin credentials\n\n# TTL 설정\nvaultctl admin credentials --ttl 7d\n\n# 클립보드에 복사\nvaultctl admin credentials --copy-secret\n```\n\n### vaultctl admin put\n\n시크릿은 자동으로 저장됩니다 - 경로를 먼저 만들 필요 없음:\n\n```bash\n# proxmox/lxc/100 경로 자동 생성\nvaultctl admin put 100 DB_HOST=localhost DB_PASSWORD=secret\n\n# 기존 값과 병합 (기본)\nvaultctl admin put 100 NEW_KEY=value\n\n# 전체 값 교체\nvaultctl admin put 100 ONLY_THIS=value --replace\n```\n\n### vaultctl env\n\n```bash\n# 현재 디렉토리에 .env 생성\nvaultctl env 100\n\n# 다른 경로에 저장\nvaultctl env 100 -o /opt/myapp/.env\n\n# stdout으로 출력\nvaultctl env 100 --stdout\n```\n\n---\n\n## Docker Compose 통합\n\n### 빠른 설정\n\n```bash\ncd /opt/myapp\nvaultctl compose init 100\nvaultctl compose up 100\n```\n\n### `compose init`이 하는 일\n\n1. Vault에서 `.env.secrets` 생성\n2. `docker-compose.yml`에 `env_file` 항목 추가\n3. `ctl.sh` 관리 스크립트 생성 (선택)\n4. `.gitignore` 업데이트\n\n**변경 전:**\n```yaml\nservices:\n  app:\n    image: myapp\n```\n\n**변경 후:**\n```yaml\nservices:\n  app:\n    image: myapp\n    env_file:\n      - .env\n      - .env.secrets\n```\n\n### 관리 스크립트\n\n```bash\nvaultctl compose init 100 --script\n\n./ctl.sh up       # 시크릿 동기화 후 시작\n./ctl.sh restart  # 동기화 후 재시작\n./ctl.sh logs -f  # 로그 확인\n./ctl.sh status   # 상태 확인\n```\n\n---\n\n## 확장 명령어 (teller 스타일)\n\n### vaultctl run\n\n```bash\nvaultctl run 100 -- node index.js\nvaultctl run 100 -- docker compose up -d\nvaultctl run 100 --shell -- 'echo $DB_PASSWORD | base64'\n```\n\n### vaultctl sh\n\n```bash\neval \"$(vaultctl sh 100)\"\n```\n\n### vaultctl scan\n\n```bash\nvaultctl scan ./src\nvaultctl scan --error-if-found  # CI/CD\n```\n\n### vaultctl watch\n\n```bash\nvaultctl watch 100 -- docker compose up -d\n```\n\n---\n\n## 설정\n\n### 파일\n\n| 경로 | 설명 |\n|------|------|\n| `~/.config/vaultctl/config` | 사용자 설정 |\n| `~/.cache/vaultctl/token` | 캐시된 토큰 |\n\n### 형식\n\n```bash\n# ~/.config/vaultctl/config\nVAULT_ADDR=https://vault.example.com\nVAULT_KV_MOUNT=kv\nVAULT_KV_PATH=proxmox/lxc\nVAULT_ROLE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\nVAULT_SECRET_ID=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy\n```\n\n### 환경변수\n\n| 변수 | 기본값 | 설명 |\n|------|--------|------|\n| `VAULTCTL_VAULT_ADDR` | - | Vault 서버 주소 |\n| `VAULTCTL_KV_MOUNT` | `kv` | KV 엔진 마운트 경로 |\n| `VAULTCTL_KV_PATH` | `proxmox/lxc` | 시크릿 베이스 경로 |\n| `VAULTCTL_APPROLE_ROLE_ID` | - | AppRole Role ID |\n| `VAULTCTL_APPROLE_SECRET_ID` | - | AppRole Secret ID |\n\n---\n\n## APT 서버 구축\n\n### APT 서버 설치\n\n```bash\nsudo vaultctl admin setup apt-server\n```\n\n### 클라이언트 설정\n\n```bash\nsudo vaultctl admin setup apt-client https://apt.example.com -u apt -p \"password\"\n```\n\n### 패키지 관리\n\n```bash\nvaultctl admin repo add vaultctl_0.1.0_amd64.deb\nvaultctl admin repo list\nvaultctl admin repo remove vaultctl\n```\n\n---\n\n## 패키지 빌드 및 배포\n\n```mermaid\nflowchart LR\n    subgraph dev[\"💻 개발\"]\n        D1[\"git clone\"] --\u003e D2[\"./build-deb.sh\"]\n        D2 --\u003e D3[\"dist/vaultctl_x.x.x_amd64.deb\"]\n    end\n\n    subgraph apt[\"📦 APT 서버\"]\n        A1[\"vaultctl admin repo add\"]\n        A2[\"reprepro\"]\n        A1 --\u003e A2\n    end\n\n    subgraph clients[\"🖥️ LXC 클라이언트\"]\n        C1[\"apt update\"]\n        C2[\"apt install vaultctl\"]\n        C1 --\u003e C2\n    end\n\n    D3 --\u003e|scp| A1\n    A2 --\u003e|https| C1\n```\n\n```bash\n# 빌드\n./build-deb.sh\n\n# 배포\nscp dist/vaultctl_*.deb root@apt-server:/tmp/\nssh root@apt-server \"vaultctl admin repo add /tmp/vaultctl_*.deb\"\n\n# 클라이언트 업데이트\nsudo apt update \u0026\u0026 sudo apt upgrade vaultctl\n```\n\n---\n\n## 보안 참고사항\n\n### 파일 권한\n\n```bash\nchmod 600 ~/.config/vaultctl/config\nchmod 600 ~/.cache/vaultctl/token\n```\n\n### 토큰 관리\n\n- AppRole 토큰은 만료 시 자동 갱신됩니다\n- 캐시된 토큰은 `~/.cache/vaultctl/token`에 저장됩니다\n- `vaultctl admin token status`로 토큰 TTL을 확인하세요\n\n---\n\n## 문제 해결\n\n### 인증 오류\n\n```bash\nvaultctl status\nvaultctl init  # 재초기화\n```\n\n### 권한 거부 (Permission Denied)\n\n```bash\nvaultctl config\n# Policy에 다음이 포함되어야 함: path \"kv/data/proxmox/*\" { ... }\n```\n\n### 연결 문제\n\n```bash\ncurl -s https://vault.example.com/v1/sys/health | jq\n```\n\n---\n\n## 라이선스\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeloncafe%2Fvaultctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeloncafe%2Fvaultctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeloncafe%2Fvaultctl/lists"}