# hieunguyen2711/parser-fuzzer architecture

> Architecture diagram of the GitHub repository hieunguyen2711/parser-fuzzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hieunguyen2711/parser-fuzzer
- Repository: https://github.com/hieunguyen2711/parser-fuzzer

## Overview

Parser Fuzzer is a grammar-guided, LLM-assisted fuzzer for the mxml XML parser. Its principal workflow generates a Hypothesis strategy, validates it cheaply, runs a campaign through a sanitizer-enabled C harness, then summarizes results and refines the strategy. A separate grammar-check capability compares the standard and mxml-adjusted grammars with mxml’s actual acceptance. The graph preserves the README-documented grammar-check branch; unsampled implementation details are represented only where the README supports them.

Main entry points: [`fuzzer/loop.py`](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/loop.py) (Refinement loop), [`fuzzer/seed_run.py`](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/seed_run.py) (Seed run), [`fuzzer/triage.py`](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/triage.py) (Crash triage), [`grammar/compare_grammars.py`](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/grammar/compare_grammars.py) (Grammar comparison)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Strategy generation"]
  node_seed["Seed run<br/>[seed_run.py]"]
  node_refinement["Refinement loop<br/>[loop.py]"]
  node_prompt["Prompt construction<br/>[prompts.py]"]
  node_strategy_io["Strategy loading<br/>[strategy_io.py]"]
  node_strategies["Hypothesis strategies"]
end

subgraph group_campaign["Fuzzing campaign"]
  node_validation["Strategy validation<br/>[validate.py]"]
  node_examples["Example generation<br/>[examples.py]"]
  node_campaign_run["Campaign execution<br/>[campaign.py]"]
  node_runner["Harness runner<br/>[runner.py]"]
  node_score["Campaign scoring<br/>[score.py]"]
  node_triage["Crash triage<br/>[triage.py]"]
  node_summary["Run summary<br/>[summary.py]"]
  node_findings["Crash findings"]
end

subgraph group_target["Parser harness"]
  node_harness["C harness<br/>[harness.c]"]
  node_target_glue["mxml adapter<br/>[fuzz_target.c]"]
  node_mxml["mxml parser"]
end

subgraph group_grammar["Grammar verification"]
  node_standard_grammar["XML grammar<br/>[XMLParser.g4]"]
  node_mxml_grammar["mxml grammar<br/>[XMLmxmlParser.g4]"]
  node_grammar_check["Grammar comparison"]
  node_mxml_probe["Acceptance probe<br/>[probe_mxml.c]"]
end

node_user(("Engineer"))
node_model["Vertex AI model"]

node_user -->|"starts seed"| node_seed
node_user -->|"starts refinement"| node_refinement
node_seed -->|"builds prompt"| node_prompt
node_seed -->|"requests strategy"| node_model
node_refinement -->|"builds prompts"| node_prompt
node_refinement -->|"requests revisions"| node_model
node_model -->|"returns strategy"| node_seed
node_model -->|"returns revisions"| node_refinement
node_seed -->|"extracts and loads"| node_strategy_io
node_refinement -->|"extracts and loads"| node_strategy_io
node_strategy_io -->|"loads module"| node_strategies
node_seed -->|"checks strategy"| node_validation
node_refinement -->|"checks strategy"| node_validation
node_validation -->|"draws samples"| node_examples
node_validation -->|"runs samples"| node_runner
node_refinement -->|"runs campaign"| node_campaign_run
node_campaign_run -->|"runs inputs"| node_runner
node_campaign_run -->|"signs crashes"| node_triage
node_refinement -->|"scores results"| node_score
node_refinement -->|"summarizes results"| node_summary
node_refinement -->|"saves findings"| node_triage
node_summary -->|"reads statistics"| node_campaign_run
node_summary -->|"reads findings"| node_triage
node_triage -->|"uses run results"| node_runner
node_triage -->|"writes reports"| node_findings
node_runner -->|"executes process"| node_harness
node_harness -->|"dispatches input"| node_target_glue
node_target_glue -->|"parses document"| node_mxml
node_user -->|"runs check"| node_grammar_check
node_grammar_check -->|"compares grammar"| node_standard_grammar
node_grammar_check -->|"compares grammar"| node_mxml_grammar
node_grammar_check -->|"compiles probe"| node_mxml_probe
node_mxml_probe -->|"tests acceptance"| node_mxml

click node_seed "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/seed_run.py"
click node_refinement "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/loop.py"
click node_prompt "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/prompts.py"
click node_strategy_io "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/strategy_io.py"
click node_strategies "https://github.com/hieunguyen2711/parser-fuzzer/tree/main/fuzzer/strategies"
click node_validation "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/validate.py"
click node_examples "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/examples.py"
click node_campaign_run "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/campaign.py"
click node_runner "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/runner.py"
click node_score "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/score.py"
click node_triage "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/triage.py"
click node_summary "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/summary.py"
click node_findings "https://github.com/hieunguyen2711/parser-fuzzer/tree/main/crashes"
click node_harness "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/harness/harness.c"
click node_target_glue "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/harness/fuzz_target.c"
click node_mxml "https://github.com/hieunguyen2711/parser-fuzzer/tree/main/target"
click node_standard_grammar "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/grammar/XMLParser.g4"
click node_mxml_grammar "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/grammar/XMLmxmlParser.g4"
click node_grammar_check "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/grammar/compare_grammars.py"
click node_mxml_probe "https://github.com/hieunguyen2711/parser-fuzzer/blob/main/grammar/probe_mxml.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_seed,node_refinement,node_prompt,node_strategy_io,node_strategies toneBlue
class node_validation,node_examples,node_campaign_run,node_runner,node_score,node_triage,node_summary,node_findings toneAmber
class node_harness,node_target_glue,node_mxml toneMint
class node_standard_grammar,node_mxml_grammar,node_grammar_check,node_mxml_probe toneRose
class node_user,node_model toneIndigo
```

## Components

### Strategy generation

- [Seed run](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/seed_run.py): `fuzzer/seed_run.py`
- [Refinement loop](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/loop.py): `fuzzer/loop.py`
- [Prompt construction](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/prompts.py): `fuzzer/prompts.py`
- [Strategy loading](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/strategy_io.py): `fuzzer/strategy_io.py`
- [Hypothesis strategies](https://github.com/hieunguyen2711/parser-fuzzer/tree/main/fuzzer/strategies): `fuzzer/strategies`

### Fuzzing campaign

- [Strategy validation](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/validate.py): `fuzzer/validate.py`
- [Example generation](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/examples.py): `fuzzer/examples.py`
- [Campaign execution](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/campaign.py): `fuzzer/campaign.py`
- [Harness runner](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/runner.py): `fuzzer/runner.py`
- [Campaign scoring](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/score.py): `fuzzer/score.py`
- [Crash triage](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/triage.py): `fuzzer/triage.py`
- [Run summary](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/fuzzer/summary.py): `fuzzer/summary.py`
- [Crash findings](https://github.com/hieunguyen2711/parser-fuzzer/tree/main/crashes): `crashes`

### Parser harness

- [C harness](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/harness/harness.c): `harness/harness.c`
- [mxml adapter](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/harness/fuzz_target.c): `harness/fuzz_target.c`
- [mxml parser](https://github.com/hieunguyen2711/parser-fuzzer/tree/main/target): `target`

### Grammar verification

- [XML grammar](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/grammar/XMLParser.g4): `grammar/XMLParser.g4`
- [mxml grammar](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/grammar/XMLmxmlParser.g4): `grammar/XMLmxmlParser.g4`
- [Grammar comparison](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/grammar/compare_grammars.py): `grammar/compare_grammars.py`
- [Acceptance probe](https://github.com/hieunguyen2711/parser-fuzzer/blob/main/grammar/probe_mxml.c): `grammar/probe_mxml.c`

### Other components

- **Engineer**
- **Vertex AI model**

## Connections

- Engineer → Seed run: starts seed (evidence: `README.md`)
- Engineer → Refinement loop: starts refinement (evidence: `README.md`)
- Seed run → Prompt construction: builds prompt (evidence: `fuzzer/seed_run.py`)
- Seed run → Vertex AI model: requests strategy (evidence: `fuzzer/seed_run.py`)
- Refinement loop → Prompt construction: builds prompts (evidence: `fuzzer/loop.py`)
- Refinement loop → Vertex AI model: requests revisions (evidence: `fuzzer/loop.py`)
- Vertex AI model → Seed run: returns strategy (evidence: `README.md`)
- Vertex AI model → Refinement loop: returns revisions (evidence: `README.md`)
- Seed run → Strategy loading: extracts and loads (evidence: `fuzzer/seed_run.py`)
- Refinement loop → Strategy loading: extracts and loads (evidence: `fuzzer/loop.py`)
- Strategy loading → Hypothesis strategies: loads module (evidence: `fuzzer/strategy_io.py`)
- Seed run → Strategy validation: checks strategy (evidence: `fuzzer/seed_run.py`)
- Refinement loop → Strategy validation: checks strategy (evidence: `fuzzer/loop.py`)
- Strategy validation → Example generation: draws samples (evidence: `fuzzer/validate.py`)
- Strategy validation → Harness runner: runs samples (evidence: `fuzzer/validate.py`)
- Refinement loop → Campaign execution: runs campaign (evidence: `fuzzer/loop.py`)
- Campaign execution → Harness runner: runs inputs (evidence: `fuzzer/campaign.py`)
- Campaign execution → Crash triage: signs crashes (evidence: `fuzzer/campaign.py`)
- Refinement loop → Campaign scoring: scores results (evidence: `fuzzer/loop.py`)
- Refinement loop → Run summary: summarizes results (evidence: `fuzzer/loop.py`)
- Refinement loop → Crash triage: saves findings (evidence: `fuzzer/loop.py`)
- Run summary → Campaign execution: reads statistics (evidence: `fuzzer/summary.py`)
- Run summary → Crash triage: reads findings (evidence: `fuzzer/summary.py`)
- Crash triage → Harness runner: uses run results (evidence: `fuzzer/triage.py`)
- Crash triage → Crash findings: writes reports
- Harness runner → C harness: executes process (evidence: `README.md`)
- C harness → mxml adapter: dispatches input (evidence: `README.md`)
- mxml adapter → mxml parser: parses document (evidence: `harness/fuzz_target.c`)
- Engineer → Grammar comparison: runs check (evidence: `README.md`)
- Grammar comparison → XML grammar: compares grammar (evidence: `README.md`)
- Grammar comparison → mxml grammar: compares grammar (evidence: `README.md`)
- Grammar comparison → Acceptance probe: compiles probe (evidence: `README.md`)
- Acceptance probe → mxml parser: tests acceptance (evidence: `README.md`)
