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

### Pre-Install Mode (Bash 훅)

`.claude/settings.json`에 `PreToolUse:Bash` 훅을 구성하여
패키지 관리자 설치 명령에 대한 사전 실행 감사를 활성화합니다. 이는
Intercept Mode를 보완하는 것이지 대체하는 것이 아닙니다 — 함께 계층형 방어를 구성합니다.

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

**Intercept Mode 외에 이것이 존재하는 이유:** 사후 쓰기 심은
Bash를 인식하지 못합니다. `npm install [email protected]`은 감사가 발동되기 전에
완료되고(postinstall 스크립트도 실행됨), `npm install -g
typosquat-pkg`는 프로젝트 매니페스트를 전혀 쓰지 않습니다. Pre-Install Mode는
이러한 공백을 구조적으로 메웁니다.

Pre-Install Mode는 사용자가 **입력한** 것(명령줄의 `pkg@version` 인자)만
볼 수 있습니다. 리졸버가 실제로 설치할 전이 의존성 트리는 볼 수 없습니다.
**Post-Install Mode** (아래)는 설치가 완료되면 lockfile을 감사합니다 —
두 모드는 상호 보완적이며 중복이 아닙니다.

**범위:** 여기서 다루는 패키지 관리자 CLI는 다섯 개 에코시스템에 걸쳐 있습니다
(npm/pnpm/yarn/bun/npx/deno, pip/pip3/pipx/pipenv/uv/uvx/poetry, gem/bundle,
go, cargo), Maven은 Intercept Mode를 통해 포함됩니다(Maven 의존성은 일반적으로
`pom.xml`/`build.gradle`에 선언되며 CLI 동사로 추가되지 않습니다).

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

에코시스템별 인식 구문:

| PM | 동사 | 구체적 버전 핀 구문 |
|---|---|---|
| `npm`, `pnpm`, `yarn`, `bun` | `install`, `i`, `add` (추가로 `yarn`/`pnpm dlx`, `bun x`, `yarn create`) | `[email protected]`, `@scope/[email protected]` |
| `npx` | (동사 없음 — 패키지가 첫 번째 위치 인자) | `[email protected]` |
| `deno` | `add`, `install` | `npm:[email protected]` (npm 접두사 사양) |
| `pip`, `pip3`, `pipx`, `pipenv`, `uv`, `uvx`, `poetry` | `install` (pip/pip3/pipx/pipenv) / `add` (uv/poetry) / 동사 없음 (uvx) | `pkg==1.2.3` (extras `pkg[extra]==X`도 처리) |
| `gem`, `bundle` | `install` (gem) / `add` | `-v 1.2.3`, `--version 1.2.3`, `--version=1.2.3` (별도 플래그) |
| `go` | `get`, `install` | `[email protected]` (Go 모듈 규칙에 따라 `v` 접두사 포함 필수) |
| `cargo` | `add`, `install` | `[email protected]` |

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

**실패 모드:** fail-open입니다. 모든 오류(파이썬 누락, 네트워크 일시 장애,
잘못된 입력)는 출력 없이 0으로 종료되어 bash가 계속 진행하도록 합니다.
설치 후에도 Intercept Mode가 계속 실행되므로 사전 실행 실패는
기존 보호로 우아하게 폴백됩니다.

**거부 예시:**```
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가 다음 작업을 수행할 때 자동으로 발동합니다:

**매니페스트 / 설치 작업**
- `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` 등) — Pre-Install은 명령 인수를 감사하고, Post-Install은 결과 잠금 파일을 감사합니다
- 고정된 패키지 관리자 설치 단계를 포함하는 `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 확장)

## 이 저장소의 구성

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

| File | Role |
|---|---|
| `skills/safer-dependencies.md` | **스킬**(설치 시 `SKILL.md`가 됨). 감사 절차를 설명하며 설치/통계용 관리 모드를 포함합니다. |
| `skills/safer-dependencies-shim.sh` | `PostToolUse:Write`/`Edit` 훅 — 매니페스트 + 잠금 파일 쓰기를 감사하고 취약한 버전을 제자리에서 자동 수정합니다(Intercept 모드). |
| `skills/safer-dependencies-pretooluse-bash.sh` | `PreToolUse:Bash` 훅 — 패키지 관리자 설치 명령에 대한 사전 OSV 감사; 설치가 실행되기 전에 취약한 버전으로 고정된 패키지를 거부합니다(Pre-Install 모드). |
| `skills/safer-dependencies-posttooluse-bash.sh` | `PostToolUse:Bash` 훅 — Bash 명령 후 사후 감사; 새로 작성된 잠금 파일, `sed`/`jq`/스크립트로 편집된 매니페스트, 일반 `pip install`의 의존성 해석 결과 환경에서 전이적 CVE를 포착합니다(Post-Install 모드). |
| `skills/safer-dependencies-pretooluse-agent.sh` + `skills/safer-dependencies-posttooluse-agent.sh` | `PreToolUse:Agent` + `PostToolUse:Agent` 훅 쌍 — 하위 에이전트 커버리지 공백을 해소합니다. 모드 2–4는 루트 세션 도구 호출에서만 발동하므로 하위 에이전트가 작성하는 모든 매니페스트는 이를 우회합니다. Post-Agent는 각 Agent 도구 호출이 반환된 후 하위 에이전트가 작성한 모든 것을 감사합니다(Post-Agent 모드). |
| `skills/scripts/` | 모든 훅이 사용하는 공유 Python 라이브러리(`safedep/`) 및 독립형 리졸버 스크립트. |
| `skills/scripts/safer_dependencies_manager.py` | 대화형 설치, 사용 통계 및 설정 검증을 위한 관리 모듈. |

스킬 파일만으로는 충분하지 않습니다 — 훅이 없으면 자동 호출은 Claude가 스킬을 사용하기로 결정하는 데 달려 있습니다. 전체 커버리지를 위해 다섯 구성 요소를 모두 설치하세요. 많은 스킬과 슬래시 명령이 내부적으로 하위 에이전트를 파견하므로, 직접 명시적으로 하나도 생성하지 않더라도 Post-Agent 쌍이 중요합니다. (스킬 단독으로는 커버리지를 보장할 수 없는 이유는 [FAQ.md](https://github.com/robert-auger/safer-dependencies/blob/HEAD/FAQ.md#why-a-skill-alone-is-not-sufficient)를 참조하세요.)

## 지원되는 에코시스템

| 에코시스템 | 매니페스트 | 잠금 파일 |
|-----------|----------|-----------|
| npm | `package.json` | `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` |
| PyPI | `requirements.txt`, `pyproject.toml`, `Pipfile`, `setup.py`, `setup.cfg` | `Pipfile.lock`, `poetry.lock`, `uv.lock` |
| RubyGems | `Gemfile`, `*.gemspec` | `Gemfile.lock` |
| Maven | `pom.xml`, `build.gradle`, `libs.versions.toml` | -- |
| Go | `go.mod` | `go.sum` |
| Rust | `Cargo.toml` | `Cargo.lock` |
| PHP (Composer) | `composer.json` | `composer.lock` |

## 설치

프로젝트가 처음이신가요? **[GETTING-STARTED.md](https://github.com/robert-auger/safer-dependencies/blob/HEAD/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

보다 쉬운 분석을 위해 로그를 수동으로 파싱하는 대신 Claude에게 사용 통계를 요청하세요:```
"Show safer-dependencies stats for the last month"

Pre-Install Mode example (Bash hook, vulnerable pin denied):```json
{
  "ts": "2026-04-23T06:56:21Z",
  "schema": "2.2",
  "source": {
    "component": "bash.pretooluse",
    "script": "pretooluse-bash.sh",
    "hook": "PreToolUse:Bash",
    "tool": "Bash",
    "mode": "intercept",
    "model": "claude-sonnet-4-6"
  },
  "file": "bash:npm install [email protected] [email protected]",
  "ecosystem": "npm",
  "checked": ["[email protected]", "[email protected]"],
  "findings": [
    "BLOCKED: [email protected] GHSA-35jh-r3h4-6jhm (CVSS:3.1/...): Command Injection in lodash"
  ],
  "abandoned": [],
  "stale": [],
  "typosquat": [],
  "unknown": [],
  "signatures": [],
  "notes": [],
  "clean": ["[email protected]"]
}

A fail-open 항목은 "이 훅이 실행되었지만 필수 조건이 누락되어 감사(audit)를 수행하지 않고 조기 종료되었습니다"를 의미합니다. 위의 jq 필터(`select(.source.mode == "fail_open")`)를 사용하여 로그에서 모든 무음 보호 손실 이벤트를 표시하십시오.

shim이 dry-run 모드(`SAFE_DEP_DRY_RUN=1`)로 실행되면 항목에는 `"mode": "dry_run"`도 포함되므로 사후 분석에서 감사 전용 호출을 필터링할 수 있습니다.

## 요구 사항

- Python 3.9+ (훅이 이를 확인하며 이전 버전 인터프리터에서는 fail-open 처리됨)
- `curl` (레지스트리 API 호출 및 OSV 취약점 확인용)
- 에코시스템 도구(선택 사항, 없으면 스킬이 OSV API로 대체):
  - `npm` (npm 패키지용)
  - `pip-audit` (Python 패키지용)
  - `bundle` (Ruby 패키지용)
  - `dependency-check` (Java 패키지용)

## FAQ

설계 결정 근거(`PostToolUse` 대신 `PreToolUse`를 사용하는 이유, 서명이 검증되지 않는 이유, 스크립트와 shim이 중복되는 이유, 스킬 로딩 문제 등)는 [`FAQ.md`](https://github.com/robert-auger/safer-dependencies/blob/HEAD/FAQ.md)에 문서화되어 있습니다.