Passive, policy-driven network detection framework that performs kernel-assisted packet capture and deep packet inspection in user space to identify violations of defined security policies in live network traffic.
Architecture · Policy Configuration · Detection Logic · Tests · Source
SentinelNet is a passive network detection framework designed to identify insecure protocols, cleartext authentication, and legacy communication patterns that violate defined security policies in enterprise-style networks.
flowchart TB
A["Policy Configuration<br/>Capture · Rules · Output"] --> B["SentinelNet Core"]
B --> C["Detection Engine<br/>Stateless Packet Evaluation"]
C --> D["Alert Pipeline<br/>Structured Events"]
D --> E1["Machine Output<br/>alerts.jsonl"]
D --> E2["Human Output<br/>alerts.log / console"]
F["Live Network Traffic"] --> B
The tool emphasizes defensive visibility, policy-driven analysis, and explainable alerts, modeling how SOC teams reason about network risk rather than focusing on raw packet capture or active enforcement. SentinelNet is intended as a research and learning framework for understanding network security monitoring, protocol risk analysis, and detection engineering concepts in controlled lab environments.
-
src/
Core detection engine and packet processing logic. Modules handle packet capture, protocol parsing, and policy evaluation. -
policies/
Configuration files defining allowed and disallowed protocols, authentication rules, and network behavior expectations. -
docs/
Detailed documentation covering detection logic, supported policy rules, and analysis methodology for each detection category. -
logs/
Structured alert and event logs generated by the detector (.jsonl,.log), suitable for ingestion into SIEM platforms or further analysis. -
tests/
Controlled packet construction and validation tests used to verify detection accuracy. These tests simulate policy-violating traffic patterns for validation purposes only.
Identifies traffic using insecure or deprecated protocols such as FTP, Telnet, or other cleartext services that violate defined network policy.
Inspects packet payloads to detect authentication credentials transmitted without encryption, including HTTP Basic Authentication and legacy login mechanisms.
Flags traffic that violates explicitly defined policy rules, such as the use of disallowed ports or legacy name resolution services within internal networks.
Detects services commonly disabled in hardened environments, such as NetBIOS, LLMNR, or SMBv1, to highlight unnecessary attack surface.
Each detection generates a structured event describing:
- Source and destination context
- Protocol and service involved
- Policy rule violated
- Severity and justification
This section outlines how to run SentinelNet locally after downloading or cloning the repository.
SentinelNet is developed and tested using Python 3.11+.
Ensure Python and pip are installed and available in your system path.
Verify your installation:
python --version
pip --versionNote
If Python is not installed, download it from:
https://www.python.org/downloads/
git clone https://github.com/<your-username>/SentinelNet.git
cd SentinelNetSentinelNet relies on Scapy for packet capture and inspection.
Install required Python packages:
pip install -r requirements.txtIf running tests or modifying the detection logic, install pytest as well:
pip install pytestPacket capture may require elevated privileges depending on your operating system and network interface.
The detection engine is executed from the src/ directory and is driven by a JSON-based policy file located in policies/ by default.
Basic example:
python src/sentinelnet.pyCommon options:
--policy: Path to the policy configuration file--iface: Network interface to monitor--count: Optional packet limit (0 = unlimited)
python src/sentinelnet.py --policy policies/default.json --iface "Ethernet"SentinelNet will begin passively capturing traffic and generating alerts based on the active policy rules.
By default, SentinelNet generates:
- Machine-readable alerts (
alerts.jsonl) suitable for parsing or SIEM ingestion - Human-readable logs (
alerts.log) for direct review
Output behavior and paths can be customized in the policy file.
SentinelNet includes unit tests that validate detection behavior using constructed packets.
From the project root, run:
pytestAll tests should pass before modifying detection logic or policies
This section provides safe, reproducible commands that can be used to generate network activity and validate SentinelNet detection behavior.
All examples below produce real alerts and populate both alerts.jsonl and alerts.log.
These actions are benign test scenarios, not exploits.
Ensure SentinelNet is running and actively capturing traffic:
python src/sentinelnet.py --policy policies/default.json --iface "Ethernet"Notes:
- Some commands require a second machine or VM on the same network (recommended)
- Alternatively, target your router or another reachable LAN host
- Packet capture may require elevated privileges depending on your OS
This detection is commonly triggered automatically on Windows systems but can be forced manually.
Windows
ping nonexistentsentinelhostWhy this works
- Windows attempts LLMNR / NBNS name resolution
- Generates UDP traffic on ports 5355 (LLMNR) or 137 (NBNS)
- SentinelNet logs
LEGACY_NAME_RESOLUTION
This is the fastest way to generate immediate alert output.
ftp <target-ip>Even a failed connection attempt is sufficient.
Expected alert
DISALLOWED_PORTservice: FTP
telnet <target-ip>Triggers immediately on connection attempt.
Linux / WSL
nc <target-ip> 445Windows
net use \\<target-ip>\shareThis is one of SentinelNet’s most visible detections.
curl -u testuser:testpass http://<target-ip>/Why this works
- Sends an
Authorization: Basic <base64>header - SentinelNet detects and decodes the credential payload
- Logs
CLEARTEXT_HTTP_BASIC_AUTH - Evidence field is populated when possible
$pair = "user:pass"
$bytes = [System.Text.Encoding]::UTF8.GetBytes($pair)
$encoded = [Convert]::ToBase64String($bytes)
Invoke-WebRequest http://<target-ip>/ -Headers @{
Authorization = "Basic $encoded"
}ftp <target-ip>Then enter:
USER testuser
PASS testpass
Expected alert
FTP_CLEARTEXT_CREDENTIALS- Evidence may include extracted username and password (best effort)
Run the following commands in quick succession:
ping fakehost123
curl -u admin:admin http://<target-ip>/
ftp <target-ip>
telnet <target-ip>This will generate:
- Legacy name resolution alerts
- HTTP Basic Authentication alerts
- Disallowed port alerts
- FTP cleartext credential alerts
This scenario is ideal for demonstrating multiple detections back-to-back in the log files.
To explicitly trigger legacy UDP detections:
nc -u <target-ip> 137
nc -u <target-ip> 5355After running the commands above, SentinelNet will generate alerts such as:
LEGACY_NAME_RESOLUTIONDISALLOWED_PORTCLEARTEXT_HTTP_BASIC_AUTHFTP_CLEARTEXT_CREDENTIALS
Alerts will include:
- Varying severity levels
- Different protocol and service identifiers
- Evidence fields where applicable
- Clean, UTC timestamps
For documentation or demonstration purposes:
- Run SentinelNet in one terminal
- Generate test traffic in another
- Capture screenshots of:
- Console output
alerts.jsonlalerts.log
This provides a clear, end-to-end demonstration of SentinelNet’s detection capabilities.
This project is licensed under the MIT License.