B. 오프라인 — 모든 RMM, SCCM, Intune (API 접근 불필요)

인벤토리를 hostname, software, version 열(선택 사항 device_id, os)을 가진 CSV로 내보낸 후:

-InputCsv는 전혀 NinjaOne 호출을 하지 않습니다 — OAuth 없음, API 없음. 여전히 NVD 및 기타 공개 피드를 쿼리하므로 config.json에 nvd.api_key가 필요하고 유효한 output.report_dir이 필요합니다. 입력 계약 및 RMM별 내보내기 방법은 docs/rmm-adapters.md를 참조하십시오.

필수 구성 요소 설치

• PowerShell 7 — macOS: brew install powershell; Windows: winget install Microsoft.PowerShell; Debian/Ubuntu: Microsoft 패키지 저장소(packages.microsoft.com)에서 설치.
• sqlite3 (선택 사항, 히스토리/트렌드 지원) — macOS: 사전 설치 또는 brew install sqlite; Debian/Ubuntu: apt-get install sqlite3; Windows: sqlite.org에서 SQLite "tools" 번들을 다운로드하고 sqlite3.exe를 PATH에 또는 스크립트 옆에 배치. 없어도 스캔은 실행됩니다. first_seen은 실행 날짜로 대체됩니다.

요구 사항

• PowerShell 7 (7.4+ 권장). 병렬 스캔에는 7.0+가 필요합니다.
• sqlite3 — 선택 사항; 히스토리 DB, 트렌드, SLA first_seen 추적을 활성화합니다. 없으면 해당 기능이 건너뛰고 스캔은 계속 완료됩니다.
• 네트워크 아웃바운드 — NVD, CISA(KEV), epss.empiricalsecurity.com (EPSS 벌크 점수 호스트 — FIRST가 EPSS 데이터 호스팅을 이전), MSRC, endoflife.date, GitHub raw (CVE Program cvelistV5) — 라이브 모드에서는 NinjaOne API도 필요.
• 자격 증명 — 라이브 모드는 NinjaOne OAuth2 클라이언트 ID/비밀 필요; 오프라인 모드는 인벤토리 CSV만 필요. NVD API 키는 기술적으로 선택 사항이지만 플릿 규모에서는 사실상 필수: NVD는 키 사용 시 30초에 50개 요청, 키 없이 5개 요청을 허용합니다. 스캐너는 키 유무를 감지하여 속도를 조절하므로, 키 없이 실행해도 올바르지만 약 10배 느려집니다 — 소수의 제품에는 괜찮지만 실제 플릿에는 비현실적입니다. 키는 무료입니다.

구성 참조

구성은 JSON 파일입니다(기본값은 스크립트 옆의 config.json; -ConfigPath로 재정의 가능). config.example.json에서 시작하십시오. 스캐너가 읽는 모든 키, 생략 시 기본값 및 역할:

ninjaone (라이브 모드)

nvd

스캔 및 점수

캐싱 및 속도 제한

nvd_min_spacing_ms, nvd_rate_limit, parallel_throttle은 스캐너가 읽지만 config.example.json에는 없습니다 — 조정이 필요한 경우에만 추가하십시오. docs/rate-limiting.md 참조.

강화 및 SLA

output

출력물

아래 모든 항목은 output.report_dir에 저장됩니다.

• vuln-report-YYYY-MM-DD.csv — 발견 항목별 보고서. 28개 열(스키마는 아래 참조).
• vuln-history.db — SQLite 히스토리(sqlite3 필요): runs(실행별 집계), findings(각 (device, software, cve)별 열린 발견 히스토리, first_seen/last_seen/resolved_date/epss_score 포함), changes(유형화된 주간 이벤트).
• cve-dashboard.html — 독립형 HTML 대시보드(차트 라이브러리 인라인, 외부 요청 없음). 선택적으로 output.dashboard_share에 복사.
• eol-report-YYYY-MM-DD.csv — 수명 종료 제품군이 감지되면 작성.
• denied-report-YYYY-MM-DD.csv — denied_software_csv가 구성되고 일치할 때 작성.
• 캐시 파일 — nvd-cache.json, kev-cache.json, epss-cache.json, eol-cache.json, msrc-cache.json, cvelist-cache.json(모두 gitignore됨).
• 마크다운 노출 페이지 — output.wiki_security_page에, 설정된 경우에만.

CSV 스키마 (28개 열)

열 세트는 고정되어 있으며 게이트에서 강제됩니다. 순서:

스케줄링

Run-WeeklyScan.ps1은 예약된 실행을 위한 래퍼입니다: 자체 디렉터리에서 스캐너를 실행하고, 모든 출력 스트림을 <script dir>/logs/ 아래의 날짜별 로그로 캡처하며(-LogDir로 재정의 가능), 스캐너의 종료 코드를 전파하여 스케줄러가 실패를 감지할 수 있습니다.

Windows 작업 스케줄러:

cron (Linux/macOS):

대시보드 호스팅

cve-dashboard.html은 완전히 독립적입니다 — 직접 열거나, 정적 호스트나 파일 공유에 넣거나, output.dashboard_share를 통해 각 실행 시 자동으로 복사할 수 있습니다. 접근 제어 호스팅을 위해 dashboard-auth/ 디렉터리는 Microsoft Entra(Azure AD) 인증이 포함된 최소 ASP.NET 호스트를 제공합니다. 해당 README 및 RUNBOOK을 참조하십시오.

정직한 제한 사항 (신뢰하기 전에 읽으십시오)

• CPE 매칭은 본질적으로 퍼지(fuzzy)합니다. 일반적인 인벤토리의 40~60%에는 NVD 항목이 전혀 없어 건너뜁니다(로깅되며, 절대 조용히 처리되지 않음). 이름 기반 CPE 선택은 잘못된 제품을 선택할 수 있습니다. 필요에 의해 억제 워크플로가 존재합니다. 이것이 무료 NVD 접근 방식의 한계입니다 — 큐레이팅된 탐지 카탈로그를 가진 유료 스캐너가 더 정확합니다. 이 도구의 가치는 무료이고 투명하며 감사 가능하다는 점입니다.
• UNKNOWN은 일급 판결(first-class verdict)입니다. 스캐너가 취약/패치됨을 증명할 수 없을 때 추측하지 않고 그렇게 명시합니다.
• NinjaOne에 대해서만 검증됨. 스캔 엔진은 RMM에 구애받지 않습니다(입력은 단순히 장치 + 소프트웨어 + 버전). -InputCsv 모드를 사용하면 모든 RMM/SCCM/Intune 내보내기가 이를 공급할 수 있지만, 프로덕션에서는 NinjaOne 어댑터만 실행되었습니다.

전체 포괄 목록(CPE 건너뛰기 비율, 중복 제거 키 마스킹, 1페이지 totalResults, MSRC 대체 간격 등)은 docs/known-limitations.md에 있습니다.

설계 노트

• 단일 파일, 모듈 아님. 스캔 핫 경로는 ForEach-Object -Parallel 내에서 실행되며, 해당 런스페이스는 외부 범위의 함수를 볼 수 없습니다. 이것이 몇 가지 도우미가 의도적으로 병렬 블록 내에서 중복되는 이유입니다. 함수당 하나의 파일 모듈 레이아웃은 해당 중복을 제거하지 않습니다(병렬 본문에는 여전히 런스페이스당 소스 주입이 필요함). 빌드 단계를 추가하고 파일 하나 복사 배포 모델을 깨뜨릴 뿐입니다. 프로젝트가 단일 파일을 벗어나게 되면 패키징은 v2 형태의 변경이지 패치가 아닙니다.
• [PSCustomObject] 레코드, 클래스가 아님. 발견 레코드는 병렬 런스페이스 내에서 생성되어 주 런스페이스로 마샬링됩니다. PowerShell 클래스 인스턴스는 해당 경계를 안정적으로 통과하지 못합니다. [PSCustomObject]는 통과하며, CSV 열 계약은 유형 시스템 대신 릴리스 게이트에 의해 강제됩니다.
• 일반 PS7 테스트 스크립트, Pester 아님. tests/의 스위트는 종속성이 없는 스크립트로, 종료 코드 어설션을 사용하며 pwsh가 존재하는 모든 곳(스캔 서버 포함)에서 실행 가능하며 설치할 것이 없습니다. CI는 Windows와 Ubuntu에서 모두 실행합니다.

문서

• docs/how-it-works.md — 스캔 파이프라인 단계별, 판결 로직, 캐시 규율, 및 페일-소프트 계약.
• docs/known-limitations.md — 스캐너가 잘못될 수 있는 모든 알려진 방식과 그 이유.
• docs/rate-limiting.md — 운영자 가이드 및 튜닝 표로서의 NVD 속도 제한 교훈.
• docs/rmm-adapters.md — 입력 계약, 두 가지 내장 인벤토리 경로, 네이티브 어댑터 추가 방법.
• docs/HISTORY.md — 간결하고 정리된 버전 기록과 각 릴리스의 엔지니어링 교훈.

기여

PR 환영합니다 — 특히 RMM 어댑터. 기본 규칙 및 안전 방향 요구 사항은 CONTRIBUTING.md를 참조하십시오(상태 로직은 더 많은 가시성 방향으로만 오류를 허용하며, 조용히 PATCHED로 오류를 허용하지 않음).

데이터 소스 및 저작자 표시

이 도구는 결합하는 무료 공식 피드만큼만 유용합니다. 다음 각각은 스캔 시 조회됩니다. 이를 기반으로 구축하는 경우 해당 조건을 준수하시기 바랍니다.

• NIST National Vulnerability Database (NVD) — NVD API를 통한 CVE 레코드 및 영향을 받는 버전 범위. 이 제품은 NVD API를 사용하지만 NVD의 보증 또는 인증을 받지 않았습니다. https://nvd.nist.gov/
• CISA Known Exploited Vulnerabilities (KEV) Catalog — 실제 환경에서 악용되는 것으로 알려진 CVE의 공식 목록. https://www.cisa.gov/known-exploited-vulnerabilities-catalog
• CVE Program — cvelistV5 — CVE 레코드와 CISA ADP가 제공한 SSVC/vulnrichment 데이터. CVE®는 MITRE Corporation의 등록 상표입니다. https://github.com/CVEProject/cvelistV5
• SSVC (Stakeholder-Specific Vulnerability Categorization) — 이 도구의 act/attend/track 결정 로직은 CERT/CC SSVC(카네기 멜론 대학교 소프트웨어 공학 연구소) 및 CISA SSVC 조정자 결정 트리 버전 2.0.3에서 파생되었습니다. CERT/CC 및 CISA에 대한 크레딧이 필요합니다. https://www.cisa.gov/ssvc · https://github.com/CERTCC/SSVC
• FIRST.org EPSS (Exploit Prediction Scoring System) — 향후 30일 내 악용 확률. EPSS 데이터는 FIRST에서 제공합니다. Jay Jacobs, Sasha Romanosky, Benjamin Edwards, Michael Roytman, Idris Adjerid (2021), Exploit Prediction Scoring System, Digital Threats: Research and Practice, 2(3) 참조. https://www.first.org/epss/
• Microsoft Security Response Center (MSRC) — CVRF API, Microsoft 보안 업데이트가 이미 발견 항목을 포함하는지 확인하는 데 사용됩니다. © Microsoft Corporation. https://api.msrc.microsoft.com/ · https://msrc.microsoft.com/
• endoflife.date — 더 이상 패치되지 않을 소프트웨어의 수명 종료 및 지원 종료 날짜. 데이터는 endoflife.date 프로젝트 제공. https://endoflife.date/

라이선스

Apache-2.0 — LICENSE 참조.