시작하기

**GETTING-STARTED.md**가 약 5분 만에 설치 완료 상태까지 안내합니다 — 사전 요구 사항, 대화형 설치, 검증. 전체 설치 참조(전역/프로젝트/수동 설치, Windows 관련 사항, 권한 허용 목록, 업데이트, 제거)는 **INSTALLATION.md**를 참조하세요.

일상적인 사용: 훅이 설치되면 실행할 것이 없습니다 — safer-dependencies는 백그라운드에서 자동으로 작동합니다. Claude가 패키지를 추가하거나 설치할 때, 위험한 의존성에 플래그를 지정하고 취약한 버전을 안전한 버전으로 제자리에서 업그레이드하며 — 알려진 취약점이 있는 설치는 실행 전에 차단합니다 — 따라서 안전하지 않은 패키지는 요청하지 않아도 감지되고 수정됩니다. 언제든지 직접 호출할 수도 있습니다: "[email protected]이 안전한가요?", "safer-dependencies 설정 확인", "safer-dependencies 통계 표시".

기능

Claude가 프로젝트에 패키지를 추가하려고 할 때, safer-dependencies가 차단하고 5가지 검사를 실행합니다:

1. 출처 -- 공식 레지스트리, 타이포스쿼팅 감지(npm/PyPI/RubyGems/Maven/crates.io), 패키지 연령
2. 버전 노후화 -- 7일 이상 전에 게시된 최신 안정 버전을 선택합니다(쿨다운 기간)
3. 취약점 스캔 -- OSV API, 가능한 경우 생태계 네이티브 도구(npm audit, pip-audit, bundle audit) 사용
4. 해시 고정 무결성 -- --hash=sha256:... 고정이 있는 PyPI requirements.txt 줄의 경우, 선언된 해시가 PyPI의 게시된 해시와 대조 검증됩니다. 불일치 시 WARNING이 발생합니다
5. 유지 관리 중단 및 오래된 패키지 -- 알려진 유지 관리 중단 패키지(예: paperclip, request, pycrypto, github.com/dgrijalva/jwt-go)는 대체 패키지 제안과 함께 즉시 하드 차단됩니다. 2년 이상 안정 릴리스가 없는 패키지는 권고 STALE: 경고를 받습니다. 하드 차단된 패키지는 매니페스트에서 제거되고 Claude가 진행 방법을 묻습니다. 오래된 패키지만 있는 경우는 그대로 둡니다.

문제가 발견되면 Claude가 경고를 발생시키고 더 안전한 버전으로 되돌아갈 수 있습니다. 모든 검사는 ~/.claude/safer-dependencies-audit-YYYY-MM.log에 기록됩니다(월별 파일 하나).

트리거 조건

이 스킬은 Claude가 다음 작업을 수행할 때 자동으로 실행됩니다:

매니페스트 / 설치 작업

• package.json, requirements.txt, Gemfile, pom.xml, build.gradle, Cargo.toml, go.mod 또는 기타 지원되는 매니페스트에서 패키지를 추가하거나 업데이트
• 매니페스트에 아직 선언되지 않은 패키지에 대한 import, require 또는 use 작성
• 잠금 파일 생성 또는 업데이트(새 항목/변경 항목만 검사)
• Bash를 통한 패키지 관리자 설치 실행(npm install, bundle install, poetry install, uv sync, go mod tidy 등) — 설치 전은 명령 인수를 감사하고, 설치 후는 결과 잠금 파일을 감사
• 고정된 패키지 관리자 설치 단계가 포함된 Dockerfile 또는 CI 워크플로(.github/workflows/*.yml 등) 작성

선택 및 추천 질문

• 라이브러리/프레임워크 비교: "axios와 node-fetch 중 무엇을 사용해야 하나요?", "moment vs dayjs?", "X와 Y 중 어느 것이 더 나은가요?"
• 추천 요청: "Python용 좋은 HTTP 클라이언트는 무엇인가요?", "Go용 로깅 라이브러리를 추천해 주세요", "Node에서 CSV를 처리하는 패키지는 무엇인가요?"
• 버전 선택: "어떤 Django 버전을 사용해야 하나요?", "최신 안정 Flask?"

사용 의도 표현(추가 전)

• "이 프로젝트에 FastAPI를 사용하고 싶어요", "Celery를 추가할 생각이에요", "ORM으로 Prisma를 검토 중이에요", "Tailwind를 사용하자"

패키지 상태 및 신뢰 질문

• "moment.js가 아직 유지 관리되나요?", "이 gem이 아직 활성인가요?", "X가 유지 관리 중단되었나요?", "X가 EOL인가요?", "이 패키지를 신뢰할 수 있나요?", "faker가 마지막으로 업데이트된 것은 언제인가요?"

스캐폴딩 명령

• npx create-react-app, npm create vite@latest, django-admin startproject, rails new, cargo new + cargo add, "새 FastAPI 프로젝트 부트스트랩"

암시적 패키지 추가(새 의존성을 암시하는 기능 요청)

• "앱에 Redis 캐싱 추가", "Postgres에 연결", "JWT 인증 추가", "이메일 전송 코드 작성" — 해당 기능에 대한 패키지가 매니페스트에 아직 없는 경우 실행됩니다

마이그레이션 및 포팅

• "requests에서 httpx로 마이그레이션", "CRA에서 Vite로 이동", "moment에서 date-fns로 포팅" — 새로 도입되는 패키지를 감사합니다

다음 경우에는 실행되지 않습니다:

• 표준 라이브러리 임포트(os, fs, java.util.* 등)
• 변경되지 않는 이미 선언된 의존성
• 패키지 내부 작동 방식에 대한 학술적 논의("React의 reconciler 설명", "webpack의 모듈 해석이 어떻게 작동하나요?") — 비교 및 선택 질문은 여전히 실행됩니다
• OS 수준 앱, 런타임 또는 IDE 확장 설치(Python 자체, Docker, Homebrew, VS Code 확장)

이 저장소의 구성

이것은 스킬 + 훅 번들이며, 단일 스킬 파일이 아닙니다. 완전한 설치는 다음 구성 요소를 배포합니다:

스킬 파일만으로는 충분하지 않습니다 — 훅이 없으면 자동 호출은 Claude가 스킬을 사용하기로 결정하는 데 의존합니다. 전체 커버리지를 위해 다섯 가지 구성 요소를 모두 설치하세요. 많은 스킬과 슬래시 명령이 내부적으로 하위 에이전트를 디스패치하므로, 명시적으로 하위 에이전트를 생성하지 않더라도 Post-Agent 쌍이 중요합니다. (스킬 단독으로 커버리지를 보장할 수 없는 이유는 FAQ.md를 참조하세요.)

지원 생태계

설치

프로젝트가 처음이신가요? **GETTING-STARTED.md**부터 시작하세요. 간단히 요약하면:```bash git clone https://github.com/robert-auger/safer-dependencies /tmp/safer-dependencies python3 /tmp/safer-dependencies/skills/scripts/safer_dependencies_manager.py interactive_install

The same verbs work outside a Claude session:```bash python3 skills/scripts/safer_dependencies_manager.py config set cooloff.days 14

상위 에이전트는 이러한 신호를 사용하여 영향을 받는 코드를 식별하고 필요에 따라 리팩터링합니다.

사전 설치 모드 (Bash 훅)

.claude/settings.json에 PreToolUse:Bash 훅을 구성하여 패키지 관리자 설치 명령에 대한 사전 점검 감사를 활성화합니다. 이는 인터셉트 모드를 보완하며(대체하지 않음) 함께 계층형 방어를 구성합니다.

1. Claude가 Bash 도구 호출을 시도합니다(예: npm install [email protected])
2. 호출이 실행되기 전에 PreToolUse 훅이 실행되어 safer-dependencies-pretooluse-bash.sh를 호출합니다
3. 순수 bash 기반 조기 필터가 약 115ms 내에 패키지 관리자 명령이 아닌 것을 차단합니다(Python 호출 없음). 따라서 git status / ls / npm test는 핫 경로에서 무시할 수 있는 비용만 부담합니다
4. 인식된 패키지 관리자 설치(npm/pnpm/yarn의 install/i/add)의 경우 헬퍼가 shlex로 토큰화하고 각 pkg@version 인수를 추출한 다음 OSV에 POST합니다
5. 취약한 구체적 핀(pin)이 발견되면 훅은 발견 항목별 GHSA-ID + CVSS + 요약과 함께 permissionDecision: "deny"를 반환하고 safer-dependencies 스킬을 호출하라는 힌트를 제공합니다
6. 설치가 실행되지 않습니다 — 네트워크 가져오기 없음, postinstall 스크립트 없음

인터셉트 모드 외에 이 기능이 존재하는 이유: 쓰기 후 심(shim)은 Bash를 인식하지 못합니다. npm install [email protected]은 감사가 실행되기 전에 완료까지 실행되고(postinstall 스크립트도 실행됨) npm install -g typosquat-pkg는 프로젝트 매니페스트를 전혀 작성하지 않습니다. 사전 설치 모드는 이러한 공백을 구조적으로 메웁니다.

사전 설치 모드는 사용자가 입력한 내용(명령줄의 pkg@version 인수)만 볼 수 있습니다. 리졸버가 실제로 설치할 전이적 트리는 볼 수 없습니다. 사후 설치 모드(아래)는 설치가 완료되면 잠금 파일을 감사합니다 — 두 모드는 중복이 아니라 상호 보완적입니다.

범위: 여기서 다루는 패키지 관리자 CLI는 5개 생태계(npm/pnpm/yarn/bun/npx/deno, pip/pip3/pipx/pipenv/uv/uvx/poetry, gem/bundle, go, cargo)를 포괄하며, Maven은 인터셉트 모드를 통해 처리됩니다(Maven 종속성은 일반적으로 CLI 동사가 아닌 pom.xml/build.gradle에 선언됩니다).

알려진 공백: Maven CLI는 mvn dependency:get -Dartifact=group:art:version 및 mvn dependency:copy를 통한 직접 다운로드를 지원합니다. 이 훅은 아직 이러한 호출을 인식하지 못합니다. 이를 정기적으로 사용하는 경우 기존 쓰기 후 심이 매니페스트에 기록되는 모든 것을 계속 포착하지만, 사전 가져오기 보호는 위에 나열된 생태계에만 적용됩니다. 후속 작업으로 추적됩니다.

인식되는 생태계별 구문:

범위 핀(npm ^4.17, pip >=, poetry ^/~, Go @latest) 및 버전 미지정은 설치 후 인터셉트 모드로 전달됩니다 — 쓰기 후 심이 리졸버가 선택한 항목을 감사합니다. 안전한 버전으로의 자동 재작성은 후속 작업으로 예약되어 있습니다.

실패 모드: 실패 시 열림(fail-open). 모든 오류(Python 누락, 네트워크 일시 장애, 잘못된 입력)는 출력 없이 0으로 종료되어 bash가 계속 진행되도록 합니다. 인터셉트 모드는 설치 후에도 계속 실행되므로 사전 점검 실패 시 기존 보호 기능으로 원활하게 전환됩니다.

거부 예시:``` safer-dependencies pre-flight audit blocked this install. Vulnerable pinned version(s) detected:

• [email protected] → GHSA-35jh-r3h4-6jhm (CVSS:7.4): Command Injection in lodash Re-run with a patched version, or invoke the safer-dependencies skill for a recommended pin.

Post-Agent 모드 (Agent 훅 쌍)

위의 네 가지 모드는 루트 세션 도구 호출에만 적용됩니다. 루트 세션이 하위 에이전트를 파견할 때(Agent 도구를 통해 — 많은 스킬과 슬래시 명령이 내부적으로 이 작업을 수행합니다), 하위 에이전트의 Write/Edit/Bash 호출은 이 모든 모드를 우회합니다. Post-Agent 모드는 이러한 공백에 대한 반응형 안전망입니다.

1. PreToolUse:Agent 훅(safer-dependencies-pretooluse-agent.sh)이 각 Agent 파견 직전에 실행되어 /tmp/.safer-deps-agent-<PPID>-<session_id>.sentinel에 센티널 파일을 생성합니다(세션 ID를 사용할 수 없을 때는 PPID만 사용하는 이름으로 대체)
2. 하위 에이전트가 실행되며 매니페스트 또는 잠금 파일을 작성할 수 있습니다
3. PostToolUse:Agent 훅(safer-dependencies-posttooluse-agent.sh)이 Agent 호출이 반환된 후 실행되어, 센티널보다 최신인 모든 매니페스트와 잠금 파일을 find로 찾아 동일한 shim 경로를 통해 각각을 감사합니다
4. 발견 사항은 루트 세션의 다음 턴에 additionalContext로 표시되며, 센티널은 제거됩니다

중첩된 하위 에이전트는 자동으로 처리됩니다 — 루트의 PostToolUse:Agent 훅은 외부 에이전트의 모든 작업(자체가 파견한 모든 것을 포함)이 디스크에 기록된 후에만 실행됩니다. 유일한 공백은 매니페스트나 잠금 파일을 작성하지 않는 전역 설치(npm install -g …)입니다: 스캔할 대상이 없습니다. 다른 훅과 마찬가지로 실패 시 열림(fail open) 방식입니다 — 모든 오류(센티널 누락, shim 누락, 읽을 수 없는 페이로드)는 조용히 0으로 종료됩니다. 전체 설계 근거는 skills/safer-dependencies.md에 있습니다.

감사 로그

모든 검사는 ~/.claude/safer-dependencies-audit-YYYY-MM.log에 기록됩니다(달력 월별 파일 하나, YYYY-MM은 UTC 연도-월) — 단일 JSON 줄로 기록됩니다. 전체 경로를 SAFE_DEP_AUDIT_LOG 환경 변수로 재정의할 수 있습니다(설정 시 날짜 접미사는 추가되지 않습니다). 파일은 SAFE_DEP_LOG_MAX_BYTES(기본값 10 MiB, 0으로 설정하면 비활성화)를 초과할 때 크기 순환됩니다. SAFE_DEP_MODEL을 설정하여 각 항목의 source.model에 기록되는 모델 값을 재정의할 수 있습니다 — 모델 버전 간 A/B 비교에 유용합니다.

다섯 가지 모드 모두 동일한 파일에 추가됩니다. 각 항목은 어떤 구성 요소가 기록했는지 식별하는 source 블록(스키마 2.2)을 포함합니다:

source.model은 세션에서 활성화된 Claude Code 모델(예: "claude-sonnet-4-6")을 기록합니다. 스키마 2.1+에 존재하며, 이전 설치로 작성된 항목은 이 필드를 생략합니다. stats 명령은 해당 필드가 없을 때 "unknown"으로 정상적으로 처리합니다.

jq로 source.component별 필터링:```bash jq -r '.source.component' audit.log | sort | uniq -c | sort -rn jq -c 'select(.source.component == "bash.pretooluse")' audit.log

Surface every silent fail-open across all hooks:

jq -c 'select(.source.mode == "fail_open") | {component: .source.component, reason: .fail_open.reason, ts}' audit.log

이 감사 로그에서 추출한 활동, 보안 영향 및 성능 지표에 대한 사람이 읽을 수 있는 요약을 제공합니다.

항목 형태(스키마 2.2). 동일한 ts / schema / source 헤더를 공유하는 세 가지 서로 다른 형태가 있습니다:

감사 항목: 인터셉트 모드는 전체 파이프라인(출처, 버전 연식, OSV, abandoned/stale, typosquat, 서명)을 실행하므로 모든 배열이 채워질 수 있습니다. 사전 설치 모드는 현재 OSV만 실행하므로 abandoned / stale / typosquat / signatures는 항상 비어 있습니다. 설치 후 디스패치(잠금 파일 감사)는 shim.posttooluse 아래에 기록되며, findings는 잠금 파일 감사자의 WARNING: 문자열로 채워집니다. notes 배열은 정보성 NOTE: 신호(예: 매니페스트가 고정되지 않아 건너뜀)를 전달합니다.

스키마 2.2는 잠금 파일 감사 항목에 네 가지 필드를 추가적으로(비파괴적으로) 추가했습니다: lockfile, manifest_ref, relation_summary(플래그된 각 패키지를 형제 매니페스트에 대해 직접/전이/알 수 없음으로 분류) 및 적용 중인 transitive 계층을 기록하는 policy 블록. 이 변경은 하위 호환됩니다: 2.1 항목의 읽는 쪽은 새 필드를 허용하며, source.model 필드는 2.1부터 계속 존재합니다.```json { "ts": "2026-04-19T12:34:56Z", "schema": "2.2", "source": { "component": "shim.posttooluse", "script": "shim.sh", "hook": "PostToolUse:Write", "tool": "Write", "mode": "intercept", "model": "claude-sonnet-4-6" }, "file": "/path/to/project/package.json", "ecosystem": "npm", "checked": ["[email protected]", "[email protected]"], "findings": ["UPDATED: express 4.18.2 → 4.22.1 (HIGH: 1 CVE fixed)"], "abandoned": [], "stale": [], "typosquat": [], "unknown": [], "signatures": [], "notes": [], "clean": ["[email protected]"] }

Fail-open 모드 예시(인접한 shim 없이 호출되는 설치 후 Bash 훅 — 손상된 설치):```json { "ts": "2026-05-03T07:14:11Z", "schema": "2.2", "source": { "component": "bash.posttooluse", "script": "safer-dependencies-posttooluse-bash.sh", "hook": "PostToolUse", "tool": "Bash", "mode": "fail_open", "model": "claude-sonnet-4-6" }, "fail_open": { "reason": "shim_missing", "detail": "/home/alice/.claude/skills/safer-dependencies" } }