NetSentry

Advanced Network Monitoring and Analysis System

Overview • Features • Architecture • Installation • API • Dashboard • Contributing

Overview

NetSentry is a high-performance, extensible network monitoring system built with modern C++. It combines real-time system metrics collection, network packet analysis, and sophisticated alerting capabilities to provide comprehensive visibility into your network infrastructure.

Key Features

Feature	Description
Advanced System Monitoring	• Real-time CPU, memory, and disk metrics • Process-level resource tracking • Performance trend analysis
Deep Network Analysis	• Packet capture and inspection • Protocol detection (HTTP, DNS, TLS) • Traffic pattern recognition • Connection tracking
Sophisticated Alert System	• Configurable thresholds and conditions • Multi-channel notifications • Alert correlation and grouping
Powerful Visualization	• Real-time dashboards • Historical metrics exploration • Network traffic graphs • Prometheus/Grafana integration
Modern API Architecture	• RESTful API with comprehensive endpoints • Real-time data streaming • Seamless third-party integration
Enterprise-Grade Deployment	• Docker containerization • Kubernetes orchestration • High-availability configurations • Horizontal scaling support

Technical Architecture

NetSentry leverages cutting-edge C++17 features and software design principles:

Core Metrics Engine: High-performance time-series metrics collection
Network Analysis Module: Deep packet inspection and protocol analysis
Custom Memory Management: Optimized memory pools and allocators
Thread-Safe Concurrency: Lock-free algorithms and robust synchronization
Pluggable Alert System: Policy-based design for flexible alerting
Data Storage Layer: Configurable retention and storage backends
RESTful API Layer: Modern API for data access and control
Web Dashboard: Real-time visualization interface

Performance Benchmarks

Metric	Value	Conditions
Packet processing rate	2.4M packets/sec	Single thread, 10GbE interface
CPU overhead	< 3% per core	Intel Xeon E5-2680v4
Memory usage	~120MB base + ~2GB/10Gbps	Full packet capture enabled
Storage efficiency	~200MB/day/host	Default metrics collection
Alert latency	< 500ms	From event trigger to notification

Getting Started

Quick Start with Docker

The easiest way to get started with NetSentry is using Docker:

# Clone the repository
git clone https://github.com/muhkartal/netsentry.git
cd netsentry

# Run the installation script
chmod +x install.sh
./install.sh

This will set up NetSentry with Prometheus and Grafana for a complete monitoring stack.

Manual Installation

Click to expand installation instructions

Prerequisites

C++17 compatible compiler (GCC 8+, Clang 7+)
CMake 3.14+
libpcap development libraries
Boost libraries (system, filesystem)

Building from Source

# Clone the repository
git clone https://github.com/muhkartal/netsentry.git
cd netsentry

# Create build directory
mkdir build && cd build

# Configure and build
cmake ..
make -j$(nproc)

# Install (optional)
sudo make install

Verifying Installation

After installation, verify that NetSentry is running correctly:

# Check service status
netsentry --version
netsentry --check-config

# Start the service
netsentry --config /path/to/config.yaml

Kubernetes Deployment

Click to expand Kubernetes deployment instructions

For production environments, we provide Kubernetes manifests:

# Apply Kubernetes configuration
kubectl apply -f kubernetes/deployment.yaml

# Check deployment status
kubectl get pods -l app=netsentry

# Verify services are running
kubectl get services -l app=netsentry

# Access the dashboard
kubectl port-forward svc/netsentry-dashboard 9090:9090

For high-availability deployment, see kubernetes/ha-deployment.yaml.

Configuration

NetSentry uses YAML for configuration. The default configuration file is located at configs/netsentry.yaml:

# Example configuration
log_level: "info"
enable_api: true
api_port: 8080
enable_web: true
web_port: 9090
enable_packet_capture: true
capture_interface: "eth0"

Click to expand advanced configuration options

Advanced Configuration

# Storage configuration
storage:
   type: "prometheus" # Options: prometheus, influxdb, local
   retention_days: 30
   local_path: "/var/lib/netsentry/data"
   remote_url: "http://prometheus:9090"

# Network analysis configuration
network_analysis:
   capture_interfaces: ["eth0", "eth1"]
   bpf_filter: "not port 22"
   capture_snaplen: 96
   enable_protocol_detection: true
   enable_geolocation: true
   protocols:
      - http
      - dns
      - tls
      - smtp

# Alert configuration
alerts:
   config_path: "/etc/netsentry/alerts/"
   notification_channels:
      - type: "email"
        recipients: ["admin@example.com"]
      - type: "webhook"
        url: "https://hooks.slack.com/services/XXX/YYY/ZZZ"
      - type: "prometheus-alertmanager"
        url: "http://alertmanager:9093/api/v1/alerts"

# Performance tuning
performance:
   threads: 4 # 0 = auto-detect
   packet_batch_size: 1024
   use_zero_copy: true
   memory_limit_mb: 2048
   enable_lock_free_queues: true

See the Configuration Guide for complete documentation.

Usage Examples

Monitoring System Resources

NetSentry automatically collects CPU, memory, and disk metrics out of the box:

# View real-time system metrics
curl http://localhost:8080/api/v1/metrics

Example Response

{
   "timestamp": "2023-07-25T15:21:33Z",
   "host": "server-prod-01",
   "metrics": {
      "cpu": {
         "usage_percent": 23.5,
         "load_avg_1m": 1.23,
         "load_avg_5m": 1.15,
         "load_avg_15m": 0.98,
         "core_count": 8,
         "temperature_celsius": 42.3
      },
      "memory": {
         "total_bytes": 17179869184,
         "used_bytes": 8203091968,
         "used_percent": 47.75,
         "swap_used_percent": 5.12
      },
      "disk": {
         "total_bytes": 1099511627776,
         "used_bytes": 351383035904,
         "used_percent": 31.96,
         "inodes_used_percent": 14.32,
         "io_utilization_percent": 2.1
      }
   }
}

Analyzing Network Traffic

Enable packet capture to analyze network traffic:

# Start NetSentry with packet capture
./netsentry --interface eth0

View Top Connections

# Get top connections by traffic volume
curl http://localhost:8080/api/v1/network/connections?limit=5

# Response
{
  "timestamp": "2023-07-25T15:24:45Z",
  "connections": [
    {
      "source_ip": "192.168.1.105",
      "source_port": 49321,
      "dest_ip": "172.217.20.110",
      "dest_port": 443,
      "protocol": "TCP",
      "bytes_tx": 1532842,
      "bytes_rx": 25437219,
      "packets_tx": 12392,
      "packets_rx": 18329,
      "duration_sec": 293.4,
      "state": "ESTABLISHED",
      "application_protocol": "HTTPS"
    },
    ...
  ]
}

Setting Up Alerts

Create alerts for important metrics:

# Create a high CPU usage alert via the API
curl -X POST http://localhost:8080/api/v1/alerts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High CPU Usage",
    "metric": "cpu.usage",
    "comparator": "gt",
    "threshold": 90.0,
    "severity": "warning"
  }'

Advanced Alerting Example

# Create a complex alert with multiple conditions
curl -X POST http://localhost:8080/api/v1/alerts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Potential Port Scan",
    "description": "Detects potential port scanning activity",
    "conditions": [
      {
        "metric": "network.connection_count",
        "filter": "src_ip = $src_ip",
        "comparator": "gt",
        "threshold": 100,
        "time_range": "60s"
      },
      {
        "metric": "network.unique_dest_port_count",
        "filter": "src_ip = $src_ip",
        "comparator": "gt",
        "threshold": 20,
        "time_range": "60s"
      }
    ],
    "condition_logic": "AND",
    "severity": "critical",
    "throttle_sec": 300,
    "notifications": [
      {
        "type": "email",
        "recipients": ["security@example.com"]
      },
      {
        "type": "webhook",
        "url": "https://example.com/security-alerts"
      }
    ]
  }'

API Documentation

NetSentry provides a comprehensive REST API for integration with other systems. Here are some key endpoints:

Endpoint	Method	Description
`/api/v1/metrics`	GET	List all available metrics
`/api/v1/network/connections`	GET	List active network connections
`/api/v1/network/hosts`	GET	List top hosts by traffic
`/api/v1/alerts`	GET/POST	Manage alerts
`/api/v1/capture`	POST	Control packet capturing
`/api/v1/config`	GET/PUT	View and update configuration

For complete API documentation, see API.md.

Terminal Output

NetSentry provides comprehensive monitoring information directly in the terminal:

$ ./netsentry --interface eth0 --api-enable --web-enable

[2025-04-26 14:32:10] [INFO] NetSentry v1.0.0 starting up...
[2025-04-26 14:32:10] [INFO] Thread pool initialized with 8 threads
[2025-04-26 14:32:10] [INFO] Database initialized: sqlite
[2025-04-26 14:32:10] [INFO] System collectors started
[2025-04-26 14:32:10] [INFO] Capturing packets on interface: eth0
[2025-04-26 14:32:10] [INFO] REST API server started on port 8080
[2025-04-26 14:32:10] [INFO] Web dashboard started on port 9090
[2025-04-26 14:32:10] [INFO] NetSentry is running. Press Ctrl+C to exit.

NetSentry - Network Monitoring Tool
==================================

System Metrics:
--------------
cpu.usage                     : 72.30
cpu.core.0.usage              : 68.42
cpu.core.1.usage              : 76.15
cpu.core.2.usage              : 75.84
cpu.core.3.usage              : 69.03
memory.total                  : 16384.00
memory.used                   : 10617.86
memory.free                   : 5766.14
memory.usage_percent          : 64.80

Network Statistics:
------------------
Packets captured: 14528
Bytes captured: 26853421

Top Connections:
1. 192.168.1.105:48329 -> 35.214.152.91:443 [TLS]
   Sent: 1342 packets, 286421 bytes | Received: 2156 packets, 24531642 bytes
2. 192.168.1.105:45129 -> 172.217.169.36:443 [TLS]
   Sent: 842 packets, 156214 bytes | Received: 1024 packets, 15124536 bytes
3. 192.168.1.107:52415 -> 104.26.10.233:443 [TLS]
   Sent: 645 packets, 124532 bytes | Received: 782 packets, 12653214 bytes
4. 192.168.1.110:59812 -> 13.107.42.14:443 [TLS]
   Sent: 421 packets, 86421 bytes | Received: 512 packets, 8653215 bytes
5. 192.168.1.105:47291 -> 34.107.221.82:443 [TLS]
   Sent: 312 packets, 65421 bytes | Received: 386 packets, 6325421 bytes

Top Hosts by Traffic:
1. 35.214.152.91: 24818063 bytes
2. 172.217.169.36: 15280750 bytes
3. 104.26.10.233: 12777746 bytes
4. 13.107.42.14: 8739636 bytes
5. 34.107.221.82: 6390842 bytes

Thread pool queue size: 0

The dashboard provides:

Real-time metrics visualization
Network connection tables
Protocol distribution charts
Alert management interface

Development and Contributing

We welcome contributions from the community! See CONTRIBUTING.md for guidelines.

Development Setup

# Set up development environment
git clone https://github.com/muhkartal/netsentry.git
cd netsentry

# Install dev dependencies
./scripts/install_dev_deps.sh

# Build with tests enabled
mkdir build && cd build
cmake -DBUILD_TESTS=ON ..
make -j$(nproc)

# Run tests
ctest

Project Troubleshooting

Click to view our development troubleshooting

Current Quarter

Enhance protocol analyzers for encrypted protocols
Add machine learning-based anomaly detection
Improve dashboard visualizations

Future Development

Native eBPF support for Linux
Custom DSL for network pattern matching
Mobile companion app
Cloud service integration
Extended API capabilities

For more information about upcoming features and development plans, see our TROBULESHOOTING.md.

License

NetSentry is released under the MIT License. See LICENSE for details.

Acknowledgements

libpcap for packet capture functionality
Boost C++ Libraries for networking components
Prometheus for metrics storage
Grafana for metrics visualization

NetSentry - Advanced Network Monitoring in Modern C++

GitHub • Docker Hub • API Docs • Developer Website

Developed by Muhammad Ibrahim Kartal | kartal.dev

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github/workflows		.github/workflows
configs		configs
docs		docs
images		images
kubernetes		kubernetes
prometheus		prometheus
src		src
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
install.sh		install.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

NetSentry

Overview

Key Features

Technical Architecture

Performance Benchmarks

Getting Started

Quick Start with Docker

Manual Installation

Prerequisites

Building from Source

Verifying Installation

Kubernetes Deployment

Configuration

Advanced Configuration

Usage Examples

Monitoring System Resources

Analyzing Network Traffic

Setting Up Alerts

API Documentation

Terminal Output

Development and Contributing

Development Setup

Project Troubleshooting

Current Quarter

Future Development

License

Acknowledgements

About

Uh oh!

Releases

Packages

Uh oh!

Languages

License

muhkartal/netSentry-Core

Folders and files

Latest commit

History

Repository files navigation

NetSentry

Overview

Key Features

Technical Architecture

Performance Benchmarks

Getting Started

Quick Start with Docker

Manual Installation

Prerequisites

Building from Source

Verifying Installation

Kubernetes Deployment

Configuration

Advanced Configuration

Usage Examples

Monitoring System Resources

Analyzing Network Traffic

Setting Up Alerts

API Documentation

Terminal Output

Development and Contributing

Development Setup

Project Troubleshooting

Current Quarter

Future Development

License

Acknowledgements

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages