Skip to content

About

NetSentinel is a Windows-first desktop application for defensive network visibility and authorized security auditing. It is being developed as a modular Python portfolio project with a PySide6 interface, SQLite persistence, Scapy/Npcap discovery, optional Nmap service detection, and evidence-based reporting.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

NetSentinel

NetSentinel is a Windows-first desktop application for defensive network visibility and authorized security auditing. It is being developed as a modular Python portfolio project with a PySide6 interface, SQLite persistence, Scapy/Npcap discovery, optional Nmap service detection, and evidence-based reporting.

Development status: NetSentinel currently provides its project shell, domain safety layer, SQLite persistence, authorized discovery and bounded TCP Connect services, reusable Qt workers, desktop controls for those two operations, and a read-only local Network Monitor backed by psutil. The scan controls require a normalized local scope, operator identity, reason, explicit confirmation, and a second confirmation dialog before work is queued. The current build does not run Nmap from the UI or claim to implement any security assessment.

Project goals

The project will provide a clear workflow for authorized operators:

  1. Define and confirm an explicit target scope.
  2. Run bounded discovery and TCP checks without blocking the interface.
  3. Normalize results into a persistent device and service inventory.
  4. Produce security observations only when supported by collected evidence.
  5. Export reproducible JSON, CSV, and PDF reports.

NetSentinel will not include exploitation, credential attacks, brute force, denial-of-service behavior, or unrestricted target expansion.

Planned features

  • Network Discovery: authorized local IPv4 discovery through Scapy and Npcap, including IP, MAC, OUI/vendor, hostname, latency, and state where available.
  • Port Scanner: bounded TCP Connect checks with custom ports, common port profiles, timeouts, progress, cancellation, and optional Nmap service/version detection.
  • Network Monitor: Windows-compatible interface enumeration and traffic counters with periodic updates and real-time charts.
  • Device Inventory: persistent first/last-seen records, search, filtering, and CSV/JSON export.
  • Security Assessment: deterministic, evidence-linked observations, recommendations, severity, confidence, and an explicitly heuristic risk score.
  • Reports: versioned JSON and CSV exports plus PDF reports containing scope, timestamps, assets, ports, findings, and limitations.
  • Desktop UI: dark PySide6 interface with navigation for Dashboard, Discovery, Port Scanner, Monitor, Inventory, Assessment, Reports, Settings, and About.

Features are added stage by stage. The checklist in TODO.md is the source of truth for what is complete.

Technology stack

  • Python 3.12+
  • PySide6
  • SQLite via Python's standard-library sqlite3
  • Scapy with Npcap on Windows for authorized local discovery
  • Nmap executable for optional service and version detection
  • psutil for interface statistics
  • pyqtgraph for charts
  • ReportLab for PDF generation
  • pytest, pytest-qt, Ruff, and mypy for development quality checks

Repository structure

NetSentinel/
├── main.py
├── pyproject.toml
├── README.md
├── LICENSE
├── CHANGELOG.md
├── TODO.md
├── src/netsentinel/
│   ├── domain/          # Framework-independent models and policies
│   ├── application/     # Use cases and orchestration
│   ├── infrastructure/  # SQLite, OS, Scapy, Nmap, and logging adapters
│   ├── reporting/       # Export and report rendering
│   └── ui/              # PySide6 windows, views, and workers
├── tests/
├── assets/
└── data/                # Local runtime data, ignored by Git

Requirements

  • Windows 10 or Windows 11 for the primary supported environment.
  • Python 3.12 or newer.
  • Npcap for Scapy packet operations. Some operations may require suitable permissions depending on the selected interface and Windows configuration.
  • Nmap installed separately and available on PATH or configured explicitly when service/version detection is enabled.
  • A network scope that the operator is authorized to audit.

Npcap and Nmap are external tools with their own licensing and installation requirements. NetSentinel does not bundle them in this repository.

Installation

Create a virtual environment and install the project with development tools:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Check the local Python configuration without starting the GUI:

python -m netsentinel --check-config

Start the current application shell:

python -m netsentinel

The desktop currently exposes authorized Network Discovery and TCP Port Scanner controls plus a read-only Network Monitor. Scan operations validate the scope and resource limits, record operator authorization in SQLite, and run through a background worker with progress and cooperative cancellation. The monitor reads local interface counters through psutil on a configurable timer and does not send network probes. Discovery still requires Scapy/Npcap on Windows; the default test suite uses fake adapters and does not generate traffic. Nmap service detection and the remaining audit modules remain library-only or planned.

Development checks

Run the checks from the activated virtual environment:

python -m pytest
ruff check .
mypy src

The default test suite will use fake adapters and local temporary data. It will not scan arbitrary hosts, require Npcap, or launch Nmap. Windows/Npcap/Nmap integration tests will be explicitly marked and opt-in.

Configuration

Runtime configuration is read from a typed configuration object and validated before a job starts. The current bootstrap supports these settings:

  • SQLite database location and report output directory.
  • Nmap executable path.
  • Selected network interface.
  • Timeout, rate, concurrency, maximum port, and maximum scope limits. These can be overridden with the NETSENTINEL_* environment variables used by the bootstrap configuration.
  • Logging level and retention settings.

The database path can be overridden with NETSENTINEL_DATABASE_PATH. Credentials and secrets will not be stored in the project configuration.

Responsible use

NetSentinel is for defensive auditing of networks and systems where the operator has explicit authorization. Before any active feature runs, the application will display the normalized scope and require confirmation. Every active operation will be bounded by policy and recorded in an audit trail.

Do not use NetSentinel to scan systems or networks without permission. The authors are not responsible for misuse, service disruption, privacy violations, or legal consequences caused by operating the software outside an authorized scope.

Documentation and contributions

The project follows a staged development process. Review TODO.md for current work and CHANGELOG.md for verified changes. Contributions should preserve the domain/infrastructure/UI boundaries, add tests for new behavior, document Windows prerequisites, and avoid introducing unsafe active operations.

Please do not submit real scan data, credentials, packet captures, or other sensitive artifacts in issues or pull requests.

License

NetSentinel is released under the MIT License. External dependencies remain subject to their respective licenses.

About

NetSentinel is a Windows-first desktop application for defensive network visibility and authorized security auditing. It is being developed as a modular Python portfolio project with a PySide6 interface, SQLite persistence, Scapy/Npcap discovery, optional Nmap service detection, and evidence-based reporting.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages