A modular Network Reconnaissance & Attack Surface Assessment Platform built entirely from scratch using Python.
Installation • CLI Usage • GUI • Scan Profiles • Architecture • Plugins • Roadmap
SentinelScan is a network reconnaissance and attack surface assessment tool designed for authorized security assessments, network inventory, and educational use. It maps open ports, identifies running services, fingerprints operating systems, and evaluates security configurations — all through scanning logic implemented entirely within this project.
SentinelScan does not invoke, wrap, embed, or depend on Nmap, Masscan, RustScan, Unicornscan, ZMap, or any other external scanning executable. Every port-scanning technique, service detector, banner grabber, fingerprinting method, vulnerability check, and report generator is implemented from scratch in Python.
⚠️ Authorized use only. SentinelScan is intended for systems and networks you own or have explicit written permission to test. It performs passive and active-safe assessment only — it does not implement brute-force authentication, exploitation, or any offensive capability.
This repository contains the official SentinelScan implementations, including the Windows Edition (CLI + PyQt6 desktop GUI) and the Streamlit Edition (browser-based web interface). Both editions are maintained within a single repository to simplify development, issue tracking, and release management while providing different user experiences built around the SentinelScan project. A future Vercel Edition is planned for lightweight web deployment.
Both the Windows Edition and the Streamlit Edition share the same SentinelScan scanning engine and core detection capabilities while providing different user interfaces optimized for their respective platforms.
Port Scanning (10 techniques) TCP Connect, SYN, ACK, FIN, NULL, Xmas, Window, Maimon, Idle (zombie), and UDP scans — each implemented as an independent, documented strategy.
Host Discovery (4 methods) ICMP, ARP, TCP, and UDP discovery, automatically combined for reliable results across firewalled and non-firewalled targets.
Graceful Privilege Handling Raw-socket techniques (SYN/ACK/FIN/NULL/Xmas/Window/Maimon/Idle scans, ICMP/ARP discovery, OS fingerprinting) automatically detect whether Administrator privileges are available and fall back to TCP-based equivalents when they aren't — the application never crashes or aborts a scan due to missing privileges or an unusable network interface.
Service & Protocol Detection Banner grabbing and protocol probes for HTTP, HTTPS, SSH, FTP, SMTP, and DNS, plus a generic passive-banner fallback, with a confidence-scored (Confirmed / Probable / Speculative) identification model.
TLS/SSL Analysis Protocol version, cipher suite, and certificate inspection, with detection of weak/deprecated protocols, expired certificates, and self-signed certificates.
Independent OS Fingerprinting Heuristic fingerprinting from TTL, TCP window size, and TCP options, returning a confidence score rather than a false-certain answer.
Safe Vulnerability Assessment Passive checks (weak TLS, plaintext protocols) and active-safe checks (anonymous FTP detection, risky HTTP method detection) — no brute-force, no exploitation, by design.
Network Mapping & Attack Surface Analysis Topology summarization and attack-surface reporting, including a dedicated view of exposed remote-management services (RDP, SSH, WinRM, VNC, Telnet).
Reporting Professional reports in JSON, CSV, HTML, and PDF (PDF generated natively with ReportLab — not an HTML-to-PDF conversion), including executive summary, findings, risk levels, and recommendations.
Plugin Framework Extend detection, vulnerability checks, reporting, and export behavior without touching the core engine — see Plugin Support.
Professional CLI and Desktop GUI A scriptable command-line interface and a PyQt6 desktop application, both driven by the same underlying scan engine.
Persistence & Observability SQLite-backed scan history, externalized YAML configuration, and structured JSON logging.
SentinelScan follows a layered architecture with strict separation of concerns — no layer reaches into the internals of a layer above it, and only one module (core.packet.raw_socket) ever performs raw Scapy I/O directly.
Presentation → gui/ (PyQt6 desktop app) · cli/ (command-line interface)
Application → core/orchestrator.py (coordinates every scan phase)
Scan Engine → core/scanner/ (10 scan strategies + discovery + privilege handling)
Analysis → core/detection/ · core/vuln/ · core/mapping/
Reporting → reporting/ (JSON / CSV / HTML / PDF generators)
Storage → storage/ (SQLite history, YAML config)
Plugin Layer → plugins/ (filesystem-manifest-based discovery)
Every module is documented in-place with its Purpose, Internal Workflow, Design Decisions, and Public API — see docs/DEVELOPER_GUIDE.md and docs/API_REFERENCE.md for the full module map.
Requirements: Windows 10/11, Python 3.12+. Administrator privileges are optional — required only to unlock raw-socket scan techniques; everything else runs as a standard user.
git clone https://github.com/Shubh404-glitch/SentinelScan.git
cd SentinelScan
py -3.12 -m venv .venv
.venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements.txt
pip install -e .Verify the install:
sentinelscan check-privileges
sentinelscan profiles listFull setup, PyInstaller packaging, and privilege details are in docs/INSTALLATION.md.
The Streamlit Edition provides a browser-based interface powered by the same SentinelScan project. To launch it:
cd "Streamlit edition"
pip install -r requirements.txt
streamlit run app.py# Check whether raw-socket scanning is available in the current session
sentinelscan check-privileges
# List the built-in scan profiles
sentinelscan profiles list
# Run a scan (authorization confirmation is required)
sentinelscan scan --targets 192.168.1.0/24 --profile quick --i-am-authorized
# Run an Attack Surface Assessment with all report formats
sentinelscan scan --targets example.com --profile attack_surface \
--formats json,csv,html,pdf --i-am-authorized
# Override ports and scan types for a custom run
sentinelscan scan --targets 10.0.0.5 --profile custom \
--ports 1-1024,8080,8443 --scan-types tcp_syn,tcp_connect --i-am-authorized
# View scan history
sentinelscan history list
sentinelscan history show --scan-id <scan-id>Full flag reference: docs/USER_GUIDE.md.
Launch the desktop application with:
sentinelscan-guiThe GUI is built with PyQt6 and provides eight views, all driven by the same scan engine as the CLI:
| View | Purpose |
|---|---|
| Dashboard | Recent scan history and at-a-glance statistics |
| New Scan | Configure targets, scan profile, ports, and concurrency; confirm authorization; launch |
| Live Progress | Real-time event log while a scan runs |
| Reports | Select a past scan, generate a report in any format, and open it |
| Plugin Manager | View discovered detector/vuln/report/export plugins |
| Profile Manager | Reference table of the built-in scan profiles |
| Settings | Timeouts, concurrency, default profile, log level, directories |
| Logs | View the structured application log |
Scans run on a background thread via an async/Qt bridge, so the interface never freezes during long scans, and progress streams live into the Live Progress view.
The Streamlit Edition provides:
- Browser-based interface
- Live scan progress
- Interactive reports
- Dashboard
- Plugin Manager
- Settings
- Logs
- Network Map visualization
Launch it with:
streamlit run app.py
| Profile | Description |
|---|---|
| Quick Scan | Top common ports, fast discovery, service detection |
| Full TCP Scan | All 65,535 TCP ports, service detection, banner grabbing |
| Full TCP + UDP Scan | Full TCP plus common UDP ports, extended service detection |
| Stealth Scan | SYN scan, reduced timing, minimal footprint |
| Service Enumeration | Banner grabbing, protocol detection, version detection |
| Attack Surface Assessment | Remote management services, TLS analysis, certificates, safe vulnerability checks |
| Custom | Fully user-defined ports, scan types, and detection options |
Every scan can generate reports in:
- JSON — full machine-readable scan result + derived summary, for automation and SIEM ingestion
- CSV — flat, spreadsheet-friendly export of open ports and services
- HTML — professional, styled report for on-screen review or sharing
- PDF — generated natively with ReportLab (not an HTML-to-PDF conversion), suitable for management/technical audiences
Reports include an executive summary, target information, scan metadata, open ports, services, banners, OS fingerprinting results, risk levels, security findings, recommendations, and attack-surface statistics.
SentinelScan can be extended without modifying the core engine. Plugins are discovered from a filesystem directory, each with a plugin.toml manifest and a Python module implementing one of four interfaces:
- DetectorPlugin — add recognition for a service the core doesn't cover
- VulnPlugin — add a custom finding/vulnerability check
- ReportPlugin — add a custom report section
- ExportPlugin — send results to an external system
A plugin that raises an exception is logged and skipped — it never aborts a scan. See docs/PLUGIN_GUIDE.md and the working example in src/sentinelscan/plugins/examples/.
SentinelScan ships with a tiered automated test suite — 22/22 tests passing as of v1.0.1 — covering:
- Unit tests — domain models, port-range parsing, privilege/fallback logic, risk scoring, service detection, OS fingerprinting resilience, raw-socket transmission-failure handling
- Integration tests — real localhost scans through the orchestrator, including resilience regression tests for optional-phase failures
- End-to-end tests — full scan-to-report pipeline across all four report formats
- Performance tests — throughput smoke tests for large port ranges
Both the Windows Edition and the Streamlit Edition have been independently tested and validated prior to release.
pytest
pytest --cov=sentinelscan --cov-report=term-missingSentinelScan/
├── src/sentinelscan/ # Windows Edition source
├── Streamlit edition/ # Streamlit Edition
├── docs/
├── tests/
├── assets/
├── build/
├── LICENSE
├── README.md
└── CHANGELOG.md
SentinelScan consists of multiple official editions, each designed for a different deployment experience while sharing the same overall project vision:
- ✅ Windows Edition — Stable (v1.0.1)
- ✅ Streamlit Edition — Stable (v1.0)
- 🚧 Vercel Edition — Planned
Toward v2.0:
- Additional protocol probes (SMB, RDP, MQTT, database protocols)
- Expanded plugin ecosystem and a plugin marketplace/registry
- Richer network topology visualization
- Signed, notarized release builds
Contributions are welcome — see docs/CONTRIBUTING.md for guidelines, including the project's hard rule against depending on any external scanning executable.
- Installation Guide
- User Guide
- Developer Guide
- Plugin Guide
- API Reference
- Troubleshooting
- Changelog
- Contributing
Released under the MIT License © Shubh Sharma.
SentinelScan is provided for authorized security assessment, network inventory, and educational purposes only. The author is not responsible for misuse or damage caused by this tool. Always obtain explicit permission before scanning any system or network you do not own.