windows-defensive-scanner - A modular, read-only defensive security auditing a

项目说明

Windows Defensi Scanner

A modular, read-only defensi auditing and threat detection tool for Windows 10, Windows 11, and Windows Server 2016+ (Python 3.8+).

Designed for incident response, threat hunting, and host integrity auditing, the scanner identifies indicators of compromise (IOCs), autostart persistence mechanisms, process masquerading, credential theft attempts, covert sur, and stealth installations without altering system state or introducing destructi.

---

Problem Being Solved

Windows endpoints in enterprise and lab en are frequently targeted with stealth persistence mechanisms, LOLBAS (Li Binaries and Scripts), and userland tradecraft that bypass basic antivirus signatures:
* Executables and scripts dropped into user-writable directories (%TEMP%, %APPDATA%, C:\Users\*).
* Masquerading processes that mimic critical Windows binaries (s.exe, lsass.exe, csrss.exe) from unauthorized paths, or utilize lookalikes and homoglyph typosquatting (s.exe, 1sass.exe).
* Nati dumping of LSASS utilities (comsvcs.dll #24) or tools like Mimikatz and PyPyKatz.
* Covert keystroke interception via AppInit_DLLs registry injection or keyboard hook APIs (SetWindowsHookEx, WH_KEYBOARD_LL, GetAsyncKeyState).
* Unauthorized remote access tools, covert , and scheduled screen capture scripts.
* Stealth services with stripped display names or unquoted service paths subject to CWE-428 hijacking.

The Windows Defensi Scanner provides defenders, analysts, and incident responders with an automated, lightweight, non-destructive tool to audit endpoints locally or across fleets .

---

Architecture

The scanner is built on a modular design utilizing standard Python libraries, with optional performance enhancements when psutil or wmi are a:

Architectural Principles

1. Read-Only & Non-Destructive: Zero modifications to files, registry keys, services, or running processes.
2. Graceful Degradation: If an indi data source fails (e.g. registry access permission error or service query failure), remaining checks proceed without aborting the scan.
3. Cross-Platform Testability: Uses dependency injection and mock pro, allowing all unit, integration, and ad tests to run on both Windows and non-Windows en (Linux, macOS).
4. Standardized Schema: Every detector outputs findings conforming to a unified dictionary model.

---

Detector Modules

| Module | Category | Primary Detection Techniques & Heuristics |
| :--- | :--- | :--- |
| persistence_detector.py | Persistence | • Scans HKLM and HKCU Run, RunOnce, RunServices, and StartupApproved keys (including Wow6432Node).<br>• Flags orphaned autostart entries pointing to non-existent binaries.<br>• Flags entries pointing to user-writable paths (%TEMP%, %APPDATA%, C:\Users\*).<br>• Flags unsigned autostart executables.<br>• Audits User and All Users Startup folders for non-shortcut files (.exe, .bat, .vbs, .ps1, .js).<br>• Identifies unquoted autostart and service paths containing spaces (CWE-428). |
| process_detector.py | Process Spoofing / A | • running processes claiming critical system names (s.exe, lsass.exe, csrss.exe, winlogon.exe, services.exe, smss.exe, explorer.exe) against canonical system paths.<br>• Detects process typosquatting and lookalikes using Le distance and homoglyph mapping (s.exe, 1sass.exe, scvhost.exe, csrs.exe, winlog0n.exe, ser.exe).<br>• Identifies trailing whitespace or dot abuse (s.exe ).<br>• Scans process command lines for offensive tool indicators (mimikatz, meterpreter, cobaltstrike, beacon, stealer, etc.).<br>• Flags unsigned or untrusted binaries running from system directories (System32, SysWOW64).<br>• Measures Shannon entropy on the first 4KB of executables, flagging packed or encrypted PE binaries ($H > 7.5$). |
| keylogger_detector.py | Keylogging | • Inspects AppInit_DLLs and LoadAppInit_DLLs in 32-bit and 64-bit registry hives for global DLL injection.<br>• Audits loaded modules (DLLs) of running processes for third-party hook libraries (hook, keylog), filtering out legitimate signed system DLLs.<br>• Scans process arguments for keyboard interception APIs (SetWindowsHookEx, WH_KEYBOARD, WH_KEYBOARD_LL, GetAsyncKeyState, GetKeyboardState, RegisterRawInputDevices). |
| credential_theft_detector.py | Credential Theft | • Detects process command lines in known dumping tools (mimikatz, sekurlsa, wce, pwdump, procdump, safetykatz, nanodump, sharpsecdump, lazagne, pypykatz, dumpert).<br>• Detects command lines targeting LSASS memory (lsass combined with dump, minidump, inject, or read).<br>• Detects nati memory dumping via comsvcs.dll (rundll32.exe ... comsvcs.dll, #24 or MiniDump).<br>• Heuristic e of LSASS process access permissions and elevated token pri (SeDebugPri). |
| sur.py | Covert Sur | • Detects processes or services associated with covert screen capture, webcam/microphone recording, or hidden VNC.<br>• Whitelists legitimate system and tools (mstsc.exe, , .exe, .exe, perfmon.exe, taskmgr.exe).<br>• Analyzes Scheduled Tasks for automated screenshot grabbers (PowerShell scripts in CopyFromScreen, System.Drawing, Graphics, nircmd, ffmpeg -f gdigrab). |
| hidden_install_detector.py | Hidden Installation | • Enumerates Windows services and scheduled tasks whose executable paths point to %TEMP%, %APPDATA%, or user profile directories.<br>• Identifies auto-start services lacking display names or descriptions.<br>• Flags unquoted service and task paths containing spaces (CWE-428). |

---

Detection Methodology

The scanner employs a multi-tiered inspection model:
1. Host Context & Pri E: administrator ele status to adjust scan depth (certain features, such as inspecting LSASS handles and HKLM system hives, require ele).
2. Cascading Telemetry Pro: Collects system state via psutil or wmi when present, falling back gracefully to nati command utilities (tasklist.exe, schtasks.exe, PowerShell CIM cmdlets) or mock pro during testing.
3. Multi-Signal Contextual Correlation: Rather than relying on isolated keyword matches, detections correlate path trust (system ), Authenticode signature , binary Shannon entropy, and command line semantics.
4. Centralized Allowlist Filtering: Software names that match known benign utilities (e.g. Chrome, VS Code) are against execution paths; if an allowlisted name executes from an untrusted location like %TEMP%, the allowlist is bypassed to catch process masquerading.

---

Finding Schema

Every detector outputs findings using the standardized Finding class (detectors/finding.py), which subclasses dict for 100% backward compatibility with dictionary lookups, iteration, and standard JSON serialization:

Schema Fields

| Field | Type | Description |
| :--- | :--- | :--- |
| finding_id | str | Unique finding identifier (FIND-<12_HEX_DIGITS>). |
| rule_id | str or null | Stable rule identifier (e.g. RULE-PROC-MASQUERADE). |
| category | str | Threat category (Persistence, Process Spoofing, Keylogging, etc.). |
| se | str | Se classification (CRITICAL, ALERT, WARN, INFO). |
| confidence | float | Estimated confidence le between 0.05 and 0.99. |
| risk_score | int | Explainable composite risk score bounded between 0 and 100. |
| description | str | Human-readable explanation of the anomaly. |
| e | str | Factual technical e string. |
| recommendation | str or null | Remediation and in guidance. |
| timestamp | str | ISO-8601 UTC timestamp. |
| host | str | Hostname where the anomaly was observed. |
| process | str or null | Process name associated with finding (if applicable). |
| pid | int or null | Integer process ID (if applicable). |
| path | str or null | File, registry key, or task path (if applicable). |
| risk_factors | list[str] | Transparent breakdown of point contributions to the risk score. |

---

Risk Scoring Model

The scanner features a centralized, explainable heuristic scoring engine (detectors/scoring.py).

> Important Note: This scoring system is strictly heuristic and deterministic. It does not use machine learning, probability distributions, or claim scientifically malware classification.

Scoring Formula

$$\text{Risk Score} = \text{clamp}_{[0, 100]}\left(\text{Base Score} + \sum \text{Signal Weights} + \sum \text{Reductions}\right)$$

Point Contributions

* Base Scores by Se:
* CRITICAL: 60
* ALERT (High): 45
* WARN (Medium): 25
* INFO (Low): 10
* Positi Weights:
* known_attack_tool (Mimikatz, PyPyKatz, procdump, nanodump, comsvcs dump): +25
* process_masquerading (Typosquatting lookalike or canonical path ): +25
* user_writable_path (Execution from %TEMP%, %APPDATA%, C:\Users\*): +20
* unsigned_binary (Untrusted or missing Authenticode signature): +15
* high_entropy (Shannon entropy > 7.5 indicating packed/compressed PE): +15
* suspicious_cmdline (Hooks, memory dump syntax, SeDebugPri): +15
* suspicious_persistence (Direct script in startup folder, AppInit_DLLs): +15
* unquoted_path (CWE-428 search path ): +10
* stealth_profile (Auto-start service missing display name or description): +10
* multiple_indicators (Two or more independent positi present): +10
* Mitigating Reductions:
* allowlist_match ( benign application or service): -30
* standard_system_path (Resides in canonical C:\Windows or C:\Program Files): -15

---

Installation

Prerequisites

* Windows 10, Windows 11, or Windows Server 2016+ (Local execution)
* Python 3.8 or higher installed and added to PATH
* Administrator pri recommended for complete into LSASS, system services, and HKLM registry hives.

1. Clone Repository

2. (Optional) Install Dependencies

The core scanner operates using Python's standard library alone. For enhanced process memory mapping, WMI querying, and legacy console coloring:

---

Usage

Full Scan (Default)

Run Specific Detection Modules

Specify Output Log Path

JSON Output Mode (Machine-Readable)

Execution Logging

---

CLI Examples

Command Line Flags (scanner.py)

| Flag | Short | Description |
| :--- | :--- | :--- |
| --output <path> | -o | Specify path for the output audit log file (default: defensi.txt) |
| --module <name...>| -m | Specific module(s) to run (persistence, process, keylogger, credential_theft, sur, hidden_install) |
| --json | | Output pure machine-readable JSON to stdout (suppresses console banner and tables) |
| --no-color | | Disable ANSI terminal color codes |
| -- | -v | Enable debugging output |
| --help | -h | Display usage instructions |

Sample Console Output

---

JSON Example

When invoked with --json, human-readable banners, module progress lines, and summary tables are suppressed from stdout. Standard output provides machine-readable output:

---

Exit Codes

The scanner emits scriptable exit codes suitable for CI/CD or security automation pipelines:
* 0 — Clean scan (no ALERT, CRITICAL, or WARN findings).
* 1 — Suspicious items or anomalies detected (WARN level).
* 2 — High-se threats or IOCs detected (ALERT or CRITICAL level).

---

Remote Endpoint Scanning (remote_scanner.py)

remote_scanner.py orchestrates multi-host security audits across remote Windows endpoints using nati / PowerShell Remoting without requiring permanent agent installations:
1. Dynamically bundles scanner.py and detectors/ into an in-memory zip archive.
2. Deploys the package to target machines under $env:TEMP\DefScanner_<guid>.
3. Executes scanner.py --json --no-color.
4. Retrieves JSON findings o output.
5. Reliably wipes staging directories in a finally block on target endpoints.
6. Generates a consolidated audit log (remote_defensi.txt).

Remote Execution Commands

---

Security Considerations & Credential Handling

* No Hard-Coded Credentials: Passwords are ne in source files, config files, or audit logs.
* Process Table Protection: Subprocess in feeds credentials to PowerShell through standard input (-Command -) and private subprocess en (DEFSCAN_TARGET_PASS) rather than CLI argument strings, pre credential exposure in process listings (Get-Process, ps).
* Recursi: Error strings, remote exceptions, and output dictionaries recursively redact cleartext passwords ([REDACTED]).
* Target & Username : Enforces strict regex on hostnames and usernames before script block interpolation to prevent command injection.
* Temporary Artifact Cleanup: Remote staging folders are wiped inside a guaranteed finally block on target machines.

---

Limitations

* Kernel-Le & Filter Drivers: Filter dri (e.g. hooking kbdclass.sys) operate below user-mode Windows APIs. They do not appear in user-space loaded modules or AppInit_DLLs. Detecting kernel rootkits requires dri enforcement auditing (sigcheck -k), kernel memory analysis, or dedicated EDR sensors.
* In-Memory Process Injection / Process Hollowing: If malicious shellcode is injected directly into an already-running, legitimately signed process (e.g. explorer.exe) without modifying its on-disk binary or command line, userland process enumeration displays the legitimate binary path. Detecting process hollowing requires thread start address analysis or memory scanning (e.g. pe-sieve / moneta).
* WinRM & Network Transport: Remote scanning requires WinRM (TCP 5985/5986) enabled on target endpoints and administrati. Unencrypted WinRM o workgroups without Kerberos/SPNEGO is to interception and not recommended.
* Remote Python Requirement: Remote endpoints must ha 3.x installed and present in PATH.

---

False-Positi

* Centralized Allowlisting: Broad keyword matching can flag legitimate de tools (e.g. Chrome with --enable-logging, Python scripts with logging modules, VS Code windows). The scanner uses detectors/allowlist.py to recognize standard software in canonical directories.
* Location Sensitivity: Allowlisting strictly respects file paths. A process named chrome.exe running from C:\Users\Public or %TEMP% is never allowlisted, ensuring masquerading malware cannot evade detection.
* Compounding E: A single ambiguous keyword (logger, hidden, c2) on standard software does not trigger an ALERT unless accompanied by additional indicators (such as execution from user-writable paths or unsigned binaries).

---

Testing

The scanner includes an automated test suite containing 124 unit, integration, and ad tests:

Test Co

* test_base_detector.py: Base entropy calculation, path extraction, and pri checks.
* test_finding_model.py: Schema conformity, type safety, JSON serialization, and bounding.
* test_scoring_engine.py: Heuristic scoring, compounding indicator bonuses, allowlist reductions, and boundary limits.
* test_false_positi.py: Legitimate software allowlisting, user-writable o protections, and keyword ambiguity handling.
* test_ad.py: Exercises all 15 failure scenarios (missing dependencies, permission rejections, malformed rows, corrupt processes, empty cmdlines).
* test_cli_reporting_enhanced.py: Human-readable summary output, JSON mode suppression, ISO timestamps, and exit codes.
* test_remote_scanner_security.py: Stdin credential passing, password redaction, input , and SSO authentication.
* test_hard_scenarios.py: Typosquatting, homoglyphs, trailing whitespace, 8.3 paths, and LOLBAS dumps.
* test_usermode_applications.py: User-mode threat simulations (keyloggers, stealers, sur, packed droppers).
* test_end_to_end.py: End-to-end requirement scenarios and full scan pipeline execution.

---

Continuous Integration (CI/CD)

Automated testing is configured Actions (.github/workflows/ci.yml):
* Tested across operating systems: ubuntu-latest and windows-latest.
* Tested across Python : 3.8, 3.9, 3.10, 3.11, 3.12, 3.13.
* Enforces syntax compilation (python -m py_compile) and test execution (pytest).

---

Defensive / Read-Only Disclaimer

This project is strictly a defensi security auditing tool. It does not perform destructi, process termination, file deletion, registry remediation, malware deployment, persistence installation, credential theft, or sur. It is intended solely for security analysts, incident responders, and system administrators to audit Windows endpoints defensively.

---

Roadmap

* [ ] Structured export formats for SARIF and STIX 2.1.
* [ ] Local event log auditing (Security Event IDs 4688, 4697, 7045) library APIs.
* [ ] Hash-based threat intelligence lookup against local offline IOC databases.
* [ ] Native YARA rule scanning integration for suspicious autostart executables.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

项目信息

开发语言：Python

Star 数：3

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A modular, read-only defensive security auditing and threat detection tool for Windows 10, Windows 11, and Windows Server 2016+ (Python 3.8+). Designed for incident response, threat hunting, and host integrity auditing, the scanner identifies indicators of compromise (IOCs), autostart persistence mechanisms, process masquerading, credential theft 展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。