Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

4 Commits
build
build
 
 
include
include
 
 
src
src
 
 
tests
tests
 
 
CMakeLists.txt
CMakeLists.txt
 
 
README.md
README.md
 
 
generate_test_pcap.py
generate_test_pcap.py
 
 
test_dpi.pcap
test_dpi.pcap
 
 

Repository files navigation

CipherPulse

Multi-threaded Deep Packet Inspection engine with JA4+ TLS fingerprinting, Encrypted Traffic Intelligence, and C2 beaconing detection — written in C++17 with zero external dependencies.

✨ What Makes This Different

Most open-source DPI tools rely on SNI (Server Name Indication) to classify traffic. In 2025–2026, Encrypted Client Hello (ECH) is making SNI invisible — the industry needs a new approach.

CipherPulse introduces Encrypted Traffic Intelligence (ETI): a statistical fingerprinting layer that classifies and threat-scores traffic without decryption and without SNI:

Technique What It Does
JA4+ Fingerprinting Generates a structured TLS fingerprint from cipher suites, extensions, and supported groups — uniquely identifies clients and detects known malware (CobaltStrike, Sliver C2, Metasploit)
Flow Behavioral Analysis Classifies flows as video streaming, VoIP, C2 beaconing, file transfer, or browsing using packet size distributions and inter-arrival timing (Welford online statistics)
DNS Correlation Parses DNS responses in the capture, builds an IP→domain cache, and uses it to label encrypted flows where SNI is absent
Threat Scoring Combines JA4 match + beaconing detection + flow anomalies into a [0, 1] threat score with CRITICAL/HIGH/MEDIUM/LOW levels

Architecture

PCAP Input
    │
    ▼
┌─────────────────┐
│  Reader Thread  │  ← parse packets, feed DNS correlator
└────────┬────────┘
         │  hash(5-tuple)
    ┌────┴────┐
    ▼         ▼
  [LB 0]   [LB 1]     ← Load Balancers (consistent hashing)
    │         │
  ┌─┴─┐   ┌─┴─┐
  ▼   ▼   ▼   ▼
 FP0 FP1 FP2 FP3     ← Fast Path Processors (DPI + ETI per thread)
    └────┬────┘
         │
    ┌────▼────┐
    │ Output  │       ← Write filtered PCAP
    │ Writer  │
    └─────────┘

Each Fast Path thread owns its own flow table (no cross-thread locking on hot path). Threads communicate via bounded, condition-variable-driven queues with proper sentinel-based shutdown (no sleep hacks).

Features

  • PCAP I/O — reads/writes standard .pcap files; handles byte-swapped captures
  • Protocol Parsing — Ethernet / IPv4 / IPv6 / TCP / UDP (strict-aliasing safe)
  • TLS SNI Extraction — parse TLS 1.0–1.3 Client Hello, extract SNI hostname
  • HTTP Host Extraction — extract Host: header from plaintext HTTP
  • DNS Parsing — extract queried domains from DNS requests and responses
  • JA4+ Fingerprinting — full implementation (cipher suites, extensions, ALPN, supported groups, GREASE filtering), embedded malicious fingerprint DB
  • Flow Behavioral Analysis — Welford running stats, beaconing detection, traffic pattern classification
  • DNS Correlation — IP→domain cache with TTL-based expiry
  • Threat Scoring — multi-factor scoring with alert levels
  • App Classification — 28 recognized applications (YouTube, TikTok, OpenAI, etc.)
  • Multi-threaded — configurable LB × FP thread topology
  • JSON Output — --json flag for machine-readable reports

Quick Start

Build

mkdir build && cd build
cmake ..
make -j$(nproc)

Produces three binaries:

Binary Purpose
packet_analyzer Basic packet viewer (Ethernet/IP/TCP dump)
dpi_simple Single-threaded DPI with SNI classification
dpi_engine Full multi-threaded DPI + ETI engine

Generate Test Data

python3 generate_test_pcap.py
# Creates test_dpi.pcap with TLS, HTTP, DNS, and simulated C2 traffic

Run

# Basic — classify and report
./dpi_engine test_dpi.pcap output.pcap

# Block applications
./dpi_engine test_dpi.pcap output.pcap --block-app YouTube --block-app TikTok

# Block by IP or domain
./dpi_engine test_dpi.pcap output.pcap --block-ip 192.168.1.50 --block-domain facebook

# Multi-threaded (4 LBs × 4 FPs = 16 processing threads)
./dpi_engine test_dpi.pcap output.pcap --lbs 4 --fps 4

# JSON output for programmatic parsing
./dpi_engine test_dpi.pcap output.pcap --json > report.json

Sample Output

╔══════════════════════════════════════════════════════════════╗
║          CipherPulse v2.0 — Multi-threaded DPI + ETI         ║
╠══════════════════════════════════════════════════════════════╣
║ Load Balancers:  2    FPs per LB:  2    Total FPs:  4     ║
║ Features: SNI • JA4+ • Flow Analysis • DNS Correlation       ║
╚══════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════╗
║                    CIPHERPULSE REPORT                        ║
╠══════════════════════════════════════════════════════════════╣
║ Total Packets:             77                               ║
║ Forwarded:                 69                               ║
║ Dropped:                    8                               ║
║ Threat Alerts:              2                               ║
╠══════════════════════════════════════════════════════════════╣
║              THREAT INTELLIGENCE (ETI)                       ║
╠══════════════════════════════════════════════════════════════╣
║  [CRITICAL] Known malicious JA4 fingerprint                  ║
║    JA4: t13d881516h2_8daaf6152771_02713d6af862               ║
║  [HIGH    ] C2 beaconing pattern                             ║
╚══════════════════════════════════════════════════════════════╝

[Detected Domains / SNIs]
  - www.youtube.com -> YouTube
  - www.facebook.com -> Facebook
  - open.spotify.com -> Spotify
  - github.com -> GitHub

Encrypted Traffic Intelligence — Deep Dive

JA4+ Fingerprinting

JA4 (2023, FoxIO) is the production-standard TLS fingerprinting algorithm used by CrowdStrike, Cloudflare, and GreyNoise. Unlike JA3 (MD5-based, trivially evaded by extension reordering), JA4 is:

  • Stable under extension reordering — cipher suites and extensions are sorted before hashing
  • Human-readable — the format encodes TLS version, SNI presence, cipher count, and ALPN
  • Evasion-resistant — GREASE values (RFC 8701) are stripped before computation

Format: t<version><sni><#ciphers><#exts><alpn>_<sorted_cipher_hash>_<sorted_ext_hash>

t13d1516h2_8daaf6152771_02713d6af862
│││ │    │  │             │
│││ │    │  └─ FNV-1a hash of sorted extensions
│││ │    └──── FNV-1a hash of sorted cipher suites
│││ └───────── ALPN first char ('h' = h2 / HTTP2)
││└─────────── extension count
│└──────────── TLS version ('13' = TLS 1.3)
└───────────── transport ('t' = TCP)

Embedded malicious fingerprint database includes signatures for:

  • CobaltStrike (default + common profiles)
  • Metasploit Meterpreter
  • Sliver C2
  • AsyncRAT
  • Havoc C2
  • Brute Ratel C4

Flow Behavioral Analysis

Traffic classification without SNI using packet-level statistics:

Pattern Indicators
C2_BEACONING Mean IAT CoV < 0.12, mean packet < 500 bytes
VIDEO_STREAMING Mean size > 900 bytes, server→client ratio > 90%
VOIP_WEBRTC Mean size < 400 bytes, IAT CoV < 0.40
FILE_TRANSFER Mean size > 1000 bytes, size stddev < 30%
WEB_BROWSING Variable sizes, bidirectional

Uses Welford's online algorithm for numerically stable single-pass variance computation — no buffering of all packet sizes required.

DNS Correlation

Even when ECH hides SNI, DNS queries precede HTTPS connections. CipherPulse:

  1. Parses DNS response packets (QR=1, A records)
  2. Caches IP→domain with DNS TTL-based expiry
  3. When an HTTPS flow reaches a cached IP, labels it with the resolved domain
  4. Handles DNS pointer compression (RFC 1035 §4.1.4)

Project Structure

CipherPulse/
├── include/
│   ├── types.h              # FiveTuple, AppType, ThreatLevel, FlowFeatures
│   ├── pcap_reader.h        # PCAP file I/O
│   ├── packet_parser.h      # Ethernet/IP/TCP/UDP parsing
│   ├── sni_extractor.h      # TLS SNI, HTTP Host, DNS, QUIC extractors
│   ├── ja4_fingerprint.h    # ★ JA4+ TLS fingerprinting
│   ├── flow_analyzer.h      # ★ Statistical flow behavioral analysis
│   ├── dns_correlator.h     # ★ DNS IP→domain cache
│   ├── platform.h           # Portable byte-order helpers
│   └── thread_safe_queue.h  # Bounded TSQueue
│
├── src/
│   ├── main.cpp             # Basic packet viewer
│   ├── main_working.cpp     # Single-threaded DPI
│   ├── dpi_mt.cpp           # ★ Multi-threaded DPI + ETI (main engine)
│   ├── packet_parser.cpp    # Protocol parsing (memcpy-safe, no aliasing UB)
│   ├── sni_extractor.cpp    # SNI/HTTP/DNS/QUIC extraction
│   ├── types.cpp            # App classification, utilities
│   ├── ja4_fingerprint.cpp  # ★ JA4+ implementation
│   ├── flow_analyzer.cpp    # ★ Welford stats, beaconing detection
│   └── dns_correlator.cpp   # ★ DNS parser + LRU cache
│
├── tests/
│   ├── test_ja4.cpp         # JA4 fingerprint unit tests
│   └── test_flow_analyzer.cpp # Flow analyzer unit tests
│
├── generate_test_pcap.py    # Test PCAP generator
└── CMakeLists.txt           # Builds all targets + tests

Technical Notes

  • Zero external dependencies — no OpenSSL, no libpcap, no Boost. Pure C++17 STL.
  • Memory safe — no raw pointer aliasing, std::memcpy for all multi-byte reads
  • Thread safe — flow tables are per-FP-thread (no hot-path locking); shared state uses atomics + mutex
  • Proper shutdown — sentinel packets propagate through the LB→FP→Output chain; no sleep() races
  • IPv6 aware — basic IPv6 header parsing with next-header protocol dispatch

Requirements

  • C++17 compiler (GCC 8+, Clang 7+, MSVC 2019+)
  • CMake 3.16+
  • pthreads (Linux/macOS) — linked automatically via find_package(Threads)

No external libraries required.

About

Multi-threaded Deep Packet Inspection engine with JA4+ TLS fingerprinting, encrypted traffic intelligence, and C2 beaconing detection. Built in C++17 with zero external dependencies.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages