safe-npm

보안에 중점을 둔 npm 설치 도구로, 새로 손상된 패키지로부터 프로젝트를 보호합니다.

왜 존재하는가?

npm 패키지에 대한 공급망 공격은 증가하는 위협입니다. 공격자는 때때로 합법적인 패키지를 손상시킵니다:

• 관리자 자격 증명 도용
• 인기 패키지에 악성 업데이트 게시
• 버려진 패키지 인수

이러한 공격은 종종 갑작스럽게 발생합니다. 어제는 안전했던 패키지가 오늘 손상될 수 있습니다. safe-npm은 최소 기간(기본 90일) 동안 공개적으로 사용 가능했던 패키지 버전만 설치하여 사용자를 보호합니다. 이는 보안 커뮤니티가 악성 릴리스를 발견하고 보고할 시간을 제공하여 프로젝트에 도달하기 전에 차단합니다.

작동 방식

safe-npm install을 실행하면 다음을 수행합니다:

1. package.json 또는 명령줄 인수에서 종속성을 읽습니다
2. npm 레지스트리를 조회하여 사용 가능한 모든 버전을 찾습니다
3. 최소 연령 임계값보다 최근에 게시된 버전을 필터링합니다
4. semver 요구 사항과 연령 요구 사항을 모두 충족하는 최신 버전을 선택합니다
5. npm을 사용하여 안전한 버전을 설치합니다

예를 들어 react@^18을 지정하고 어제 악성 [email protected]이 게시된 경우, safe-npm은 대신 최소 90일 된 최신 버전을 설치합니다.

설치

npm에서 설치 (권장)

# Install globally
npm install -g @dendronhq/safe-npm

# Now you can use it anywhere
safe-npm install

소스에서 빌드

# Clone and build
git clone <repository-url>
cd safe-npm
npm install
npm run build

# Link the binary globally
npm link

기본 사용법

package.json에서 종속성 설치

# Use the minimum age of 90 days (default)
safe-npm install

# Or specify your own minimum age
safe-npm install --min-age-days 120

특정 패키지 설치

# Install packages directly with version constraints
safe-npm install react@^18 lodash@^4.17.0

# These will be filtered to only use versions at least 90 days old
safe-npm install express --min-age-days 60

설치될 내용을 미리 보려면 드라이 런

# Preview which versions would be installed without actually installing
safe-npm install --dry-run

구성 옵션

--min-age-days <n>

기본값: 90

패키지 버전이 설치되기 전에 게시된 최소 일수입니다.

예시: --min-age-days 120은 패키지가 최소 4개월 이상이어야 함을 의미합니다.

조정 시점:

• 최대 보안을 위해 증가 (예: 중요한 프로덕션 시스템의 경우 180일)
• 새로운 기능이 필요하고 약간의 위험을 감수할 수 있다면 감소 (예: 30일)

--ignore <pkg1,pkg2>

연령 요구 사항을 우회하는 쉼표로 구분된 패키지 목록입니다. 이러한 패키지는 여전히 semver 범위를 따르지만 최소 연령은 무시합니다.

예시: --ignore typescript,@types/node

사용 시점:

• 신뢰하는 빠르게 업데이트되는 패키지 (예: TypeScript 또는 빌드 도구)
• 조직의 내부 패키지
• 최신 기능이 긴급히 필요한 패키지

--strict

어떤 종속성이라도 연령 요구 사항을 충족하는 버전으로 확인될 수 없으면 오류와 함께 종료합니다.

예시: safe-npm install --strict

사용 시점:

• 문제가 있는 패키지를 건너뛰지 않고 빌드가 실패하도록 하려는 CI/CD 파이프라인
• 확실성이 필요한 프로덕션 배포

--dev / --prod-only

package.json에서 처리할 종속성을 제어합니다.

예시:

• safe-npm install --dev - devDependencies만 설치
• safe-npm install --prod-only - 프로덕션 종속성만 설치

사용 시점:

• 더 엄격한 요구 사항이 있는 개발 도구 설치
• dev와 prod 종속성에 대해 다른 연령 정책을 적용하려는 프로덕션 빌드

--strategy <direct|overrides>

기본값: direct

safe-npm이 확인된 버전을 설치하는 방법:

direct - npm install package@version을 사용하여 확인된 버전을 직접 설치합니다.

• 간단하고 직관적입니다.
• 일회성 설치나 스크립트에 적합합니다.

overrides - 확인된 버전을 package.json의 overrides 필드에 기록한 다음 npm install을 실행합니다.

• 전체 종속성 트리(전이 종속성 포함)에 버전을 강제 적용합니다.
• 참고: 이 기능은 아직 올바르게 작동하지 않아 현재 비활성화되어 있습니다.

--registry <url>

기본값: https://registry.npmjs.org

대체 npm 레지스트리를 지정합니다.

예시: --registry https://registry.company.com

사용 시점:

• 사설 npm 레지스트리
• 미러 또는 캐시

--dry-run

변경하지 않고 설치될 내용을 표시합니다.

예시: safe-npm install --dry-run

사용 시점:

• 구성 테스트
• 사용 가능한 버전 이해
• 프로덕션 시스템 변경 전

일반적인 워크플로

새 프로젝트 보호

# Create a new project
mkdir my-project && cd my-project
npm init -y

# Install dependencies safely
safe-npm install express@^4 lodash

# This creates package-lock.json with versions at least 90 days old

기존 프로젝트 감사

# Check what versions would be installed with age requirements
safe-npm install --dry-run

# If you're happy, install them
safe-npm install

CI/CD 통합

# In your CI pipeline, fail the build if any package can't meet age requirements
safe-npm install --strict --min-age-days 120

# Or allow newer packages for dev dependencies only
safe-npm install --prod-only --strict

긴급 업데이트

# Need to urgently update a specific package? Add it to ignore list
safe-npm install --ignore package-with-critical-fix

테스트

프로젝트에는 실행할 수 있는 테스트 스위트가 포함되어 있습니다:

npm test

자동화된 테스트를 위해 픽스처를 사용하여 레지스트리 응답을 모킹할 수 있습니다:

export SAFE_NPM_FIXTURES=/path/to/fixtures.json
safe-npm install

픽스처 파일에는 각 패키지에 대한 npm 레지스트리 응답을 반영하는 JSON이 포함되어야 합니다.

보호 방식

실제 시나리오:

1. 인기 패키지 popular-lib이 신뢰할 수 있는 개발자가 유지 관리합니다
2. 공격자가 관리자의 npm 자격 증명을 손상시킵니다
3. 공격자가 악성코드가 포함된 [email protected]을 게시합니다
4. ^5.0.0을 사용하는 프로젝트는 즉시 악성 버전을 설치하게 됩니다
5. safe-npm을 사용하면 4.9.0(90일 이상 전의 최신 버전)을 계속 사용하게 됩니다
6. 보안 연구자가 손상 사실을 발견하고 보고합니다
7. 악성 버전이 게시 취소됩니다
8. 여러분은 손상된 버전을 설치하지 않았습니다

제한 사항

• 처음부터 악성 패키지는 보호하지 못합니다
• 합법적인 새로운 기능과 버그 수정에 대한 접근이 지연됩니다
• 이전 버전에 발견되지 않은 취약점이 없다는 신뢰가 필요합니다
• 연령 기반 필터링은 경험적 방법이며 보장된 것은 아닙니다

철학

보안은 절충에 관한 것입니다. safe-npm은 갑작스러운 공급망 손상에 대한 보호를 위해 최첨단 업데이트를 희생합니다. 이는 심층 방어 전략의 한 계층이며, 다음을 포함해야 합니다:

• 정기적인 보안 감사 (npm audit)
• 새 패키지 추가 전 종속성 검토
• 보안 권고 모니터링
• 재현 가능한 빌드를 위해 잠금 파일 사용
• 샌드박스 또는 컨테이너화된 환경에서 실행

요구 사항

• Node.js 18 이상
• npm (기본 설치용)

라이선스

ISC