nullforge 0.1.0__py3-none-any.whl

nullforge/molds/netsec.py

@@ -0,0 +1,237 @@
+"""Network security and hardening configuration mold."""
+
+from ipaddress import IPv6Network, ip_network
+from typing import Literal
+
+from pydantic import Field, field_validator
+
+from nullforge.models.netsec import SshHostKeyType
+
+from .base_mold import BaseMold
+
+
+SSH_PORT = 22
+"""Default SSH port."""
+
+
+class SshMold(BaseMold):
+    """SSH daemon key material and key-exchange configuration."""
+
+    host_keys: list[SshHostKeyType] | None = Field(
+        default=None,
+        description="Host key types sshd offers, one HostKey directive per entry. "
+        "None keeps distro default set; missing key files are generated.",
+    )
+    pq_kex_priority: bool = Field(
+        default=True,
+        description="Prefer post-quantum hybrid key exchange by prepending PQ algorithms",
+    )
+    strip_weak_algorithms: bool = Field(
+        default=True,
+        description="Remove weak algorithms from the sshd offer and sub-3072-bit DH group-exchange moduli.",
+    )
+
+    @field_validator("host_keys")
+    @classmethod
+    def _validate_host_keys(cls, value: list[SshHostKeyType] | None) -> list[SshHostKeyType] | None:
+        if value is None:
+            return value
+        if not value:
+            raise ValueError("host_keys cannot be empty: sshd needs at least one host key (use None for defaults)")
+        return list(dict.fromkeys(value))
+
+
+class FirewallRule(BaseMold):
+    """A single UFW firewall rule, to ``ufw`` CLI invocation.
+
+    Fields map directly to UFW command:
+      ufw ACTION [DIRECTION] [on IFACE] [proto PROTO]
+          from FROM_IP to TO_IP [port PORT] [comment "COMMENT"]
+    """
+
+    port: int | str | None = Field(
+        default=None,
+        description="Port number (22), range string ('8080:8090'), or None for IP-only rules",
+    )
+    proto: Literal["tcp", "udp", "any"] = Field(
+        default="any",
+        description="Protocol to match; 'any' omits the proto clause entirely",
+    )
+    from_ip: str | None = Field(
+        default=None,
+        description="Source IP address or CIDR (IPv4 or IPv6). None resolves to 'any'",
+    )
+    to_ip: str | None = Field(
+        default=None,
+        description="Destination IP address or CIDR. None resolves to 'any'",
+    )
+    action: Literal["allow", "deny", "reject", "limit"] = Field(
+        default="allow",
+        description="UFW action to apply",
+    )
+    direction: Literal["in", "out"] | None = Field(
+        default=None,
+        description="Traffic direction; None lets UFW apply its default (in)",
+    )
+    interface: str | None = Field(
+        default=None,
+        description="Bind rule to a specific network interface, e.g. 'eth0'",
+    )
+    comment: str | None = Field(
+        default=None,
+        description="Optional label stored in UFW rule metadata",
+    )
+
+    @property
+    def is_ipv6(self) -> bool:
+        """True when this rule references IPv6 address exclusively.
+
+        Rules where from_ip and to_ip are None are considered protocol-agnostic
+        and are not classified as IPv6-only. Mixed rules that reference both IPv4
+        and IPv6 address are also not IPv6-only.
+        """
+
+        candidates = [a for a in (self.from_ip, self.to_ip) if a and a not in ("any", "anywhere")]
+        if not candidates:
+            return False
+        try:
+            networks = [ip_network(addr, strict=False) for addr in candidates]
+        except ValueError:
+            return False
+        return all(isinstance(net, IPv6Network) for net in networks)
+
+
+def _default_firewall_rules() -> list[FirewallRule]:
+    """Default UFW ruleset — allow SSH from anywhere."""
+
+    return [FirewallRule(port=SSH_PORT, comment="SSH")]
+
+
+def _default_system_sysctl() -> dict[str, int]:
+    """Get the default sysctl parameters."""
+
+    sysctl = {
+        # --- SYSTEM RESOURCE LIMITS ---
+        "fs.nr_open": 3000000,
+        "fs.file-max": 2097152,
+        "vm.swappiness": 10,
+    }
+
+    return sysctl
+
+
+def _default_conntrack_sysctl() -> dict[str, int]:
+    """Get the default sysctl parameters for conntrack."""
+
+    return {
+        # --- TCP TIMEOUTS ---
+        "net.netfilter.nf_conntrack_tcp_timeout_established": 3600,  # default 432000
+        "net.netfilter.nf_conntrack_tcp_timeout_time_wait": 30,
+        "net.netfilter.nf_conntrack_tcp_timeout_close_wait": 30,
+        "net.netfilter.nf_conntrack_generic_timeout": 120,
+        # --- UDP TIMEOUTS ---
+        "net.netfilter.nf_conntrack_udp_timeout": 30,
+        "net.netfilter.nf_conntrack_udp_timeout_stream": 120,
+    }
+
+
+def _default_ipv4_sysctl() -> dict[str, str | int]:
+    """Get the default sysctl parameters for IPv4 stack."""
+
+    net_sysctl = {
+        # --- ROUTING & CORE ---
+        "net.ipv4.conf.all.rp_filter": 2,
+        "net.ipv4.conf.default.rp_filter": 2,
+        "net.core.default_qdisc": "fq",
+        "net.ipv4.tcp_congestion_control": "bbr",
+        # --- BACKLOGS ---
+        "net.core.somaxconn": 65535,
+        "net.core.netdev_max_backlog": 65535,
+        "net.ipv4.tcp_max_syn_backlog": 65535,
+        # --- PORT MANAGEMENT ---
+        "net.ipv4.ip_local_port_range": "15000 60999",
+        "net.ipv4.tcp_tw_reuse": 1,
+        "net.ipv4.tcp_fin_timeout": 30,
+        # --- MEMORY BUFFERS ---
+        "net.core.optmem_max": 65536,
+        "net.core.rmem_default": 262144,
+        "net.core.wmem_default": 262144,
+        "net.core.rmem_max": 67108864,
+        "net.core.wmem_max": 67108864,
+        "net.ipv4.tcp_rmem": "4096 87380 67108864",
+        "net.ipv4.tcp_wmem": "4096 65536 67108864",
+        "net.ipv4.udp_rmem_min": 16384,
+        "net.ipv4.udp_wmem_min": 16384,
+        # --- TCP FEATURES ---
+        "net.ipv4.tcp_mtu_probing": 1,
+        "net.ipv4.tcp_slow_start_after_idle": 0,
+        "net.ipv4.tcp_keepalive_time": 600,
+        "net.ipv4.tcp_keepalive_intvl": 30,
+        "net.ipv4.tcp_keepalive_probes": 3,
+        "net.ipv4.tcp_syncookies": 1,
+        "net.ipv4.tcp_fastopen": 3,
+        "net.ipv4.tcp_notsent_lowat": 16384,
+    }
+
+    return net_sysctl
+
+
+def _default_ipv6_sysctl() -> dict[str, int]:
+    """Get the default sysctl parameters for IPv6 stack."""
+
+    net_sysctl = {
+        # --- NEIGHBOR DISCOVERY ---
+        "net.ipv6.neigh.default.gc_thresh1": 128,
+        "net.ipv6.neigh.default.gc_thresh2": 512,
+        "net.ipv6.neigh.default.gc_thresh3": 4096,
+        # --- BINDING ---
+        "net.ipv6.bindv6only": 0,
+    }
+
+    return net_sysctl
+
+
+class NetSecMold(BaseMold):
+    """Full network configuration mold."""
+
+    install: bool = Field(
+        default=True,
+        description="Whether to apply network security and hardening",
+    )
+    firewall: bool = Field(
+        default=True,
+        description="Whether to enable firewall (UFW on Debian/Ubuntu, firewalld on RHEL)",
+    )
+    firewall_rules: list[FirewallRule] = Field(
+        default_factory=_default_firewall_rules,
+        description="Ordered list of firewall rules to apply. Rules with IPv6 addresses "
+        "are automatically skipped on hosts without IPv6 connectivity.",
+    )
+    ssh: SshMold = Field(
+        default_factory=SshMold,
+        description="SSH daemon host key and key-exchange configuration",
+    )
+    system_sysctl: dict[str, int] | None = Field(
+        default_factory=_default_system_sysctl,
+        description="Sysctl parameters to apply",
+    )
+    conntrack_sysctl: dict[str, int] | None = Field(
+        default_factory=_default_conntrack_sysctl,
+        description="Conntrack sysctl parameters to apply",
+    )
+    ipv4_sysctl: dict[str, str | int] | None = Field(
+        default_factory=_default_ipv4_sysctl,
+        description="IPv4 sysctl parameters to apply",
+    )
+    ipv6_sysctl: dict[str, int] | None = Field(
+        default_factory=_default_ipv6_sysctl,
+        description="IPv6 sysctl parameters to apply",
+    )
+    reinstall: bool = Field(
+        default=False,
+        description="Whether to force reconfigure the firewall even if already active",
+    )
+
+    @property
+    def is_active(self) -> bool:
+        return self.install

nullforge/molds/profiles.py

@@ -0,0 +1,30 @@
+"""Profiles configuration mold."""
+
+from pydantic import Field
+
+from nullforge.models.profiles import NerdFont
+
+from .base_mold import BaseMold
+
+
+class ProfilesMold(BaseMold):
+    for_root: bool = Field(
+        default=True,
+        description="Whether to install the profiles for the root user",
+    )
+    for_user: bool = Field(
+        default=False,
+        description="Whether to install the profiles for the user",
+    )
+    reinstall: bool = Field(
+        default=False,
+        description="Whether to reinstall profiles and tools even if already installed",
+    )
+    font: NerdFont | None = Field(
+        default=None,
+        description="Nerd Font family to install on the target; `None` skips font installation",
+    )
+
+    @property
+    def is_active(self) -> bool:
+        return self.for_root or self.for_user

nullforge/molds/system.py

@@ -0,0 +1,140 @@
+"""Base system config: locales, timezone, base packages."""
+
+from pydantic import Field, field_validator
+
+from nullforge.models.system import SwapAlgo, SwapType
+
+from .base_mold import BaseMold
+
+
+def _default_packages_base() -> list[str]:
+    """Get the default base packages to install."""
+
+    return [
+        "acl",
+        "aha",
+        "apt-transport-https",
+        "bat",
+        "bind9-host",
+        "bison",
+        "btop",
+        "build-essential",
+        "dnsutils",
+        "duf",
+        "file",
+        "fontconfig",
+        "g++",
+        "gcc",
+        "git",
+        "gnupg",
+        "ifupdown2",
+        "ipcalc",
+        "iputils-ping",
+        "jq",
+        "libevent-dev",
+        "locales",
+        "mtr-tiny",
+        "ncat",
+        "ncurses-dev",
+        "net-tools",
+        "nmap",
+        "pkg-config",
+        "unzip",
+        "wget",
+        "whois",
+        "xsel",
+        "zsh",
+    ]
+
+
+def _default_locales() -> list[str]:
+    """Get the default locales to generate."""
+
+    return ["en_US.UTF-8 UTF-8"]
+
+
+def _default_timezone() -> str:
+    """Get the default timezone."""
+
+    return "Etc/UTC"
+
+
+class SwapMold(BaseMold):
+    """System swap configuration."""
+
+    enabled: bool = Field(
+        default=False,
+        description="Whether swap should be enabled.",
+    )
+    type: SwapType = Field(
+        default=SwapType.ZRAM,
+        description="Type of swap to use (basic file or zram).",
+    )
+    algo: SwapAlgo = Field(
+        default=SwapAlgo.ZSTD,
+        description="Algorithm of ZRAM compression to use.",
+    )
+    size: str = Field(
+        default="60%",
+        description="Swap size (e.g., '4G', '512M', '50%'). For zram, usually percentage of RAM.",
+    )
+    swappiness: int = Field(
+        default=70,
+        description="Kernel swappiness value (0-100).",
+        ge=0,
+        le=100,
+    )
+
+
+class SystemMold(BaseMold):
+    """Full system configuration mold."""
+
+    packages_base: list[str] = Field(
+        default_factory=_default_packages_base,
+        min_length=1,
+        description="System-wide base packages to install",
+    )
+    locales: list[str] = Field(
+        default_factory=_default_locales,
+        min_length=1,
+        description="Locales to generate",
+    )
+    timezone: str = Field(
+        default_factory=_default_timezone,
+        description="System timezone (e.g. 'UTC' or 'Europe/Amsterdam')",
+    )
+    hostname: str | None = Field(
+        default=None,
+        description="System hostname (FQDN). If None, hostname is not configured.",
+    )
+    swap: SwapMold = Field(
+        default_factory=SwapMold,
+        description="Swap configuration.",
+    )
+    ensure_ipv6: bool = Field(
+        default=True,
+        description="Ensure IPv6 kernel stack.",
+    )
+
+    @field_validator("hostname")
+    @classmethod
+    def _validate_hostname(cls, v: str | None) -> str | None:
+        """Validate hostname format."""
+
+        if v is None:
+            return v
+        if not v or len(v) > 253:
+            raise ValueError("hostname must be between 1 and 253 characters")
+        if "." not in v:
+            raise ValueError("hostname should be a FQDN (contain a dot)")
+        labels = v.split(".")
+        for label in labels:
+            if not label:
+                raise ValueError("hostname contains empty label (consecutive dots or leading/trailing dot)")
+            if len(label) > 63:
+                raise ValueError(f"hostname label '{label}' exceeds 63 characters")
+            if label.startswith("-") or label.endswith("-"):
+                raise ValueError(f"hostname label '{label}' cannot start or end with a hyphen")
+            if not all(c.isalnum() or c == "-" for c in label):
+                raise ValueError(f"hostname label '{label}' contains invalid characters")
+        return v

nullforge/molds/telemt.py

@@ -0,0 +1,140 @@
+"""Telemt (MTProto proxy) configuration mold."""
+
+import re
+from typing import ClassVar, Literal
+
+from pydantic import Field, field_validator, model_validator
+
+from .base_mold import BaseMold
+
+
+TelemtIpPreference = Literal[4, 6]
+"""Address family telemt prefers when both are available (network.prefer)."""
+
+_SECRET_RE = re.compile(r"^[0-9a-f]{32}$")
+"""Telemt user secrets are 16 bytes rendered as 32 lowercase hex characters."""
+
+_USERNAME_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+"""Usernames become TOML keys under [access.users]."""
+
+
+class TelemtMold(BaseMold):
+    """Telemt MTProto proxy for Telegram."""
+
+    _sensitive_fields: ClassVar[tuple[str, ...]] = ("users",)
+
+    install: bool = Field(
+        default=False,
+        description="Whether to install the telemt MTProto proxy",
+    )
+    port: int = Field(
+        default=8443,
+        ge=1,
+        le=65535,
+        description="TCP port telemt listens on",
+    )
+    tls_domain: str = Field(
+        default="",
+        description="Fake-TLS / SNI masking domain used in generated ee-links (censorship.tls_domain)",
+    )
+    users: dict[str, str] = Field(
+        default_factory=dict,
+        description="Access users mapping username -> 32 hex-char secret ([access.users])",
+    )
+    max_connections: int = Field(
+        default=16384,
+        ge=1,
+        le=65535,
+        description="Maximum concurrent client connections (server.max_connections)",
+    )
+    client_handshake: int = Field(
+        default=30,
+        gt=0,
+        le=300,
+        description="Seconds for client to finish handshake (timeouts.client_handshake)",
+    )
+    fast_mode: bool = Field(
+        default=True,
+        description="Enable telemt fast mode (general.fast_mode)",
+    )
+    use_middle_proxy: bool = Field(
+        default=False,
+        description="Route via Telegram middle proxies to enable ad tags (general.use_middle_proxy)",
+    )
+    mode_classic: bool = Field(
+        default=False,
+        description="Enable classic (unobfuscated) MTProto mode (general.modes.classic)",
+    )
+    mode_secure: bool = Field(
+        default=False,
+        description="Enable secure (dd-prefixed) MTProto mode (general.modes.secure)",
+    )
+    mode_tls: bool = Field(
+        default=True,
+        description="Enable Fake-TLS (ee-prefixed) MTProto mode (general.modes.tls)",
+    )
+    ipv6: bool = Field(
+        default=True,
+        description="Allow IPv6 upstream connections (network.ipv6)",
+    )
+    prefer: TelemtIpPreference = Field(
+        default=6,
+        description="Preferred address family when both are available (network.prefer)",
+    )
+    api_enabled: bool = Field(
+        default=False,
+        description="Expose the local management/metrics API (server.api.enabled)",
+    )
+    unknown_sni_action: str | None = Field(
+        default=None,
+        description="How to treat connections with an unexpected SNI (censorship.unknown_sni_action)",
+    )
+    pq_check: bool = Field(
+        default=True,
+        description=(
+            "Probe tls_domain for X25519MLKEM768 (post-quantum) support at deploy time and warn when "
+            "it is missing, since Telegram's iOS client tends to get blocked on such domains"
+        ),
+    )
+    route_via_warp: bool = Field(
+        default=False,
+        description="Route Telegram-bound egress through WARP via per-uid policy routing",
+    )
+    synfix: bool = Field(
+        default=False,
+        description="Apply MEKO SYN rate-limiting fix",
+    )
+
+    @property
+    def is_active(self) -> bool:
+        return self.install
+
+    @field_validator("tls_domain")
+    @classmethod
+    def _strip_domain(cls, v: str) -> str:
+        return v.strip()
+
+    @field_validator("users")
+    @classmethod
+    def _validate_users(cls, v: dict[str, str]) -> dict[str, str]:
+        normalized: dict[str, str] = {}
+        for name, secret in v.items():
+            if not _USERNAME_RE.fullmatch(name):
+                raise ValueError(f"Invalid telemt username {name!r}: use only letters, digits, '-' and '_'")
+            secret = secret.strip().lower()
+            if not _SECRET_RE.match(secret):
+                raise ValueError(f"Invalid telemt secret for {name!r}: expected 32 hexadecimal characters")
+            normalized[name] = secret
+        return normalized
+
+    @model_validator(mode="after")
+    def _validate_enabled(self) -> "TelemtMold":
+        if not self.install:
+            return self
+        if not self.users:
+            raise ValueError("at least one entry in `users` is required when install is True")
+        if self.mode_tls and not self.tls_domain:
+            raise ValueError("`tls_domain` is required when install is True and the Fake-TLS mode is enabled")
+        if not (self.mode_classic or self.mode_secure or self.mode_tls):
+            raise ValueError("at least one of mode_classic/mode_secure/mode_tls must be enabled when install is True")
+        return self

nullforge/molds/tor.py

@@ -0,0 +1,28 @@
+"""Tor proxy configuration mold."""
+
+from pydantic import Field
+
+from .base_mold import BaseMold
+
+
+class TorMold(BaseMold):
+    install: bool = Field(
+        default=False,
+        description="Whether to install Tor proxy",
+    )
+    socks_port: int = Field(
+        default=9050,
+        ge=1,
+        le=65535,
+        description="The port to use for the Tor proxy",
+    )
+    dns_port: int = Field(
+        default=5353,
+        ge=1,
+        le=65535,
+        description="The port to use for the Tor proxy DNS",
+    )
+
+    @property
+    def is_active(self) -> bool:
+        return self.install

nullforge/molds/user.py

@@ -0,0 +1,77 @@
+"""User configuration mold."""
+
+import re
+from typing import ClassVar
+
+from pydantic import Field, field_validator
+
+from nullforge.models.users import Shell
+
+from .base_mold import BaseMold
+
+
+class UserMold(BaseMold):
+    _sensitive_fields: ClassVar[tuple[str, ...]] = ("password",)
+
+    manage: bool = Field(
+        default=True,
+        description="Whether to manage the user",
+    )
+    name: str = Field(
+        default="core",
+        description="The username for the user",
+    )
+    password: str | None = Field(
+        default=None,
+        description="The password for the user",
+    )
+    sudo: bool = Field(
+        default=True,
+        description="Whether to add the user to the sudo group",
+    )
+    shell: Shell = Field(
+        default=Shell.ZSH,
+        description="The shell for the user to use ",
+    )
+    copy_root_keys: bool = Field(
+        default=True,
+        description="Whether to copy the root user's SSH keys to the user",
+    )
+    fetch_key_from_github: str | None = Field(
+        default=None,
+        description="GitHub username whose public SSH keys to import",
+    )
+    set_root_shell_like_user: bool = Field(
+        default=True,
+        description="Whether to set the root user's shell to the user's shell",
+    )
+
+    @property
+    def is_active(self) -> bool:
+        return self.manage
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def _validate_name(cls, value: str) -> str:
+        if not value:
+            raise ValueError("Name cannot be empty")
+
+        if value.startswith("-"):
+            raise ValueError("Name cannot start with a hyphen")
+
+        if not re.match(r"^[A-Za-z0-9._-]+$", value):
+            raise ValueError("Name must only contain characters from the portable filename character set")
+
+        return value
+
+    @field_validator("fetch_key_from_github")
+    @classmethod
+    def _validate_fetch_key_from_github(cls, value: str | None) -> str | None:
+        if value is not None and not re.match(r"^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$", value):
+            raise ValueError(f"Invalid GitHub username: {value!r}")
+
+        return value
+
+    @property
+    def shell_path(self) -> str:
+        return self.shell.value