Guard your dependencies against supply chain attacks. **단일 정적 바이너리, Rust 크레이트 의존성 0개.**
제공: **[[arnica](https://arnica.io?utm_source=depsguard&utm_medium=referral&utm_campaign=community)]**
## 목차
- [개요](#overview)
- [설치](#install)
- [사용법](#usage)
- [검사 대상](#what-gets-checked)
- [구성 파일 위치](#config-file-locations)
- [긴급 보안 수정](#urgent-security-fix)
- [백업 및 복원](#backups-and-restore)
- [작동 방식](#how-it-works)
- [문제 해결](#troubleshooting)
- [도움말 및 피드백](#help--feedback)
- [가이드](#guides)
- [참고](#see-also)
- [라이선스](#license)
## 개요
DepsGuard는 시스템에서 **npm**, **pnpm**, **yarn**, **bun**, **uv**, **pip**, **poetry**, **aube**를 찾아 해당 구성 파일을 읽고 권장 공급망 설정과 비교한 후 **대화형으로 수정 사항을 적용**할 수 있습니다. 또한 저장소에서 **Renovate** 및 **Dependabot** 구성을 검사합니다. 패키지 설치를 실행하지 않으며, 승인한 구성 파일만 편집하고 변경 전에 **백업**을 만듭니다.
### 주요 기능
- 대화형 TUI: 검사, 검토, 수정 토글, 적용
- 읽기 전용 보고를 위한 `scan` 하위 명령
- 백업을 선택해 파일을 롤백하는 `restore` 하위 명령
- 크로스 플랫폼: Linux, macOS, Windows
- 타사 Rust 크레이트 번들 없음 (표준 라이브러리 + 터미널용 소량의 플랫폼 FFI)
### 기술 스택
| 영역 | 세부 정보 |
|------|---------|
| 언어 | Rust (MSRV **1.74**, `Cargo.toml` 참조) |
| CLI / TUI | `src/main.rs`, `src/ui.rs`, `src/term.rs` |
| 구성 로직 | `src/manager.rs`, `src/fix.rs` |
| 웹사이트 | `docs/` 아래 정적 사이트 (바이너리와 별도) |
## 설치
### 사전 빌드된 바이너리
각 [GitHub 릴리스](https://github.com/arnica/depsguard/releases)에는 다음 플랫폼용 아카이브가 포함됩니다:
- Linux: `x86_64` (glibc), `x86_64` (musl), `aarch64` (glibc)
- macOS: Intel 및 Apple Silicon
- Windows: `x86_64` ZIP (`depsguard.exe` 포함)
플랫폼에 맞는 아카이브를 다운로드하고 압축을 푼 다음 바이너리를 `PATH`에 추가하세요.
릴리스 페이지에서 각 자산 옆에 있는 해당 `.sha256` 파일을 사용하여 무결성을 검증하세요.
### 플랫폼별 설치
#### Linux (APT를 사용한 Debian/Ubuntu)```bash
sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://depsguard.com/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/depsguard.gpg
echo "deb [arch=amd64,arm64 signed-by=/etc/apt/keyrings/depsguard.gpg] https://depsguard.com/apt stable main" | sudo tee /etc/apt/sources.list.d/depsguard.list >/dev/null
sudo apt update
sudo apt install depsguard
조직에서 Homebrew, Scoop 또는 WinGet을 통해 DepsGuard를 배포한다면 해당 채널의 지침을 따르세요. 해당 채널의 설정 또는 자동화(Homebrew core PR, 버킷, WinGet PR, CI 시크릿)는 메인테이너용 문서이며, Release & distribution 아래의 AGENTS.md를 참조하세요.
실행 – depsguard를 실행하면 대화형 TUI가 시작됩니다. 시스템을 스캔하고 발견된 사항을 표로 보여줍니다. 아무 키나 누르면 수정 선택기로 진행합니다. 저장소 수준 설정 검색은 현재 디렉터리에서 시작하여 하위 디렉터리로 진행됩니다. 읽기 전용 보고서에는 depsguard scan을, 재귀적 파일 검색을 건너뛰고 사용자 수준 설정만 확인하려면 depsguard --no-search를 사용하세요.
참고: 일부 설정에는 최소 버전이 필요합니다. 버전이 너무 오래된 경우 다음 메시지가 표시됩니다:
ℹ min-release-age – requires npm ≥ 11.10 (have 10.2.0).
npm install -g npm@latest로 업그레이드한 후 다시 실행하세요.
이동 및 선택 – ↑↓로 목록을 탐색하고 (^u^d로 페이지 이동), Space를 눌러 수정 항목을 켜고 끕니다. 빠른 필터 키로 파일별 일괄 선택을 할 수 있습니다: a 전체, n .npmrc, u uv.toml 등 – 한 번 누르면 선택, 다시 누르면 선택 해제, 세 번째 누르면 필터가 초기화됩니다. f를 누르면 현재 선택된 수정 항목만 표시됩니다.
미리 보기 – d를 눌러 적용 전에 변경될 내용의 diff를 확인하세요.
적용 – Enter를 눌러 선택한 수정 사항을 적용합니다. 파일이 기록되기 전에 타임스탬프가 포함된 백업이 생성됩니다.
재스캔 – DepsGuard는 적용 후 자동으로 스캔을 다시 실행하므로 모든 것이 정상인지 확인할 수 있습니다.
복원 – 언제든지 depsguard restore를 실행하여 백업 목록에서 롤백할 수 있습니다. q 또는 Esc를 눌러 종료하세요.
검사 대상
매니저
설정 파일
설정 항목
대상 값
설명
npm
~/.npmrc
min-release-age
7 (일)
새로 출시된 릴리스를 지연시킵니다 (npm >= 11.10 필요)
npm/pnpm
~/.npmrc
ignore-scripts
true
설치 스크립트 위험을 줄입니다 (npm은 .npmrc에서 이 설정을 따르며, pnpm >= 11은 .npmrc가 아닌 pnpm-workspace.yaml / 전역 config.yaml에서 읽습니다)
pnpm
~/.npmrc
minimum-release-age
10080 (분)
새 버전을 7일간 지연시킵니다 (pnpm 10.16–10.x 전용, pnpm >= 11은 .npmrc를 무시하므로 pnpm-workspace.yaml을 사용하세요)
pnpm
전역 rc (pnpm <= 10)
minimum-release-age
10080 (분)
새 버전을 7일간 지연시킵니다 (pnpm >= 10.16 필요)
pnpm
전역 rc (pnpm <= 10)
block-exotic-subdeps
true
신뢰할 수 없는 전이적 의존성을 차단합니다 (pnpm >= 10.26 필요)
pnpm
전역 rc (pnpm <= 10)
trust-policy
no-downgrade
출처(provenance) 다운그레이드를 차단합니다 (pnpm >= 10.21 필요)
pnpm
전역 rc (pnpm <= 10)
strict-dep-builds
true
검토되지 않은 빌드 스크립트에서 실패 처리합니다 (pnpm >= 10.3 필요)
pnpm
전역 rc (pnpm <= 10)
ignore-scripts
true
악성 설치 스크립트를 차단합니다
pnpm
전역 config.yaml (pnpm >= 11)
minimumReleaseAge
10080 (분)
새 버전을 7일간 지연시킵니다
pnpm
전역 config.yaml (pnpm >= 11)
설정 파일 위치
매니저
Linux
macOS
Windows
npm/pnpm/aube
~/.npmrc
~/.npmrc
%USERPROFILE%\.npmrc
pnpm 전역 (pnpm <= 10)
$XDG_CONFIG_HOME/pnpm/rc 또는 ~/.config/pnpm/rc
$XDG_CONFIG_HOME/pnpm/rc 또는 ~/Library/Preferences/pnpm/rc
%LOCALAPPDATA%\pnpm\config\rc
pnpm 전역 (pnpm >= 11)
$XDG_CONFIG_HOME/pnpm/config.yaml 또는 ~/.config/pnpm/config.yaml
$XDG_CONFIG_HOME/pnpm/config.yaml 또는 ~/Library/Preferences/pnpm/config.yaml
%LOCALAPPDATA%\pnpm\config\config.yaml
yarn
~/.yarnrc.yml
~/.yarnrc.yml
%USERPROFILE%\.yarnrc.yml
pnpm
pnpm-workspace.yaml
pnpm-workspace.yaml
pnpm-workspace.yaml
bun
$XDG_CONFIG_HOME/.bunfig.toml 또는 ~/.bunfig.toml
$XDG_CONFIG_HOME/.bunfig.toml 또는 ~/.bunfig.toml
%USERPROFILE%\.bunfig.toml
uv
$XDG_CONFIG_HOME/uv/uv.toml 또는 ~/.config/uv/uv.toml
$XDG_CONFIG_HOME/uv/uv.toml 또는 ~/.config/uv/uv.toml
%APPDATA%\uv\uv.toml
pip
$XDG_CONFIG_HOME/pip/pip.conf 또는 ~/.config/pip/pip.conf
~/Library/Application Support/pip/pip.conf 또는 ~/.config/pip/pip.conf (설정된 경우 $XDG_CONFIG_HOME/pip/pip.conf)
%APPDATA%\pip\pip.ini
poetry
$XDG_CONFIG_HOME/pypoetry/config.toml 또는 ~/.config/pypoetry/config.toml
(설정된 경우) 또는
사용자 수준 설정 파일은 표준 위치(도구가 지원하는 경우 XDG 기반 경로 포함)에서 읽습니다. 저장소 수준 설정은 현재 디렉터리에서 시작하여 하위 디렉터리로 검색되며, 알려진 대용량 디렉터리(node_modules, .git, target, Library, .cache 등)는 건너뛰어 스캔 속도를 유지합니다. 저장소 수준의 .npmrc, .yarnrc.yml, pnpm-workspace.yaml, Renovate 설정, Dependabot 설정이 모두 검색됩니다. pnpm 설정은 ~/.npmrc(pnpm <= 10 전용, pnpm >= 11은 .npmrc에서 인증/레지스트리 설정만 읽음), pnpm 전역 설정 파일(pnpm <= 10의 rc, pnpm >= 11의 config.yaml), 또는 pnpm-workspace.yaml에 위치할 수 있으며, DepsGuard는 세 위치를 모두 독립적으로 확인합니다. pip, uv, poetry의 경우 DepsGuard는 단일 유효 사용자 수준 설정을 찾아 해당 파일만 보고하며, 가려진(shadowed) 파일을 별도로 표시하지 않습니다. pip와 poetry는 우선순위에 따라 설정 파일을 병합합니다. 즉, 쿨다운을 설정한 최우선순위 파일이 적용되며, 그런 파일이 없으면 선호 위치가 사용됩니다. uv는 두 파일을 병합하는 대신 단일 사용자 파일(XDG_CONFIG_HOME이 설정된 경우 $XDG_CONFIG_HOME/uv/uv.toml, 그렇지 않으면 ~/.config/uv/uv.toml)을 읽습니다. bun의 경우 사용자 수준 설정 파일이 여러 개 존재하면(예: XDG 경로와 홈 디렉터리 경로), DepsGuard는 존재하는 각 파일을 개별적으로 스캔합니다. aube는 npm/pnpm과 동일한 ~/.npmrc(minimumReleaseAge, 분 단위)를 읽으며, 발견된 저장소 수준 .npmrc 파일도 확인합니다. pip와 poetry는 사용자 수준 설정(pip.conf / pypoetry/config.toml)에서 스캔됩니다.
긴급 보안 수정
패치된 버전이 쿨다운 기간보다 더 최신인 경우, 좁은 범위의 예외를 추가하고 수정 사항을 설치한 다음 예외를 제거하세요.
전역 쿨다운을 낮추는 것보다 패키지별 예외를 사용하는 것이 좋습니다. 이렇게 하면 다른 모든 의존성에는 지연이 유지됩니다.
매니저
쿨다운을 우회하는 방법
npm
npm install <pkg>@<ver> --min-release-age=0
pnpm
pnpm-workspace.yaml의 minimumReleaseAgeExclude에 항목을 추가하고 pnpm add <pkg>@<ver>를 실행한 다음 항목을 제거하세요. 패키지 이름으로 제외하는 것은 pnpm 10.16+에서 작동하며, 특정 버전(<pkg>@<ver>)을 고정하려면 추가로 pnpm 10.19+가 필요합니다. pnpm에는 minimumReleaseAge에 대한 문서화된 CLI 재정의가 없습니다.
yarn
.yarnrc.yml의 npmPreapprovedPackages에 <pkg>(또는 glob)을 추가하거나, 한 번의 명령으로 YARN_NPM_MINIMAL_AGE_GATE=0s yarn up <pkg>@<ver>를 실행하세요. npmPreapprovedPackages는 연령 게이트(age gate)뿐만 아니라 모든 Yarn 패키지 게이트에서 일치하는 항목을 면제합니다.
bun
저장소 수준의 bunfig.toml 또는 사용자 수준의 ~/.bunfig.toml에 있는 install.minimumReleaseAgeExcludes에 <pkg>를 추가하거나, bun add <pkg>@<ver> --minimum-release-age 0를 실행하세요.
aube
.npmrc의 minimumReleaseAgeExclude에 <pkg>를 추가하거나, 단일 설치를 위해 AUBE_MINIMUM_RELEASE_AGE=0(또는 npm_config_minimum_release_age=0)를 설정하세요.
uv
uv.toml 또는 pyproject.toml의 exclude-newer-package에 "<pkg>" = false를 추가하고 uv add <pkg>==<ver>를 실행한 다음 항목을 제거하세요. exclude-newer-package는 전역 exclude-newer 기준에 대한 별도의 패키지별 재정의입니다. uv의 CLI는 --exclude-newer-package PACKAGE=DATE는 허용하지만 PACKAGE=false는 허용하지 않습니다.
pip
단일 설치를 위해 pip install <pkg>==<ver> --uploaded-prior-to=P0D를 실행하세요. P0D는 해당 명령에서만 쿨다운을 비활성화합니다. pip는 설정에 패키지별 제외 기능이 없습니다.
poetry
poetry.toml/config.toml의 solver.min-release-age-exclude(쉼표로 구분)에 <pkg>를 추가하고 poetry add <pkg>@<ver>를 실행한 다음 항목을 제거하세요. solver.min-release-age-exclude-source는 대신 지정된 인덱스의 모든 패키지를 면제합니다.
쿨다운을 우회하기 전에:
CVE가 실제로 사용 환경에 영향을 미치는지 확인하세요.
정상 동작이 확인된 이전 버전이 이미 사용 가능한지 확인하세요. 롤백이 더 안전할 수 있습니다.
업그레이드 후 임시 예외를 제거하세요.
백업 및 복원
DepsGuard는 파일을 수정하기 전에 ~/.depsguard/backups/에 백업을 작성합니다.
depsguard restore를 실행하면 백업 목록을 확인하고 하나를 복원할 수 있습니다.
- **타사 크레이트 없음**: 보안 관련 소규모 도구를 위한 의도적인 선택입니다. 해당 정책을 변경하려면 `AGENTS.md`를 참조하세요.
- **색상**은 ANSI 시퀀스를 사용합니다. Windows의 최신 터미널(예: Windows Terminal)이 지원됩니다.
## 문제 해결
| 증상 | 시도할 방법 |
|---------|-------------|
| `depsguard: command not found` | 설치 디렉터리가 `PATH`에 있는지 확인하거나 바이너리의 전체 경로를 사용하세요. |
| 설정 쓰기 중 권한 오류 | DepsGuard는 사용자 프로필의 파일만 편집합니다. 해당 파일이 관리자 소유가 아닌 경우 관리자 권한 없이 일반 사용자로 실행하세요. |
| Windows에서 키가 작동하지 않음 | **Windows Terminal** 또는 VT를 지원하는 다른 터미널을 사용하세요. 레거시 `cmd.exe`는 모든 키를 처리하지 못할 수 있습니다. |
| pnpm 워크스페이스 누락 | `pnpm-workspace.yaml`이 홈 디렉터리 트리 아래에 있는지 확인하세요. 매우 특이한 레이아웃은 발견되지 않을 수 있습니다. |
| `cargo install` 실패 | [rustup](https://rustup.rs/)을 통해 Rust를 설치하고 Rust **≥ 1.74**를 사용하세요. |
## 도움말 및 피드백
- [버그 신고 또는 기능 요청](https://github.com/arnica/depsguard/issues)
- [보안 취약점 신고](https://github.com/arnica/depsguard/security/advisories/new) (참조: [`SECURITY.md`](https://github.com/arnica/depsguard/blob/main/SECURITY.md))
- 기여자를 위한 개발 워크플로는 [`AGENTS.md`](https://github.com/arnica/depsguard/blob/main/AGENTS.md)에 있습니다.
## 가이드
[depsguard.com](https://depsguard.com)의 심층 가이드는 각 강화 설정과 해당 설정이 방어하는 공급망 공격을 설명합니다:
- [npm 공급망 공격으로부터 보호하는 방법](https://depsguard.com/guide/) (전체 강화 가이드)
- [의존성 쿨다운 (최소 릴리스 연령)](https://depsguard.com/cooldown/)
- [ignore-scripts로 설치 스크립트 차단](https://depsguard.com/ignore-scripts/)
- [신뢰할 수 없는 전이 의존성 차단 (block-exotic-subdeps)](https://depsguard.com/block-exotic-subdeps/)
- [검토되지 않은 빌드 스크립트에서 실패 (strict-dep-builds)](https://depsguard.com/strict-dep-builds/)
- [출처(provenance) 다운그레이드 차단 (trust-policy)](https://depsguard.com/trust-policy/)
- 사고 분석 글: [axios](https://depsguard.com/axios-npm-attack/) · [Shai-Hulud](https://depsguard.com/shai-hulud/) · [TanStack](https://depsguard.com/tanstack-npm-attack/)
## 함께 보기
- [**Dependency Cooldowns** (`cooldowns.dev`)](https://cooldowns.dev/): **최소 릴리스 연령 쿨다운**에 특화된 참조 가이드 및 동반 셸 도우미(`cooldowns.sh`)입니다. DepsGuard를 보완합니다. 쿨다운 축에서 더 넓은 생태계(pip, uv, npm, pnpm, Yarn, Bun, Deno, Cargo)를 다루는 반면, DepsGuard는 npm/pnpm/yarn/bun/aube/uv/pip/poetry와 Renovate/Dependabot을 다루고 대화형 TUI, diff 미리보기, 백업/복원과 함께 다른 강화 설정(`ignore-scripts`, `block-exotic-subdeps`, `trust-policy`, `strict-dep-builds`)을 추가로 제공합니다.
## 라이선스
MIT
---
**링크:** [저장소](https://github.com/arnica/depsguard) · [문서 사이트](https://depsguard.com)
arnica/depsguard
```text
_ _
| | ___ _ __ ___ __ _ _ _ __ _ _ __ | |
/ 