🦈 Z-Shark: Mathematical Network Forensics Platform

---

Table of Contents

1. Legal Disclaimer
2. Architectural Philosophy
3. Detection Engines (Deep Dive)
4. System Architecture
5. Installation & Setup
6. Usage Guide
7. License

⚠️ Legal Disclaimer: Use Responsibly

This tool is intended strictly for educational purposes, forensic analysis, and defensive security assessments. Z-Shark provides deep insight into network traffic patterns using advanced statistical models. The author (Delta-Security) is not responsible for any misuse of this tool on unauthorized networks. By using this software, you agree to do so in compliance with all applicable laws.

---

💡 Architectural Philosophy: Math Over Signatures

Z-Shark is not a traditional IDS that relies on static signatures. Instead, it is a Mathematical Network Forensics Platform designed to detect anomalies that evade standard rule-based systems. It leverages Signal Processing (FFT), Information Theory (Entropy), and Statistical Profiling (Z-Scores) to identify subtle threat patterns.

The Professional & Modular Approach

1. Streaming Architecture: Z-Shark slices PCAP streams into time-based chunks, allowing it to analyze massive capture files without exhausting memory.
2. Explainable AI (XAI): Every detection includes a mathematically rigorous justification and evidence payload, ensuring analysts understand why an alert was triggered.
3. Global CLI: Once installed via the Debian package, zshark becomes a native system command accessible from any directory.

---

⚙️ Detection Engines: Feature Deep Dive

Z-Shark includes a suite of specialized detection models:

1. C2 Beaconing Detection (BeaconingDetector)

• Mechanism: Tracks the Inter-Arrival Times (IAT) of packets and applies Fast Fourier Transform (FFT).
• Math Used: numpy.fft.fft calculates the magnitude spectrum.
• Trigger: A significant peak in the frequency spectrum indicates automated communication typical of malware beacons.

2. Volumetric Anomaly & DDoS (DDoSDetector)

• Math Used: * Z-Score: Measures standard deviations from the historical mean to catch volume spikes.
  • Shannon Entropy: Monitors Source IP randomness; a sudden drop suggests a concentrated flood.

3. DGA & DNS Tunneling (DNSAnomalyDetector)

• Mechanism: Analyzes lexical properties of queried domain names.
• Math Used: Shannon Entropy applied to character distribution to detect Domain Generation Algorithms.

---

🏛️ System Architecture and Data Flow

Component	Responsibility
Packet Streamer	Lazy-loading of PCAP files to minimize RAM usage.
Window Processor	Slices the packet stream into time windows for temporal analysis.
Analysis Engine	Applies loaded models to each window.
Reporting Engine	Renders professional PDF forensics reports from JSON data.

graph LR
    A[Input PCAP] -->|Stream| B(PacketStreamer)
    B -->|Raw Packets| C{WindowProcessor}
    C -->|"Time Window"| D[Analyzer Engine]
    
    subgraph Models
    D --> E[FFT Beaconing]
    D --> F[Z-Score DDoS]
    D --> G[Entropy DNS]
    D --> H[Stateful ARP]
    end
    
    E & F & G & H -->|Detections| I[Aggregator]
    I -->|JSON Export| J[analysis.json]
    J -->|Render| K[PDF Forensic Report]

Loading

🛠️ Installation and Setup

Recommended: Debian Package (.deb)

The easiest way to install Z-Shark on Kali Linux or any Debian-based system:

sudo apt update
sudo apt install ./zshark_2.1.1_all.deb

🛠️ Installation and Setup

Installation (Development Mode)

If you want to run it from source or contribute to the project:

1. Clone the Repository:

git clone [https://github.com/Delta-Security/z-shark.git](https://github.com/Delta-Security/z-shark.git)
cd z-shark

2. Install Dependencies: Z-Shark relies on heavy scientific computing libraries (numpy, scipy, pandas).

python -m venv .venv

source .venv/bin/activate  # Linux/macOS

pip install -r requirements.txt

🚀 Usage Guide

Z-Shark is driven by a powerful Typer-based CLI (zshark/cli/main.py).

1. Analyze a PCAP File Run the full suite of mathematical models on a capture file.

zshark analyze capture.pcap -o results/ -v

python -m zshark.cli.main analyze capture.pcap --out-dir results/ #(Development Mode)

• Output: Generates a raw analysis.json containing all window stats and detection evidence.

2. Generate Forensic Report

Convert the JSON analysis into a human-readable PDF.

zshark report results/analysis.json -o Forensic_Report.pdf

python -m zshark.cli.main report results/capture_analysis.json --pdf-path report.pdf #(Development Mode)

• Output: A professional PDF report with charts, evidence tables, and justifications.

3. Quick Statistical Summary

(Placeholder/Beta) Get a quick overview of top talkers and protocols.

zshark summary results/analysis.json --top 10

python -m zshark.cli.main summary capture.pcap --top 10 #(Development Mode)

⚖️ License

This project is licensed under the MIT License - see the LICENSE file for details.

Developed by Delta-Sec | Mathematics meets Cybersecurity GitHub: github.com/Delta-Sec