A safety-first vulnerability scanner for ICS/OT protocols.
A safety-first vulnerability scanner for ICS/OT protocols. It identifies devices and checks them against known CVEs and insecure defaults — actively (probing an explicit, authorized target list) or passively (reading a SPAN/TAP or pcap and transmitting nothing) — correlates findings to CVEs, and can emit deployable detection content for Zeek, Suricata, Sigma, and Splunk.
Responsible use. icsScanner can send active probes and authentication attempts to live industrial systems, where unexpected traffic can disrupt physical processes. Only scan devices you own or are explicitly authorized to test. Active checks are off by default (safe mode reports fingerprint-only); the passive mode (
discover sniff) transmits nothing and is the right choice on live OT networks. See SECURITY.md.
The check corpus spans many ICS/OT protocols. Most checks target factory-default credentials and insecure
defaults; the CVE-correlation candidates are built from structured vulnerability feeds — the ICS Advisory
Project, Japan's MyJVN, CISA's CSAF 2.0 OT advisories, and ENISA's EU Vulnerability Database. Reporting is
JSONL + a text summary, with HTML / CSV / SVG export. See 04-USAGE-GUIDE.md for the full how-to, or
"Running a scan" below for the short version.
Prior-art research found real ICS/OT vulnerability-scanning coverage gaps: Nessus's SCADA plugin family is mature but closed/commercial; Nuclei and Metasploit's ICS content is thin; nmap NSE covers fingerprinting well but has no CVE-level checks. Nobody has an open, safety-first, actively extensible active-CVE-check layer for ICS. icsScanner fills that gap.
| File | Purpose |
|---|---|
00-PROJECT-CHARTER.md | Scope, decisions, phased milestones (0–5), LOE |
01-METHODOLOGY-AND-CHECKLISTS.md | Safe active-check development method + the "is this a safe check?" gate |
02-DISCLOSURE-PLAYBOOK.md | The disclosure_status contract for consuming upstream findings safely |
03-STYLE-AND-DECISIONS.md | Identity, naming, and the private-for-now publication decision |
04-USAGE-GUIDE.md | Full how-to: CLI + web UI, target inventory/scan policy formats, safety model, API reference, troubleshooting |
lab-notes/gap-survey-and-prior-art.md | The 2026-08-12 prior-art sweep (Nessus, Nuclei, Metasploit, nmap NSE, geeknik/scada-scanner, ICS Advisory Project) |
lab-notes/check-inventory.md | Mapping of own findings (both sibling projects) to planned checks, with disclosure status |
lab-notes/default-credentials-sweep.md | Phase-by-phase log of the default-credentials sweep — most of the 98 checks' origin story |
core/ | Engine — registry, target/policy loading, safety/throttling layer, logging, reporting |
core/passive.py / core/detect_match.py / core/detections.py | Zero-transmit passive mode — capture/dissect/inventory, native detection matching, the Observed-Activity report section |
checks/ | Check registry content, organized by protocol; checks/candidates/ holds research-stage stubs, never executable |
detection-gen/ | Generates deployable detections (Sigma / Splunk-ESCU / Suricata / Zeek signature + ATT&CK-for-ICS policy) from the same checks/ detection_hints |
icsscanner.py | CLI driver — active scan and passive discover sniff; see above |
icsscanner-web.py / web/ | Web UI — a local control panel over the same engine |
templates/ | Example target-inventory and scan-policy YAML files |
lab-notes/passive-mode.md | Passive-mode architecture + TSA system-requirements (sizing from the PNNL OT-IDS dataset) |
Three ways to run it, grouped by how much they touch the network. Pick by what the target environment allows — the transmit posture is the safety-critical distinction:
| Mode | Transmits? | Use when | Commands |
|---|---|---|---|
| Passive | No — RX-only, zero packets (discover sniff) | Live OT where active probing is disallowed (safety, fragile legacy devices, change control) | discover sniff (SPAN/TAP/pcap/Zeek-logs); discover passive (ARP-listen + Sparkplug — see the caveat below) |
| Active scan | Yes — sends probes, and opt-in logins | Assets you own or have explicit written permission to test | scan (default CLI / policy file / web UI); discover active (ARP sweep to find hosts first) |
| Malcolm interop | Read-only API calls to your own Malcolm | You already run a Malcolm / Hedgehog passive stack | discover malcolm (read inventory + correlate; --push sends findings back); discover sniff --push-malcolm (push a passive run's findings) |
Each mode is detailed below. scan and discover sniff are the primary commands; discover active /
discover passive are secondary discovery helpers within the Active / Passive modes. Safe mode
(fingerprint-only, no destructive checks) is the default in every mode that can transmit.
Full detail in 04-USAGE-GUIDE.md. Short version — three ways in, all driving the same engine:
# Ad hoc CLI: just point at a target inventory, optionally narrow by protocol/check-id.
python3 icsscanner.py --inventory templates/target-inventory.example.yaml --protocol http
# Policy-file CLI: bundles target inventory + check selection + rate profile + output dir into
# one reusable YAML (00-PROJECT-CHARTER.md § Scope — the decided invocation model). CLI flags
# below still override individual policy fields for a one-off tweak.
python3 icsscanner.py --policy templates/scan-policy.example.yaml
# Web UI: a form + run view at http://127.0.0.1:8807/ — same policy/inventory model, same
# safe-mode default, a two-step confirm click in place of the CLI's interactive prompt.
python3 icsscanner-web.py
Copy templates/target-inventory.example.yaml (and optionally templates/scan-policy.example.yaml)
before editing — don't scan straight from the template. Only list devices you own or have
explicit written permission to test. Each target is one exact host: — an IP or FQDN, never a
CIDR range; this is a deliberate scope decision (small known asset lists, not a network sweep
tool), not a missing feature — see 04-USAGE-GUIDE.md.
Every check that actually does something (a real login attempt, etc.) is destructive: true.
Safe mode is the default — destructive checks report fingerprint-only and never fire unless
you pass --include-destructive (or set include_destructive: true in a policy file), and even
then icsscanner.py requires an explicit y at an interactive confirmation prompt (or --yes/
-y to skip it) before anything live happens. The web UI enforces the same thing as an explicit second "Confirm and Run" click instead of
a terminal prompt — the first submission only shows what would run. The web UI also has no
authentication and binds 127.0.0.1 (localhost-only) by default for that reason — see
04-USAGE-GUIDE.md before exposing it any wider.
python3 icsscanner.py --help lists every flag. Results land in --output's directory (default
./output, already gitignored) as a timestamped icsscanner-*.jsonl plus a printed text summary.