Anomalia

Real-time network traffic analyzer for online game servers

Features • Screenshots • Getting Started • Building • Plugins • License

---

Anomalia is a modular, plugin-based network traffic analyzer designed for online game servers. It captures packets in real time, decrypts game-specific protocols through dynamic plugins, catalogs packet structures, and applies statistical heuristics to detect bots, anomalies, and suspicious behavior.

Built for server administrators, game security researchers, and anti-cheat developers who need deep visibility into what is happening on the wire.

Features

• Real-Time Packet Capture — high-performance capture engine powered by Npcap/libpcap with a lock-free SPSC queue for zero-contention packet processing.

• Plugin-Based Protocol Decoding — each game gets its own plugin (DLL/.so) that handles decryption, deobfuscation, and opcode mapping. No engine modifications needed to add a new game.

• Packet Structure Cataloging — parses C header files at runtime to dissect binary packets into named fields (position, HP, item IDs, etc.) with full type awareness.

• Statistical Analysis Engine — online computation of mean, variance, frequency, and inter-arrival time (IAT) using Welford's algorithm via Boost.Accumulators for numerical stability.

• Bot Detection — four weighted heuristics that combine into a single bot probability score:

  Heuristic	Weight	What it detects
  IAT Mechanical	40%	Near-zero variance in packet timing
  Pattern Regularity	20%	Low coefficient of variation in movement fields
  Opcode Entropy (Shannon)	20%	Limited repertoire of opcodes
  Response Consistency	20%	Uniform mechanical timing between opcodes

• Anomaly Detection — flags irregular traffic patterns, unusual opcode sequences, and statistical outliers that deviate from normal player behavior.

• Player Tracking — plugins can expose player lists, detailed player info (level, position, HP), and connection statistics through the API.

• Session Management — tracks individual player connections, handles TCP reassembly, and detects disconnections (FIN, RST, timeout).

• Flexible Packet Header Descriptors — plugins describe the exact binary layout of their game's packet headers (opcode position, size field, endianness, custom fields) so the engine never assumes a fixed format.

• Persistent Storage — SQLite-backed database for storing session data, alerts, and historical statistics.

• Terminal UI (TUI) — fullscreen console dashboard built with FTXUI featuring five tabs: Dashboard, Packets, Players, Alerts, and Config.

Screenshots

Dashboard — plugin info, IP ranking, RTT, opcode frequency

Packets (dissected) — struct fields with offsets and statistics

Packets (hex dump) — raw hex + ASCII for uncataloged opcodes

Players — account/character info, per-player bot detection

Getting Started

Prerequisites

Dependency	Version	Notes
C++ Compiler	C++20	MSVC 2022+, GCC 12+, or Clang 15+
CMake	3.16+	Build system
Boost	1.74+	system, thread (compiled); accumulators, lockfree (header-only)
Npcap SDK	1.16+	Windows only — packet capture driver
FTXUI	5.0.0	Auto-downloaded via CMake FetchContent

Quick Start (Windows)

1. Install Npcap (runtime driver).

2. Clone the repository:

   git clone https://github.com/your-username/anomalia.git
   cd anomalia

3. Build:

   cmake -B build
   cmake --build build --config Release

4. Place game plugin DLLs in the plugins/ directory.

5. Run:

   ./build/Release/Anomalia.exe

Building

Console UI (default)

cmake -B build
cmake --build build --config Release

Qt6 GUI (in development)

cmake -B build -DANOM_BUILD_UI=ON
cmake --build build --config Release

Note: The Qt6 graphical interface is currently under active development and is not yet feature-complete.

Linux (in development)

Linux support is planned and under development. The codebase uses platform abstractions (LoadLibrary/dlopen, GetProcAddress/dlsym) to facilitate the port, but it has not been fully tested on Linux yet.

# Future — not yet fully supported
cmake -B build
cmake --build build

Plugins

Anomalia uses a dynamic plugin system to support different games. Each game requires its own plugin — a shared library that implements packet decryption and provides metadata through a pure C ABI.

Creating a plugin is simple:

1. Include plugin_api.h (the only dependency).
2. Implement AnomGetPluginInfo and AnomDecryptPacket (required).
3. Optionally implement opcode mapping, header descriptors, and player tracking.
4. Compile as a DLL/.so and drop it in plugins/.

#include "plugin_api.h"

ANOM_EXPORT AnomPluginResult AnomGetPluginInfo(AnomPluginInfo* info) {
    info->abi_version   = ANOM_PLUGIN_ABI_VERSION;
    info->name          = "My Game";
    info->game_id       = "mygame";
    info->version_major = 1;
    info->version_minor = 0;
    info->protocol      = ANOM_PROTO_TCP;
    info->default_ports[0] = 7777;
    info->num_ports     = 1;
    return ANOM_OK;
}

ANOM_EXPORT AnomPluginResult AnomDecryptPacket(
    const uint8_t* in, uint32_t in_size,
    uint8_t* out, uint32_t* out_size,
    AnomPacketDirection direction,
    uint32_t client_ip, uint16_t client_port,
    uint32_t server_ip)
{
    // Your decryption logic here
    memcpy(out, in, in_size);
    *out_size = in_size;
    return ANOM_OK;
}

For the full plugin development guide, see docs/PLUGINS.md.

Project Structure

anomalia/
├── src/
│   ├── Core/              # Core engine, types, platform abstractions
│   ├── Plugins/           # Plugin API and dynamic loader
│   ├── Pipeline/          # Capture engine and lock-free packet queue
│   ├── Catalog/           # Struct cataloging and C header parser
│   ├── Stats/             # Statistical engine and bot detector
│   ├── Database/          # SQLite persistence layer
│   └── UI/
│       ├── Console/       # FTXUI terminal interface
│       └── Qt/            # Qt6 graphical interface (in development)
├── plugins/               # Game plugin DLLs (runtime)
├── catalog/               # Game struct header files (.h)
├── 3rdparty/              # Npcap SDK, SQLite
├── docs/
│   ├── DESIGN.md          # Software design document
│   ├── PLUGINS.md         # Plugin development guide
│   └── img/               # Documentation images
├── CMakeLists.txt
└── LICENSE

Roadmap

• Core capture engine with lock-free queue
• Dynamic plugin system with ABI versioning
• Packet structure cataloging from C headers
• Statistical analysis engine (Welford/Boost.Accumulators)
• Bot detection (4 combined heuristics)
• FTXUI terminal dashboard
• Player tracking API (ABI v4+)
• SQLite persistence
• Qt6 graphical interface
• Linux platform support
• Plugin hot-reload
• REST API for external integrations
• Alert webhooks (Discord, Slack)
• Replay/playback of captured sessions

Contributing

Contributions are welcome. Please open an issue first to discuss what you would like to change.

When submitting a plugin for a new game, follow the guidelines in docs/PLUGINS.md.

License

This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details.

Support the Project

If Anomalia is useful to you, consider supporting its development:

Bitcoin: bc1q40mtqs5dz0mzfsnag97a6we8dtrls7fwr23fcg

Contact

• GitHub: @jrzanol
• Email: jrzanol.92@gmail.com