sys-inspector 0.30.9

eBPF-based System Inspector and Forensic Tool

sys-inspector - eBPF-based System Inspector and Audit Tool

Sys-Inspector is an advanced observability and forensic tool powered by eBPF (Extended Berkeley Packet Filter).

Unlike traditional tools that poll /proc periodically, Sys-Inspector hooks directly into the Linux Kernel to capture events (process execution, file I/O, network connections) in real-time.

Features (v0.30.9)

• Kernel-Level Visibility: Uses eBPF kprobes/tracepoints for zero-blindspot monitoring.
• Deep Forensics:
  • Real-time MD5 Hashes: Calculates hashes of executed binaries instantly.
  • Context Awareness: Detects SSH origin IPs, Sudo users, and Tmux sessions.
  • Recursive Alert Bubbling: Child process anomalies (e.g., Unsafe Libs, Net Errors) propagate warnings up to the parent process in the tree view.
• Topology & Infrastructure:
  • Storage Topology: Hierarchical view of Disks -> Partitions -> LVM -> Mount Points with HCTL info.
  • Network Topology: Auto-detection of Gateway, DNS servers, and Interfaces.
• Enterprise Reporting:
  • Generates self-contained, interactive HTML Dashboards.
  • Custom Logo Support: Embeds your organization's logo automatically.
  • Visual Badges: Instant identification of [SSH], [SUDO], [UNSAFE], [NET ERR].

Requirements

• Linux Kernel 4.15+ (5.x+ recommended for BTF support).
• Root privileges (sudo).
• Python 3.6+.
• BCC Tools (python3-bcc).
• iproute2 (for tc command, required only for Chaos Maker).

Installation (PyPI)

Works on any Linux distribution with Python 3.6+.

pip install sys-inspector

Installation (RPM / openSUSE)

You can install Sys-Inspector directly via zypper using the openSUSE Build Service repository.

1. Add the Repository:

zypper addrepo [https://download.opensuse.org/repositories/home:mariosergiosl:sys-inspector/15.6/home:mariosergiosl:sys-inspector.repo](https://download.opensuse.org/repositories/home:mariosergiosl:sys-inspector/15.6/home:mariosergiosl:sys-inspector.repo)

2. Refresh and Accept GPG Key: During the refresh, you will be asked to trust the repository GPG key.

Fingerprint: 7CF0 5795 053C F397 8E00 948E 9F8D 1AC9 E2BE EABC

zypper refresh
# Type 'a' to trust always when prompted.

3. Install the Package:

zypper install sys-inspector

4. Run: Once installed, the command is available globally:

sys-inspector

Usage

Sys-Inspector can now be run with or without arguments. It handles directory creation automatically.

1. Default Mode (Recommended)

Captures 20 seconds of activity and saves the report to /var/log/sys-inspector/ with an auto-generated name containing the hostname and timestamp.

sudo python3 src/inspector.py
# Output Example: /var/log/sys-inspector/sys-inspector_v0.30.3_hostname_20251201_100000.html

2. Custom Parameters

You can specify the duration and the output file path manually.

# Capture for 60 seconds and save to a specific file
sudo python3 src/inspector.py --duration 60 --html /tmp/my_investigation.html

Argument	Short	Default	Description
--duration	-d	20	Capture duration in seconds.
--html		(Auto)	Path to output HTML file. If omitted, defaults to /var/log/sys-inspector/.

3. Custom Logo

To include your company logo in the report header, simply place a PNG file at the following path:

/etc/sys-inspector/logo.png

The application will automatically detect, resize (max-height: 40px), encode it to Base64, and embed it in the HTML.

Chaos Engineering (Testing Tool)

Included in scripts/chaos_maker.sh is a stress testing tool designed to validate the inspector's detection capabilities.

⚠️ WARNING: DO NOT RUN ON PRODUCTION SYSTEMS. This script uses tc (Traffic Control) to purposefully degrade network quality (packet loss/latency) and consumes CPU/Disk resources.

Capabilities:

• Network Degradation: Injects 100ms latency and 20% packet loss to trigger [NET ERR] alerts in the report.
• Process Anomalies: Hides processes in /dev/shm to trigger [WARN] alerts.
• Unsafe Library Loading: Forces loading of dynamic libraries from /tmp via a Python script to trigger [UNSAFE] alerts.
• Disk Stress: Generates high I/O throughput to test IO accounting.

How to Run:

sudo ./scripts/chaos_maker.sh

To Stop: Press Ctrl+C. The script traps the signal and automatically cleans up the network rules (tc qdisc del) and temporary files.

Project Structure

├── src/
│   ├── inspector.py           # Main Entry Point
│   └── sys_inspector/
│       ├── bpf_programs.py    # C eBPF Code
│       ├── sys_info.py        # Inventory & Topology
│       └── report_generator.py # HTML Engine
├── scripts/
│   ├── chaos_maker.sh         # Chaos Engineering Tool
│   └── run_python_test.sh     # Linter (Pylint/Flake8)
├── logs/                      # Default output directory
└── README.md