toolgovern-cli 0.1.1__py3-none-any.whl

toolgovern/classifier/information_flow.py

@@ -0,0 +1,154 @@
+"""TG08 -- Information-Flow Control (confidentiality-label propagation).
+
+Ported from ``packages/toolgovern/src/classifier/information-flow.ts``.
+
+A categorically different question from TG01-TG05: those all ask "should this call happen" (is
+this argument dangerous, is this path/host/credential in scope). This asks "can this *data* flow
+here" -- does a call read from a source the caller has labeled confidential-or-higher, and
+write/send that data to a destination whose declared trust tier is lower (or not declared at
+all)? That is the same governance question Microsoft Agent Framework's FIDES answers with a full
+confidentiality-label lattice tracked across an MCP gateway boundary -- this module is
+deliberately NOT that. It is the smallest real primitive that lets a genuine label-propagation
+check exist at all: one flat, closed label order (``ConfidentialityLabel`` in ``../types.py``), a
+caller-declared source/sink labeling (``IfcPolicy``), and a single per-call rule.
+
+What this explicitly does NOT do, disclosed rather than hidden:
+
+- No automatic label inference. toolgovern cannot know that ``args["table"] == "customers.ssn"``
+  is confidential, or that ``args["webhook"]`` points at an untrusted third party -- those are
+  business facts only the integrator has. ``IfcPolicy.sources`` / ``IfcPolicy.sink_trust`` are a
+  real, if minimal, labeling API the caller must declare; this rule only evaluates what was
+  declared.
+- No cross-call / session-level taint tracking. Each call is evaluated in isolation, exactly like
+  every other TG0x rule -- if confidential data is read in one call and only handed to an
+  untrusted sink two calls later, this rule does not see that.
+- No reader/principal-scoped lattice. ``ConfidentialityLabel`` is one flat total order, not a set
+  of readers or a join/meet lattice over multiple simultaneous principals.
+- No result-value inspection. This evaluates the call's declared source/sink arguments, not the
+  actual data a tool call returns.
+
+Fail-closed posture (the one property this module does commit to): a call whose source is
+labeled confidential-or-higher and whose destination's trust tier is NOT declared in
+``IfcPolicy.sink_trust`` never silently allows -- it requires human approval. Only a destination
+explicitly declared trustworthy enough (rank >= the source's label) is allowed through
+unchallenged; a destination explicitly declared LOWER-trust is denied outright.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, List, Mapping, Optional, Sequence
+
+from ..types import ConfidentialityLabel, RuleContext, RuleMatch
+
+_CATEGORY = "TG08"
+
+# Total order for ConfidentialityLabel, least to most sensitive.
+_LABEL_ORDER: Sequence[str] = ("public", "internal", "confidential", "restricted")
+
+# Argument key names a caller may use to name the source/sink of a labeled data flow.
+# Deliberately separate, explicit key sets from TG02/TG04's path/credential-style keys and TG03's
+# host/url-style keys -- reusing those would mean silently *inferring* that any path/host/
+# credential argument is "the source" or "the sink" of a two-sided flow, which is exactly the
+# automatic inference this module disclaims. A caller opts into TG08 by naming the source and
+# sink explicitly under one of these keys.
+_SOURCE_KEYS = ["source", "sourceId", "from", "readFrom"]
+_SINK_KEYS = ["sink", "sinkId", "to", "destination", "sendTo", "forwardTo"]
+
+
+@dataclass
+class _Rule:
+    id: str
+    category: str
+    description: str
+    _evaluate: Callable[[RuleContext], Optional[RuleMatch]]
+
+    def evaluate(self, ctx: RuleContext) -> Optional[RuleMatch]:
+        return self._evaluate(ctx)
+
+
+def _label_rank(label: str) -> int:
+    return _LABEL_ORDER.index(label)
+
+
+def _first_string(args: Mapping[str, Any], keys: Sequence[str]) -> Optional[str]:
+    for key in keys:
+        value = args.get(key)
+        if isinstance(value, str) and len(value) > 0:
+            return value
+    return None
+
+
+def _lookup_label(identifier: str, labels: Mapping[str, str]) -> Optional[str]:
+    """Whether ``identifier`` matches an entry in a declared IfcPolicy label map -- exact match,
+    a trailing path-segment match, or a substring match. Mirrors ``is_credential_granted()``'s
+    matching style in ``util.py``. Exact match is checked across the whole map first so a
+    longer, more specific declared key is never shadowed by an unrelated shorter key that
+    merely happens to be a substring of it."""
+    lower = identifier.lower()
+    for key, label in labels.items():
+        if key.lower() == lower:
+            return label
+    for key, label in labels.items():
+        k = key.lower()
+        if k and (lower.endswith(f"/{k}") or k in lower):
+            return label
+    return None
+
+
+def _match(rule_id: str, decision: str, reason: str, matched_argument: str) -> RuleMatch:
+    return RuleMatch(
+        rule_id=rule_id,
+        category=_CATEGORY,  # type: ignore[arg-type]
+        decision=decision,  # type: ignore[arg-type]
+        reason=reason,
+        matched_argument=matched_argument,
+    )
+
+
+def _confidential_source_to_untrusted_sink_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    ifc = ctx.scope.ifc
+    if ifc is None:
+        return None
+
+    source = _first_string(ctx.args, _SOURCE_KEYS)
+    if not source:
+        return None
+    source_label = _lookup_label(source, ifc.sources)
+    if not source_label or source_label == "public":
+        return None
+
+    sink = _first_string(ctx.args, _SINK_KEYS)
+    if not sink:
+        return None
+
+    sink_trust = _lookup_label(sink, ifc.sink_trust)
+    if sink_trust is None:
+        return _match(
+            "TG08-confidential-source-to-untrusted-sink",
+            "require-approval",
+            f'Call reads from "{source}" labeled "{source_label}" and sends to "{sink}", whose '
+            "trust tier is not declared in the IFC policy. Failing closed pending human review.",
+            sink,
+        )
+    if _label_rank(sink_trust) < _label_rank(source_label):
+        return _match(
+            "TG08-confidential-source-to-untrusted-sink",
+            "deny",
+            f'Call reads from "{source}" labeled "{source_label}" but destination "{sink}" is '
+            f'only trusted for "{sink_trust}" data.',
+            sink,
+        )
+    return None
+
+
+information_flow_rules: List[_Rule] = [
+    _Rule(
+        "TG08-confidential-source-to-untrusted-sink",
+        _CATEGORY,
+        "A call reads from a source labeled confidential-or-higher and writes/sends to a "
+        "destination whose declared trust tier is lower than the source's label, or whose "
+        "trust tier was never declared at all (fails closed to require-approval, not allow).",
+        _confidential_source_to_untrusted_sink_evaluate,
+    ),
+]

toolgovern/classifier/network_egress.py

@@ -0,0 +1,289 @@
+"""TG03 -- Undeclared Network Egress.
+
+Ported from ``packages/toolgovern/src/classifier/network-egress.ts``.
+
+Fires when a call reaches a host not present in the caller's declared network scope
+(``scope.network``: ``False`` for no access, ``True`` for unrestricted, or an explicit host
+allowlist).
+"""
+
+from __future__ import annotations
+
+import re
+import socket
+import threading
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional
+
+from ..shared.paths import host_matches_allowed, is_ip_literal, is_private_or_metadata_target
+from ..types import RuleContext, RuleMatch
+from .util import extract_candidate_host, extract_command, extract_host
+
+_CATEGORY = "TG03"
+
+_KNOWN_RELAY_DOMAINS = [
+    "pastebin.com",
+    "pastebin-mirror.io",
+    "transfer.sh",
+    "ngrok.io",
+    "ngrok-free.app",
+    "requestbin.com",
+    "webhook.site",
+    "file.io",
+]
+
+
+@dataclass
+class _Rule:
+    id: str
+    category: str
+    description: str
+    _evaluate: Callable[[RuleContext], Optional[RuleMatch]]
+
+    def evaluate(self, ctx: RuleContext) -> Optional[RuleMatch]:
+        return self._evaluate(ctx)
+
+
+def _match(rule_id: str, decision: str, reason: str, matched_argument: str) -> RuleMatch:
+    return RuleMatch(
+        rule_id=rule_id,
+        category=_CATEGORY,  # type: ignore[arg-type]
+        decision=decision,  # type: ignore[arg-type]
+        reason=reason,
+        matched_argument=matched_argument,
+    )
+
+
+def _is_host_in_scope(host: str, network) -> bool:
+    if network is True:
+        return True
+    if network is False:
+        return False
+    return any(host_matches_allowed(host, allowed) for allowed in network)
+
+
+def _network_disabled_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    if ctx.scope.network is not False:
+        return None
+    host = extract_candidate_host(ctx.args)
+    if not host:
+        return None
+    return _match(
+        "TG03-network-disabled",
+        "deny",
+        f'Network call to "{host}" attempted with network scope disabled.',
+        host,
+    )
+
+
+def _host_not_in_scope_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    if ctx.scope.network is False or ctx.scope.network is True:
+        return None
+    host = extract_candidate_host(ctx.args)
+    if not host:
+        return None
+    if _is_host_in_scope(host, ctx.scope.network):
+        return None
+    return _match(
+        "TG03-host-not-in-scope", "deny", f'Host "{host}" is not in the declared network allowlist.', host
+    )
+
+
+def _raw_ip_literal_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    host = extract_candidate_host(ctx.args)
+    if not host or not is_ip_literal(host):
+        return None
+    # An explicit, exact allowlist entry for this host is honored even if it is private/
+    # metadata -- that's a deliberate, specific operator decision (they named this exact
+    # address), unlike the blanket scope.network is True grant checked below, which
+    # incidentally covers everything including metadata endpoints without the operator ever
+    # having considered this specific address.
+    if isinstance(ctx.scope.network, (list, tuple)) and host in ctx.scope.network:
+        return None
+    if is_private_or_metadata_target(host):
+        # Loopback, RFC1918/unique-local, link-local, and cloud-metadata targets are denied
+        # outright for any scope that did not explicitly name this exact host above -- this
+        # check must run before the scope.network is True early-return below, not after it:
+        # an agent with unrestricted (but not host-specific) network access must still never
+        # be able to reach an internal network or cloud-metadata endpoint via this rule.
+        # That's the entire point of "never approvable" -- it cannot be conditional on a
+        # blanket network=True grant.
+        return _match(
+            "TG03-raw-ip-literal",
+            "deny",
+            f'Connection to loopback/private/cloud-metadata IP literal "{host}" is never approvable.',
+            host,
+        )
+    if ctx.scope.network is True:
+        return None
+    return _match("TG03-raw-ip-literal", "require-approval", f'Connection to raw IP literal "{host}".', host)
+
+
+_PORT_PATTERN = re.compile(r":(\d{2,5})\b")
+
+
+def _non_standard_port_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    raw = extract_host(ctx.args) or extract_command(ctx.args) or ""
+    port_match = _PORT_PATTERN.search(raw)
+    if not port_match:
+        return None
+    port = int(port_match.group(1))
+    if port in (80, 443):
+        return None
+    host = extract_candidate_host(ctx.args)
+    if not host:
+        return None
+    if ctx.scope.network is True:
+        return None
+    if isinstance(ctx.scope.network, (list, tuple)) and host in ctx.scope.network:
+        return None
+    return _match(
+        "TG03-non-standard-port",
+        "require-approval",
+        f'Connection to "{host}" on non-standard port {port}.',
+        f"{host}:{port}",
+    )
+
+
+def _dns_exfil_pattern_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    host = extract_candidate_host(ctx.args)
+    if not host:
+        return None
+    first_label = host.split(".")[0] if host else ""
+    if len(first_label) < 40:
+        return None
+    return _match(
+        "TG03-dns-exfil-pattern", "require-approval", f'Unusually long subdomain label on "{host}".', host
+    )
+
+
+def _known_paste_relay_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    host = extract_candidate_host(ctx.args)
+    if not host:
+        return None
+    hit = next(
+        (domain for domain in _KNOWN_RELAY_DOMAINS if host == domain or host.endswith(f".{domain}")),
+        None,
+    )
+    if not hit:
+        return None
+    if isinstance(ctx.scope.network, (list, tuple)) and hit in ctx.scope.network:
+        return None
+    return _match(
+        "TG03-known-paste-relay", "deny", f'Host "{host}" matches known paste/relay service "{hit}".', host
+    )
+
+
+_DNS_LOOKUP_TIMEOUT_SECONDS = 3.0
+
+
+def _resolve_host_addresses(host: str) -> List[str]:
+    """Resolves every address a hostname maps to via the OS resolver (``socket.getaddrinfo``,
+    which also honors ``/etc/hosts`` -- so an operator-added ``127.0.0.1  internal-alias`` entry
+    is caught exactly like a real DNS A/AAAA record would be), racing it against a hard timeout
+    in a worker thread so a hung/unresponsive resolver cannot stall the call indefinitely.
+
+    ``socket.getaddrinfo()`` has no built-in timeout of its own and cannot be cancelled once
+    started, so this uses the same thread + ``join(timeout)`` idiom
+    ``middleware/on_tool_call.py``'s ``_resolve_approval`` already uses for approval timeouts,
+    rather than inventing a second timeout mechanism.
+
+    Raises on failure or timeout -- never returns a value implying "safe, nothing found" for
+    those cases. Callers must treat an exception as "unknown, fail closed."
+    """
+    result_box: Dict[str, Any] = {}
+
+    def _run() -> None:
+        try:
+            result_box["infos"] = socket.getaddrinfo(host, None)
+        except Exception as error:  # noqa: BLE001 -- re-raised on the calling thread below
+            result_box["error"] = error
+
+    thread = threading.Thread(target=_run, daemon=True)
+    thread.start()
+    thread.join(_DNS_LOOKUP_TIMEOUT_SECONDS)
+    if thread.is_alive():
+        raise TimeoutError(
+            f'DNS lookup for "{host}" timed out after {_DNS_LOOKUP_TIMEOUT_SECONDS}s'
+        )
+    if "error" in result_box:
+        raise result_box["error"]  # type: ignore[misc]
+    infos = result_box.get("infos", [])
+    return [info[4][0] for info in infos]
+
+
+def _dns_resolves_private_evaluate(ctx: RuleContext) -> Optional[RuleMatch]:
+    host = extract_candidate_host(ctx.args)
+    # A raw IP literal is already fully handled by TG03-raw-ip-literal; resolving it would be a
+    # no-op (or, for a bare decimal-encoded literal, actively wrong) -- this rule only concerns
+    # itself with actual hostnames.
+    if not host or is_ip_literal(host):
+        return None
+    # Mirrors TG03-raw-ip-literal's own carve-out: an explicit, exact allowlist entry for this
+    # hostname is a deliberate, specific operator decision, honored even if it turns out to
+    # resolve to a private address.
+    if isinstance(ctx.scope.network, (list, tuple)) and host in ctx.scope.network:
+        return None
+
+    try:
+        addresses = _resolve_host_addresses(host)
+    except Exception as error:
+        # Fail CLOSED on a DNS-resolution failure (NXDOMAIN, timeout, resolver error, whatever the
+        # cause) -- an unresolvable host is never treated as "safe to allow." require-approval
+        # (not an automatic allow) matches TG03-raw-ip-literal's own use of require-approval for
+        # anything not affirmatively known to be safe.
+        return _match(
+            "TG03-dns-resolves-private",
+            "require-approval",
+            f'DNS resolution for host "{host}" failed ({error}); failing closed rather than '
+            "assuming an unresolvable host is safe to reach.",
+            host,
+        )
+
+    if not addresses:
+        # Some resolvers return an empty record set rather than raising for an unknown name --
+        # treated identically to a resolution failure above, for the same fail-closed reason.
+        return _match(
+            "TG03-dns-resolves-private",
+            "require-approval",
+            f'DNS resolution for host "{host}" returned no addresses; failing closed rather than '
+            "assuming an unresolvable host is safe to reach.",
+            host,
+        )
+
+    private_address = next((a for a in addresses if is_private_or_metadata_target(a)), None)
+    if not private_address:
+        return None
+
+    return _match(
+        "TG03-dns-resolves-private",
+        "deny",
+        f'Host "{host}" resolves via DNS to loopback/private/cloud-metadata address '
+        f'"{private_address}" -- denied even though the call argument is a hostname, not a raw '
+        "IP literal. Residual limitation, disclosed rather than hidden: this is a "
+        "resolve-then-check at classification time, not a connection-time guarantee -- it "
+        "narrows but does not eliminate DNS-rebinding TOCTOU, since an attacker who controls "
+        "this name's DNS answer can still swap it to a private/internal address after this "
+        "check runs and before the tool's own HTTP client actually connects. True TOCTOU-proof "
+        "protection would require the tool's own HTTP client to connect to this exact "
+        "resolved+validated address (DNS pinning), which a pre-execution argument gate like "
+        "govern_tool() cannot enforce -- see docs/security-model.md.",
+        host,
+    )
+
+
+network_egress_rules: List[_Rule] = [
+    _Rule("TG03-network-disabled", _CATEGORY, "Any network egress attempted while the agent has no network scope at all.", _network_disabled_evaluate),
+    _Rule("TG03-host-not-in-scope", _CATEGORY, "The target host is not present in the declared network allowlist.", _host_not_in_scope_evaluate),
+    _Rule("TG03-raw-ip-literal", _CATEGORY, "Connection to a raw IP literal, bypassing a domain-based allowlist.", _raw_ip_literal_evaluate),
+    _Rule("TG03-non-standard-port", _CATEGORY, "Connection to a non-standard port on a host outside the allowlist.", _non_standard_port_evaluate),
+    _Rule("TG03-dns-exfil-pattern", _CATEGORY, "Suspiciously long, high-entropy subdomain label -- a common DNS-exfil shape.", _dns_exfil_pattern_evaluate),
+    _Rule("TG03-known-paste-relay", _CATEGORY, "Target host matches a known paste/relay/tunnel service commonly used for exfil.", _known_paste_relay_evaluate),
+    _Rule(
+        "TG03-dns-resolves-private",
+        _CATEGORY,
+        "A hostname argument that resolves via DNS to a loopback/RFC1918/link-local/cloud-metadata "
+        "address, even though the argument itself is a domain name, not a raw IP literal.",
+        _dns_resolves_private_evaluate,
+    ),
+]