Security

보안

kiwoom-cli의 보안 모델은 OS 키체인이 암호화 경계라는 원칙 위에 서 있습니다. gh, aws, docker CLI와 동일한 모델입니다.

v2.1 변경: 앱 자체 비밀번호/Fernet 암호화 계층이 제거되었습니다. 모든 명령이 비밀번호·생체인증 프롬프트 없이 동작합니다. 배경은 아래 설계 원칙 참고.

아키텍처 개요

┌──────────────────────────────────────────────────────────┐
│  OS 키체인                                                │
│  (macOS Keychain / Windows Credential Manager /          │
│   Linux Secret Service)                                  │
│  ├── {profile}:appkey                                    │
│  ├── {profile}:secretkey                                 │
│  └── {profile}:token                                     │
│                                                          │
│  → 디스크 저장 시 OS가 암호화                             │
│  → 사용자 계정 단위 접근 제어                             │
└──────────────────────────────────────────────────────────┘

~/.kiwoom/config.toml (비민감 정보만)
├── domain
├── account
└── default_profile

저장 위치별 보안

항목	저장 위치	암호화	프롬프트
appkey / secretkey	OS 키체인	OS 담당	X
토큰	OS 키체인	OS 담당	X
domain / account	config.toml	없음 (비민감)	X
캐시 (종목 리스트)	~/.kiwoom/cache/	없음 (비민감)	X

설계 원칙: 왜 비밀번호 계층이 없는가

v2.0까지는 appkey/secretkey를 앱 자체 비밀번호(PBKDF2 + Fernet)로 한 번 더 암호화했습니다. v2.1에서 이 계층을 의도적으로 제거했습니다:

• 자동화가 불가능해짐 — 대화형 비밀번호 프롬프트는 크론잡, CI, AI 에이전트가 답할 수 없습니다. 자동화하려면 결국 비밀번호를 파일이나 환경변수에 평문으로 두게 되어, 보안 계층이 형식만 남습니다.
• OS 키체인으로 충분 — 키체인은 디스크 저장 시 암호화하고 사용자 계정 단위로 접근을 제어합니다. gh auth, aws configure, docker login 모두 같은 이유로 앱 자체 암호화 계층을 두지 않습니다.
• 마찰 대비 이득 없음 — 공격자가 이미 사용자 계정으로 로컬 셸을 확보한 상황이라면, 앱 비밀번호는 키로거·메모리 덤프로 우회 가능합니다. 방어해야 할 것은 원격/파일 수준 노출이고, 그건 키체인이 해결합니다.

주문 안전

주문 명령어는 실행 전 주문 미리보기 + 대화형 확인을 거칩니다:

kiwoom order buy 005930 10 --type market
# → 주문 내용 미리보기 출력
# → "주문을 실행하시겠습니까? [y/N]:"

자동화 시에만 --confirm으로 명시적으로 스킵합니다:

kiwoom order buy 005930 10 --type market --confirm

확인 게이트는 주문(order buy/sell/modify/cancel, 신용, 금현물, 미국주식)과 환전(account exchange apply)에 적용됩니다. 조회 명령에는 없습니다.

공격 시나리오별 방어

공격	방어
파일 읽기 (cat ~/.kiwoom/config.toml)	키 없음 — 도메인/계좌번호만 존재
AI 에이전트가 설정 파일 Read	키 없음
디스크 탈취 (오프라인 공격)	키체인이 디스크 저장 시 암호화
다른 OS 계정의 접근	키체인 사용자 단위 접근 제어
토큰 탈취	만료되는 값, auth logout으로 즉시 폐기 가능
실수/폭주 주문	미리보기 + 대화형 확인 (기본), --confirm은 명시적 선택

환경변수 정책

appkey/secretkey는 환경변수를 지원하지 않습니다. 환경변수는 /proc/*/environ이나 ps e, 로그로 노출될 수 있기 때문입니다.

지원되는 환경변수 (비민감 정보만):

• KIWOOM_DOMAIN
• KIWOOM_ACCOUNT
• KIWOOM_PROFILE

v2.0 이하에서 업그레이드

이전 암호화 저장소 형식(_salt 센티널)이 감지되면 안내 메시지가 표시됩니다. kiwoom config setup을 한 번 다시 실행하면 이전 암호문과 센티널이 정리되고 새 방식으로 저장됩니다. 토큰은 그대로 유지됩니다.

취약점 제보

보안 취약점은 공개 이슈로 등록하지 말고 Security Advisories로 비공개 제보해 주세요. 정책: SECURITY.md