NPQ 문서

이 디렉토리에는 NPQ(Node Package Quality) 보안 감사 도구에 대한 포괄적인 문서가 포함되어 있습니다.

핵심 문서

optional-features.md

선택적 보안 기능의 구성 및 사용 방법, 그리고 최근 개선 사항과 버그 수정 사항을 다룹니다.

age.marshall.md

패키지 연령과 성숙도를 검증하는 Age Marshall 보안 구성 요소에 대한 상세 문서입니다.

기능 문서

feature/ 디렉토리에는 특정 기능 및 구현에 대한 상세 문서가 포함되어 있습니다:

최근 개발 사항

• test-coverage-improvements.md - 전체 커버리지를 84.4%에서 93.39%로 개선한 포괄적인 테스트 커버리지 강화
• signature-verification-fix.md - 버전 범위(예: @angular/common@^20.2.4)가 있는 서명 검증을 위한 중요 버그 수정

기존 기능

• auto-continue.md - 패키지 설치 워크플로우를 간소화하는 auto-continue 기능에 대한 문서
• exit-codes.md - npq 및 npq-hero 프로세스 종료 동작에 대한 참조
• json-output.md - CI 및 자동화를 위한 버전 관리된 기계 판독 가능 감사 전용 출력
• malicious-package.md - Snyk/OSV 데이터를 통한 알려진 악성 패키지 탐지에 대한 문서
• pacote-dependency-reduction.md - 선택적 pacote 종속성 축소에 대한 구현 요약

문서 표준

구조

• 각 기능은 feature/ 디렉토리에 자체 마크다운 파일을 가집니다
• 핵심 기능은 루트 문서 수준에서 문서화됩니다
• 코드 예제와 함께 기술 구현 세부 사항이 포함됩니다
• 사용자 대상 구성은 사용 예제와 함께 문서화됩니다

콘텐츠 지침

• 개요: 기능/구성 요소에 대한 간략한 설명
• 기술 설계: 아키텍처 및 구현 세부 사항
• 사용 예제: 코드 스니펫이 포함된 실용적인 예제
• 테스트: 커버리지 및 검증 정보
• 향후 고려 사항: 유지 관리 및 발전 관련 메모

Marshall 문서

Marshall 구성 요소는 NPQ의 핵심 보안 검증 모듈입니다. 각 marshall은 특정 보안 문제에 중점을 둡니다:

• Age Marshall (age.marshall.md) - 패키지 연령 및 성숙도 검증
• Signature Marshall - NPM 레지스트리 서명 검증(signature-verification-fix.md 참조)
• Provenance Marshall - 패키지 빌드 증명(attestation) 검증
• Snyk Marshall - 취약점 데이터베이스 통합
• Typosquatting Marshall - 패키지 이름 유사성 탐지

문서 기여

새 기능을 추가하거나 중요한 변경을 할 때:

1. 기능 문서: feature/ 디렉토리에 새 파일 생성
2. 인덱스 업데이트: 이 README에 항목 추가
3. 상호 참조: 관련 문서 파일 업데이트
4. 예제: 실용적인 사용 예제 포함
5. 테스트: 테스트 커버리지 및 검증 문서화

빠른 참조

프로젝트 컨텍스트

• 개발 - 로컬 설정, 워크플로우 및 유용한 명령어.
• 테스트 - 테스트 명령어, 테스트 구성 및 검증 기대 사항.
• 아키텍처 - 저장소 구조, 패키지 경계 및 중요한 흐름.
• 규칙 - 코딩, 문서화 및 유지 관리 규칙.

설계 사양

• 사용자 정의 레지스트리 지원 - npm 호환 Artifactory 및 프라이빗 레지스트리 지원을 위한 승인된 설계.
• 코딩 에이전트 JSON 탐지 - 코딩 에이전트 환경에서 JSON 감사 모드를 자동으로 선택하기 위한 승인된 설계.
• JSON 감사 출력 - 버전 관리된 비대화형 기계 판독 가능 감사 결과를 위한 승인된 설계.
• 만료된 도메인 유지 관리자 ID 경고 - 귀속 가능한 만료된 도메인 경고를 위한 승인된 설계.
• 만료된 도메인 해석 버전 - 만료된 도메인 검사를 위한 정확한 종속성 버전 해석 설계.

구현 계획

• 사용자 정의 레지스트리 지원 - 이슈 #429에 대한 작업별 구현 계획.
• 코딩 에이전트 JSON 탐지 - npq 및 npq-hero 전반에 걸친 이슈 #426에 대한 테스트 우선 구현 계획.
• JSON 감사 출력 - 버전 관리된 감사 전용 JSON CLI 출력을 위한 작업별 계획.
• 만료된 도메인 해석 버전 - 만료된 도메인 검사에서 정확한 종속성 버전 해석을 위한 구현 계획.
• 만료된 도메인 유지 관리자 ID 경고 - 귀속 가능한 만료된 도메인 경고를 위한 테스트 우선 구현 계획.