NetSentinel

A terminal-based Intrusion Detection System written in modern C++.

---

Overview

NetSentinel is a defensive, terminal-first Intrusion Detection System built in modern C++17. It analyzes live network packets or simulated network events, detects suspicious behavior, prints color-coded alerts directly in the terminal, and stores local event and alert logs for later review.

The project focuses on practical blue-team use cases such as TCP port scan detection, SSH brute force detection, event logging, alert filtering, configurable thresholds, and real-time terminal monitoring.

Keywords

intrusion-detection-system ids network-security cybersecurity cpp cplusplus terminal cli blue-team security-monitoring port-scan-detection ssh-bruteforce-detection packet-analysis real-time-monitoring network-analysis threat-detection security-tool defensive-security

Features

• Live packet analysis with libpcap
• Auto interface selection or explicit interface selection with --interface
• Simulation mode for safe defensive testing
• TCP, UDP, and ICMP network event normalization
• TCP port scan detection
• Network-based SSH brute force detection
• Configurable detection thresholds
• Color-coded terminal output
• Severity-specific alert colors
• Suspicion scoring per source IP
• Security summary with reasons and recommendations
• Local event and alert logging
• CLI-based stored alert filtering
• Modular detection engine
• Lightweight C++ tests for detection rules

Terminal First

NetSentinel does not use a web dashboard. All interaction happens through the terminal.

Running ./netsentinel starts live packet analysis using the configured interface. If the interface is set to auto, NetSentinel chooses the first non-loopback capture interface found by libpcap.

Live capture may require administrator permissions:

sudo ./netsentinel

Use simulation mode when you want safe deterministic test traffic:

./netsentinel --simulate

Example output:

[INFO] NetSentinel started
[INFO] Config: config/ids.conf
[INFO] Analyzing live packets on interface en0 for 100 packets
[EVENT] 2026-06-12 14:20:31 192.168.1.80:50000 -> 192.168.1.10:20 TCP
[ALERT][MEDIUM][PORT_SCAN] 192.168.1.80 contacted 10 unique TCP ports in 10s
[ALERT][HIGH][SSH_BRUTE_FORCE] 192.168.1.50 attempted 15 SSH connections in 30s
[STATUS] Processed events: 65
[STATUS] Generated alerts: 2
[SECURITY SUMMARY] Source reputation
- 192.168.1.80 score 84 CRITICAL | events=10 alerts=1 unique_ports=10 unique_hosts=1
  reason: Triggered MEDIUM PORT_SCAN alert
  recommendation: Investigate immediately, identify the device, and isolate it if it is unknown.

Alert colors:

• LOW: green
• MEDIUM: yellow
• HIGH: magenta
• CRITICAL: bold red background

Architecture

NetSentinel
├── Capture / Input
│   ├── LiveCapture reads TCP, UDP, and ICMP packets with libpcap
│   └── EventSimulator generates safe defensive test events
├── Event Model
│   └── NetworkEvent represents normalized network activity
├── Detection Engine
│   └── Runs detection rules over event streams
├── Detection Rules
│   └── Contains port scan and SSH brute force detection
├── Alert Manager
│   └── Stores and formats security alerts
├── Security Analyzer
│   └── Scores source IPs and explains suspicious behavior
├── Storage / Logging
│   └── Writes events and alerts locally
├── Configuration
│   └── Loads thresholds and runtime settings
└── Terminal UI / CLI
    └── Displays live events, alerts, status, and filters

Tech Stack

• Language: C++17
• Interface: Terminal / CLI
• Build systems: Makefile and CMake
• Packet capture: libpcap
• Storage: Local log files
• Testing: Lightweight C++ test executable

libpcap is the only external runtime dependency. It is used only for defensive packet capture and network event analysis.

Build

Using Make:

make

Using CMake:

cmake -S . -B build
cmake --build build

Presentation Demo

For a short teacher presentation, use the deterministic demo mode. It does not require live suspicious traffic and is safe to run.

make
make test
./netsentinel --simulate --config config/demo.conf

What to explain during the demo:

• NetSentinel starts with a terminal banner.
• EventSimulator creates normal traffic and suspicious patterns.
• DetectionEngine sends each event through detection rules.
• DetectionRules detects port scans and repeated SSH connections.
• AlertManager prints colored alerts.
• SecurityAnalyzer ranks suspicious source IPs and explains why.
• FileLogger writes events and alerts into local log files.

Good one-sentence summary:

NetSentinel is a modular terminal-based IDS prototype that captures or simulates network events, applies detection rules, prints colored alerts, logs the results, and explains suspicious source IP behavior.

Run

For the presentation, these are the only runtime commands you need to show.

Run the safe demo:

./netsentinel --simulate --config config/demo.conf

Start live packet analysis:

sudo ./netsentinel

Choose a specific Wi-Fi or network interface if needed:

sudo ./netsentinel --interface en0
sudo ./netsentinel --interface wlan0

Show help:

./netsentinel --help

Configuration

Default configuration lives in config/ids.conf.

# Live capture
live_capture_interface=auto
live_capture_packet_count=100

# Detection thresholds
port_scan_port_threshold=10
ssh_brute_force_attempt_threshold=15

# Terminal output
ansi_color_enabled=true

Values not listed in the file use safe defaults from the code. This keeps the project easier to explain while still allowing advanced tuning later.

For the presentation demo, use config/demo.conf:

port_scan_port_threshold=5
ssh_brute_force_attempt_threshold=6
simulation_event_count=40
ansi_color_enabled=true

The demo thresholds are lower so the simulated run creates alerts quickly.

Supported severities:

• LOW
• MEDIUM
• HIGH
• CRITICAL

Supported alert types:

• PORT_SCAN
• SSH_BRUTE_FORCE

Source Reputation

NetSentinel does not only print packets. It also builds a source-IP reputation profile while traffic is processed.

Each source IP receives a suspicion score from 0 to 100 based on:

• triggered alerts
• alert severity
• contact with risky service ports such as SSH, Telnet, SMB, RDP, VNC, Redis, and Elasticsearch
• number of unique destination ports
• number of unique destination hosts

Score bands:

• 0-24: LOW
• 25-49: MEDIUM
• 50-79: HIGH
• 80-100: CRITICAL

At the end of a run, NetSentinel prints a security summary with the most suspicious source IPs, the reasons for the score, and a recommended next action.

Detection Rules

TCP Port Scan Detection

NetSentinel detects potential port scans by tracking how many unique TCP destination ports a single source IP contacts within a configurable time window.

Example rule:

If one source IP contacts 10 or more unique destination ports within 10 seconds,
generate a PORT_SCAN alert.

Generated alert metadata includes:

• unique_ports
• port_summary
• window_seconds

SSH Brute Force Detection

NetSentinel currently performs network-based SSH brute force detection. It does not read authentication logs.

An SSH brute force alert is generated when one source IP makes repeated TCP connections to the configured SSH port within the configured time window.

Example rule:

If one source IP performs 15 or more SSH connections within 30 seconds,
generate an SSH_BRUTE_FORCE alert.

Generated alert metadata includes:

• attempt_count
• ssh_port
• window_seconds
• detection_source=network_connections

Logs

NetSentinel stores local logs for later analysis:

logs/events.log
logs/alerts.log

Log files are runtime artifacts and are not committed.

Running Tests

make test

The tests cover:

• Port scan detection above threshold
• Port scan behavior below threshold
• SSH brute force detection above threshold
• SSH brute force behavior below threshold
• Alert field validation
• Source reputation scoring
• Configuration loading

Security Scope

NetSentinel is a defensive security monitoring tool.

This project does not include and should not include:

• Exploit code
• Malware
• Offensive scanning tools
• Brute force tools
• Credential attacks
• Persistence techniques
• Security bypass functionality

The purpose of this project is detection, monitoring, alerting, and learning.

Roadmap

• Add authentication log parsing for SSH failures
• Add SQLite storage backend
• Add allowlist and blocklist support
• Add export to JSON or CSV
• Add more defensive detection rules
• Improve terminal dashboard view

Author

Created by Iliass Alami-Qammouri.