# cisco/mercury architecture

> Architecture diagram of the GitHub repository cisco/mercury, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cisco/mercury
- Repository: https://github.com/cisco/mercury

## Overview

##### Main System Components

- Packet Capture Engine (AF_PACKET/TPACKETv3)
- Worker Threads Pool
- Protocol Analyzers
- Fingerprint Generator
- Output Manager

b) Input Sources (Left Side):
- Network Interface (Live Capture)
- PCAP Files
- Standard Input

c) Output Destinations (Right Side):
- JSON Output (Fingerprints)
- PCAP/MCAP Files
- Statistics Output

##### Key Architectural Patterns

a) Multi-threaded Processing Pipeline:
- Ring Buffers (Zero-copy)
- Worker Thread Pool
- Thread-safe Output Handling

b) Protocol Analysis Layers:
- Network Layer (IP, TCP, UDP)
- Application Layer Protocols
- TLS/DTLS
- SSH
- HTTP
- DNS
- Multiple other supported protocols

c) Analysis Components:
- Fingerprint Generation
- Process Identification
- Metadata Extraction
- Protocol Message Reassembly

##### Data Flow Representation

- Packet flow from input sources through processing pipeline
- Metadata extraction paths
- Analysis results flow
- Output generation paths

##### Component Details

- Configuration Management
- Resource Management
- Security Controls (privilege dropping)
- Statistics Collection
- File Rotation Logic

##### Integration Points

Connections to:
- System Resources (CPU, Memory)
- File System
- Network Interfaces
- External Analysis Resources

##### Additional Elements

Include:
- Configuration Options
- Resource File Dependencies
- Security Boundaries
- Performance Optimization Points

##### Technical Details

Annotations for:
- Ring Buffer Sizing
- Thread Pool Configuration
- File Format Specifications
- Protocol Support List
- Performance Characteristics

##### Operational Aspects

Show:
- Systemd Service Integration
- Directory Structure
- User/Permission Management
- Resource File Locations

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Input
        NIC["Network Interface"]:::input
        PCAP["PCAP Files"]:::input
        click PCAP "https://github.com/cisco/mercury/blob/main/src/pcap.cc"
        STDIN["Standard Input"]:::input
    end

    subgraph Core
        PCE["Packet Capture Engine"]:::core
        click PCE "https://github.com/cisco/mercury/blob/main/src/af_packet_v3.c"
        WTP["Worker Threads Pool"]:::core
        click WTP "https://github.com/cisco/mercury/blob/main/src/pkt_processing.cc"
        
        subgraph "Protocol Analysis"
            PA["Protocol Analyzers"]:::analyzer
            click PA "https://github.com/cisco/mercury/tree/main/src/libmerc"
            TLS["TLS/DTLS"]:::protocol
            click TLS "https://github.com/cisco/mercury/blob/main/src/libmerc/tls.cc"
            SSH["SSH"]:::protocol
            click SSH "https://github.com/cisco/mercury/blob/main/src/libmerc/ssh.cc"
            HTTP["HTTP"]:::protocol
            click HTTP "https://github.com/cisco/mercury/blob/main/src/libmerc/http.cc"
            DNS["DNS"]:::protocol
            click DNS "https://github.com/cisco/mercury/blob/main/src/libmerc/dns.cc"
            PA --> TLS & SSH & HTTP & DNS
        end
        
        FPG["Fingerprint Generator"]:::core
        click FPG "https://github.com/cisco/mercury/blob/main/src/fingerprint.cc"
        OM["Output Manager"]:::core
        click OM "https://github.com/cisco/mercury/blob/main/src/output.c"
    end

    subgraph Management
        CM["Configuration Management"]:::mgmt
        click CM "https://github.com/cisco/mercury/blob/main/src/config.c"
        RM["Resource Management"]:::mgmt
        SC["Security Controls"]:::mgmt
        click SC "https://github.com/cisco/mercury/blob/main/src/signal_handling.c"
        ST["Statistics Collection"]:::mgmt
        click ST "https://github.com/cisco/mercury/blob/main/src/libmerc/stats.h"
    end

    subgraph Output
        JSON["JSON Output"]:::output
        click JSON "https://github.com/cisco/mercury/blob/main/src/json_file_io.c"
        PCAPOUT["PCAP/MCAP Files"]:::output
        STATS["Statistics Output"]:::output
    end

    NIC & PCAP & STDIN --> PCE
    PCE --> WTP
    WTP --> PA
    PA --> FPG
    FPG --> OM
    OM --> JSON & PCAPOUT & STATS
    
    CM --> PCE & WTP & OM
    RM --> PCE & WTP
    SC --> PCE & WTP
    ST --> STATS

    classDef input fill:#90EE90,stroke:#333,stroke-width:2px
    classDef core fill:#87CEEB,stroke:#333,stroke-width:2px
    classDef analyzer fill:#FFD700,stroke:#333,stroke-width:2px
    classDef protocol fill:#FFE4B5,stroke:#333,stroke-width:2px
    classDef output fill:#FFA500,stroke:#333,stroke-width:2px
    classDef mgmt fill:#D3D3D3,stroke:#333,stroke-width:2px

    subgraph Legend
        L1["Input Components"]:::input
        L2["Core Components"]:::core
        L3["Analysis Components"]:::analyzer
        L4["Protocol Handlers"]:::protocol
        L5["Output Components"]:::output
        L6["Management Components"]:::mgmt
    end
```
