Quick start

You need PowerShell 7 (pwsh). Two ways to run:

A. Live NinjaOne scan

B. Offline — any RMM, SCCM, or Intune (no API access)

Export your inventory to a CSV with columns hostname, software, version (optional device_id, os), then:

-InputCsv makes zero NinjaOne calls — no OAuth, no API. It still queries NVD and the other public feeds, so you still want an nvd.api_key in config.json and a valid output.report_dir. See docs/rmm-adapters.md for the input contract and per-RMM export recipes.

Installing prerequisites

• PowerShell 7 — macOS: brew install powershell; Windows: winget install Microsoft.PowerShell; Debian/Ubuntu: install from the Microsoft package repo (packages.microsoft.com).
• sqlite3 (optional, powers history/trending) — macOS: preinstalled or brew install sqlite; Debian/Ubuntu: apt-get install sqlite3; Windows: download the SQLite "tools" bundle from sqlite.org and put sqlite3.exe on PATH or beside the script. Without it the scan still runs; first_seen falls back to the run date.

Requirements

• PowerShell 7 (7.4+ recommended). The parallel scan requires 7.0+.
• sqlite3 — optional; enables the history DB, trending, and SLA first_seen tracking. Absent = those features skip, scan still completes.
• Network egress to NVD, CISA (KEV), epss.empiricalsecurity.com (the EPSS bulk-score host — FIRST moved EPSS data hosting there), MSRC, endoflife.date, and GitHub raw (CVE Program cvelistV5) — plus the NinjaOne API in live mode.
• Credentials — live mode needs NinjaOne OAuth2 client id/secret; offline mode needs only an inventory CSV. An NVD API key is technically optional but effectively required at fleet scale: NVD allows 50 requests/30s with a key and only 5/30s without one. The scanner detects which you have and throttles to match, so a keyless run is correct but roughly 10x slower — fine for a handful of products, impractical for a real fleet. Keys are free.

Configuration reference

Config is a JSON file (default config.json beside the script; override with -ConfigPath). Start from config.example.json. Every key the scanner reads, its default when omitted, and what it does:

ninjaone (live mode)

nvd

Scan & scoring

Caching & rate limiting

nvd_min_spacing_ms, nvd_rate_limit, and parallel_throttle are read by the scanner but not present in config.example.json — add them only if you need to tune. See docs/rate-limiting.md.

Enrichment & SLA

output

Outputs

Everything below lands in output.report_dir.

• vuln-report-YYYY-MM-DD.csv — the per-finding report. 28 columns (schema below).
• vuln-history.db — SQLite history (requires sqlite3): runs (per-run aggregates), findings (per (device, software, cve) open-finding history with first_seen / last_seen / resolved_date / epss_score), and changes (typed week-over-week events).
• cve-dashboard.html — self-contained HTML dashboard (charting library inlined, no external requests). Optionally copied to output.dashboard_share.
• eol-report-YYYY-MM-DD.csv — written when end-of-life families are detected.
• denied-report-YYYY-MM-DD.csv — written when denied_software_csv is configured and matches.
• Cache files — nvd-cache.json, kev-cache.json, epss-cache.json, eol-cache.json, msrc-cache.json, cvelist-cache.json (all gitignored).
• Markdown exposure page — at output.wiki_security_page, only when set.

CSV schema (28 columns)

The column set is fixed and gate-enforced. In order:

Scheduling

Run-WeeklyScan.ps1 is a wrapper for scheduled runs: it runs the scanner from its own directory, captures all output streams to a dated log under <script dir>/logs/ (override with -LogDir), and propagates the scanner's exit code so the scheduler sees failures.

Windows Task Scheduler:

cron (Linux/macOS):

Dashboard hosting

cve-dashboard.html is fully self-contained — open it directly, drop it on any static host or file share, or copy it automatically each run via output.dashboard_share. For access-controlled hosting, the dashboard-auth/ directory ships a minimal ASP.NET host with Microsoft Entra (Azure AD) authentication; see its README and RUNBOOK.

Honest limitations (read before trusting it)

• CPE matching is fuzzy by nature. 40–60% of typical inventory has no NVD entry at all and is skipped (logged, never silently). Name-based CPE selection can pick the wrong product; a suppression workflow exists because it has to. This is the ceiling of the free-NVD approach — a paid scanner with a curated detection catalog will be more accurate. This tool's value is being free, transparent, and auditable.
• UNKNOWN is a first-class verdict. When the scanner can't prove vulnerable-or-patched, it says so instead of guessing.
• Verified against NinjaOne only. The scan engine is RMM-agnostic (input is just device + software + version); the -InputCsv mode lets any RMM/SCCM/Intune export feed it, but only the NinjaOne adapter has been run in production.

The full, unflinching list — the CPE skip rate, dedup-key masking, page-1 totalResults, MSRC supersedence gaps, and more — is in docs/known-limitations.md.

Design notes

A few structural choices that look unconventional are deliberate:

• Single file, not a module. The scan hot path runs inside ForEach-Object -Parallel, and those runspaces cannot see outer-scope functions — which is why a handful of helpers are intentionally duplicated inside the parallel block. A one-function-per-file module layout would not remove that duplication (the parallel body would still need the source injected per runspace); it would just add a build step and break the copy-one-file deployment model. If the project ever outgrows single-file, packaging is the v2-shaped change, not a patch.
• [PSCustomObject] records, not classes. Finding records are produced inside parallel runspaces and marshaled back to the main runspace. PowerShell class instances do not reliably survive that boundary; [PSCustomObject] does, and the CSV column contract is enforced by the release gate instead of a type system.
• Plain PS7 test scripts, not Pester. The suites in tests/ are dependency-free scripts with exit-code assertions, runnable anywhere pwsh exists — including the scan server — with nothing to install. CI runs them all on Windows and Ubuntu.

Documentation

• docs/how-it-works.md — the scan pipeline stage by stage, verdict logic, cache discipline, and the fail-soft contract.
• docs/known-limitations.md — every known way the scanner can be wrong, and why.
• docs/rate-limiting.md — the NVD rate-limit lessons as an operator guide and tuning table.
• docs/rmm-adapters.md — the input contract, the two built-in inventory paths, and how to add a native adapter.
• docs/HISTORY.md — condensed, sanitized version history and the engineering lessons behind each release.

Contributing

PRs welcome — RMM adapters most of all. See CONTRIBUTING.md for the ground rules and the safe-direction requirement (status logic may only err toward more visibility, never silently toward PATCHED).

Data sources & attribution

This tool is only as useful as the free, authoritative feeds it joins against. Each of the following is queried at scan time; please honor their terms if you build on this.

• NIST National Vulnerability Database (NVD) — CVE records and affected version ranges, via the NVD API. This product uses the NVD API but is not endorsed or certified by the NVD. https://nvd.nist.gov/
• CISA Known Exploited Vulnerabilities (KEV) Catalog — the authoritative list of CVEs known to be exploited in the wild. https://www.cisa.gov/known-exploited-vulnerabilities-catalog
• CVE Program — cvelistV5 — CVE records plus the SSVC / vulnrichment data contributed by the CISA ADP. CVE® is a registered trademark of The MITRE Corporation. https://github.com/CVEProject/cvelistV5
• SSVC (Stakeholder-Specific Vulnerability Categorization) — the act / attend / track decision logic in this tool is derived from CERT/CC SSVC (Carnegie Mellon University Software Engineering Institute) and the CISA SSVC Coordinator decision tree, version 2.0.3. Credit to CERT/CC and CISA is required. https://www.cisa.gov/ssvc · https://github.com/CERTCC/SSVC
• FIRST.org EPSS (Exploit Prediction Scoring System) — probability of exploitation in the next 30 days. EPSS data is provided by FIRST. See 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) — the CVRF API, used to confirm when a Microsoft security update already covers a finding. © Microsoft Corporation. https://api.msrc.microsoft.com/ · https://msrc.microsoft.com/
• endoflife.date — end-of-life and end-of-support dates for software that will never be patched again. Data courtesy of the endoflife.date project. https://endoflife.date/

License

Apache-2.0 — see LICENSE.