# yahel150/elf-analysis-and-debugging-tool architecture

> Architecture diagram of the GitHub repository yahel150/elf-analysis-and-debugging-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yahel150/elf-analysis-and-debugging-tool
- Repository: https://github.com/yahel150/elf-analysis-and-debugging-tool

## Overview

xdbg is a Linux x86-64 ELF inspection and debugging tool. Users invoke analysis, disassembly, local debugging, or remote debugging through the CLI. Analysis maps an ELF file before reporting its headers, segments, sections, symbols, and security properties; decoding disassembles its text section and explains instructions. Debugging controls a target process with breakpoints, stepping, register and memory inspection, source mapping, and an optional TUI. Remote debugging relays commands between a client and a worker hosting the debugger. Some module wiring is inferred only from documented capabilities and filenames; unsampled implementation details are not asserted.

Main entry points: [`debugger/debugger.c`](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/debugger.c) (Debugger session), [`main.c`](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/main.c) (Command dispatcher), [`decoder/decode.c`](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/decode.c) (Text disassembly), [`remote/remote_worker.c`](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/remote/remote_worker.c) (Remote worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and analysis"]
  node_main["Command dispatcher<br/>[main.c]"]
  node_elf_parser["ELF mapping and lookup<br/>[elf_parser.c]"]
  node_elf_sections["Section reporting<br/>[elf_sections.c]"]
  node_elf_segments["Segment reporting<br/>[elf_segments.c]"]
  node_elf_symbols["Symbol reporting<br/>[elf_symbols.c]"]
  node_elf_security["Security analysis<br/>[elf_security.c]"]
end

subgraph group_decode["Instruction decoding"]
  node_decode_entry["Text disassembly<br/>[decode.c]"]
  node_decode_opcode["Opcode decoding<br/>[opcode.c]"]
  node_decode_rex["REX parsing<br/>[rex.c]"]
  node_decode_modrm["ModR/M parsing<br/>[modrm.c]"]
  node_decode_immediate["Immediate parsing<br/>[immediate.c]"]
  node_decode_print["Instruction explanation<br/>[pretty_print.c]"]
end

subgraph group_debug["Local debugging"]
  node_debugger["Debugger session<br/>[debugger.c]"]
  node_breakpoints["Breakpoint control<br/>[breakpoint.c]"]
  node_memory["Process memory<br/>[memory.c]"]
  node_registers["Register access<br/>[registers.c]"]
  node_singlestep["Execution stepping<br/>[singlestep.c]"]
  node_signals["Signal handling<br/>[signals.c]"]
  node_live_got["Live GOT view<br/>[live_got.c]"]
  node_source_map["Source mapping<br/>[source_map.c]"]
  node_tui["Terminal interface<br/>[tui.c]"]
end

subgraph group_remote["Remote debugging"]
  node_remote_entry["Remote command entry<br/>[remote.c]"]
  node_remote_worker["Remote worker<br/>[remote_worker.c]"]
  node_remote_client["Remote client<br/>[remote_client.c]"]
  node_remote_ipc["Worker IPC<br/>[remote_ipc.c]"]
  node_remote_net["Network transport<br/>[remote_net.c]"]
end

node_user(("User"))
node_elf_input["ELF input"]
node_target(("Debug target"))

node_user -->|"runs command"| node_main
node_main -->|"opens ELF"| node_elf_parser
node_elf_input -->|"mapped input"| node_elf_parser
node_main -->|"analyzes security"| node_elf_security
node_main -->|"prints sections"| node_elf_sections
node_main -->|"prints segments"| node_elf_segments
node_main -->|"prints symbols"| node_elf_symbols
node_main -->|"decodes text"| node_decode_entry
node_decode_entry -->|"reads ELF data"| node_elf_parser
node_decode_entry -->|"parses prefixes"| node_decode_rex
node_decode_entry -->|"decodes opcode"| node_decode_opcode
node_decode_entry -->|"parses operands"| node_decode_modrm
node_decode_entry -->|"reads immediates"| node_decode_immediate
node_decode_entry -->|"formats explanation"| node_decode_print
node_main -->|"starts debugger"| node_debugger
node_target -->|"debugged by"| node_debugger
node_debugger -->|"manages breakpoints"| node_breakpoints
node_debugger -->|"reads and writes"| node_memory
node_debugger -->|"reads registers"| node_registers
node_debugger -->|"controls stepping"| node_singlestep
node_debugger -->|"handles signals"| node_signals
node_debugger -->|"inspects GOT"| node_live_got
node_debugger -->|"resolves source"| node_source_map
node_debugger -->|"renders interface"| node_tui
node_main -->|"starts remote mode"| node_remote_entry
node_remote_entry -->|"runs worker"| node_remote_worker
node_remote_entry -->|"runs client"| node_remote_client
node_remote_worker -->|"launches backend"| node_debugger
node_remote_worker -->|"exchanges events"| node_remote_ipc
node_remote_worker -->|"serves connection"| node_remote_net
node_remote_client -->|"connects and sends"| node_remote_net

click node_main "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/main.c"
click node_elf_parser "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/elf/elf_parser.c"
click node_elf_sections "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/elf/elf_sections.c"
click node_elf_segments "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/elf/elf_segments.c"
click node_elf_symbols "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/elf/elf_symbols.c"
click node_elf_security "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/elf/elf_security.c"
click node_decode_entry "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/decode.c"
click node_decode_opcode "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/opcode.c"
click node_decode_rex "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/rex.c"
click node_decode_modrm "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/modrm.c"
click node_decode_immediate "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/immediate.c"
click node_decode_print "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/pretty_print.c"
click node_debugger "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/debugger.c"
click node_breakpoints "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/breakpoint.c"
click node_memory "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/memory.c"
click node_registers "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/registers.c"
click node_singlestep "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/singlestep.c"
click node_signals "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/signals.c"
click node_live_got "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/live_got.c"
click node_source_map "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/dwarf/source_map.c"
click node_tui "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/tui/tui.c"
click node_remote_entry "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/remote/remote.c"
click node_remote_worker "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/remote/remote_worker.c"
click node_remote_client "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/remote/remote_client.c"
click node_remote_ipc "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/remote/remote_ipc.c"
click node_remote_net "https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/remote/remote_net.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_main,node_elf_parser,node_elf_sections,node_elf_segments,node_elf_symbols,node_elf_security,node_user toneBlue
class node_decode_entry,node_decode_opcode,node_decode_rex,node_decode_modrm,node_decode_immediate,node_decode_print toneAmber
class node_debugger,node_breakpoints,node_memory,node_registers,node_singlestep,node_signals,node_live_got,node_source_map,node_tui toneMint
class node_remote_entry,node_remote_worker,node_remote_client,node_remote_ipc,node_remote_net toneRose
class node_elf_input,node_target toneIndigo
```

## Components

### CLI and analysis

- [Command dispatcher](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/main.c): `main.c`
- [ELF mapping and lookup](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/elf/elf_parser.c): `elf/elf_parser.c`
- [Section reporting](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/elf/elf_sections.c): `elf/elf_sections.c`
- [Segment reporting](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/elf/elf_segments.c): `elf/elf_segments.c`
- [Symbol reporting](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/elf/elf_symbols.c): `elf/elf_symbols.c`
- [Security analysis](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/elf/elf_security.c): `elf/elf_security.c`

### Instruction decoding

- [Text disassembly](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/decode.c): `decoder/decode.c`
- [Opcode decoding](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/opcode.c): `decoder/opcode.c`
- [REX parsing](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/rex.c): `decoder/rex.c`
- [ModR/M parsing](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/modrm.c): `decoder/modrm.c`
- [Immediate parsing](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/immediate.c): `decoder/immediate.c`
- [Instruction explanation](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/decoder/pretty_print.c): `decoder/pretty_print.c`

### Local debugging

- [Debugger session](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/debugger.c): `debugger/debugger.c`
- [Breakpoint control](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/breakpoint.c): `debugger/breakpoint.c`
- [Process memory](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/memory.c): `debugger/memory.c`
- [Register access](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/registers.c): `debugger/registers.c`
- [Execution stepping](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/singlestep.c): `debugger/singlestep.c`
- [Signal handling](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/signals.c): `debugger/signals.c`
- [Live GOT view](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/debugger/live_got.c): `debugger/live_got.c`
- [Source mapping](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/dwarf/source_map.c): `dwarf/source_map.c`
- [Terminal interface](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/tui/tui.c): `tui/tui.c`

### Remote debugging

- [Remote command entry](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/remote/remote.c): `remote/remote.c`
- [Remote worker](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/remote/remote_worker.c): `remote/remote_worker.c`
- [Remote client](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/remote/remote_client.c): `remote/remote_client.c`
- [Worker IPC](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/remote/remote_ipc.c): `remote/remote_ipc.c`
- [Network transport](https://github.com/yahel150/elf-analysis-and-debugging-tool/blob/main/remote/remote_net.c): `remote/remote_net.c`

### Other components

- **User**
- **ELF input**
- **Debug target**

## Connections

- User → Command dispatcher: runs command
- Command dispatcher → ELF mapping and lookup: opens ELF
- ELF input → ELF mapping and lookup: mapped input
- Command dispatcher → Security analysis: analyzes security
- Command dispatcher → Section reporting: prints sections
- Command dispatcher → Segment reporting: prints segments
- Command dispatcher → Symbol reporting: prints symbols
- Command dispatcher → Text disassembly: decodes text
- Text disassembly → ELF mapping and lookup: reads ELF data
- Text disassembly → REX parsing: parses prefixes
- Text disassembly → Opcode decoding: decodes opcode
- Text disassembly → ModR/M parsing: parses operands
- Text disassembly → Immediate parsing: reads immediates
- Text disassembly → Instruction explanation: formats explanation
- Command dispatcher → Debugger session: starts debugger
- Debug target → Debugger session: debugged by
- Debugger session → Breakpoint control: manages breakpoints
- Debugger session → Process memory: reads and writes
- Debugger session → Register access: reads registers
- Debugger session → Execution stepping: controls stepping
- Debugger session → Signal handling: handles signals
- Debugger session → Live GOT view: inspects GOT
- Debugger session → Source mapping: resolves source
- Debugger session → Terminal interface: renders interface
- Command dispatcher → Remote command entry: starts remote mode
- Remote command entry → Remote worker: runs worker
- Remote command entry → Remote client: runs client
- Remote worker → Debugger session: launches backend
- Remote worker → Worker IPC: exchanges events
- Remote worker → Network transport: serves connection
- Remote client → Network transport: connects and sends