zscams 2.0.1__py2.py3-none-any.whl

zscams/__main__.py

@@ -0,0 +1,101 @@
+"""
+Main entry point for ZSCAMs Agent
+"""
+
+import os
+import asyncio
+import sys
+import argparse
+from zscams.agent.src.core.api.backend.bootstrap import bootstrap
+from zscams.agent.src.core.api.backend.update_machine_info import update_machine_info
+from zscams.agent.src.support.configuration import get_config, CONFIG_PATH
+from zscams.agent.src.support.logger import get_logger
+from zscams.agent.src.core.tunnel.tls import create_ssl_context
+from zscams.agent.src.core.tunnels import start_all_tunnels
+from zscams.agent.src.core.services import start_all_services
+from zscams.agent.src.core.service_health_check import monitor_services
+from zscams.agent.src.core.api.backend.client import backend_client
+
+logger = get_logger("tls_tunnel_main")
+
+
+def ensure_bootstrapped():
+    """Ensure the agent is bootstrapped with the backend."""
+
+    bootstrapped = backend_client.is_bootstrapped()
+    logger.debug("Agent bootstrapped: %s", bootstrapped)
+    if not bootstrapped:
+        logger.error(
+            "Agent is not bootstrapped. Please run `zscams --bootstrap` to start the bootstrap process.",
+        )
+        sys.exit(1)
+
+
+async def async_main():
+    """Asynchronous main function to start tunnels and services."""
+
+    config = get_config()
+    config_dir = os.path.dirname(CONFIG_PATH)
+    ssl_context = create_ssl_context(config["remote"], config_dir=config_dir)
+    remote_host = config["remote"]["host"]
+    remote_port = config["remote"]["port"]
+
+    # Start tunnels and wait for readiness
+    tunnel_tasks = await start_all_tunnels(
+        config.get("forwards", []), remote_host, remote_port, ssl_context
+    )
+
+    # Start services that depend on tunnels
+    service_tasks = asyncio.create_task(
+        start_all_services(config.get("services", []), config_dir=config_dir)
+    )
+
+    # Start health checks
+    monitor_task = asyncio.create_task(
+        monitor_services(
+            config.get("services", []),
+            config_dir=config_dir,
+            interval=config.get("general", {}).get("health_check_interval", 300),
+        )
+    )
+
+    logger.info("[*] All tunnels and services started. Press Ctrl+C to stop.")
+    await asyncio.gather(*tunnel_tasks, service_tasks, monitor_task)
+
+
+def main():
+    """Main function to run the asynchronous main."""
+    parser = argparse.ArgumentParser(description="ZSCAMs Agent")
+    parser.add_argument(
+        "--bootstrap",
+        action="store_true",
+        help="Run bootstrap process and exit",
+    )
+    parser.add_argument(
+        "--update-machine-info",
+        action="store_true",
+        help="Run bootstrap process and exit",
+    )
+    args = parser.parse_args()
+
+    if args.bootstrap:
+        try:
+            bootstrap()
+            sys.exit(0)
+        except Exception as exception:
+            logger.error(exception)
+            sys.exit(1)
+
+    if args.update_machine_info:
+        update_machine_info()
+        sys.exit(0)
+
+    try:
+        ensure_bootstrapped()
+        asyncio.run(async_main())
+    except KeyboardInterrupt:
+        logger.info("Exiting TLS Tunnel Client")
+
+
+if __name__ == "__main__":
+    main()

zscams/agent/config.yaml

@@ -0,0 +1,121 @@
+---
+logging:
+  level: 10
+
+general:
+  health_check_interval: 30 # seconds between health checks for services
+
+remote:
+  host: 81.255.240.214 # stunnel server IP or hostname
+  port: 443 # Single TLS port on stunnel server
+  verify_cert: false # set false for self-signed certs
+  ca_cert: certificates/ca_chain.pem
+  client_cert: certificates/client.crt
+  client_key: certificates/client.key
+  ca_chain: certificates/ca_chain.pem
+
+forwards:
+  - local_port: 4422
+    sni_hostname: ssh-tunnel
+    description: "Forward to SSH backend"
+  - local_port: 4423
+    sni_hostname: monitor-tunnel
+    description: "Forward to Seculogs"
+
+backend:
+  base_url: "http://22.0.122.40:5000/api"
+  cache_dir: ".cache"
+
+bootstrap_info:
+  csr:
+    country: "FR"
+    state: "Ile-de-France"
+    locality: "Paris"
+    common_name: "zscams-agent.example.com"
+    organization: "zscams-agent.orangecyberdefense.com"
+  cert_issuer: "ZSCAMs"
+  blacklist_ports: []
+
+services:
+  - name: "Reverse SSH"
+    script: "src/services/reverse_ssh.py"
+    # Its just for reference in logs but not used within the service as the
+    # actual port is passed via params (Remote Port). Im setting it to 22 as
+    # its the eventual port that will be connected to
+    port: 22
+    args: []
+    health:
+      host: localhost
+      # port that should be open if service is healthy
+      port: 22
+
+    # -R [remote_listen_address:]remote_listen_port:local_host:local_port
+    params:
+      remote_host: "localhost"
+      # The forwarding port on ZSCAMs server to connect to in order to create
+      # the reverse tunnel, this should match the local_port of one of the
+      # forwards above
+      local_port: 4422
+      server_ssh_user: "ssh_user"
+      # Port on ZSCAMS server to forward to this agent, this port should be
+      # dynamically assigned by the server and passed to the agent via some
+      # secure means
+      reverse_port: 53612
+      # Path to private key for authentication
+      private_key: 'zscams/agent/keys/autoport.key'
+      ssh_options:
+        - "-o LogLevel=error"
+        - "-o UserKnownHostsFile=/dev/null"
+        - "-o StrictHostKeyChecking=no"
+        - "-o ServerAliveInterval=30"
+        - "-o ServerAliveCountMax=2"
+    prerequisites:
+      files:
+        - 'zscams/agent/keys/autoport.key'
+      services: []
+      ports:
+        - 22
+  - name: "Monitor Forwarder"
+    script: "src/services/ssh_forwarder.py"
+    port: 530
+    args: []
+    health:
+      host: localhost
+      # port that should be open if service is healthy
+      port: 44514
+    params:
+      remote_host: "194.51.14.159"
+      remote_port: 530
+      local_port: 4423 #Stunnel port
+      forwarder_port: 44514 #Port the forwarder will listen on and forward to remote host and port
+      server_ssh_user: "ssh_user"
+      private_key: 'zscams/agent/keys/autoport.key'
+      ssh_options:
+        - "-o LogLevel=error"
+        - "-o UserKnownHostsFile=/dev/null"
+        - "-o StrictHostKeyChecking=no"
+        - "-o ServerAliveInterval=30"
+        - "-o ServerAliveCountMax=2"
+    prerequisites:
+      files:
+        - 'zscams/agent/keys/autoport.key'
+      services: []
+      ports: []
+  - name: "Monitor Service"
+    script: "src/services/system_monitor.py"
+    port: 44514
+    args: []
+    health:
+      host: localhost
+      port: 44514
+    params:
+      remote_host: "localhost"
+      remote_port: 44514
+      equipment_name: "zpa-connector"
+      equipment_type: "zpa"
+      service_name: "Zscaler-AppConnector"
+    prerequisites:
+      files: []
+      services: []
+      ports:
+        - 44514

zscams/agent/keys/autoport.key

@@ -0,0 +1,27 @@
+-----BEGIN RSA PRIVATE KEY-----
+MIIEpQIBAAKCAQEA4kpci9i3k9OhuYpC1+0OSQCpXVRThIjtmwl9Nl4oRSsse9zj
+vkzPShMvlZwvEzzZ/Y3hVDHLD5W3hhy63pyi75uxC9RDzb/7ckc1SdunTzj0mtAt
+FhV+cXFZfv79NfaluN/WZwrbpMO+7+uATuEFIGe/t05PgYX9CzhaagCsC355jFHt
+t2z/9Ul40mJkpMZwr+pk6BOSo/DeW7LNikFljqU8BjoZmGuwGuIHzF6ivhDA8hRz
+aKVfw3e+BuxSyOH3xWxzpHSYiZGU5x9hHk8VEbkP7lISxqYdncCw1Is0O6awfXs0
+azx7yzfUumjDdNSmrwpb5/ard30x/aE96upnRwIDAQABAoIBAQC2ghUcMWD2WDTS
+iSGaNzZTSLZQcKefeDRy23didxRxnP2WtLP2EssIymqRdtM859JFPr4igrpsymqn
+Ptq0mo6LQ/3KNZuuAQ4SwD3JYOAS9DPL/OSwMAu4ARyWYZ/lexV0AwxQNSCrRbjk
+lgL5G2FgHm0wsXdMVr2c5Al//yTDauzgOJtQfi/LzuHusnz05iHzEp0ByBfiRL8z
+xKQ9LFW7pIYUsgn4kXry5tQokH6NwDZ7vGPcjAQLD0lLDfAHF9HOiwpkQYXw8q91
+lNvhaFHxa9jyfvuG9e66Q72YCevsCGBEl8Hvmbpz5/9oBZ6Pt82BZKjSouYh7Cya
+a+JVxQcxAoGBAPSKdJdMXH6hCi5DBYhWnGSpDKvRwvxb2PgntCwajkaEZmuITj4y
+dk9IH89ryl0yAmF6q2pKLyWHOir0fVX1HsnC9m2SErhMuSrhSVpcOLiI09wFwcAM
+PRbS/6g1h/Q+MoaVuD0h9ElO8GkONBIBrmiVYqOifotXuPXjMMGT8oNpAoGBAOzk
++OSilwjwtwv/MkLOXqGFymSnG7l5zmt/KGxMCThjxY9b1DzyvXcUvojCRjFl4L0W
+OyDbKRiEJZHSH6jV1gj2N8/53b3C1ziCRvHWvix7MJ7DeDfZLp0QEYZBm6Xm7mG+
+TZ27kya0Hprev/t960UfOpwhb8+MNd1dxdgspC8vAoGBALcGpcrTyWqxZ2hGm252
+vKkOacBzyAePSu448T4NRi17TRjwtPcSV8BxD/X0DEsCcgu5f3CXQ4BIHP4nbWOX
+icqi1EQgD0jHi9OPOJKb8YwURNUpreDqiBJ8LAMexbnFj5Vxm6qNrkPsBD3s9oX/
+oiT+ogwtQ59RMcs/lq9b5yf5AoGAbPmYFXVGDXLOgdJPiLPujFdDl7HX6ybBcmn4
+ank/9JTRGPWhWLhBuDnuvHLCX48CJ3nGkYLAEOsZbU9ACSb1YwIBAsdq3hR3dSNZ
+B39F1KiG4UICV46tBsuRhDVCKLtnBcfJZLoZI0DQo2W84zA1voJzL8eh69QQI1kz
+3hILJTkCgYEAwT+XKnxX8jExNvpe71O2pm3mit6UyOHXB1KyT4Y3UuKjDxwZZ4w1
+vPp6eQ3VcI+4+mpf0qs1cgDz8w35EInt60nKy0+0hwQaM7N0EmsguASHRprESZR9
+dAPDJQ1UJlAMSJxZxFzTvMzDQHY+86GGh5mdoNwJDb0142etE7rSFUI=
+-----END RSA PRIVATE KEY-----

zscams/agent/src/core/__init__.py

@@ -0,0 +1 @@
+running_services = set()

zscams/agent/src/core/api/backend/bootstrap.py

@@ -0,0 +1,21 @@
+from zscams.agent.src.core.api.backend.client import backend_client
+from zscams.agent.src.support.logger import get_logger
+
+logger = get_logger("agent_bootstrap")
+
+
+def bootstrap():
+    """Ensure the agent is bootstrapped with the backend."""
+
+    if backend_client.is_bootstrapped():
+        logger.info("Agent ID %s is already bootstrapped.", backend_client.agent_id)
+        return
+
+    username = input("LDAP Username: ")
+    totp = input("TOTP: ")
+
+    backend_client.login(username, totp)
+
+    equipment_name = input("Equipment Name: ")
+    enforced_id = input("Enforced Agent ID (Optional): ")
+    backend_client.bootstrap(equipment_name, enforced_id or None)

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

@@ -0,0 +1,242 @@
+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
+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)
+
+        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"),
+            csr_info.get("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],
+            "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))
+
+        ca_chain: list[str] = res_json.get("response", {}).get("ca_chain", [])
+        signed_cert: str = res_json.get("response", {}).get("signed_certificate", [])
+        self._write_certificates(ca_chain, signed_cert)
+
+        # To cache the machine info
+        self.get_machine_info(ignore_cache=True)
+
+        return res_json
+
+    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('/')}"
+
+
+backend_client = BackendClient()

zscams/agent/src/core/api/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/api/backend/update_machine_info.py

@@ -0,0 +1,16 @@
+from zscams.agent.src.core.api.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)