leviathan
4f30d00a1c
Adds core/host.{h,c} — a single struct skeletonkey_host populated once
at startup and handed to every module callback via ctx->host. Replaces
the per-detect uname / /etc/os-release / sysctl / userns-fork-probe
calls scattered across the corpus with O(1) cached lookups, and gives
the dispatcher one consistent view of the host.
What's in the fingerprint:
- Identity: kernel_version (parsed from uname.release), arch (machine),
nodename, distro_id / distro_version_id / distro_pretty (parsed once
from /etc/os-release).
- Process state: euid, real_uid (defeats userns illusion via
/proc/self/uid_map), egid, username, is_root, is_ssh_session.
- Platform family: is_linux, is_debian_family, is_rpm_family,
is_arch_family, is_suse_family (file-existence checks once).
- Capability gates (Linux): unprivileged_userns_allowed (live
fork+unshare probe), apparmor_restrict_userns,
unprivileged_bpf_disabled, kpti_enabled, kernel_lockdown_active,
selinux_enforcing, yama_ptrace_restricted.
- System services: has_systemd, has_dbus_system.
Wiring:
- core/module.h forward-declares struct skeletonkey_host and adds the
pointer to skeletonkey_ctx. Modules opt-in by including
../../core/host.h.
- core/host.c is fully POD (no heap pointers) — uses a single file-
static instance, returns a stable pointer on every call. Lazily
populated on first skeletonkey_host_get().
- skeletonkey.c calls skeletonkey_host_get() at main() entry, stores
in ctx.host before any register_*() runs.
- cmd_auto's bespoke distro-fingerprint code (was an inline
read_os_release helper) is replaced with skeletonkey_host_print_banner(),
which emits a two-line banner of identity + capability gates.
Migrations:
- dirtydecrypt: kernel_version_current() -> ctx->host->kernel.
- fragnesia: removed local fg_userns_allowed() fork-probe in favour of
ctx->host->unprivileged_userns_allowed (no per-scan fork). Also
pulls kernel from ctx->host. The PRECOND_FAIL message now notes
whether AppArmor restriction is on.
- pack2theroot: access('/etc/debian_version') -> ctx->host->is_debian_family;
also short-circuits when ctx->host->has_dbus_system is false (saves
the GLib g_bus_get_sync attempt on systems without system D-Bus).
- overlayfs: replaced the inline is_ubuntu() /etc/os-release parser
with ctx->host->distro_id comparison. Local helper preserved for
symmetry / standalone builds.
Documentation: docs/ARCHITECTURE.md gains a 'Host fingerprint'
section describing the struct, the opt-in include pattern, and
example detect() usage. ROADMAP --auto accuracy log notes the
landing and flags remaining modules as an incremental follow-up.
Build verification:
- macOS (local): make clean && make -> Mach-O x86_64, 31 modules,
banner prints with distro=?/? (no /etc/os-release).
- Linux (docker gcc:latest + libglib2.0-dev): make clean && make ->
ELF 64-bit, 31 modules. Banner prints with kernel + distro=debian/13
+ 7 capability gates. dirtydecrypt correctly says 'predates the
rxgk code added in 7.0'; fragnesia PRECOND_FAILs with
'(host fingerprint)' annotation; pack2theroot PRECOND_FAILs on
no-DBus; overlayfs reports 'not Ubuntu (distro=debian)'.
92 lines
4.4 KiB
C
92 lines
4.4 KiB
C
/*
|
|
* SKELETONKEY — host fingerprint
|
|
*
|
|
* Populated once at startup, before any module's detect() runs. Every
|
|
* module receives a stable pointer via skeletonkey_ctx.host and can
|
|
* consult it without re-parsing /proc, /etc/os-release, uname(2), or
|
|
* forking another userns probe.
|
|
*
|
|
* The struct is deliberately POD (no heap pointers, fixed-size
|
|
* arrays) so lifetime reasoning is trivial. A single static instance
|
|
* lives in core/host.c; skeletonkey_host_get() returns the same
|
|
* pointer on every call. The first call probes; subsequent calls
|
|
* are O(1) lookups.
|
|
*
|
|
* Fields that don't apply on a given platform (e.g. AppArmor sysctls
|
|
* on a non-Linux dev build, KPTI on aarch64) stay at their false /
|
|
* "?" defaults. Probing is best-effort: a missing sysctl never fails
|
|
* the call, just leaves the corresponding bool false.
|
|
*/
|
|
|
|
#ifndef SKELETONKEY_HOST_H
|
|
#define SKELETONKEY_HOST_H
|
|
|
|
#include "kernel_range.h"
|
|
|
|
#include <stdbool.h>
|
|
#include <stddef.h>
|
|
#include <sys/types.h>
|
|
|
|
struct skeletonkey_host {
|
|
/* ── identity ─────────────────────────────────────────────── */
|
|
|
|
struct kernel_version kernel; /* uname.release parsed */
|
|
char arch[32]; /* uname.machine ("x86_64", "aarch64") */
|
|
char nodename[64]; /* uname.nodename (for log lines) */
|
|
|
|
char distro_id[64]; /* /etc/os-release ID ("ubuntu", "debian", "fedora", "?") */
|
|
char distro_version_id[64]; /* /etc/os-release VERSION_ID ("24.04", "13", "?") */
|
|
char distro_pretty[128]; /* /etc/os-release PRETTY_NAME for log lines */
|
|
|
|
/* ── process state ─────────────────────────────────────────── */
|
|
|
|
uid_t euid; /* geteuid() */
|
|
uid_t real_uid; /* outer uid (defeats userns illusion via /proc/self/uid_map) */
|
|
gid_t egid; /* getegid() */
|
|
char username[64]; /* getpwuid(euid)->pw_name or "" */
|
|
bool is_root; /* euid == 0 */
|
|
bool is_ssh_session; /* SSH_CONNECTION env var set */
|
|
|
|
/* ── platform family ───────────────────────────────────────── */
|
|
|
|
bool is_linux; /* compiled / running on Linux */
|
|
bool is_debian_family; /* /etc/debian_version exists */
|
|
bool is_rpm_family; /* redhat / fedora / rocky / almalinux release file */
|
|
bool is_arch_family; /* /etc/arch-release */
|
|
bool is_suse_family; /* /etc/SuSE-release or /etc/SUSE-brand */
|
|
|
|
/* ── capability / gate flags (Linux) ──────────────────────── */
|
|
|
|
bool unprivileged_userns_allowed; /* fork+unshare(CLONE_NEWUSER) succeeded */
|
|
bool apparmor_restrict_userns; /* sysctl: 1 = AA blocks unpriv userns */
|
|
bool unprivileged_bpf_disabled; /* /proc/sys/kernel/unprivileged_bpf_disabled = 1 */
|
|
bool kpti_enabled; /* /sys/.../meltdown contains "Mitigation: PTI" */
|
|
bool kernel_lockdown_active; /* /sys/kernel/security/lockdown != [none] */
|
|
bool selinux_enforcing; /* /sys/fs/selinux/enforce = 1 */
|
|
bool yama_ptrace_restricted; /* /proc/sys/kernel/yama/ptrace_scope > 0 */
|
|
|
|
/* ── system services ──────────────────────────────────────── */
|
|
|
|
bool has_systemd; /* /run/systemd/system exists */
|
|
bool has_dbus_system; /* /run/dbus/system_bus_socket exists */
|
|
|
|
/* Informational: the SKELETONKEY component that populated this
|
|
* snapshot (for log/JSON output). */
|
|
const char *probe_source;
|
|
};
|
|
|
|
/* Get the host fingerprint. Returns a stable, non-null pointer that
|
|
* lives for the process lifetime. Probes happen lazily on the first
|
|
* call (~50ms; dominated by the userns fork-probe), are cached, and
|
|
* subsequent calls are free.
|
|
*
|
|
* Probing is best-effort: missing files / unsupported sysctls leave
|
|
* the corresponding bool false. The function does not fail. */
|
|
const struct skeletonkey_host *skeletonkey_host_get(void);
|
|
|
|
/* Print a two-line "host fingerprint" banner to stderr suitable for
|
|
* --auto / --scan verbose output. Silent on JSON mode. */
|
|
void skeletonkey_host_print_banner(const struct skeletonkey_host *h, bool json);
|
|
|
|
#endif /* SKELETONKEY_HOST_H */
|