zscams 2.0.4__py3-none-any.whl

zscams/agent/src/core/backend/client.py

@@ -0,0 +1,281 @@
+import json
+import os
+from pathlib import Path
+import requests
+
+from typing import Optional, cast
+
+from .exceptions import AgentBootstrapError
+
+from zscams.agent.src.support.configuration import (
+    CONFIG_PATH,
+    ROOT_PATH,
+    get_config,
+    override_config,
+)
+from zscams.agent.src.support.yaml import resolve_placeholders, assert_no_placeholders_left
+from zscams.agent.src.support.mac import get_mac_address
+from zscams.agent.src.support.filesystem import resolve_path, ensure_dir, is_file_exists
+from zscams.agent.src.support.network import get_local_hostname, get_local_ip_address
+from zscams.agent.src.support.openssl import (
+    generate_csr_from_private_key,
+    generate_private_key,
+)
+from zscams.agent.src.support.logger import get_logger
+
+
+class BackendClient:
+    """Client to interact with the backend service."""
+
+    MACHINE_INFO_FILE_NAME = "machine_info.json"
+
+    def __init__(self):
+        config = get_config()
+        self.services_config = config.get("services", [])
+        self.backend_config = config.get("backend", {})
+        self.bootstrap_info = config.get("bootstrap_info", {})
+        self.remote_config = config.get("remote", {})
+        self.url = self.backend_config.get("base_url")
+        self.session = requests.session()
+        self.agent_id = get_mac_address()
+        self.logger = get_logger("backend_client")
+
+        self.__machine_cache_path = Path(
+            os.path.join(
+                ROOT_PATH.parent,
+                self.backend_config.get("cache_dir"),
+                self.MACHINE_INFO_FILE_NAME,
+            )
+        )
+
+    def bootstrap(self, equipment_name: str, enforced_id: Optional[str] = None):
+        """Bootstrap the agent with the backend."""
+
+        if not self.is_authenticated():
+            self.logger.error("Couldn't authenticate")
+            raise AgentBootstrapError(
+                "Client is not authenticated to bootstrap. Please login first."
+            )
+
+        self.logger.info("bootstrapping agent ID %s", self.agent_id)
+
+        csr_info = self.bootstrap_info.get("csr", {})
+        remote_configs = get_config().get("remote", {})
+
+        private_key_path = cast(
+            str,
+            resolve_path(
+                remote_configs.get("client_key"), os.path.dirname(CONFIG_PATH)
+            ),
+        )
+
+        self.logger.info("Generating the private key...")
+        private_key_content = generate_private_key(private_key_path)
+
+        self.logger.info("Generated the private key at %s", private_key_path)
+
+        common_name = (
+            f"{equipment_name}.orangecyberdefense.com"
+            if equipment_name
+            else csr_info.get("default_common_name")
+        )
+
+        ip = get_local_ip_address()
+        csr = generate_csr_from_private_key(
+            private_key_content,
+            csr_info.get("country"),
+            csr_info.get("state"),
+            csr_info.get("locality"),
+            csr_info.get("organization"),
+            common_name,
+        )
+
+        payload = {
+            "private_ip": ip,
+            "lan_ip": ip,
+            "hostname": get_local_hostname(),
+            "equipment_name": equipment_name,
+            "csr": csr,
+            "enforced_id": enforced_id,
+            "services": [service.get("name") for service in self.services_config if service.get("custom_port_name", None)],
+            "blacklist_ports": self.bootstrap_info.get("blacklist_ports", []),
+            "cert_issuer": self.bootstrap_info.get("cert_issuer", None),
+        }
+
+        self.logger.debug(
+            "bootstrapping the agent with payload %s", json.dumps(payload, indent=2)
+        )
+
+        res = self._post(f"agent-bootstrap/{self.agent_id}", payload)
+        res_json = res.json()
+
+        if not res.ok or res_json.get("success") is False:
+            message = (
+                res_json.get("message", None)
+                or res_json.get("error", None)
+                or res_json.get("errors", None)
+                or "Unknown error"
+            )
+            raise AgentBootstrapError(
+                f"Bootstrapping failed on backend request: {message}"
+            )
+
+        self.logger.info("Signed the cert")
+        self.logger.debug("Signed cert response: %s", json.dumps(res_json, indent=2))
+
+        customer_machine = res_json.get("response", {})
+        ca_chain: list[str] = customer_machine.get("ca_chain", [])
+        signed_cert: str = customer_machine.get("signed_certificate", [])
+        self._write_certificates(ca_chain, signed_cert)
+
+        # To cache the machine info
+        self.get_machine_info(ignore_cache=True)
+
+        self.__override_config_services_ports(customer_machine.get("services", []))
+
+        return customer_machine
+
+    def get_machine_info(self, ignore_cache: bool = False):
+        """Get machine information from the backend."""
+
+        if not ignore_cache and is_file_exists(self.__machine_cache_path, self.logger):
+            return self.__load_machine_info_from_cache()
+
+        res = self._get(f"customers-machines/machine-id/{self.agent_id}")
+        res.raise_for_status()
+
+        machine_info = res.json().get("response", {})
+        self.logger.debug(
+            "Fetched machine info: %s", json.dumps(machine_info, indent=2)
+        )
+        self.__cache_machine_info(machine_info)
+        return machine_info
+
+    def __load_machine_info_from_cache(self):
+        """Cache machine information to a local file."""
+
+        self.logger.info(
+            "Loading machine info from cache at %s", self.__machine_cache_path
+        )
+        with open(self.__machine_cache_path, "r", encoding="utf-8") as cache_file:
+            return json.load(cache_file)
+
+    def __cache_machine_info(self, machine_info: dict):
+        """Cache machine information to a local file."""
+
+        ensure_dir(str(self.__machine_cache_path.parent.absolute()))
+        self.logger.info("Caching machine info to %s", self.__machine_cache_path)
+        with open(self.__machine_cache_path, "w", encoding="utf-8") as cache_file:
+            json.dump(machine_info, cache_file, indent=2)
+
+    def _write_certificates(self, ca_chain: list[str], cert: str):
+        if cert:
+            cert_path = os.path.join(ROOT_PATH, self.remote_config.get("client_cert"))
+
+            self.logger.info("Writing signed certificate to %s", cert_path)
+            with open(cert_path, "w", encoding="utf-8") as cert_file:
+                cert_file.write(cert)
+
+        if ca_chain:
+            ca_chain_path = os.path.join(ROOT_PATH, self.remote_config.get("ca_chain"))
+
+            self.logger.info("Writing CA chain to %s", ca_chain_path)
+            with open(ca_chain_path, "w", encoding="utf-8") as ca_chain_file:
+                ca_chain_file.write("\n\n".join(ca_chain))
+
+    def is_bootstrapped(self) -> bool:
+        """Check if the agent is bootstrapped."""
+
+        is_bootstrapped_res = self._get(
+            f"agent-bootstrap/{self.agent_id}/is-bootstrapped"
+        )
+        is_bootstrapped_res.raise_for_status()
+
+        return (
+            is_bootstrapped_res.json().get("response", {}).get("is-bootstrapped", False)
+        )
+
+    def _get(self, path: str):
+        """Perform a GET request to the backend."""
+
+        return self.session.get(self.__prepare_path(path))
+
+    def _post(self, path: str, body: dict):
+        """Perform a POST request to the backend."""
+
+        return self.session.post(self.__prepare_path(path), json=body)
+
+    def _put(self, path: str, body: dict):
+        """Perform a PUT request to the backend."""
+
+        return self.session.put(self.__prepare_path(path), json=body)
+
+    def _delete(self, path: str):
+        """Perform a DELETE request to the backend."""
+
+        return self.session.delete(self.__prepare_path(path))
+
+    def login(self, username: str, totp: str):
+        """Perform login to the backend using username and TOTP."""
+
+        payload = {
+            "username": username,
+            "totp": totp,
+            "client_id": "orchestrator-client",
+            "grant_type": "password",
+        }
+
+        self.logger.info("Logging in to backend as %s", username)
+
+        response = self.session.post(
+            self.__prepare_path("authentication/temp/login"), json=payload
+        )
+        if not response.ok:
+            self.logger.error(
+                "Login failed with status code %d: %s",
+                response.status_code,
+                response.text,
+            )
+            response.raise_for_status()
+
+        token = response.json().get("access_token")
+        if token:
+            self.session.headers.update({"Authorization": f"Bearer {token}"})
+
+        self.logger.info("Login successful")
+
+        return response.json()
+
+    def is_authenticated(self) -> bool:
+        """Check if the client is authenticated."""
+        return self.session.headers.get("Authorization") is not None
+
+    def __prepare_path(self, path):
+        return f"{self.url}/{path.lstrip('/')}"
+            
+    def __override_config_services_ports(self, cm_services: list[dict]):
+        self.logger.debug("Overriding configuration services ports...")
+
+        config = get_config()
+        custom_ports = {}
+        for cm_service in cm_services:
+            for cfg_service_idx, cfg_service in enumerate(config.get("services", [])):
+                if cm_service.get("name") == cfg_service.get("name"):
+
+                    if not config["services"][cfg_service_idx]["params"]:
+                        config["services"][cfg_service_idx]["params"] = {}
+
+                    port_field_name = cfg_service.get("custom_port_name", None)
+                    if port_field_name:
+                        custom_ports[port_field_name] = cm_service.get("port")
+                        config["services"][cfg_service_idx]["params"][port_field_name] = (
+                            cm_service.get("port")
+                        )
+        resolve_placeholders(config, custom_ports)
+        assert_no_placeholders_left(config)
+        self.logger.debug("Done overriding the configurations")
+
+        return override_config(config)
+
+
+backend_client = BackendClient()

zscams/agent/src/core/backend/exceptions.py

@@ -0,0 +1,10 @@
+class AgentBootstrapError(Exception):
+    """Base exception for agent bootstrap-related errors."""
+
+
+class AgentNotBootstrapped(AgentBootstrapError):
+    """Raised when an operation requires a bootstrapped agent, but the agent is not bootstrapped."""
+
+
+class AgentAlreadyBootstrapped(AgentBootstrapError):
+    """Raised when attempting to bootstrap an already bootstrapped agent."""

zscams/agent/src/core/backend/update_machine_info.py

@@ -0,0 +1,16 @@
+from zscams.agent.src.core.backend.client import backend_client
+from zscams.agent.src.support.logger import get_logger
+
+logger = get_logger("agent_machine_info")
+
+
+def update_machine_info():
+    """Ensure the agent is bootstrapped with the backend."""
+
+    username = input("LDAP Username: ")
+    totp = input("TOTP: ")
+
+    backend_client.login(username, totp)
+
+    logger.info("Getting machine info from backend...")
+    backend_client.get_machine_info(ignore_cache=True)

zscams/agent/src/core/prerequisites.py

@@ -0,0 +1,36 @@
+from zscams.agent.src.support.logger import get_logger
+from zscams.agent.src.support.filesystem import is_file_exists
+from zscams.agent.src.core import running_services
+from zscams.agent.src.support.network import is_port_open, is_service_running
+
+logger = get_logger("service_prerequisites")
+
+
+def check_prerequisites(prereqs: dict) -> bool:
+    """
+    Perform a one-shot prerequisites check (no waiting or retry).
+    Returns True only if all listed conditions are satisfied.
+    """
+    if not prereqs:
+        return True
+
+    results = []
+
+    # Check file prerequisites
+    for path in prereqs.get("files", []):
+        results.append(is_file_exists(path, logger))
+
+    # Check port prerequisites
+    for port in prereqs.get("ports", []):
+        results.append(is_port_open("localhost", port, logger))
+
+    # Check service prerequisites
+    for svc in prereqs.get("services", []):
+        results.append(is_service_running(svc, running_services, logger))
+
+    all_ok = all(results)
+    if not all_ok:
+        logger.warning("Some prerequisites failed for this service.")
+    else:
+        logger.info("All prerequisites satisfied.")
+    return all_ok

zscams/agent/src/core/service_health_check.py

@@ -0,0 +1,49 @@
+"""
+Health monitor for agent services.
+
+This module periodically checks the defined health ports of all services.
+If a service is not responding on its port, it will be restarted.
+"""
+
+import asyncio
+from zscams.agent.src.support.logger import get_logger
+from zscams.agent.src.core.services import start_service
+from zscams.agent.src.core import running_services
+from zscams.agent.src.support.network import is_port_open
+
+logger = get_logger("health_monitor")
+
+
+async def monitor_services(services: list, config_dir: str, interval: int = 60):
+    """
+    Periodically check service health by port.
+
+    If a service's health port is closed, attempt to restart it.
+    """
+    logger.info(f"Health monitor started (interval={interval}s)")
+    await asyncio.sleep(30)  # Initial delay to allow services to start
+    while True:
+        for svc in services:
+            name = svc["name"]
+            health = svc.get("health", {})
+
+            host = health.get("host", "localhost")
+            port = health.get("port")
+            if not port:
+                logger.debug(f"Skipping {name}: no health port defined.")
+                continue
+
+            if name in running_services and is_port_open(host, port, logger):
+                logger.debug(f"{name} is healthy on {host}:{port}")
+                continue
+
+            logger.warning(f"{name} not healthy, restarting...")
+            if name in running_services:
+                running_services.remove(name)
+            try:
+                await start_service(svc, config_dir)
+                logger.info(f"Restarted service: {name}")
+            except Exception as e:
+                logger.error(f"Failed to restart {name}: {e}")
+
+        await asyncio.sleep(interval)

zscams/agent/src/core/services.py

@@ -0,0 +1,86 @@
+"""
+Service launcher utilities for TLS Tunnel Client
+
+- Generic solution: any service can receive parameters via `SERVICE_PARAMS` env variable
+- Starts services asynchronously using asyncio
+- Supports both Python scripts and executables
+"""
+
+import asyncio
+import json
+import os
+from zscams.agent.src.support.logger import get_logger
+from zscams.agent.src.core.prerequisites import check_prerequisites
+from zscams.agent.src.core import running_services
+
+logger = get_logger("service_launcher")
+
+
+async def start_service(service_cfg, config_dir=None):
+    """
+    Launch an external script/service asynchronously.
+
+    Args:
+        service_cfg (dict): Service configuration from config.yaml
+            - name: service name
+            - script: path to script/executable
+            - port: associated port (optional)
+            - args: list of extra arguments
+            - params: dict of arbitrary parameters (SERVICE_PARAMS)
+        config_dir (str, optional): Base directory to resolve relative script paths
+
+    Returns:
+        asyncio.subprocess.Process or None
+    """
+    base_dir = config_dir or os.getcwd()
+    script_path = os.path.join(base_dir, service_cfg["script"])
+    prereqs = service_cfg.get("prerequisites")
+    name = service_cfg["name"]
+    # Wait for prerequisites before starting
+    logger.info("Checking prerequisites for %s...", name)
+    ok = check_prerequisites(prereqs)
+    if not ok:
+        logger.error("Prerequisites not met for %s. Skipping start.", name)
+        return
+
+    if not os.path.exists(script_path):
+        logger.error("Service script not found: %s", script_path)
+        return None
+
+    env = os.environ.copy()
+    params = service_cfg.get("params")
+    if params:
+        # Pass generic parameters to the service via JSON environment variable
+        env["SERVICE_PARAMS"] = json.dumps(params)
+
+    cmd = ["python", script_path] + service_cfg.get("args", [])
+    logger.info(
+        "Starting service %s on port %d: %s",
+        service_cfg.get("name"),
+        service_cfg.get("port", 0),
+        cmd,
+    )
+
+    try:
+        process = await asyncio.create_subprocess_exec(*cmd, env=env)
+        running_services.add(name)
+        return process
+    except Exception as e:
+        logger.error("Failed to start service %s: %s", service_cfg.get("name"), e)
+        return None
+
+
+async def start_all_services(services_cfg_list, config_dir=None):
+    """
+    Start all services defined in the configuration concurrently.
+
+    Args:
+        services_cfg_list (list): List of service configuration dictionaries
+        config_dir (str, optional): Base directory to resolve relative script paths
+    """
+    tasks = []
+    for svc in services_cfg_list:
+        tasks.append(start_service(svc, config_dir=config_dir))
+
+    # Wait for all services to start
+    await asyncio.gather(*tasks)

zscams/agent/src/core/tunnel/__init__.py

@@ -0,0 +1,144 @@
+"""
+Forwarding utilities for TLS Tunnel Client with:
+- Auto-reconnect with exponential backoff
+- Health checks
+"""
+
+import asyncio
+from zscams.agent.src.support.logger import get_logger
+
+READ_BUFFER_SIZE = 4096
+
+logger = get_logger("tls_forward")
+
+
+async def forward(reader: asyncio.StreamReader, writer: asyncio.StreamWriter):
+    """
+    Forward data from reader to writer until connection closes.
+    Handles Windows-specific connection resets gracefully.
+    """
+    try:
+        while True:
+            data = await reader.read(READ_BUFFER_SIZE)
+            if not data:
+                break
+            writer.write(data)
+            await writer.drain()
+    except (ConnectionResetError, OSError) as err:
+        # Handle Windows WinError 64 and other disconnects gracefully
+        logger.debug("Connection closed by peer (expected): %s", err)
+    except Exception as err:
+        logger.error("Unexpected forwarding error: %s", err)
+    finally:
+        try:
+            writer.close()
+            await writer.wait_closed()
+        except Exception:
+            pass  # ignore errors on close
+
+
+async def handle_client(
+    local_reader, local_writer, remote_host, remote_port, sni_hostname, ssl_context
+):  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    """
+    Forward a single local connection to the remote TLS server with SNI.
+    Handles abrupt disconnects gracefully.
+    """
+    try:
+        remote_reader, remote_writer = await asyncio.open_connection(
+            host=remote_host,
+            port=remote_port,
+            ssl=ssl_context,
+            server_hostname=sni_hostname,
+        )
+        logger.debug(
+            "New connection: local -> %s:%s (SNI=%s)",
+            remote_host,
+            remote_port,
+            sni_hostname,
+        )
+
+        await asyncio.gather(
+            forward(local_reader, remote_writer), forward(remote_reader, local_writer)
+        )
+
+    except (ConnectionResetError, OSError) as e:
+        logger.debug("Connection closed unexpectedly: %s", e)
+    except Exception as e:
+        logger.error("Unexpected client handling error: %s", e)
+    finally:
+        try:
+            local_writer.close()
+            await local_writer.wait_closed()
+            logger.debug(
+                f"Connection closed: local -> {remote_host}:{remote_port} (SNI={sni_hostname})"
+            )
+        except Exception as e:
+            logger.error("Unexpected client handling error: %s", e)
+
+
+async def start_tunnel(
+    local_port,
+    remote_host,
+    remote_port,
+    sni_hostname,
+    ssl_context,
+    reconnect_max_delay=60,
+    ready_event=None,
+):  # pylint: disable=too-many-arguments,too-many-positional-arguments
+    """
+    Start a TCP listener on local_port and forward connections to the remote TLS server.
+    Automatically reconnects on failure with exponential backoff and performs periodic health checks.
+
+    Args:
+        local_port (int)
+        remote_host (str)
+        remote_port (int)
+        sni_hostname (str)
+        ssl_context (ssl.SSLContext)
+        reconnect_max_delay (int): Maximum delay between reconnect attempts
+    """
+    backoff = 1  # initial delay in seconds
+
+    while True:
+        try:
+            server = await asyncio.start_server(
+                lambda r, w: handle_client(
+                    r, w, remote_host, remote_port, sni_hostname, ssl_context
+                ),
+                "127.0.0.1",
+                local_port,
+            )
+            addr = server.sockets[0].getsockname()
+            logger.info(
+                "Listening on :%s -> %s:%s (SNI=%s)",
+                addr[1],
+                remote_host,
+                remote_port,
+                sni_hostname,
+            )
+
+            # Health check task: logs tunnel is alive every 30 seconds
+            async def health_check():
+                while True:
+                    await asyncio.sleep(600)
+                    logger.info(
+                        "Tunnel on local port %s is healthy and running", local_port
+                    )
+
+            asyncio.create_task(health_check())
+
+            # Signal ready if event is provided
+            if ready_event:
+                ready_event.set()
+
+            async with server:
+                await server.serve_forever()
+
+        except Exception as e:
+            logger.error("Tunnel error on local port %s: %s", local_port, e)
+            logger.info("Reconnecting in %s seconds...", backoff)
+            await asyncio.sleep(backoff)
+            backoff = min(backoff * 2, reconnect_max_delay)  # exponential backoff
+        else:
+            backoff = 1  # reset backoff if successful

zscams/agent/src/core/tunnel/tls.py

@@ -0,0 +1,56 @@
+import ssl
+import os
+from typing import Optional
+from zscams.agent.src.support.configuration import RemoteConfig
+from zscams.agent.src.support.filesystem import resolve_path
+from zscams.agent.src.support.logger import get_logger
+
+logger = get_logger("tls_utils")
+
+
+def create_ssl_context(
+    remote_cfg: RemoteConfig, config_dir: Optional[str] = None
+) -> ssl.SSLContext:
+    """
+    Create an SSL context for TLS connections based on configuration.
+
+    Args:
+        remote_cfg (dict): Remote server configuration including:
+            - verify_cert (bool)
+            - ca_cert (str)
+            - client_cert (str)
+            - client_key (str)
+        config_dir (str, optional): Directory to resolve relative paths from.
+
+    Returns:
+        ssl.SSLContext: Configured SSL context
+    """
+    context = ssl.create_default_context()
+
+    ca_cert = resolve_path(remote_cfg.get("ca_cert"), config_dir)
+    client_cert = resolve_path(remote_cfg.get("client_cert"), config_dir)
+    client_key = resolve_path(remote_cfg.get("client_key"), config_dir)
+
+    if not remote_cfg.get("verify_cert", True):
+        context.check_hostname = False
+        context.verify_mode = ssl.CERT_NONE
+        logger.warning("Certificate verification is disabled!")
+    else:
+        if ca_cert and os.path.exists(ca_cert):
+            context.load_verify_locations(cafile=ca_cert)
+            logger.info("Loaded CA certificate from %s", ca_cert)
+        else:
+            logger.warning("CA certificate not found or not provided: %s", ca_cert)
+
+    if client_cert and client_key:
+        if os.path.exists(client_cert) and os.path.exists(client_key):
+            context.load_cert_chain(certfile=client_cert, keyfile=client_key)
+            logger.info(
+                "Loaded client certificate/key: %s / %s", client_cert, client_key
+            )
+        else:
+            raise FileNotFoundError(
+                f"Client certificate or key not found: {client_cert}, {client_key}"
+            )
+
+    return context