# chataflndss/chatafl architecture

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

- Interactive diagram: https://gitdiagram.com/chataflndss/chatafl
- Repository: https://github.com/chataflndss/chatafl

## Overview

##### Project type and purpose
- ChatAFL Artifact is a research‐oriented protocol fuzzer that extends AFLNet by integrating large language models (LLMs) for three strategies:
1. Structure‐aware mutations using an LLM-derived grammar
2. Seed‐set enrichment via LLM-generated messages
3. Plateau-breaking LLM prompts during state stalls
- It is packaged as a ProfuzzBench extension (benchmark harness) and includes scripts for setup (Docker images), execution (run.sh), and analysis (analyze.sh).

##### File structure
- Top-level directories:
- ChatAFL-CL1, ChatAFL-CL2, ChatAFL – three fuzzer implementations (ablation variants and full)
- aflnet – modified AFLNet core
- benchmark – ProfuzzBench subset with text protocols and Lighttpd
- scripts: deps.sh, setup.sh, run.sh, analyze.sh, clean.sh
- Key source files in each fuzzer:
- afl-fuzz.c (entry point)
- chat-llm.c/.h (LLM helper)
- config.h, chat-llm.h (parameters)
- Dockerfiles in each fuzzer and benchmark subjects
- Output directories created at runtime:
- protocol-grammars, stall-interactions, queue (seed queue), benchmark/result-*

##### README insights
- Architecture is three-component: LLM grammar extractor, seed enricher, plateau breaker
- Integrates with ProfuzzBench via Docker images and run.sh orchestration
- .sh parses archives and generates coverage/state plots

a. Main components:
- ChatAFL Fuzzer Container (one per fuzzer variant)
– Core AFLNet engine (afl-fuzz)
– LLM integration module (chat-llm)
– Configuration (config.h, chat-llm.h)
- ProfuzzBench Orchestrator (run.sh + Docker Compose)
- Subject Under Test Container (e.g. pure-ftpd, kamailio, etc.)
- OpenAI LLM Service (external API endpoint)
- Analysis Module (analyze.sh + Python scripts with pandas/matplotlib)
- Benchmark Storage (volumes for results, archives, protocol-grammars)

b. Relationships and data flow:
1. run.sh invokes Docker to spin up:
– N ChatAFL containers connecting via network to N Subject containers
2. ChatAFL container startup (setup.sh):
– Build fuzzer binary (Dockerfile)
– Load config (EPSILON_CHOICE, thresholds)
3. Grammar Extraction Phase (setup_llm_grammars):
– chat-llm prompts → OpenAI API → returns protocol grammar → stored in protocol-grammars
4. Seed Enrichment Phase (get_seeds_with_message_types):
– chat-llm prompts original seeds → OpenAI API → enriched seeds added to AFL queue
5. Main Fuzz Loop (fuzz_one):
– AFLNet mutation + feedback → network messages to Subject
– On plateau: uninteresting_times triggers chat-llm prompts → OpenAI API → new test messages
6. Coverage/state logging: AFLNet instruments states, transitions → logged to result-archive
7. Container tear-down: archives volume persists testcases, logs, stall-interactions
8. .sh reads archives → CSVs → PNG plots → res_<subject>

c. Architectural patterns/design principles:
– Microservice style: each fuzzer-subject pair is an isolated container (horizontal scale)
– Modular LLM integration: chat-llm separated from AFLNet core
– Data‐driven: all artifacts (grammars, enriched seeds, stall logs) are persisted for analysis
– Configuration‐first: thresholds and retry counts in headers for easy tuning

d. Technologies/frameworks:
– C (AFLNet core, ChatAFL patches)
– Bash scripts (orchestration, benchmark harness)
– Docker (containerization)
– OpenAI GPT-3.5 API (LLM)
– Python pandas/matplotlib (analysis)
– ProfuzzBench conventions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestrator
    subgraph "ProfuzzBench Orchestrator"
        direction TB
        run["run.sh"]:::script
        setup["setup.sh"]:::script
        build["profuzzbench_build_all.sh"]:::script
        exec["profuzzbench_exec_all.sh"]:::script
        deps["deps.sh"]:::script
        clean["clean.sh"]:::script
    end

    docker["Docker Engine"]:::service

    run --> docker
    setup --> docker
    deps --> docker
    clean --> docker

    %% Containers
    subgraph "Containers"
        direction TB

        subgraph "ChatAFL Fuzzer Containers" 
            direction TB

            subgraph "Full Variant"
                CAF["ChatAFL Container"]:::container
                AFLC1["afl-fuzz.c"]:::module
                CLLM1["chat-llm.c / h"]:::module
                CFG1["config.h"]:::module
            end

            subgraph "CL1 Variant"
                CL1C["ChatAFL-CL1 Container"]:::container
                AFLC2["afl-fuzz.c"]:::module
                CLLM2["chat-llm.c / h"]:::module
                CFG2["config.h"]:::module
            end

            subgraph "CL2 Variant"
                CL2C["ChatAFL-CL2 Container"]:::container
                AFLC3["afl-fuzz.c"]:::module
                CLLM3["chat-llm.c / h"]:::module
                CFG3["config.h"]:::module
            end

            docker --> CAF
            docker --> CL1C
            docker --> CL2C

            CAF --> AFLC1
            CAF --> CLLM1
            CAF --> CFG1

            CL1C --> AFLC2
            CL1C --> CLLM2
            CL1C --> CFG2

            CL2C --> AFLC3
            CL2C --> CLLM3
            CL2C --> CFG3
        end

        subgraph "AFLNet Core Module"
            direction TB
            AFLE["AFLNet Core"]:::container
            AFLC_net["afl-fuzz.c"]:::module
            ANET_c["aflnet.c / h"]:::module
            ACfg["config.h"]:::module
            docker --> AFLE
            AFLE --> AFLC_net
            AFLE --> ANET_c
            AFLE --> ACfg
        end

        subgraph "Subject Containers"
            direction TB
            lighttpd["Lighttpd1"]:::container
            live555["Live555"]:::container
            kamailio["Kamailio"]:::container
            pureftpd["PureFTPD"]:::container
            docker --> lighttpd
            docker --> live555
            docker --> kamailio
            docker --> pureftpd
        end
    end

    %% LLM Service and Phases
    subgraph "LLM Integration Phases"
        direction TB
        grammar["Grammar Extraction"]:::phase
        seeds["Seed Enrichment"]:::phase
        plateau["Plateau Breaking"]:::phase
    end

    CAF --> grammar
    CL1C --> grammar
    CL2C --> grammar

    grammar -->|"HTTP requests"| api["OpenAI API"]:::external
    api -->|"Grammar json"| storage1["Protocol Grammars"]:::storage

    CAF --> seeds
    CL1C --> seeds
    CL2C --> seeds

    seeds -->|"Prompt/response"| api
    api -->|"Seed files"| storage2["Seed Queue"]:::storage

    CAF --> plateau
    CL1C --> plateau
    CL2C --> plateau

    plateau -->|"Prompt/response"| api
    api -->|"Messages"| storage3["Stall Interactions"]:::storage

    %% Fuzz Loop
    AFLE -->|"network messages"| lighttpd
    AFLE -->|"network messages"| live555
    AFLE -->|"network messages"| kamailio
    AFLE -->|"network messages"| pureftpd
    AFLE --> storage4["Result Archive"]:::storage

    %% Analysis
    subgraph "Analysis Module"
        direction TB
        analyze["analyze.sh"]:::script
        plot1["coverage_plotting.py"]:::script
        plot2["profuzzbench_plot.py"]:::script
        plot3["profuzzbench_state.py"]:::script
    end

    storage4 --> analyze
    analyze --> plot1
    analyze --> plot2
    analyze --> plot3
    plot1 -->|"PNG/CSV"| reports["Reports (PNG/CSV)"]:::storage

    %% Click Events
    click CAF "https://github.com/chataflndss/chatafl/tree/master/ChatAFL/Dockerfile"
    click AFLC1 "https://github.com/chataflndss/chatafl/blob/master/ChatAFL/afl-fuzz.c"
    click CLLM1 "https://github.com/chataflndss/chatafl/blob/master/ChatAFL/chat-llm.c"
    click CFG1 "https://github.com/chataflndss/chatafl/blob/master/ChatAFL/config.h"

    click CL1C "https://github.com/chataflndss/chatafl/tree/master/ChatAFL-CL1/Dockerfile"
    click AFLC2 "https://github.com/chataflndss/chatafl/blob/master/ChatAFL-CL1/afl-fuzz.c"
    click CLLM2 "https://github.com/chataflndss/chatafl/blob/master/ChatAFL-CL1/chat-llm.c"
    click CFG2 "https://github.com/chataflndss/chatafl/blob/master/ChatAFL-CL1/config.h"

    click CL2C "https://github.com/chataflndss/chatafl/tree/master/ChatAFL-CL2/Dockerfile"
    click AFLC3 "https://github.com/chataflndss/chatafl/blob/master/ChatAFL-CL2/afl-fuzz.c"
    click CLLM3 "https://github.com/chataflndss/chatafl/blob/master/ChatAFL-CL2/chat-llm.c"
    click CFG3 "https://github.com/chataflndss/chatafl/blob/master/ChatAFL-CL2/config.h"

    click AFLE "https://github.com/chataflndss/chatafl/tree/master/aflnet/Dockerfile"
    click AFLC_net "https://github.com/chataflndss/chatafl/blob/master/aflnet/afl-fuzz.c"
    click ANET_c "https://github.com/chataflndss/chatafl/blob/master/aflnet/aflnet.c"
    click ACfg "https://github.com/chataflndss/chatafl/blob/master/aflnet/config.h"

    click run "https://github.com/chataflndss/chatafl/blob/master/run.sh"
    click setup "https://github.com/chataflndss/chatafl/blob/master/setup.sh"
    click build "https://github.com/chataflndss/chatafl/blob/master/benchmark/scripts/execution/profuzzbench_build_all.sh"
    click exec "https://github.com/chataflndss/chatafl/blob/master/benchmark/scripts/execution/profuzzbench_exec_all.sh"
    click deps "https://github.com/chataflndss/chatafl/blob/master/deps.sh"
    click clean "https://github.com/chataflndss/chatafl/blob/master/clean.sh"

    click lighttpd "https://github.com/chataflndss/chatafl/tree/master/benchmark/subjects/HTTP/Lighttpd1/Dockerfile"
    click live555 "https://github.com/chataflndss/chatafl/tree/master/benchmark/subjects/RTSP/Live555/Dockerfile"
    click kamailio "https://github.com/chataflndss/chatafl/tree/master/benchmark/subjects/SIP/Kamailio/Dockerfile"
    click pureftpd "https://github.com/chataflndss/chatafl/tree/master/benchmark/subjects/FTP/PureFTPD/Dockerfile"

    click storage1 "https://github.com/chataflndss/chatafl/tree/master/ChatAFL/dictionaries"
    click storage1 "https://github.com/chataflndss/chatafl/tree/master/ChatAFL-CL1/dictionaries"
    click storage1 "https://github.com/chataflndss/chatafl/tree/master/ChatAFL-CL2/dictionaries"

    click analyze "https://github.com/chataflndss/chatafl/blob/master/analyze.sh"
    click plot1 "https://github.com/chataflndss/chatafl/blob/master/benchmark/scripts/analysis/coverage_plotting.py"
    click plot2 "https://github.com/chataflndss/chatafl/blob/master/benchmark/scripts/analysis/profuzzbench_plot.py"
    click plot3 "https://github.com/chataflndss/chatafl/blob/master/benchmark/scripts/analysis/profuzzbench_state.py"

    %% Styles
    classDef container fill:#D0E8FF,stroke:#304FFE,stroke-width:1px
    classDef script fill:#E8F5E9,stroke:#1B5E20,stroke-width:1px
    classDef service fill:#E3F2FD,stroke:#0D47A1,stroke-width:1px
    classDef external fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px,stroke-dasharray: 5 5
    classDef storage fill:#FFF3E0,stroke:#E65100,stroke-width:1px
    classDef module fill:#F1F8E9,stroke:#33691E,stroke-width:1px
    classDef phase fill:#FFEBEE,stroke:#B71C1C,stroke-width:1px,stroke-dasharray: 2 2
```
