trustlock

Git 네이티브 의존성 승인 컨트롤러입니다. 모든 의존성 변경 시 신뢰 신호를 평가합니다.

작동 방식

trustlock은 Git pre-commit 훅(권고 모드)과 CI 검사(강제 모드)로 실행됩니다:

• 권고 (pre-commit): 위반 시 경고, 종료 코드 0, 모든 패키지가 승인되면 신뢰 기준선을 업데이트합니다.
• 강제 (--enforce): 위반 시 차단, 종료 코드 1, 기준선을 업데이트하지 않습니다.

패키지별 평가 신뢰 신호:

• 쿨다운(Cooldown) — 레지스트리에 게시된 이후 경과 시간
• 출처(Provenance) — SLSA 증명이 있는지 여부
• 고정(Pinning) — 잠금 파일이 정확한 버전을 사용하는지 여부
• 설치 스크립트(Install scripts) — 설치 시 스크립트를 실행하는지 여부
• 소스(Sources) — 레지스트리, Git URL, 로컬 경로, URL 중 어디에서 왔는지
• 새 의존성(New dependencies) — 프로젝트에 처음 추가된 항목
• 전이 의존성 급증(Transitive surprise) — 예상치 못한 전이 의존성 개수 증가
• 게시자 변경(Publisher change) — 버전 간 게시자 ID 변경 여부

설치

npm install -g trustlock

Node.js >= 18.3 필요.

지원되는 잠금 파일

빠른 시작

워크플로 1 — 프로젝트 온보딩

# 1. 프로젝트에 trustlock 초기화
trustlock init

# 2. Git pre-commit 훅 설치
trustlock install-hook

# 3. (선택) 현재 의존성 상태 검토
trustlock audit

init 후 trustlock이 생성하는 파일:

• .trustlockrc.json — 정책 설정
• .trustlock/baseline.json — 신뢰하는 의존성 스냅샷
• .trustlock/approvals.json — 승인 기록
• .trustlock/.cache/ — 레지스트리 캐시 (gitignore 처리됨)

.trustlockrc.json과 .trustlock/baseline.json을 저장소에 커밋하세요.

워크플로 2 — 의존성 업데이트 확인 및 승인

# 정상적으로 의존성 설치 실행
npm install [email protected]

# pre-commit 훅으로 trustlock check가 자동 실행됩니다.
# 수동 실행:
trustlock check

# 모든 패키지가 승인된 경우 출력:
# ✔ [email protected] — 승인됨

모든 패키지가 통과하면 trustlock check가 기준선을 자동으로 업데이트하고(권고 모드만) 종료 코드 0을 반환합니다.

워크플로 3 — 차단된 의존성 처리

# 새 패키지가 쿨다운 규칙을 위반한 경우:
trustlock check
# ✖ [email protected] — 차단됨
#   exposure:cooldown  게시된 지 2시간 (정책상 72시간 필요)
#   승인하려면: trustlock approve [email protected] --override cooldown --reason "..." --expires 7d

# 예외 승인 후 재확인:
trustlock approve [email protected] \
  --override cooldown \
  --reason "기능 X에 필요함; 팀 검토로 안전 확인됨" \
  --expires 7d

trustlock check
# ✔ [email protected] — 승인됨 (예외)

워크플로 4 — 프로젝트 간 의존성 상태 비교

# 모노레포 패키지 간 버전 차이 및 출처 불일치 감지
trustlock audit --compare packages/frontend packages/backend packages/shared

명령어

정책 프로필

trustlock에는 --profile로 선택 가능한 두 가지 기본 프로필이 포함되어 있습니다:

# CI에서 엄격 프로필 사용
trustlock check --enforce --profile strict

조직 정책 상속

팀은 공유 URL에 정책을 중앙화하고 각 저장소에서 확장할 수 있습니다:

{
  "extends": "https://policy.example.com/trustlockrc.json",
  "cooldown_hours": 96
}

저장소 설정은 조직 정책을 더 엄격하게만 할 수 있습니다 — 최소 기준 강제를 통해 저장소가 조직이 정한 임계값을 낮추는 것을 방지합니다.

문서

• USAGE.md — 전체 명령어 참조, 모든 플래그, 종료 코드, 오류 메시지
• POLICY-REFERENCE.md — 모든 .trustlockrc.json 옵션
• ARCHITECTURE.md — 설계 결정 사항 및 모듈 맵
• examples/ — 설정 및 CI 워크플로 예제

CI 통합

CI 파이프라인에 trustlock 추가:

# GitHub Actions — examples/ci/github-actions.yml 참조
- run: npx trustlock check --enforce

examples/ 에서 GitHub Actions, Lefthook, Husky 설정을 확인하세요.

trustlock의 타이밍

Trustlock은 커밋 시점에 잠금 파일 변경을 평가합니다. npm install을 가로채거나 샌드박스 처리하지 않습니다. 악성 패키지가 postinstall 스크립트를 실행하는 경우 trustlock이 보기 전에 실행됩니다. Trustlock은 손상된 잠금 파일이 커밋되고 병합되는 것을 방지하여, 피해 범위를 전체 팀과 프로덕션이 아닌 단일 개발자 머신으로 제한합니다. 설치 시 스크립트 차단은 --ignore-scripts 또는 pnpm의 기본 라이프사이클 스크립트 제어를 사용하세요.

trustlock이 하지 않는 일

• 악성코드 스캐너가 아닙니다 — trustlock은 패키지 소스 코드를 검사하거나 알려진 악성 서명을 탐지하지 않습니다. 전용 스캐너를 사용하세요.
• 설치 시점 샌드박스가 아닙니다 — trustlock은 npm install을 가로채지 않습니다. --ignore-scripts를 사용하세요.
• CVE 추적기가 아닙니다 — 취약점 데이터베이스는 npm audit 또는 Snyk을 사용하세요.
• 라이선스 검사기가 아닙니다 — license-checker 등을 사용하세요.
• pnpm trustPolicy나 npm의 min-release-age를 대체하지 않습니다 — 이들은 레지스트리에서 강제하는 서버 측 제어입니다. trustlock은 저장소 경계에서 작동하는 클라이언트 측 승인 게이트입니다.

정보

trustlock은 표준 Node.js 도구 체인이 실제로 프로젝트에 무엇이 추가되는지에 대해 얼마나 수동적인지에 대한 좌절감에서 만들어졌습니다. npm install은 무엇이든 가져옵니다 — 2분 전에 게시된 패키지, 설치 시 임의의 스크립트를 실행하는 패키지, 레지스트리 tarball에서 Git URL로 밤새 전환된 패키지 — 그리고 받는 피드백은 잠금 파일 diff뿐입니다.

trustlock이 다루는 위협 모델은 좁지만 현실적입니다: 악성 버전이 게시된 후 제거되거나 플래그가 지정될 때까지의 시간 창. 취약점 스캐너는 사후에 작동합니다. trustlock은 저장소나 CI에 도달하기 전, 승인 지점에서 작동합니다.

설계는 의도적으로 최소화되었습니다. trustlock은 런타임 의존성이 없습니다 — 자체적으로 공급망 위험 제로 도구입니다. 취약점 스캐너나 의존성 감사를 대체하지 않으며, 신뢰 연속성을 강제합니다. 일단 버전이 기준선에 포함되면 신뢰됩니다. 새로운 것은 선언한 정책에 따라 승인을 받아야 합니다.

승인 워크플로는 감사 가능성을 잃지 않으면서 탈출구가 필요한 팀을 위해 존재합니다. 모든 예외는 타임스탬프가 찍히고 특정 규칙에 범위가 지정되며 만료됩니다. clean-approvals은 부수적인 고려 사항이 아니라 일급 명령어입니다.