nftgen 1.0.0__py3-none-any.whl

nftgen/__init__.py

@@ -0,0 +1,13 @@
+"""nftgen — a small, nftables-only firewall-as-code generator.
+
+YAML definitions + host policies -> a native nftables ruleset. See DESIGN.md.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Single source of truth is pyproject.toml; read it from installed metadata
+    # so __version__ can never drift from the packaged version.
+    __version__ = version("nftgen")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0+source"

nftgen/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from nftgen.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

nftgen/cli.py

@@ -0,0 +1,209 @@
+"""Command-line entry point for nftgen."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import functools
+import os
+import pathlib
+import sys
+
+import yaml
+
+from nftgen import __version__, validate
+from nftgen.definitions import DefinitionError
+from nftgen.generate import build, generate
+from nftgen.ir import BuildError
+
+
+def _clean_errors(fn):
+    """Authoring mistakes get a one-line `nftgen: error:` instead of a traceback.
+    Anything else is a bug in nftgen: one line saying so, the traceback only
+    with NFTGEN_DEBUG=1."""
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except (BuildError, DefinitionError, FileNotFoundError, yaml.YAMLError) as e:
+            print(f"nftgen: error: {e}", file=sys.stderr)
+            return 1
+        except BrokenPipeError:
+            # the reader went away (`… --stdout | head`): stop quietly, and
+            # point stdout at /dev/null so the exit flush doesn't fail again
+            with contextlib.suppress(OSError, ValueError):  # not a real file
+                os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+            return 141  # 128 + SIGPIPE, the shell convention
+        except OSError as e:
+            # permission denied, a directory where a file goes, a full disk:
+            # the environment, not a bug in nftgen
+            print(f"nftgen: error: {e}", file=sys.stderr)
+            return 1
+        except Exception as e:
+            if os.environ.get("NFTGEN_DEBUG"):
+                raise
+            print(
+                f"nftgen: internal error: {type(e).__name__}: {e} — this is a bug "
+                f"in nftgen, please report it (NFTGEN_DEBUG=1 shows the traceback)",
+                file=sys.stderr,
+            )
+            return 70  # EX_SOFTWARE
+
+    return wrapper
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nftgen",
+        description="nftables-only firewall generator (YAML -> .nft)",
+    )
+    parser.add_argument("--version", action="version", version=f"nftgen {__version__}")
+    parser.add_argument("policy", nargs="?", help="host policy YAML file")
+    parser.add_argument("--defs", help="definitions dir (default: <root>/definitions)")
+    parser.add_argument("--base", help="include base dir (default: the policies dir)")
+    parser.add_argument("--sites", help="sites dir (default: <root>/sites)")
+    parser.add_argument("--out", help="output .nft file (default: stdout)")
+    parser.add_argument(
+        "--check", action="store_true", help="validate the output with `nft -c -f`"
+    )
+    return parser
+
+
+def _defaults(policy: pathlib.Path):
+    """For a <root>/policies/hosts/<host>.yaml layout, infer defs/base/sites."""
+    include_base = policy.parent.parent  # .../policies
+    root = policy.parents[2] if len(policy.parents) >= 3 else policy.parent
+    return root / "definitions", include_base, root / "sites"
+
+
+@_clean_errors
+def _build_cmd(argv: list[str]) -> int:
+    """`nftgen build <root>` — regenerate generated/<host>.nft for every host."""
+    parser = argparse.ArgumentParser(
+        prog="nftgen build",
+        description="generate generated/<host>.nft for every host under <root>",
+    )
+    parser.add_argument("root", help="project root (definitions/, sites/, policies/)")
+    parser.add_argument("--host", help="build only this host (default: all)")
+    parser.add_argument("--out-dir", help="output dir (default: <root>/generated)")
+    parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="print the ruleset to stdout, write nothing (requires --host)",
+    )
+    parser.add_argument(
+        "--check", action="store_true", help="validate each output with `nft -c -f`"
+    )
+    args = parser.parse_args(argv)
+
+    # stdout is a single stream, so it maps to exactly one host.
+    if args.stdout and not args.host:
+        print(
+            "nftgen: error: --stdout requires --host (stdout is a single stream "
+            "— one host)",
+            file=sys.stderr,
+        )
+        return 2
+
+    # Probe before generating: a --check that can't run must fail loudly, not
+    # silently skip validation the caller (CI, the Ansible play) asked for.
+    if args.check and not validate.can_check():
+        print(
+            "nftgen: error: --check requested but `nft -c` is not usable here "
+            "(nft missing, or no netlink and no unshare fallback)",
+            file=sys.stderr,
+        )
+        return 2
+
+    results = build(args.root, host=args.host)
+
+    # --stdout: emit the one host's ruleset and write nothing (previews, pipes,
+    # a deployer rendering on the fly without touching the committed tree).
+    if args.stdout:
+        text = next(iter(results.values()))
+        rc = 0
+        if args.check:
+            result = validate.check(text)
+            if not result.ok:
+                print(
+                    f"nftgen: {args.host}: nft -c FAILED:\n{result.stderr}",
+                    file=sys.stderr,
+                )
+                rc = 1
+        sys.stdout.write(text)
+        sys.stdout.flush()  # a closed pipe fails here, inside the guard
+        return rc
+
+    out_dir = (
+        pathlib.Path(args.out_dir)
+        if args.out_dir
+        else pathlib.Path(args.root) / "generated"
+    )
+    out_dir.mkdir(parents=True, exist_ok=True)
+    rc = 0
+    for name, text in sorted(results.items()):
+        path = out_dir / f"{name}.nft"
+        path.write_text(text)
+        print(f"wrote {path}", file=sys.stderr)
+        if args.check:
+            result = validate.check(text)
+            if not result.ok:
+                print(
+                    f"nftgen: {name}: nft -c FAILED:\n{result.stderr}", file=sys.stderr
+                )
+                rc = 1
+    return rc
+
+
+@_clean_errors
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "build":
+        return _build_cmd(argv[1:])
+
+    args = build_parser().parse_args(argv)
+    if not args.policy:
+        build_parser().print_help()
+        return 0
+
+    # Same probe as `build --check`, before rendering: a check that can't run
+    # must fail loudly, not after output was already written.
+    if args.check and not validate.can_check():
+        print(
+            "nftgen: error: --check requested but `nft -c` is not usable here "
+            "(nft missing, or no netlink and no unshare fallback)",
+            file=sys.stderr,
+        )
+        return 2
+
+    policy = pathlib.Path(args.policy)
+    def_default, base_default, sites_default = _defaults(policy)
+    text = generate(
+        policy,
+        defs_dir=args.defs or def_default,
+        include_base=args.base or base_default,
+        sites_dir=args.sites or sites_default,
+    )
+
+    if args.out:
+        out = pathlib.Path(args.out)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(text)
+        print(f"wrote {out}", file=sys.stderr)
+    else:
+        sys.stdout.write(text)
+        sys.stdout.flush()
+
+    if args.check:
+        result = validate.check(text)
+        if result.ok:
+            print("nftgen: nft -c passed", file=sys.stderr)
+        else:
+            print(f"nftgen: nft -c FAILED:\n{result.stderr}", file=sys.stderr)
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nftgen/definitions.py

@@ -0,0 +1,180 @@
+"""Definitions: networks / services / interfaces, with composition.
+
+A definition value is a list whose items are either a literal (an IP/CIDR, a
+``port/proto``, or an interface device name) or the name of another group in the
+same category (composition, resolved recursively). Groups merge across files;
+a host may overlay one or more per-site definition files. Names are unique
+within a category — a duplicate (including a site overlay redefining a common
+name) is an error.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import pathlib
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+import yaml
+
+from nftgen.protocols import PORT_PROTOS, proto_name
+
+CATEGORIES = ("networks", "services", "interfaces")
+
+
+class DefinitionError(Exception):
+    """A definition is malformed, duplicated, or references something undefined."""
+
+
+class Definitions:
+    def __init__(self) -> None:
+        self.networks: dict[str, list] = {}
+        self.services: dict[str, list] = {}
+        self.interfaces: dict[str, list] = {}
+        # (category, name) -> the source that first defined it, for dual-origin
+        # provenance in duplicate errors.
+        self._origin: dict[tuple[str, str], str] = {}
+
+    # -- construction -------------------------------------------------------- #
+    @classmethod
+    def load(
+        cls, def_dir: str | pathlib.Path, site_files: Iterable[str | pathlib.Path] = ()
+    ) -> Definitions:
+        """Merge every ``*.yaml`` under ``def_dir`` recursively (common), then site overlays."""
+        def_dir = pathlib.Path(def_dir)
+        if not def_dir.is_dir():
+            # A missing dir would silently yield empty definitions, degrading
+            # every group reference downstream — fail here instead.
+            raise DefinitionError(f"definitions directory not found: {def_dir}")
+        defs = cls()
+        for path in sorted(def_dir.rglob("*.y*ml")):
+            defs._merge(yaml.safe_load(path.read_text()) or {}, str(path))
+        for sf in map(pathlib.Path, site_files):
+            if not sf.is_file():
+                raise DefinitionError(f"site definitions file not found: {sf}")
+            defs._merge(yaml.safe_load(sf.read_text()) or {}, str(sf))
+        return defs
+
+    @classmethod
+    def from_mappings(cls, *mappings: Mapping[str, Any]) -> Definitions:
+        """Build directly from in-memory mappings (tests / programmatic use)."""
+        defs = cls()
+        for i, mapping in enumerate(mappings):
+            defs._merge(mapping or {}, f"<mapping {i}>")
+        return defs
+
+    @classmethod
+    def from_named_mappings(
+        cls, mappings: Mapping[str, Mapping[str, Any]]
+    ) -> Definitions:
+        """Build from named layers ``{layer_name: mapping}``.
+
+        The layer name is the provenance reported in duplicate errors (both the
+        first-seen and the duplicating layer). Layers merge in sorted-name order
+        — determinism, not precedence: names are unique, so order never changes
+        the result, only which duplicate is reported first. This is the surface
+        the Ansible vars front-end feeds (layer name == the chunk var name).
+        """
+        defs = cls()
+        for name in sorted(mappings):
+            defs._merge(mappings[name] or {}, name)
+        return defs
+
+    def _merge(self, data: Mapping[str, Any], source: str) -> None:
+        if not isinstance(data, Mapping):
+            # A malformed layer (e.g. a list where a mapping was expected) would
+            # otherwise blow up with an opaque AttributeError deep in the loop.
+            raise DefinitionError(
+                f"definition layer {source!r} must be a mapping of "
+                f"category -> {{name: list}}, got {type(data).__name__}"
+            )
+        for category in CATEGORIES:
+            cat_data = data.get(category) or {}
+            if not isinstance(cat_data, Mapping):
+                raise DefinitionError(
+                    f"{category} in {source} must be a mapping of name -> list, "
+                    f"got {type(cat_data).__name__}"
+                )
+            target = getattr(self, category)
+            for name, value in cat_data.items():
+                if name in target:
+                    first = self._origin.get((category, name), "?")
+                    raise DefinitionError(
+                        f"duplicate {category} definition {name!r} ({first}, {source})"
+                    )
+                if not isinstance(value, list):
+                    raise DefinitionError(
+                        f"{category} {name!r} must be a list (in {source})"
+                    )
+                target[name] = value
+                self._origin[(category, name)] = source
+
+    # -- resolution ---------------------------------------------------------- #
+    def network(self, name: str) -> list[str]:
+        """Resolve a network group to an ordered, deduped list of IP/CIDR strings."""
+        return self._expand("networks", self.networks, name, _net_leaf, ())
+
+    def service(self, name: str) -> list[tuple[str, str]]:
+        """Resolve a service group to ordered, deduped (proto, port) pairs."""
+        return self._expand("services", self.services, name, _svc_leaf, ())
+
+    def interface(self, name: str) -> list[str]:
+        """Resolve an interface group to an ordered, deduped list of device names."""
+        return self._expand("interfaces", self.interfaces, name, _iface_leaf, ())
+
+    def service_ports(self, name: str, proto: str) -> list[str]:
+        """Just the ports of a service for one protocol (e.g. tcp)."""
+        return [port for p, port in self.service(name) if p == proto]
+
+    def _expand(self, category, table, name, leaf, stack: tuple) -> list:
+        if name not in table:
+            raise DefinitionError(f"undefined {category[:-1]}: {name!r}")
+        if name in stack:
+            raise DefinitionError(
+                f"{category} definition cycle: {' -> '.join((*stack, name))}"
+            )
+        stack = (*stack, name)
+        out: list = []
+        for item in table[name]:
+            key = str(item)
+            # A group referencing itself is meaningless as composition; read it
+            # as a literal so `eth0: [eth0]` names a one-device group.
+            if key in table and key != name:
+                out.extend(self._expand(category, table, key, leaf, stack))
+            else:
+                out.extend(leaf(key, name))
+        return list(dict.fromkeys(out))  # dedupe, preserve order
+
+
+# -- leaf parsers ------------------------------------------------------------ #
+def _net_leaf(item: str, group: str) -> list[str]:
+    try:
+        ipaddress.ip_network(item, strict=False)
+    except ValueError as e:
+        raise DefinitionError(
+            f"network {group!r}: {item!r} is not a known group or an IP/CIDR ({e})"
+        ) from e
+    return [item]  # preserve the author's form
+
+
+def _svc_leaf(item: str, group: str) -> list[tuple[str, str]]:
+    if "/" not in item:
+        raise DefinitionError(
+            f"service {group!r}: {item!r} must be 'port/proto' or a known service"
+        )
+    port, written = item.rsplit("/", 1)
+    if not port or not written:
+        raise DefinitionError(f"service {group!r}: malformed entry {item!r}")
+    # one spelling everywhere: `53/17` is stored as udp
+    proto = proto_name(written)
+    if proto not in PORT_PROTOS:
+        raise DefinitionError(
+            f"service {group!r}: {item!r} — {written} has no ports; services are "
+            f"port/protocol pairs ({', '.join(PORT_PROTOS)}). Match {written} "
+            f"with `proto: {written}` in a rule instead"
+        )
+    return [(proto, port)]
+
+
+def _iface_leaf(item: str, group: str) -> list[str]:
+    return [item]  # any non-group string is a literal device name