의존성 업데이트를 보안 경고 숫자보다 변경 범위부터 확인하는 법

프로젝트를 열었을 때 보안 취약점이 몇 개 있다는 문장을 보면 모두 즉시 없애야 할 것처럼 느껴집니다. 하지만 숫자만 보고 자동 수정 명령부터 실행하면 여러 패키지가 함께 바뀌고, 멀쩡하던 화면이나 빌드가 깨져도 어느 변경이 원인인지 찾기 어려워질 수 있습니다.

건물 안의 맞물린 기어 하나를 교체하는 장면을 떠올려 보세요. 낡은 부품을 그대로 두는 것도 위험하지만, 규격이 다른 새 부품을 힘으로 끼우면 주변 장치까지 멈출 수 있습니다. 의존성 업데이트도 현재 연결을 읽고, 맞는 규격을 고르고, 교체 뒤 전체가 다시 도는지 확인하는 정비에 가깝습니다.

의존성 업데이트는 연결된 부품을 바꾸는 일이다

의존성은 내 프로젝트가 작동하려고 기대는 다른 코드입니다. 내가 package.json에 직접 적은 패키지뿐 아니라 그 패키지가 다시 불러오는 하위 패키지도 연결됩니다. 그래서 경고에 처음 보는 이름이 나타났다고 해서 쓸모없는 파일이 끼어들었다고 바로 단정하면 안 됩니다.

먼저 “어떤 상위 패키지를 통해 들어왔는가”와 “내 기능이 그 경로를 실제로 사용하는가”를 나눠 봅니다. 직접 의존성을 올리면 하위 패키지도 함께 바뀔 수 있고, 반대로 하위 패키지만 억지로 고정하면 상위 패키지가 기대한 조합과 달라질 수 있습니다. 연결 경로를 모르면 삭제나 강제 교체보다 현재 상태를 읽는 일이 먼저입니다.

보안 감사는 알려진 문제를 찾는 보고서다

npm audit은 프로젝트의 의존성 설명을 기본 레지스트리에 보내 알려진 취약점 보고서를 요청하는 명령입니다. npm 공식 문서에 따르면 직접 의존성, 개발 의존성, 묶음 의존성, 선택 의존성을 확인하지만 peerDependencies는 검사 대상에 포함하지 않습니다. 보고서에는 영향을 받은 패키지, 심각도, 연결 경로와 가능한 수정 안내가 나올 수 있습니다.

감사 결과가 0이라고 모든 코드가 안전하다는 뜻은 아닙니다. 아직 알려지지 않은 문제, 직접 작성한 코드의 권한 오류, 노출된 비밀키는 별도입니다. 반대로 경고가 있다고 곧바로 공격을 당했다는 뜻도 아닙니다. 보고서는 조사할 위치를 알려 주는 화재 감지기이고, 실제 노출 조건과 사용 경로는 사람이 확인해야 합니다.

경고 개수보다 사용 경로와 영향을 먼저 본다

높은 심각도라는 표시는 중요한 출발점이지만 숫자만으로 적용 순서를 완성할 수는 없습니다. 문제가 특정 운영체제에서만 생기는지, 특정 함수가 호출될 때만 생기는지, 개발 중에만 쓰는 도구인지, 인터넷 요청을 처리하는 운영 코드인지 확인합니다. npm도 수정판이 없을 때는 보안 권고의 완화 조건과 상위 패키지 업데이트 가능성을 직접 검토하도록 안내합니다.

다음 질문에 답하지 못하면 자동 수정보다 조사 기록을 먼저 남깁니다.

• 경고가 난 패키지는 어떤 직접 의존성을 통해 들어왔나요?
• 해당 패키지를 운영 기능에서 쓰나요, 개발 도구에서만 쓰나요?
• 수정 가능한 버전이 있고 현재 허용 범위 안에 있나요?
• 큰 버전 변경이나 API 사용법 변경이 필요한가요?
• 업데이트 뒤 확인할 핵심 화면과 명령은 무엇인가요?
• 문제가 생기면 어떤 커밋이나 잠금 파일로 돌아갈 수 있나요?

조회와 변경을 서로 다른 단계로 둔다

조회는 현재 상태를 읽는 일이고 변경은 파일과 설치 결과를 바꾸는 일입니다. 두 단계를 한꺼번에 묶으면 무엇을 보고 무엇을 바꿨는지 남기기 어렵습니다. 처음에는 프로젝트 폴더가 맞는지, package.json과 잠금 파일이 있는지, Git 작업 트리에 다른 사람의 변경이 없는지 확인합니다.

조회 계획: npm audit로 알려진 취약점 보고서 읽기
변경 계획: 아직 실행하지 않음
확인 대상: 영향 패키지, 연결 경로, 수정 가능 버전
검증 계획: 기존 테스트와 빌드, 핵심 화면 한 곳
복구 기준: 업데이트 전 커밋과 잠금 파일

npm update와 npm audit fix는 파일이나 설치된 패키지를 바꿀 수 있으므로 조회용 메모와 같은 줄에서 바로 실행하지 않습니다. npm 공식 업데이트 안내도 프로젝트 루트와 package.json을 확인한 뒤 업데이트하고 결과를 다시 점검하는 순서를 제시합니다. 명령 이름보다 현재 폴더와 변경 파일을 설명할 수 있는지가 더 중요합니다.

작은 범위로 바꾸고 바로 테스트한다

여러 패키지를 한 번에 올리면 실패 원인을 가르는 데 시간이 더 듭니다. 가능하면 관련된 직접 의존성 하나 또는 한 묶음만 선택하고, 공식 변경 기록에서 더 이상 지원하지 않는 사용법이 있는지 읽습니다. 업데이트 전후의 package.json과 잠금 파일 차이를 보고 예상하지 않은 대량 변경이 생기지 않았는지도 확인합니다.

테스트는 “명령이 끝났다”를 확인하는 절차가 아닙니다. 앱이 기대한 행동을 계속 하는지 보는 절차입니다. 로그인 라이브러리를 바꿨다면 로그인과 로그아웃, 만료 흐름을 확인하고, 빌드 도구를 바꿨다면 테스트와 빌드뿐 아니라 실제 첫 화면도 봅니다. 자동 테스트가 통과해도 브라우저 오류와 핵심 사용자 경로는 따로 확인할 수 있습니다.

자동 수정이 큰 변경을 요구하면 멈춘다

npm audit fix는 호환 가능한 업데이트를 자동 설치할 수 있지만 모든 경고를 안전하게 해결한다고 보장하지 않습니다. 보고서가 큰 버전 변경을 제안하면 기존 코드가 쓰던 함수 이름이나 설정 방식이 달라질 수 있습니다. npm 문서도 잠재적인 호환성 중단 변경에는 추가 코드 수정이 필요할 수 있다고 설명합니다.

수정판이 없거나 상위 패키지가 아직 새 버전을 받아들이지 않았다면 경고를 숨기기 위해 임의 버전을 강제로 끼우지 않습니다. 사용 경로를 줄일 수 있는지, 영향을 받는 기능을 잠시 닫아야 하는지, 대체 패키지를 검토할지 판단하고 근거를 기록합니다. 보안 경고를 오래 방치하지 않되, 알 수 없는 강제 변경을 안전 조치로 착각하지 않는 것이 중요합니다.

비밀키와 운영 배포는 업데이트 실습에서 분리한다

패키지 설치 과정에서는 외부 코드를 내려받고 설치 스크립트가 실행될 수 있습니다. 출처를 확인하지 못한 패키지나 복사한 긴 명령을 운영 프로젝트에서 바로 실행하지 마세요. 특히 관리자 권한, 강제 옵션, 잠금 파일 삭제, 전체 재설치가 포함되면 대상과 이유와 복구 방법을 설명할 수 있을 때까지 멈춥니다.

사설 패키지를 쓰는 프로젝트라면 레지스트리 주소와 토큰이 설정에 들어 있을 수 있습니다. .npmrc, 비밀키, 감사 결과의 내부 패키지 이름을 화면 캡처나 AI 대화에 붙이지 않습니다. 결제, 인증, 개인정보 처리 기능의 의존성을 바꿀 때는 테스트 계정과 별도 환경을 사용하고, 테스트 통과만으로 운영 배포까지 끝났다고 기록하지 않습니다.

오늘 바로 해볼 작은 실습

실제 업데이트는 하지 않고 10분 동안 점검표만 만듭니다.

1. 연습용 또는 공개 저장소 한 곳에서 package.json과 잠금 파일의 존재만 확인합니다.
2. 의존성 하나를 골라 직접 적힌 패키지인지 하위에서 따라온 패키지인지 구분합니다.
3. 보안 감사 명령이 외부 레지스트리에 의존성 설명을 보낸다는 점을 메모합니다.
4. 경고가 나온다고 가정하고 확인할 사용 경로와 기능을 한 줄씩 적습니다.
5. 업데이트 뒤 실행할 테스트, 빌드, 핵심 화면 확인을 각각 하나 고릅니다.
6. 변경 전 저장할 Git 상태와 잠금 파일을 적고 복구 담당자를 정합니다.
7. 비밀키, 사설 패키지 이름, 결제와 개인정보가 기록에서 빠졌는지 봅니다.
8. npm update, npm audit fix, 강제 옵션은 이번 실습에서 실행하지 않습니다.

완성된 점검표에서 현재 상태, 영향 경로, 변경 대상, 검증 방법, 복구 기준을 각각 가리킬 수 있으면 첫 준비가 된 것입니다. 다음 단계에서는 한 번에 하나의 작은 업데이트만 별도 브랜치에서 적용하고, 결과를 확인한 뒤 공개 배포 여부를 결정하세요.