github.com/SparkGuard/SparkProctoringFingerprint

SparkProctoringFingerprint

Сбор отпечатка машины (host fingerprint) для прокторингового агента: операционная система, аппаратное обеспечение, мониторы, сетевые интерфейсы, материнская плата, BIOS, батарея, признаки виртуализации. Используется агентом для двух задач:

• Full snapshot — толстый разовый снимок, который сервер запоминает как baseline сессии.
• Heartbeat — лёгкий периодический снимок (≤10 мс), позволяющий обнаруживать подмену сессии (например, студент отключился и переподключился с другой машины).

Все идентификаторы (machine-id, серийники, MAC) хешируются через HMAC-SHA256 с session-scoped ключом — сырых PII за пределы агента не уходит.

Установка

go get github.com/SparkGuard/SparkProctoringFingerprint

Модуль не делает CGO-вызовов на Linux/Windows; на macOS использует системные фреймворки. Внешних рантайм-зависимостей нет, на Linux опционально применяется dmidecode (для подробной информации о DIMM).

Использование

import (
    "context"

    "github.com/SparkGuard/SparkProctoringFingerprint/pkg/fingerprint"
)

func main() {
    // sessionKey приходит с сервера на этапе AuthSession.
    coll := fingerprint.New(fingerprint.WithHashing(sessionKey))

    // Толстый снимок — один раз при старте сессии.
    full, err := coll.CollectFull(context.Background())
    if err != nil {
        // ErrNoSessionKey, если ключ не установлен.
    }
    _ = full // FullSnapshot{OS, CPU, Memory, GPUs, Disks, Monitors, Network, Board, Battery, VM, Identifiers}

    // Heartbeat — периодически (раз в 30–60 секунд).
    hb, _ := coll.CollectHeartbeat(context.Background())
    _ = hb // Heartbeat{Identifiers (хеши), BootTime, Uptime, Locale, ScreenLayout, ActiveInterface, Hypervisor*}
}

Если ключ установлен после первого CollectFull, его можно обновить — кешированные идентификаторы будут пересчитаны:

coll.SetSessionKey(newKey)

Сериализация в JSON делается стандартным encoding/json — структуры FullSnapshot и Heartbeat обладают стабильными json:"..." тегами и доходят до сервера в исходном виде.

Архитектура

pkg/fingerprint/         публичный API: интерфейс Collector + типы FullSnapshot, Heartbeat
pkg/wire/                JSON-схема (re-export'ится из pkg/fingerprint)

pkg/fingerprint/collector_darwin.go   реализация macOS (IOKit, sysctl, system_profiler)
pkg/fingerprint/collector_linux.go    реализация Linux (/sys, /proc, /etc, dmidecode)
pkg/fingerprint/collector_stub.go     заглушка для прочих платформ (Windows — TODO)

internal/hardware/       платформенные сборщики CPU/Memory/Disks/GPUs/Monitors/Network/Board (только darwin)
internal/osinfo/         сборщик OS-информации (только darwin)
internal/vmdetect/       детектор виртуализации (только darwin)
internal/ids/            HMAC-SHA256 + machine-id readers
internal/util/           обёртки над exec.Command с таймаутом

Linux-коллектор реализован монолитно в pkg/fingerprint/collector_linux.go — без разбиения на internal/*. Источники данных:

Подсистема	Источник
OS family / arch	runtime
Distribution / Version / BuildID	/etc/os-release
Kernel	unix.Uname
Locale, Timezone	$LANG, time.Local.Zone()
Boot/Uptime	/proc/uptime
CPU	/proc/cpuinfo, /sys/devices/system/cpu/cpu0/cpufreq, /sys/devices/system/cpu/cpu0/cache
Memory total/available	/proc/meminfo
Memory modules (DIMM)	dmidecode -t 17 (только под root)
Disks	/sys/block/*/{device/model,device/serial,size,removable,queue/rotational}
GPUs	/sys/class/drm/card*/device/{vendor,device}
Monitors / EDID	/sys/class/drm/card*-*/{status,modes,edid}
Network interfaces	net.Interfaces, /sys/class/net/*/wireless, /proc/net/route
DNS	/etc/resolv.conf
Board / BIOS	/sys/class/dmi/id/{board_*,bios_*,product_uuid,sys_vendor}
Battery	/sys/class/power_supply/BAT*/{energy_full,energy_full_design,cycle_count}
Machine ID	/etc/machine-id (fallback /var/lib/dbus/machine-id)
VM detection	systemd-detect-virt, /proc/cpuinfo flag, DMI sys_vendor
Keyboard layouts	localectl status (fallback /etc/default/keyboard)

CollectHeartbeat читает только из in-memory кеша (заполняется в CollectFull) — никаких syscall'ов в горячем пути.

VM detection

Linux-ветка собирает три сигнала: systemd-detect-virt --vm, systemd-detect-virt --container, наличие флага hypervisor в /proc/cpuinfo, а также проверяет DMI sys_vendor на VMware/QEMU/Xen/Hyper-V. Каждый сигнал пишется в VMReport.Signals с весом — сервер может пересчитать Confidence по своей логике.

Privacy / hashing

В соответствии с docs/privacy-and-hashing.md:

• Identifiers.*Hash — всегда HMAC-SHA256(sessionKey, raw).
• Board.SerialRaw, Board.UUIDRaw, Disks[].SerialRaw, Network.Interfaces[].MACRaw — пусто, если sessionKey установлен (хешированный режим). Сырые значения остаются только когда ключ не установлен (отладочный режим, например cmd/fingerprint-probe).
• В Heartbeat сырых идентификаторов нет ни в каком режиме.

Тестирование

go test ./...

Юнит-тесты сосредоточены на pkg/fingerprint/snapshot_test.go (round-trip JSON) и internal/ids/hmac_test.go. Платформенные сборщики проверяются вручную через CLI:

go run ./cmd/fingerprint-probe -hash $(openssl rand -hex 32) | jq .

Кросс-компиляция (минимально — должно собираться):

GOOS=linux  go build ./...
GOOS=darwin go build ./...

Windows-ветка пока представлена collector_stub.go — заполняется только Hostname/Username/AgentPID/AgentUptime.

Подробная документация

Внутренние материалы расположены в docs/ (CLAUDE.md перечисляет полный список):

• docs/architecture.md — диаграммы, потоки данных.
• docs/data-model.md — описание полей FullSnapshot / Heartbeat / VMReport.
• docs/vm-detection.md — список сигналов детекта виртуализации.
• docs/platform-linux.md, docs/platform-darwin.md — источники данных по платформам.
• docs/integration-agent.md — как агент интегрируется через internal/hostinfo.
• docs/privacy-and-hashing.md — правила обращения с PII.