Skip to content

Tutorials

Learn JoyfulJay through practical, hands-on tutorials that cover real-world use cases.

Learning Path

Whether you're new to network traffic analysis or an experienced ML practitioner, these tutorials will help you get the most out of JoyfulJay.

Beginner Path

If you're just getting started, follow these tutorials in order:

  1. Traffic Classification - Learn the fundamentals of extracting features and training a classifier to identify different types of network traffic. This tutorial covers the complete workflow from PCAP to trained model.

  2. Encrypted Traffic Analysis - Understand how to detect Tor, VPN, and DNS-over-HTTPS traffic without decrypting it. Learn about the fingerprinting techniques that make this possible.

Advanced Path

Once you're comfortable with the basics:

  1. Batch Processing - Process large PCAP datasets efficiently using parallel workers, memory-efficient iteration, and output streaming. Essential for production workloads.

  2. Real-time Monitoring - Build a complete monitoring pipeline with live capture, Kafka streaming, and Prometheus metrics. Includes Grafana dashboard setup.

  3. Custom Extractors - Create your own feature extractors to capture domain-specific information. Learn the extractor architecture and best practices.

Tutorial Overview

Tutorial Level Time What You'll Learn
Traffic Classification Beginner 30 min Feature extraction, ML pipeline, model training
Encrypted Traffic Analysis Beginner 25 min Tor/VPN/DoH detection, fingerprinting techniques
Batch Processing Intermediate 20 min Parallel processing, memory efficiency, large datasets
Real-time Monitoring Advanced 45 min Live capture, Kafka, Prometheus, Grafana
Custom Extractors Advanced 40 min Extractor architecture, custom features

Prerequisites

Before starting these tutorials, make sure you have:

  • JoyfulJay installed: See the Installation Guide
  • Python 3.10+: With pandas, numpy, and scikit-learn for ML tutorials
  • Sample PCAP files: Use your own captures or download public datasets

For learning and testing:

Quick Reference

Feature Extraction Basics

Python
import joyfuljay as jj

# Extract all features from a PCAP file
df = jj.extract("capture.pcap")

# Select specific feature groups
df = jj.extract("capture.pcap", features=["timing", "tls", "fingerprint"])

# Use configuration for fine-grained control
config = jj.Config(
    features=["timing", "size", "tls"],
    flow_timeout=30.0,
    include_ip_addresses=True
)
pipeline = jj.Pipeline(config)
df = pipeline.process_pcap("capture.pcap")

Command Line Usage

Bash
# Basic extraction
jj extract capture.pcap -o features.csv

# Select features
jj extract capture.pcap --features timing tls -o features.csv

# Live capture
jj live eth0 --duration 60 -o live.csv

# View PCAP info
jj info capture.pcap

Need Help?