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 uses the shared host PATH resolver. 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 the current host PATH.

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 a lookup tool — dig or drill (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 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
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 a lookup
    tool — ``dig`` or ``drill`` (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", find_host_tool("nft") or "", "nftables ruleset enforcement"),
        BinaryCheck("dnsmasq", find_host_tool("dnsmasq") or "", "local DNS caching resolver"),
        BinaryCheck(
            "dig/drill",
            find_host_tool("dig") or find_host_tool("drill") 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 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
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",
            find_host_tool("ip") or "",
            "in-netns IP assignment for the krun runtime",
        ),
    )