Skip to content

prereqs

prereqs

Host binary prerequisite checks for the shield runtime.

Exported for higher layers (terok-sandbox aggregator, operator diagnostics) so the place that owns each binary — shield — is the place that publishes the list of binaries it depends on. Keeps the install-time preflight and the runtime failure sites honest about what the shield actually needs.

Pure probes: every check is shutil.which or a sbin-aware variant. No subprocess invocation, no side effects.

BinaryCheck(name, path, purpose) dataclass

Result of probing for a single prerequisite binary.

name instance-attribute

Invocation name, as the shell would resolve it.

path instance-attribute

Absolute path to the resolved binary, or empty string if missing.

purpose instance-attribute

One-line rationale, rendered in verbose CLI output.

ok property

True when the binary was located on PATH or a standard sbin directory.

check_firewall_binaries()

Probe the host for binaries the shield runtime uses.

Returns a stable-ordered tuple covering nft (ruleset enforcement), dnsmasq (optional local DNS tier), and dig (profile-domain resolution). Callers render the results however they want and decide whether a missing entry should warn, block, or be ignored for their workflow.

Source code in src/terok_shield/prereqs.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
62
def check_firewall_binaries() -> tuple[BinaryCheck, ...]:
    """Probe the host for binaries the shield runtime uses.

    Returns a stable-ordered tuple covering ``nft`` (ruleset
    enforcement), ``dnsmasq`` (optional local DNS tier), and ``dig``
    (profile-domain resolution).  Callers render the results however
    they want and decide whether a missing entry should warn, block,
    or be ignored for their workflow.
    """
    return (
        BinaryCheck("nft", which_sbin_aware("nft"), "nftables ruleset enforcement"),
        BinaryCheck("dnsmasq", which_sbin_aware("dnsmasq"), "local DNS caching resolver"),
        BinaryCheck("dig", shutil.which("dig") or "", "DNS resolution for allowlist domains"),
    )

check_krun_binaries()

Probe the host for binaries the krun runtime path adds.

Separate from check_firewall_binaries because the krun runtime is experimental — callers should gate this probe on whatever flag they use to expose krun (in terok, the top-level experimental: toggle). Reporting ip as missing to an operator who never touches krun would be noise.

Source code in src/terok_shield/prereqs.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
def check_krun_binaries() -> tuple[BinaryCheck, ...]:
    """Probe the host for binaries the krun runtime path adds.

    Separate from [`check_firewall_binaries`][terok_shield.prereqs.check_firewall_binaries]
    because the krun runtime is experimental — callers should gate this
    probe on whatever flag they use to expose krun (in terok, the
    top-level ``experimental:`` toggle).  Reporting ``ip`` as missing
    to an operator who never touches krun would be noise.
    """
    return (
        BinaryCheck(
            "ip",
            which_sbin_aware("ip"),
            "in-netns IP assignment for the krun runtime",
        ),
    )