dependency-vulnerability-fix

---
name: dependency-vulnerability-fix
description: pip-audit 발견 취약점 안전 fix 패턴 — vLLM/PyTorch 같은 큰 의존성 깨지지 않게 patch 버전만 안전 업그레이드. 사용 시점 — "pip-audit", "CVE", "취약점 패치", "aiohttp 업그레이드", "cryptography CVE", "의존성 취약점", "supply chain". 4단계 (스캔 → 분류 → 안전 업그레이드 → 회귀 검증).
license: MIT
---

# dependency-vulnerability-fix

Python 프로젝트의 의존성 취약점(CVE)을 **안전하게 fix하는 4단계 패턴**.
GEM-LLM `vllm-env` 27 vulnerabilities fix 작업에서 도출 — vLLM/PyTorch처럼 큰 의존성을 깨뜨리지 않으면서 patch 단위만 정밀 업그레이드한다.

## 1. 사용 시점 (트리거)

- `pip-audit` 출력에서 CVE 또는 GHSA-* ID 발견
- "aiohttp 업그레이드", "cryptography CVE", "pillow CVE"
- supply chain 보안 검사, 정기 audit
- Dependabot / Renovate PR 검토
- GPU 환경(vLLM, torch, onnx) — CUDA 호환 깨질까 걱정될 때
- 회귀 없이 의존성을 갱신하고 싶을 때

핵심 원칙: **큰 의존성(vLLM, PyTorch, transformers)은 절대 메이저/마이너 단위로 건드리지 않는다.** patch 버전만 골라 흡수하고, 깨지면 즉시 롤백한다.

## 2. 4단계 워크플로

### Step 1: 스캔

```bash
pip install pip-audit
pip-audit --format columns
```

출력 컬럼: `Name`, `Version`, `ID`, `Fix Versions`, `Description`.

옵션:
- `pip-audit -r requirements.txt` — 파일 기반
- `pip-audit --format json > audit.json` — 자동화/diff용
- `pip-audit --ignore-vuln GHSA-xxxx` — 알려진 false positive 제외
- `pip-audit --strict` — 1개라도 있으면 exit 1 (CI용)

가상환경(특히 vllm-env)에서 실행해야 실제 깔린 버전을 본다. 시스템 python으로 돌리면 무관한 글로벌 패키지가 섞인다.

### Step 2: 분류

| 종류 | 예시 | 위험 |
|---|---|---|
| **patch** (3.13.3 → 3.13.4) | aiohttp, cryptography hot-fix | 거의 안전 (semver patch) |
| **minor** (3.13 → 3.14) | API 추가, 일부 deprecation | 호환성 주의 — 변경 로그 확인 |
| **major** (3 → 4) | breaking change | 별도 마이그레이션 작업 |
| **transitive** | vllm → mistral_common → jinja2 | 직접 핀 후 검증 |

판정 기준:
1. **Fix Versions** 컬럼이 patch만 올리면 끝나는지 본다.
2. patch 안에 fix가 있으면 **즉시 그 버전 핀**.
3. minor 이상 올려야 fix가 있으면 → 큰 의존성 호환 매트릭스부터 본다.
4. transitive는 직접 의존성에 핀 한 줄 추가하는 방식이 가장 안전.

### Step 3: 안전 업그레이드

```bash
# 단일 패키지 — patch range 만 허용
pip install --upgrade 'aiohttp>=3.13.4,<3.14'

# 여러 패키지 한 번에
pip install --upgrade \
  'aiohttp>=3.13.4,<3.14' \
  'cryptography>=46.0.7,<47' \
  'pillow>=11.3.1,<12'

# transitive deps는 cascade 막아야 한다
pip install --upgrade --upgrade-strategy only-if-needed \
  'jinja2>=3.1.6'
```

핵심:
- `<next-minor` 상한선을 항상 건다 — 다음 pip resolve가 minor를 끌어올리는 사고 방지.
- `--upgrade-strategy only-if-needed`로 deps cascade를 막는다 (기본값 `eager`는 deps도 다 올린다).
- vLLM/torch/onnx 같은 GPU 패키지는 **이 명령에 같이 넣지 않는다**.
- 작업 직전에 `pip freeze > /tmp/before.txt`로 스냅샷 — 롤백 기준점.

업그레이드 후 즉시:
```bash
pip-audit --format columns          # 줄어든 vuln 수 확인
pip freeze > /tmp/after.txt
diff /tmp/before.txt /tmp/after.txt  # 의도한 패키지만 변경됐는지
```

### Step 4: 회귀 검증

```bash
# 단위 테스트
pytest tests/unit -q

# 통합 테스트 (FastAPI + DB + 외부 mock)
pytest tests/integration -q

# 부하 테스트 (선택, GPU 워크로드)
locust -f load/test.py --headless -u 50 -r 5 -t 2m
```

검증 통과 기준:
- 단위 테스트 100% green
- 통합 테스트 100% green (system ALL GREEN)
- 응답 latency p95 회귀 없음 (±10% 이내)
- vLLM/torch import 정상 (`python -c "import vllm; import torch"`)

깨지면 즉시 롤백:
```bash
pip install 'aiohttp==3.13.3'   # 직전 버전으로 복귀
# 또는
pip install -r /tmp/before.txt --force-reinstall
```

## 3. 큰 의존성(vLLM/PyTorch) 보호

GPU 스택은 의존성 행렬이 빡빡해서 단순 `pip install --upgrade vllm`은 거의 항상 사고를 낸다.

규칙:
- **vLLM 0.x.y의 호환 매트릭스**(transformers / mistral_common / xformers / torch)를 release notes에서 먼저 확인.
- transformers, mistral_common, tokenizers는 vllm과 함께 묶어서만 갱신.
- onnx, torch, torchvision은 CUDA major 버전(12.x → 12.y)이 같은지 확인 후만 patch.
- 갱신 직후 `python -c "import vllm; vllm.__version__"` + 1회 추론 호출까지 끝나야 commit.
- `pip check` 한 번 더 돌려서 dep 충돌 없는지.

```bash
# 안전 — 같은 vllm major.minor 안에서만
pip install --upgrade 'vllm>=0.19.1,<0.20'

# 위험 — 다른 vllm minor로 점프
pip install --upgrade vllm   # transformers/torch 동시에 끌려옴 → CUDA 깨짐
```

## 4. CVE 우선순위

| Severity | SLA | 행동 |
|---|---|---|
| Critical (CVSS 9.0+) | 24h | 즉시 patch + hotfix 배포 |
| High (7.0–8.9) | 72h | 다음 daily release |
| Medium (4.0–6.9) | 다음 release cycle | 정기 audit에 포함 |
| Low (<4.0) | 분기별 | 누적해서 한 번에 |

기준: 공격 표면(외부 입력에 닿는지) + 영향(RCE/DoS/info leak) + exploit 가용성.

`pip-audit` 자체는 CVSS를 보여주지 않으므로 ID로 NVD/OSV.dev에 별도 조회.

## 5. 자동화

### CI에 pip-audit 추가

```yaml
# .github/workflows/audit.yml
name: pip-audit
on:
  schedule: [{cron: "0 9 * * 1"}]   # 매주 월요일
  push:
    paths: ["requirements*.txt", "pyproject.toml"]
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: {python-version: "3.11"}
      - run: pip install pip-audit
      - run: pip-audit -r requirements.txt --strict
```

### Dependabot vs Renovate

- **Dependabot**: GitHub 네이티브, PR 단위 fix 자동 — patch 단위 grouping 약함.
- **Renovate**: 그룹화 강력 (`groupName: "patch updates"`), 큰 의존성 따로 분리 가능 — 권장.

### 정기 audit 보고

```bash
pip-audit --format json | jq '[.dependencies[] | select(.vulns | length > 0)] | length'
# 매주 이 숫자를 README/Slack에 게시 → 추세 추적
```

## 6. 흔한 함정

1. **`pip install --upgrade <pkg>`이 deps cascade**
   기본값 `--upgrade-strategy eager`라 의도하지 않은 transitive까지 다 올라간다. 항상 `only-if-needed` 명시.

2. **transitive deps만 변경됐는데 회귀 발생**
   `pip freeze` diff를 무시하고 commit하면 다음 빌드에서 다른 환경이 된다. 핀을 직접 의존성에 박거나 lock 파일을 갱신.

3. **vLLM/torch 동시 업그레이드 → CUDA 호환 깨짐**
   `import torch; torch.cuda.is_available()`가 False로 떨어져도 import는 성공해서 CI에서 잡히지 않는다. GPU 머신에서 1회 추론까지 통과시켜야 한다.

4. **pyproject.toml과 lock 파일 불일치**
   `pip install`만 하고 `pyproject.toml`/`requirements.lock`을 같이 갱신 안 하면 다음 환경 빌드에서 옛 버전으로 회귀. 반드시 같은 PR에서.

5. **requirements.txt가 stale**
   `>=` 핀 없이 `==X.Y.Z`만 쓰면 patch CVE도 자동으로 못 받는다. 반대로 핀이 너무 헐거우면 재현 불가. 권장: `>=patch,<next-minor`.

6. **가상환경 헷갈림**
   시스템 python에서 audit 돌리고 vllm-env에서 fix하면 fix 안 한 게 된다. `which python`, `which pip-audit`로 확인.

## 7. GEM-LLM 사례 (검증)

벤치마크: vllm-env의 27 vulnerabilities를 안전 fix.

| 패키지 | 변경 | 효과 |
|---|---|---|
| aiohttp | 3.13.3 → 3.13.4 | CVE 10건 해소 (request smuggling, header parse) |
| cryptography | 46.0.5 → 46.0.7 | CVE 2건 (OpenSSL 백엔드) |
| pillow | 11.x → 11.3.1 | image parse CVE 3건 |
| jinja2 | (transitive) 3.1.5 → 3.1.6 | sandbox escape |
| vLLM | 손대지 않음 | 0.19.1 호환 유지 |
| torch | 손대지 않음 | CUDA 12.x 매트릭스 보존 |

검증 결과:
- 회귀 테스트 219/219 통과 (`pytest-fastapi-pattern` 슈트)
- `import vllm; import torch; torch.cuda.is_available()` → True
- 시스템 ALL GREEN, 다운타임 0
- 부하 테스트 50동접 latency 회귀 없음
- 작업 시간: scan 5분 + 분류 15분 + upgrade 5분 + verify 30분

## 8. 체크리스트

- [ ] `pip-audit` 출력 캡처 (before)
- [ ] 각 항목을 patch / minor / major / transitive로 분류
- [ ] patch 항목만 `>=fix,<next-minor` 핀
- [ ] vLLM/torch는 별도 PR 또는 손대지 않음
- [ ] `pip freeze` diff로 의도한 패키지만 변경 확인
- [ ] 단위 + 통합 테스트 100% green
- [ ] GPU 머신에서 1회 추론 통과
- [ ] `pip-audit` 재실행 → 줄어든 수 확인 (after)
- [ ] `requirements.txt` / `pyproject.toml` 갱신 같은 PR에서
- [ ] 깨지면 즉시 `pip install <old>` 롤백 가능 상태 유지

## 같이 보면 좋은 skill

- `vllm-bootstrap` — vLLM 의존성 매트릭스 / 부팅 실패 패턴
- `gem-llm-vllm-debug` — vLLM 의존성 버전 충돌 디버깅
- `pytest-fastapi-pattern` — 회귀 검증용 219 테스트 슈트 패턴
- `deployment-checklist` — 배포 전 보안/모니터링 체크리스트