9.0 KiB
9.0 KiB
Machine Env Service — 구현 Plan
홈랩 머신마다 동작하는 로컬 메타데이터 데몬. AWS IMDSv2와 동일한 프로토콜로 머신 스코프 시크릿/환경변수를 노출한다. 클라이언트(컨테이너/프로세스)는 Infisical 자격증명 없이 데몬에 HTTP로 fetch.
1. 목표
- 각 머신에 systemd 서비스 1개로 상주하는 데몬
- IMDSv2 프로토콜(PUT 토큰 → GET 메타데이터) 그대로 구현
- 머신 스코프 시크릿은 데몬이 Infisical에서 가져와서 노출
- 데몬만 Infisical machine identity 자격증명을 보유 (클라는 0개)
2. 인터페이스 (IMDSv2 호환)
토큰 발급
PUT /latest/api/token
Headers:
X-aws-ec2-metadata-token-ttl-seconds: <1..21600>
Response:
200 OK, body = <opaque token string>
400 if header missing/invalid
405 if method != PUT
메타데이터 조회
GET /latest/meta-data/...
Headers:
X-aws-ec2-metadata-token: <token>
Response:
200 + body
401 if token missing/expired/invalid
SSRF 방어 규칙 (IMDSv2와 동일)
PUT이 아닌 메서드로 토큰 요청 시405X-Forwarded-For헤더가 있으면 모든 요청 거부 (403)Host헤더 검증 (169.254.169.254또는 listen 중인 호스트 IP)
3. 시크릿 엔드포인트
GET /latest/meta-data/secrets/ → 키 목록 (개행 구분, IMDS 컨벤션)
GET /latest/meta-data/secrets/<KEY> → 해당 키의 값 (plain text)
추가로 전체 dump (편의용, 기본 비활성, 설정으로 켜기):
GET /latest/meta-data/secrets-bundle → JSON {key: value}
기존 KNOWN_SECRET_KEYS는 노출 화이트리스트로 활용. 화이트리스트에 없는 키는 404.
4. 머신 식별 / 자격증명
- 데몬이 부팅 시 자체적으로 dotenv 파일을 읽는다 (OS-agnostic, systemd
EnvironmentFile과 launchd plistEnvironmentVariables차이 회피)- 경로:
MACHINE_ENV_CONFIGenv로 override 가능, 기본값 OS별- Linux:
/etc/machine-env-service/env - macOS:
/usr/local/etc/machine-env-service/env
- Linux:
- 경로:
- 파일 내용:
INFISICAL_CLIENT_IDINFISICAL_CLIENT_SECRETINFISICAL_PROJECT_IDINFISICAL_ENVIRONMENT(dev|staging|prod)INFISICAL_SITE_URL(기본https://secret-manager.dahyeon.us/)
- 머신마다 별도의 Infisical machine identity를 부여 → 그 자격증명이 곧 머신 식별자
- 자격증명 파일 권한은
0600, root 소유
5. 캐시 / 갱신
- 데몬 부팅 시 1회
listSecrets호출 → 인메모리 맵 채움 - 백그라운드 타이머로 TTL마다 재조회 (기본 60초,
REFRESH_INTERVAL_SEC로 설정) - Infisical 호출 실패 시: 마지막 성공 값 유지, 로그만 남김
- 캐시는 read-mostly이므로 swap 갱신 시 잠시 락 또는 atomic 참조 교체
6. 토큰 저장소 (인메모리)
Map<tokenString, expiresAtEpochMs>- 토큰 발급:
crypto.randomBytes(32).toString("base64url") - 만료된 토큰은 lazy 청소 (요청 들어올 때 + 주기적 sweep)
- 데몬 재시작 시 모든 토큰 무효화 (의도된 동작, IMDSv2와 동일)
7. 네트워크 / 컨테이너 접근
데몬은 두 곳에 동시에 listen한다:
169.254.169.254:80— link-local. 호스트 자체에서 동작하는 프로세스용- Linux: dummy interface로 link-local 주소 추가
ip link add dev imds-dummy type dummy ip addr add 169.254.169.254/32 dev imds-dummy ip link set imds-dummy up - macOS:
lo0alias로 추가ifconfig lo0 alias 169.254.169.254/32 up - 두 경우 모두 재부팅 시 사라지므로 service manager가 부팅 시 setup 실행
- Linux: dummy interface로 link-local 주소 추가
0.0.0.0:<METADATA_PORT>(기본8675) — 호스트 LAN IP. 컨테이너에서 호스트 IP로 접근- Linux 컨테이너 (bridge):
http://<host-ip>:8675/latest/... - Docker Desktop on macOS: link-local이 VM 안에서 호스트로 라우팅 안 됨 →
http://host.docker.internal:8675/latest/...필수 - host network 강제 불필요
- Linux 컨테이너 (bridge):
80 포트 바인딩:
- Linux: systemd unit에서
AmbientCapabilities=CAP_NET_BIND_SERVICE(root 아닌 user로 실행 가능) - macOS:
CAP_NET_BIND_SERVICE같은 메커니즘 없음 → launchd plistUserName=root로 실행
8. 보안
127.0.0.1/169.254.169.254/LAN IP는 모두 신뢰 경계 안 (홈랩 내부망 전제)- 외부 노출 금지 — 방화벽에서 metadata 포트는 LAN 외부 차단
- 자격증명 파일은
0600, 데몬 user(machine-env)만 접근 - 응답 본문에 시크릿 외 다른 정보 절대 포함 금지 (IMDS 스타일)
9. 디렉토리 구조
src/
common/
secret-manager.ts # 기존 — Infisical fetch 로직 추출/재사용
known-secret-keys.ts # 기존
env-loader.ts # 기존
daemon/
main.ts # 엔트리포인트
server.ts # HTTP 서버 (node:http)
routes/
token.ts # PUT /latest/api/token
metadata.ts # GET /latest/meta-data/...
secrets.ts # GET /latest/meta-data/secrets/...
middleware/
ssrf-guard.ts # X-Forwarded-For, Host, method 검증
token-auth.ts # 토큰 헤더 검증
store/
token-store.ts # 인메모리 토큰 저장소
secret-cache.ts # Infisical 캐시 + 백그라운드 갱신
config.ts # 환경변수 파싱
deploy/
systemd/ # Linux (Ubuntu)
machine-env-service.service
machine-env-setup-link-local.service # 부팅 시 dummy interface 셋업
machine-env-service.env.example
launchd/ # macOS
us.dahyeon.machine-env-service.plist
us.dahyeon.machine-env-setup-link-local.plist
machine-env-service.env.example
scripts/
setup-link-local-linux.sh
setup-link-local-macos.sh
10. 구현 단계 (codex용 체크리스트)
-
config 모듈 —
src/daemon/config.ts- 필수 env(
INFISICAL_*) 검증, 누락 시 즉시 종료 - 선택 env(
METADATA_PORT,REFRESH_INTERVAL_SEC, 화이트리스트 모드 등) 기본값 처리
- 필수 env(
-
secret-cache —
src/daemon/store/secret-cache.tssecret-manager.ts의 Infisical fetch 로직을 클래스/함수로 추출start()/stop()/get(key)/list()API- 부팅 시 첫 fetch는 동기적으로 await, 실패해도 빈 캐시로 계속 진행
- TTL 기반 백그라운드 재조회 (
setInterval)
-
token-store —
src/daemon/store/token-store.tsissue(ttlSec): stringvalidate(token): boolean- 만료 sweep
-
middleware
ssrf-guard: 메서드/X-Forwarded-For/Host 검증token-auth:X-aws-ec2-metadata-token헤더 검증
-
routes
PUT /latest/api/token: TTL 헤더 파싱 →token-store.issue()→ 응답GET /latest/meta-data/secrets/: 화이트리스트 키 목록 (개행 구분)GET /latest/meta-data/secrets/<KEY>: 캐시에서 조회, 없으면 404GET /latest/meta-data/secrets-bundle: 설정으로 enable됐을 때만, JSON 응답
-
server —
src/daemon/server.tsnode:http로 라우팅 (외부 의존 최소화)- 두 listener 동시 기동 (
169.254.169.254:80,0.0.0.0:METADATA_PORT) - graceful shutdown (SIGTERM → 새 요청 거부 → 인플라이트 대기 → 캐시 타이머 정리)
-
main —
src/daemon/main.ts- config 로드 → secret-cache 초기화 → token-store 초기화 → server 기동
- SIGTERM/SIGINT 핸들링
-
deploy 자산
- Linux (systemd):
machine-env-service.service:Type=simple,User=machine-env,AmbientCapabilities=CAP_NET_BIND_SERVICE,CapabilityBoundingSet=CAP_NET_BIND_SERVICE,Restart=on-failuremachine-env-setup-link-local.service:Type=oneshot,RemainAfterExit=true, 부팅 시setup-link-local-linux.sh실행machine-env-service.service는After=machine-env-setup-link-local.service,Requires=...
- macOS (launchd):
us.dahyeon.machine-env-service.plist:RunAtLoad=true,KeepAlive=true,UserName=root,ProgramArguments에 node + 빌드 산출물 경로us.dahyeon.machine-env-setup-link-local.plist:RunAtLoad=true,LaunchOnlyOnce=false,setup-link-local-macos.sh실행- 설치 위치:
/Library/LaunchDaemons/
- link-local 설정 스크립트는 idempotent (이미 alias/interface 있으면 skip)
- Linux (systemd):
-
package.json 업데이트
"bin"또는"scripts"에 데몬 실행 엔트리- 빌드 스크립트 (tsc)
-
간단한 클라이언트 예제 —
examples/fetch-secret.shcurl -X PUT -H "...ttl-seconds: 60" .../latest/api/token→ 토큰curl -H "X-aws-ec2-metadata-token: $TOKEN" .../latest/meta-data/secrets/FOO
11. 추후 (이번 범위 밖)
- mTLS 또는 호출자 식별 기반 시크릿 범위 제한
- Infisical webhook 연동으로 즉시 갱신
- 머신별 dynamic 메타데이터(hostname, IP 등) 노출 (
/latest/meta-data/hostname등) - IPv6 link-local (
fe80::a9fe:a9fe) 지원