vpnhide/data/hooks.toml

# Single source of truth for the vpnhide hook registry — the global id space
# shared by the control/stats protocol (docs/protocol.md §5).
#
#   - bit N of a config `hookmask` == hook id N.
#   - a `stats` line emits `<hook_id>:<count>` pairs over the same ids.
#   - each backend acts only on `mask & <backend>_own` and ignores foreign bits.
#
# Read at codegen time by scripts/codegen-hooks.py, which renders the matching
# id enums + per-backend masks + status error codes for every language that
# touches the protocol (kmod/KPM C, zygisk Rust, lsposed-native Rust, app
# Kotlin). A CI lint step re-runs the codegen and fails if the generated files
# drift, so the numbering can never diverge between backends.
#
# APPEND-ONLY. A hook id, once assigned, is permanent: stats from an old backend
# must keep meaning the same hook forever, and an old reader skips unknown ids
# rather than misreading them (protocol §4.5). To add a hook, append it with the
# next free id — never renumber, never reuse a retired id.

# --- kernel hooks (.ko + KPM share these; ids match the install order) -------

[[hook]]
id = 0
name = "fib_route_seq_show"
backend = "kernel"
note = "/proc/net/route — IPv4 route lines"

[[hook]]
id = 1
name = "ipv6_route_seq_show"
backend = "kernel"
note = "/proc/net/ipv6_route — IPv6 route lines"

[[hook]]
id = 2
name = "rtnl_fill_ifinfo"
backend = "kernel"
note = "RTM_NEWLINK — getifaddrs() link enumeration"

[[hook]]
id = 3
name = "inet_fill_ifaddr"
backend = "kernel"
note = "RTM_GETADDR — IPv4 address dump"

[[hook]]
id = 4
name = "inet6_fill_ifaddr"
backend = "kernel"
note = "RTM_GETADDR — IPv6 address dump"

[[hook]]
id = 5
name = "dev_ioctl"
backend = "kernel"
note = "SIOCGIF* by name (per-interface ioctls)"

[[hook]]
id = 6
name = "sock_ioctl"
backend = "kernel"
note = "SIOCGIFCONF — interface list ioctl"

[[hook]]
id = 7
name = "fib_dump_info"
backend = "kernel"
note = "RTM_GETROUTE — IPv4 route dump (issue #86)"

[[hook]]
id = 8
name = "rt6_fill_node"
backend = "kernel"
note = "RTM_GETROUTE — IPv6 route dump"

[[hook]]
id = 9
name = "fib_nl_fill_rule"
backend = "kernel"
note = "RTM_GETRULE — policy routing rules"

# --- LSPosed Java hooks (system_server) ------------------------------------

[[hook]]
id = 10
name = "lsposed_link_properties"
backend = "lsposed"
note = "LinkProperties parcel/result sanitization"

[[hook]]
id = 11
name = "lsposed_network_capabilities"
backend = "lsposed"
note = "NetworkCapabilities parcel/result sanitization"

[[hook]]
id = 12
name = "lsposed_network_info"
backend = "lsposed"
note = "NetworkInfo parcel/result sanitization"

[[hook]]
id = 13
name = "lsposed_network"
backend = "lsposed"
note = "Network handle replacement/filtering"

[[hook]]
id = 14
name = "lsposed_connectivity_result"
backend = "lsposed"
note = "ConnectivityService synchronous result filtering"

[[hook]]
id = 15
name = "lsposed_connectivity_callback"
backend = "lsposed"
note = "ConnectivityService callback filtering"

[[hook]]
id = 16
name = "lsposed_connectivity_network"
backend = "lsposed"
note = "ConnectivityService Network handle APIs"

[[hook]]
id = 17
name = "lsposed_package_visibility"
backend = "lsposed"
note = "PackageManager app-hiding filters"

# --- Zygisk libc hooks -----------------------------------------------------

[[hook]]
id = 18
name = "zygisk_ioctl"
backend = "zygisk"
note = "libc ioctl() SIOCGIF* interface probes"

[[hook]]
id = 19
name = "zygisk_getifaddrs"
backend = "zygisk"
note = "libc getifaddrs() interface enumeration"

[[hook]]
id = 20
name = "zygisk_openat"
backend = "zygisk"
note = "openat() filtering for /proc/net routes and sockets"

[[hook]]
id = 21
name = "zygisk_recvmsg"
backend = "zygisk"
note = "recvmsg() netlink dump filtering"

[[hook]]
id = 22
name = "zygisk_recv"
backend = "zygisk"
note = "recv() netlink dump filtering"

[[hook]]
id = 23
name = "zygisk_recvfrom"
backend = "zygisk"
note = "recvfrom() netlink dump filtering"

[[hook]]
id = 24
name = "zygisk_recvfrom_chk"
backend = "zygisk"
note = "__recvfrom_chk() fortified netlink dump filtering"

# --- backend ids (protocol §4.3 `status backend <id>`) ----------------------
# Which backend answered a `status` read. Distinct from the hook `backend`
# field above (.ko and KPM both own "kernel" hooks but are separate backends).
# APPEND-ONLY, same as hook/error ids.

[[backend]]
id = 0
name = "kmod"
note = ".ko kretprobe backend"

[[backend]]
id = 1
name = "kpm"
note = "KernelPatch Module backend"

[[backend]]
id = 2
name = "zygisk"
note = "Zygisk libc-hook backend"

[[backend]]
id = 3
name = "lsposed"
note = "LSPosed Java-hook backend (system_server)"

# --- status error codes (protocol §5.1) -------------------------------------
# A single dominant fault code returned in a `status` payload's `error` field.

[[error]]
id = 0
name = "ok"
note = "healthy; every requested, owned hook installed"

[[error]]
id = 1
name = "unsupported_kver"
note = "no offset table for the running kernel — refused, no hooks"

[[error]]
id = 2
name = "conflicting_backend"
note = "the other kernel backend (.ko<->KPM) is loaded — refused (protocol §1.2)"

[[error]]
id = 3
name = "symbol_resolution_failed"
note = "a required kallsyms symbol was missing — refused"

[[error]]
id = 4
name = "partial_hooks"
note = "installed, but some owned hooks did not resolve (see the hooks mask)"