deptrust

     __           __                  __
 ___/ /___  ___  / /________  _______/ /_
/ _  / __ \/ _ \/ __/ ___/ / / / ___/ __/
...

deptrust는 npm, PyPI, crates.io, Go modules, RubyGems, NuGet, Maven, Packagist, pub.dev, CocoaPods, Hex.pm, Hackage, GitHub Actions 등 다양한 패키지 레지스트리의 버전별 알려진 취약점을 확인하는 CLI 도구입니다.

이 도구는 로컬에서 CLI 및 MCP 서버로 실행됩니다. 공개 패키지 레지스트리 및 OSV API를 직접 호출하며, 신뢰하거나 설정해야 하는 호스팅된 deptrust 서비스는 없습니다.

이 도구는 AI 에이전트가 지속적으로 오래된 버전을 사용하는 데서 오는 불편함에서 탄생했습니다.

목차

• Scope
• CLI 사용법
• 설치
• 에이전트 설정
• 수동 MCP 설정
• MCP 도구
• Skill 전용 사용
• 문제 해결

Scope

지원하는 생태계:

• npm (예: @clidey/ux와 같은 스코프드 패키지 포함)
• PyPI
• Cargo / crates.io
• Go modules
• RubyGems
• NuGet
• Maven (groupId:artifactId 패키지 이름 사용)
• Packagist / Composer (vendor/package 패키지 이름 사용)
• pub.dev
• CocoaPods
• Hex.pm
• Hackage
• GitHub Actions (버전으로 owner/repo 패키지 이름 및 태그, 브랜치 참조 또는 커밋 SHA 사용)

deptrust는 현재 알려진 취약점을 보고하고 간단한 권장 사항을 제공합니다:

deptrust는 또한 CVE가 아닌 위험 신호(risk signals)도 방출합니다. 예를 들어, 지난 72시간 이내에 게시된 버전은 에이전트가 새로운 릴리스를 무분별하게 설치하는 것을 막기 위해 검토 대상으로 표시됩니다.

권고 제공업체는 병렬로 조회됩니다:

• OSV
• GitHub Advisory Database (검토된 권고 및 악성코드 권고 포함)

Provider coverage는 생태계(ecosystem)별로 다릅니다. 만약 deptrust가 레지스트리 메타데이터를 해결할 수 있지만, 구성된 취약점 제공자(vulnerability provider) 중 해당 생태계를 지원하는 것이 없다면, 패키지를 안전하다고 처리하기보다는 unknown을 반환합니다.

Provider coverage:

• checked_providers: deptrust가 실제로 조회한 취약점 제공자 목록
• skipped_providers: 생태계가 지원되지 않아 건너뛴 구성된 제공자 목록
• advisory_coverage: full, partial, none, 또는 error 중 하나
• advisory_coverage_reason: 커버리지 값에 대한 간략한 설명
• registry_verification: 레지스트리 메타데이터가 버전을 확인했을 때 verified, 또는 일시적인 레지스트리 실패 후 정확한 버전 확인을 계속했을 때 unverified를 반환합니다.
• registry_verification_reason: 검증이 불가능했을 때의 레지스트리 오류

정확한 버전 확인(exact-version check)은 레지스트리 검증이 일시적으로 불가능할 때도 여전히 취약점 제공자들을 조회합니다. 이 결과는 항상 설치 불가능하며(non-installable), allow 권장 사항을 절대 받지 못합니다. latest, 알 수 없는 패키지, 그리고 명백히 존재하지 않는 버전에 대한 확인은 여전히 성공적인 레지스트리 해결(registry resolution)을 필요로 합니다.

HTTP 요청은 429, 502, 503, 및 504 응답에 대해 최대 세 번의 총 시도 횟수까지 재시도합니다. 재시도는 짧은 지수 백오프(exponential delays)를 사용하며, 최대 2초까지 Retry-After 값을 준수합니다. 서버가 요청한 더 긴 대기 시간은 빠르게 실패하여 CLI가 멈추는 것을 방지합니다. 취약점 제공자 재시도가 모두 소진되면 결과가 불완전해지고 allow 권장 사항을 받을 수 없습니다.

GitHub API 인증

GitHub Advisory Database 및 GitHub Actions API 요청에는 짧은 기간 동안 유효하며 최소 권한(least-privilege)의 GitHub App 토큰을 사용할 수 있습니다. CI 환경에서는 이를 DEPTRUST_GITHUB_TOKEN을 통해 전달하십시오:

DEPTRUST_GITHUB_TOKEN="$GITHUB_APP_TOKEN" deptrust check npm lodash 4.17.20

자격 증명(credential)의 우선순위는 DEPTRUST_GITHUB_TOKEN, GITHUB_TOKEN, 그리고 GH_TOKEN 순서입니다. 로컬 사용을 위해 선택적 GitHub CLI 대체 기능은 DEPTRUST_GITHUB_AUTH=gh deptrust check ...로 명시적으로 활성화할 수 있으며, 이 경우 프롬프트 없이 gh auth token을 실행합니다. 자격 증명이 없으면 DepTrust는 인증되지 않은 상태로 계속 진행됩니다. GitHub API의 속도 제한(rate-limit) 또는 권한 실패는 진단 정보와 함께 unknown으로 반환되며, OSV만 성공으로 간주되는 경우는 절대 아닙니다.

DepTrust는 GitHub 토큰을 저장하거나, 번들링하거나, 캐시하거나, 로깅하거나, 원격 측정(telemeters)하거나, 방출하지 않습니다. 인증 헤더는 오직 https://api.github.com으로만 전송됩니다.

CLI 사용법

정확한 버전을 확인하는 방법:

deptrust check npm lodash 4.17.20

일반 응답 예시:

npm [email protected]: 2 known vulnerabilities found
recommendation: block
risk_score: 80

최신 버전을 확인하는 방법:

deptrust check pypi requests latest

JSON 반환:

deptrust check --json cargo serde latest

Go 모듈을 확인하는 방법:

deptrust check go golang.org/x/crypto latest

RubyGems, NuGet 또는 Maven을 확인하는 방법:

deptrust check rubygems rails latest
deptrust check nuget Newtonsoft.Json latest
deptrust check maven org.apache.logging.log4j:log4j-core latest

Packagist, pub.dev, CocoaPods, Hex.pm, Hackage 또는 GitHub Actions를 확인하는 방법:

deptrust check packagist monolog/monolog latest
deptrust check pub http latest
deptrust check cocoapods AFNetworking latest
...

GitHub Actions의 경우, 전체 커밋 SHA는 고정된(pinned) 것으로 간주됩니다. v4.2.2와 같은 완전한 semver 태그는 추가적인 고정 신호 없이도 허용됩니다. v4와 같은 메이저 전용 태그나 main과 같은 브랜치 참조(branch refs)는 유효한 참조이지만, 이동할 수 있기 때문에 deptrust는 검토 신호를 추가합니다.

JSON 응답 예시:

{
  "ecosystem": "npm",
  "package": "lodash",
...
}

알려진 취약점이 없을 때만 최신 버전을 제안하는 방법:

deptrust suggest npm lodash

최신 버전 사용이 허용되지 않는 경우, suggest는 이전의 알려진 버전을 확인하고 allow 권장 사항과 함께 가장 최신 버전을 반환합니다.

어드바이저리(advisories)에 수정된 버전이 포함되어 있는 경우, suggest는 레지스트리 버전 목록을 역추적하기 전에 해당 제공업체에서 보고한 수정된 버전을 먼저 확인합니다.

두 버전을 비교하는 방법:

deptrust compare npm lodash 4.17.20 4.17.21

비교 응답 예시:

lodash 4.17.20 -> 4.17.21 improves risk: score 80 to 0.
recommendation: allow
next_action: upgrade_to_target

설치된 버전을 확인하는 방법:

deptrust version

설치 (Install)

가장 쉬운 설치 경로는 npx 또는 pnpx입니다:

npx @clidey/deptrust install
pnpx @clidey/deptrust@latest install

기본 설치 프로그램은 안내(guided) 방식으로 진행됩니다. 바이너리를 설치하고, 어떤 에이전트 통합을 구성할지 묻고, 아무것도 변경하기 전에 사용자 레벨의 대상(destinations)을 출력하며, 확인을 요청합니다. 안내 설치 프로그램은 기본적으로 MCP, 스킬 폴백(skill fallback), Codex 및 Claude Code용 의존성 안전 후크를 활성화합니다. 비대화형 바이너리 전용 설치를 하려면 --yes를 추가하거나 명시적인 통합 플래그를 전달하십시오.

설치 프로그램을 다시 실행하는 것은 안전합니다. MCP, 스킬, 후크 구성은 변경되지 않은 채 조용히 유지됩니다. 만약 어떤 통합이 오래된 deptrust 바이너리를 가리키거나 관리되는 구성이 변경되었다면, 설치 프로그램이 자동으로 업데이트합니다. 사용자는 MCP 서버를 수동으로 제거하고 다시 추가할 필요가 없습니다. 사용자 정의 스킬은 교체 전에 백업됩니다.

사용자 레벨의 바이너리, 스킬 및 MCP 항목을 제거하려면:

npx @clidey/deptrust uninstall
pnpx @clidey/deptrust@latest uninstall

Homebrew 사용자는 Clidey tap에서 설치할 수 있습니다:

brew install clidey/tap/deptrust

또는 먼저 tap을 추가한 다음, 평소처럼 설치 및 업그레이드를 수행합니다:

brew tap clidey/tap
brew install deptrust
brew upgrade deptrust

Homebrew는 설치 후 알림을 표시합니다. Homebrew 바이너리 자체를 사용하여 안내되는 Codex 및 Claude Code 설정을 실행하려면 (MCP 등록 및 의존성 안전 후크):

deptrust setup

이 안내 설정은 MCP와 의존성 안전 후크 활성화 여부를 묻습니다. 현재 바이너리를 이미 사용하는 등록만 남기고, 이전 npm, Homebrew 또는 소스 설치 경로를 가리키는 기존 DepTrust 등록을 조정합니다.

Go 사용자는 직접 설치할 수 있습니다:

go install github.com/clidey/deptrust/cmd/deptrust@latest

Nix

이 프로젝트는 이미 Nix를 사용하는 사용자를 위해 선택적 Nix flake 출력을 제공합니다. 이 flake는 사전 빌드된 릴리스 바이너리를 감쌉니다.

# 설치 없이 실행하기
nix run github:clidey/deptrust

...

일반 릴리스 워크플로우는 게시하는 아카이브와 동일한 곳에서 Nix 해시를 생성하고, 게시 전에 flake를 평가하며, 기본 브랜치를 업데이트하기 전에 이를 빌드하고 실행합니다. github:clidey/deptrust는 해당 워크플로우가 실행되는 동안 잠시 지연될 수 있습니다. 릴리스 태그는 생성된 flake 업데이트 이전의 소스 커밋을 가리키며 여전히 이전 바이너리를 참조할 수 있으므로, 재현성이 중요할 때는 flake.nix에 필요한 버전을 포함하는 커밋을 고정(pin)하세요.

Devbox

재현 가능한 개발 환경을 위해 Devbox를 사용하세요:

# Devbox가 이미 설치되어 있지 않다면 먼저 설치합니다
curl -fsSL https://get.jetify.dev/devbox | bash

...

devbox.json은 툴체인 버전으로 제약하며, 커밋된 devbox.lock은 정확한 패키지 버전과 nixpkgs 리비전을 고정합니다. 이러한 고정을 의도적으로 새로고침하려면 devbox update를 실행하세요.

또는 Homebrew를 통해 Devbox를 설치할 수 있습니다:

brew install jetify-com/devbox/devbox

에이전트 설정 (Agent Setup)

deptrust를 설치하고 안내 프롬프트 없이 설치 프로그램이 구성할 수 있는 모든 것을 등록하려면:

npx @clidey/deptrust install --all
pnpx @clidey/deptrust@latest install --all

옵션 --all은 바이너리를 설치하고, codex CLI가 사용 가능한 경우 Codex MCP를 등록하며, Codex 스킬 폴백을 설치하고, claude CLI가 사용 가능한 경우 Claude Code MCP를 등록하며, Codex와 Claude Code의 의존성 안전 후크(dependency safety hooks)를 설치합니다.

이후에 설명하는 후크는 PreToolUse 후크입니다. 이들은 패키지 설치 명령이 실행되기 전에 확인하고, 에이전트 파일 편집 도구를 통해 워크플로우 파일에 추가된 GitHub Actions도 확인합니다. 후크는 deptrust가 review, block, 또는 unknown을 반환할 때 도구 호출을 차단합니다. 설치 프로그램은 사용자 레벨의 후크 설정만 작성합니다: Codex의 경우 ~/.codex/hooks.json에, Claude Code의 경우 ~/.claude/settings.json에 기록됩니다.

gh CLI가 사용 가능한 경우, 안내 설정(guided setup)은 후크 검사를 위해 기존 로컬 로그인을 사용하는 것도 제공합니다. 이는 오직 DEPTRUST_GITHUB_AUTH=gh만 작성하며 GitHub 토큰을 절대 저장하지 않기 때문에, 후크 서브프로세스가 인증되지 않은 GitHub API 속도 제한에 걸리는 것을 방지할 수 있습니다.

선호하는 경우 더 좁은 범위의 설치를 사용하세요:

npx @clidey/deptrust install --codex-mcp
npx @clidey/deptrust install --claude-code-mcp
npx @clidey/deptrust skills install
...

MCP 설정 후, 에이전트는 업데이트나 변경 사항을 추천하기 전에 패키지를 자동으로 확인합니다. MCP 서버는

많은 클라이언트들이 다음 JSON 형태를 사용합니다:

{
  "mcpServers": {
    "deptrust": {
...

Codex의 경우, 다음 명령어로 추가할 수도 있습니다:

codex mcp add deptrust -- /absolute/path/to/deptrust mcp

Claude Code의 경우:

claude mcp add --transport stdio deptrust -- /absolute/path/to/deptrust mcp

initialize 시, 서버는 에이전트에게 언제 이 도구들을 사용해야 하는지 알려주는 MCP instructions를 반환합니다 (의존성을 추가하거나, 업데이트하거나, 추천하기 전, 또는 버전 업데이트가 안전한지 문의할 때). 서버 지침을 표시하는 클라이언트들은 이를 자동으로 적용하므로, 위의 수동 알림은 필수라기보다는 선택 사항입니다.

MCP 도구

check_package

패키지 버전을 확인하고 알려진 취약점과 추천 사항을 반환합니다.

{
  "ecosystem": "npm",
  "package": "lodash",
...