cowrie 2.7.0__py3-none-any.whl

backend_pool/README.md

@@ -0,0 +1,43 @@
+QEMU/libvirt Python examples to handle a guest
+
+# Developer Guide
+We'll start by looking at the classes that compose the Backend Pool, from "outermost" to the inner, specific classes.
+
+## pool_server.py
+The main interface of the backend pool is exposed as a TCP server in _pool\_server.py_. The protocol is a very simple
+wire protocol, always composed of an op-code, a status code (for responses), and any needed data thereafter.
+
+## pool_service.py
+The server interfaces exposes a producer-consumer infinite loop that runs on _pool\_service.py_.
+
+The **producer** is an infinite loop started by the server, and runs every 5 seconds. It creates VMs up to the
+configured limit, checks which VMs become available (by testing if they accept SSH and/or Telnet connections), and
+destroys VMs that are no longer needed.
+
+**Consumer** methods are called by server request, and basically involve requesting and freeing VMs. All operations on
+shared data in the producer-consumer are guarded by a lock, since there may be concurrent requests. The lock protects
+the _guests_ list, which contains references for each VM backend (in our case libvirt/QEMU instances).
+
+Since we won't be dealing with a very large number of VMs (never more than 100, we find that a single simple lock is
+enough.
+
+The Pool Service expects to find a "backend service" with a given interface:
+* A method to initialise the backend interface and environment (start_backend), stop it and destroy the current
+environment (stop_backend), and shutdown it permanently for the current execution (shutdown_backend).
+* A method to create a new guest (create_guest)
+* A method to destroy a guest (destroy_guest)
+
+Currently the service supports a libvirt/QEMU backend. However, by splitting the logic from generic guest handling /
+interaction with main Cowrie, from the logic to create guests in a low-level perspective, we hope to ease development
+of different kinds of backends in the future.
+
+## libvirt classes
+The main class for libvirt is _backend\_service.py_, and implements the interface discussed above. Guest, network and
+snapshot handlers deal with those specific components of libvirt's handling.
+
+Initialising libvirt involves connecting to the running system daemon, creating a network filter to restrict guest's
+Internet access, and creating a "cowrie" network in libvirt.
+
+Guest creation is started by creating a snapshot from the base qcow2 image defined in the configs, and instantiating
+a guest from the XML provided. The Guest Handler replaces templates ("{guest_name}") with user configs for the wanted
+guest. If the XML provided does not contain templates, then no replacement takes place, naturally.

backend_pool/libvirt/backend_service.py

@@ -0,0 +1,216 @@
+"""
+backend service
+"""
+
+# Copyright (c) 2019 Guilherme Borges <guilhermerosasborges@gmail.com>
+# See the COPYRIGHT file for more information
+
+from __future__ import annotations
+
+import os
+import random
+import sys
+import uuid
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+from twisted.python import log
+
+from cowrie.core.config import CowrieConfig
+
+import backend_pool.libvirt.guest_handler
+import backend_pool.libvirt.network_handler
+import backend_pool.util
+
+
+class LibvirtError(Exception):
+    pass
+
+
+class LibvirtBackendService:
+    def __init__(self) -> None:
+        # lazy import to avoid exception if not using the backend_pool
+        # and libvirt not installed (#1185)
+        import libvirt
+
+        libvirt_uri: str = CowrieConfig.get(
+            "backend_pool", "libvirt_uri", fallback="qemu:///system"
+        )
+
+        # open connection to libvirt
+        self.conn = libvirt.open(libvirt_uri)
+        if self.conn is None:
+            log.msg(
+                eventid="cowrie.backend_pool.libvirtd",
+                format="Failed to open connection to libvirtd at %(uri)s",
+                uri=libvirt_uri,
+            )
+            raise LibvirtError()
+
+        self.filter = None
+        self.network = None
+
+        # signals backend is ready to be operated
+        self.ready: bool = False
+
+        # table to associate IPs and MACs
+        seed: int = random.randint(0, sys.maxsize)
+        self.network_table = backend_pool.util.generate_network_table(seed)
+
+        log.msg(
+            eventid="cowrie.backend_pool.libvirtd",
+            format="Connection to libvirtd established at %(uri)s",
+            uri=libvirt_uri,
+        )
+
+    def start_backend(self) -> None:
+        """
+        Initialises QEMU/libvirt environment needed to run guests.
+        Namely starts networks and network filters.
+        """
+        # create a network filter
+        self.filter = backend_pool.libvirt.network_handler.create_filter(self.conn)
+
+        # create a network for the guests (as a NAT)
+        self.network = backend_pool.libvirt.network_handler.create_network(
+            self.conn, self.network_table
+        )
+
+        # service is ready to be used (create guests and use them)
+        self.ready = True
+
+    def stop_backend(self) -> None:
+        log.msg(
+            eventid="cowrie.backend_pool.libvirtd",
+            format="Doing libvirtd clean shutdown...",
+        )
+
+        self.ready = False
+
+        self.destroy_all_cowrie()
+
+    def shutdown_backend(self) -> None:
+        self.conn.close()  # close libvirt connection
+
+        log.msg(
+            eventid="cowrie.backend_pool.libvirtd",
+            format="Connection to libvirtd closed successfully",
+        )
+
+    def get_mac_ip(self, ip_tester: Callable[[str], bool]) -> tuple[str, str]:
+        """
+        Get a MAC and IP that are not being used by any guest.
+        """
+        # Try to find a free pair 500 times.
+        retries = 0
+        while retries < 500:
+            mac = random.choice(list(self.network_table.keys()))
+            ip = self.network_table[mac]
+            if ip_tester(ip):
+                return mac, ip
+
+            retries += 1
+
+        raise LibvirtError()
+
+    def create_guest(self, ip_tester):
+        """
+        Returns an unready domain and its snapshot information.
+
+        Guarantee that the IP is free with the ip_tester function.
+        """
+        if not self.ready:
+            return
+
+        # create a single guest
+        guest_unique_id = uuid.uuid4().hex
+        guest_mac, guest_ip = self.get_mac_ip(ip_tester)
+        dom, snapshot = backend_pool.libvirt.guest_handler.create_guest(
+            self.conn, guest_mac, guest_unique_id
+        )
+        if dom is None:
+            log.msg(
+                eventid="cowrie.backend_pool.libvirtd", format="Failed to create guest"
+            )
+            return None
+
+        return dom, snapshot, guest_ip
+
+    def destroy_guest(self, domain, snapshot):
+        if not self.ready:
+            return
+
+        try:
+            # destroy the domain in QEMU
+            domain.destroy()
+
+            # we want to remove the snapshot if either:
+            #   - explicitely set save_snapshots to False
+            #   - no snapshot dir was defined (using cowrie's root dir) - should not happen but prevent it
+            if (
+                (
+                    not CowrieConfig.getboolean(
+                        "backend_pool", "save_snapshots", fallback=True
+                    )
+                    or CowrieConfig.get("backend_pool", "snapshot_path", fallback=None)
+                    is None
+                )
+                and os.path.exists(snapshot)
+                and os.path.isfile(snapshot)
+            ):
+                os.remove(snapshot)  # destroy its disk snapshot
+        except Exception as error:
+            log.err(
+                eventid="cowrie.backend_pool.libvirtd",
+                format="Error destroying guest: %(error)s",
+                error=error,
+            )
+
+    def __destroy_all_guests(self) -> None:
+        domains = self.conn.listDomainsID()
+        # if not domains:
+        #     log.msg(
+        #         eventid="cowrie.backend_pool.libvirtd",
+        #         format="Could not get domain list",
+        #     )
+
+        for domain_id in domains:
+            d = self.conn.lookupByID(domain_id)
+            if d.name().startswith("cowrie"):
+                try:
+                    d.destroy()
+                except KeyboardInterrupt:
+                    pass
+
+    def __destroy_all_networks(self) -> None:
+        networks = self.conn.listNetworks()
+        # if not networks:
+        #     log.msg(
+        #         eventid="cowrie.backend_pool.libvirtd",
+        #         format="Could not get network list",
+        #     )
+
+        for network in networks:
+            if network.startswith("cowrie"):
+                n = self.conn.networkLookupByName(network)
+                n.destroy()
+
+    def __destroy_all_network_filters(self) -> None:
+        network_filters = self.conn.listNWFilters()
+        # if not network_filters:
+        #     log.msg(
+        #         eventid="cowrie.backend_pool.libvirtd",
+        #         format="Could not get network filters list",
+        #     )
+
+        for nw_filter in network_filters:
+            if nw_filter.startswith("cowrie"):
+                n = self.conn.nwfilterLookupByName(nw_filter)
+                n.undefine()
+
+    def destroy_all_cowrie(self) -> None:
+        self.__destroy_all_guests()
+        self.__destroy_all_networks()
+        self.__destroy_all_network_filters()

backend_pool/libvirt/guest_handler.py

@@ -0,0 +1,112 @@
+# Copyright (c) 2019 Guilherme Borges <guilhermerosasborges@gmail.com>
+# See the COPYRIGHT file for more information
+from __future__ import annotations
+import os
+import sys
+from configparser import NoOptionError
+
+from twisted.python import log
+
+from cowrie.core.config import CowrieConfig
+
+import backend_pool.libvirt.snapshot_handler
+import backend_pool.util
+
+
+class QemuGuestError(Exception):
+    pass
+
+
+def create_guest(connection, mac_address, guest_unique_id):
+    # lazy import to avoid exception if not using the backend_pool and libvirt not installed (#1185)
+    import libvirt
+
+    # get guest configurations
+    configuration_file: str = os.path.join(
+        CowrieConfig.get(
+            "backend_pool", "config_files_path", fallback="src/cowrie/data/pool_configs"
+        ),
+        CowrieConfig.get("backend_pool", "guest_config", fallback="default_guest.xml"),
+    )
+
+    version_tag: str = CowrieConfig.get("backend_pool", "guest_tag", fallback="guest")
+    base_image: str = CowrieConfig.get("backend_pool", "guest_image_path")
+    hypervisor: str = CowrieConfig.get(
+        "backend_pool", "guest_hypervisor", fallback="qemu"
+    )
+    memory: int = CowrieConfig.getint("backend_pool", "guest_memory", fallback=128)
+    qemu_machine: str = CowrieConfig.get(
+        "backend_pool", "guest_qemu_machine", fallback="pc-q35-3.1"
+    )
+
+    # check if base image exists
+    if not os.path.isfile(base_image):
+        log.msg(
+            eventid="cowrie.backend_pool.guest_handler",
+            format="Base image provided was not found: %(base_image)s",
+            base_image=base_image,
+        )
+        os._exit(1)
+
+    # only in some cases, like wrt
+    kernel_image: str = CowrieConfig.get(
+        "backend_pool", "guest_kernel_image", fallback=""
+    )
+
+    # get a directory to save snapshots, even if temporary
+    try:
+        # guest configuration, to be read by qemu, needs an absolute path
+        snapshot_path: str = backend_pool.util.to_absolute_path(
+            CowrieConfig.get("backend_pool", "snapshot_path")
+        )
+    except NoOptionError:
+        snapshot_path = os.getcwd()
+
+    # create a disk snapshot to be used by the guest
+    disk_img: str = os.path.join(
+        snapshot_path, f"snapshot-{version_tag}-{guest_unique_id}.qcow2"
+    )
+
+    if not backend_pool.libvirt.snapshot_handler.create_disk_snapshot(
+        base_image, disk_img
+    ):
+        log.msg(
+            eventid="cowrie.backend_pool.guest_handler",
+            format="There was a problem creating the disk snapshot.",
+        )
+        raise QemuGuestError()
+
+    guest_xml = backend_pool.util.read_file(configuration_file)
+    guest_config = guest_xml.format(
+        guest_name="cowrie-" + version_tag + "_" + guest_unique_id,
+        disk_image=disk_img,
+        base_image=base_image,
+        kernel_image=kernel_image,
+        hypervisor=hypervisor,
+        memory=memory,
+        qemu_machine=qemu_machine,
+        mac_address=mac_address,
+        network_name="cowrie",
+    )
+
+    try:
+        dom = connection.createXML(guest_config, 0)
+        if dom is None:
+            log.err(
+                eventid="cowrie.backend_pool.guest_handler",
+                format="Failed to create a domain from an XML definition.",
+            )
+            sys.exit(1)
+    except libvirt.libvirtError as e:
+        log.err(
+            eventid="cowrie.backend_pool.guest_handler",
+            format="Error booting guest: %(error)s",
+            error=e,
+        )
+        raise
+    log.msg(
+        eventid="cowrie.backend_pool.guest_handler",
+        format="Guest %(name)s has booted",
+        name=dom.name(),
+    )
+    return dom, disk_img

backend_pool/libvirt/network_handler.py

@@ -0,0 +1,100 @@
+# Copyright (c) 2019 Guilherme Borges <guilhermerosasborges@gmail.com>
+# See the COPYRIGHT file for more information
+from __future__ import annotations
+import os
+import sys
+
+from twisted.python import log
+
+from cowrie.core.config import CowrieConfig
+
+import backend_pool.util
+
+
+def create_filter(connection):
+    # lazy import to avoid exception if not using the backend_pool and libvirt not installed (#1185)
+    import libvirt
+
+    filter_file: str = os.path.join(
+        CowrieConfig.get(
+            "backend_pool", "config_files_path", fallback="src/cowrie/data/pool_configs"
+        ),
+        CowrieConfig.get(
+            "backend_pool", "nw_filter_config", fallback="default_filter.xml"
+        ),
+    )
+
+    filter_xml = backend_pool.util.read_file(filter_file)
+
+    try:
+        return connection.nwfilterDefineXML(filter_xml)
+    except libvirt.libvirtError as e:
+        log.err(
+            eventid="cowrie.backend_pool.network_handler",
+            format="Filter already exists: %(error)s",
+            error=e,
+        )
+        return connection.nwfilterLookupByName("cowrie-default-filter")
+
+
+def create_network(connection, network_table):
+    # lazy import to avoid exception if not using the backend_pool and libvirt not installed (#1185)
+    import libvirt
+
+    # TODO support more interfaces and therefore more IP space to allow > 253 guests
+    network_file: str = os.path.join(
+        CowrieConfig.get(
+            "backend_pool", "config_files_path", fallback="src/cowrie/data/pool_configs"
+        ),
+        CowrieConfig.get(
+            "backend_pool", "network_config", fallback="default_network.xml"
+        ),
+    )
+
+    network_xml = backend_pool.util.read_file(network_file)
+
+    template_host: str = "<host mac='{mac_address}' name='{name}' ip='{ip_address}'/>\n"
+    hosts: str = ""
+
+    # generate a host entry for every possible guest in this network (253 entries)
+    it = iter(network_table)
+    for guest_id in range(0, 253):
+        vm_name = "vm" + str(guest_id)
+
+        key = next(it)
+        hosts += template_host.format(
+            name=vm_name, mac_address=key, ip_address=network_table[key]
+        )
+
+    network_config = network_xml.format(
+        network_name="cowrie",
+        iface_name="virbr2",
+        default_gateway="192.168.150.1",
+        dhcp_range_start="192.168.150.2",
+        dhcp_range_end="192.168.150.254",
+        hosts=hosts,
+    )
+
+    # create a transient virtual network
+    try:
+        net = connection.networkCreateXML(network_config)
+        if net is None:
+            log.msg(
+                eventid="cowrie.backend_pool.network_handler",
+                format="Failed to define a virtual network",
+            )
+            sys.exit(1)
+
+        # set the network active
+        # not needed since apparently transient networks are created as active; uncomment if persistent
+        # net.create()
+
+    except libvirt.libvirtError as e:
+        log.err(
+            eventid="cowrie.backend_pool.network_handler",
+            format="Network already exists: %(error)s",
+            error=e,
+        )
+        return connection.networkLookupByName("cowrie")
+
+    return net

backend_pool/libvirt/snapshot_handler.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2019 Guilherme Borges <guilhermerosasborges@gmail.com>
+# See the COPYRIGHT file for more information
+
+from __future__ import annotations
+
+import getpass
+import shutil
+import subprocess
+
+
+def create_disk_snapshot(source_img: str, destination_img: str) -> bool:
+    try:
+        shutil.chown(source_img, getpass.getuser())
+    except PermissionError:
+        # log.msg('Should have root to create snapshot')
+        pass
+
+    # could use `capture_output=True` instead of `stdout` and `stderr` args in Python 3.7
+    out = subprocess.run(
+        [
+            "qemu-img",
+            "create",
+            "-f",
+            "qcow2",
+            "-F",
+            "qcow2",
+            "-b",
+            source_img,
+            destination_img,
+        ],
+        capture_output=True,
+    )
+    return out.returncode == 0

backend_pool/nat.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+from threading import Lock
+from typing import Any
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from twisted.python import failure
+    from twisted.internet.interfaces import IAddress
+from twisted.internet import protocol
+from twisted.internet import reactor
+from twisted.internet.protocol import connectionDone
+
+
+class ClientProtocol(protocol.Protocol):
+    server_protocol: ServerProtocol
+
+    def dataReceived(self, data: bytes) -> None:
+        assert self.server_protocol.transport is not None
+        self.server_protocol.transport.write(data)
+
+    def connectionLost(self, reason: failure.Failure = connectionDone) -> None:
+        assert self.server_protocol.transport is not None
+        self.server_protocol.transport.loseConnection()
+
+
+class ClientFactory(protocol.ClientFactory):
+    def __init__(self, server_protocol: ServerProtocol) -> None:
+        self.server_protocol = server_protocol
+
+    def buildProtocol(self, addr: IAddress) -> ClientProtocol:
+        client_protocol = ClientProtocol()
+        client_protocol.server_protocol = self.server_protocol
+        self.server_protocol.client_protocol = client_protocol
+        return client_protocol
+
+
+class ServerProtocol(protocol.Protocol):
+    def __init__(self, dst_ip: str, dst_port: int):
+        self.dst_ip: str = dst_ip
+        self.dst_port: int = dst_port
+        self.client_protocol: ClientProtocol
+        self.buffer: list[bytes] = []
+
+    def connectionMade(self):
+        reactor.connectTCP(self.dst_ip, self.dst_port, ClientFactory(self))
+
+    def dataReceived(self, data: bytes) -> None:
+        self.buffer.append(data)
+        self.sendData()
+
+    def sendData(self) -> None:
+        if not self.client_protocol:
+            reactor.callLater(0.5, self.sendData)  # type: ignore[attr-defined]
+            return
+
+        assert self.client_protocol.transport is not None
+        for packet in self.buffer:
+            self.client_protocol.transport.write(packet)
+        self.buffer = []
+
+    def connectionLost(self, reason: failure.Failure = connectionDone) -> None:
+        assert self.client_protocol.transport is not None
+        self.client_protocol.transport.loseConnection()
+
+
+class ServerFactory(protocol.Factory):
+    def __init__(self, dst_ip: str, dst_port: int) -> None:
+        self.dst_ip: str = dst_ip
+        self.dst_port: int = dst_port
+
+    def buildProtocol(self, addr: IAddress) -> ServerProtocol:
+        return ServerProtocol(self.dst_ip, self.dst_port)
+
+
+class NATService:
+    """
+    This service provides a NAT-like service when the backend pool
+    is located in a remote machine.  Guests are bound to a local
+    IP (e.g., 192.168.150.0/24), and so not accessible from a remote
+    Cowrie.  This class provides TCP proxies that associate accessible
+    IPs in the backend pool's machine to the internal IPs used by
+    guests, like a NAT.
+    """
+
+    def __init__(self):
+        self.bindings: dict[int, Any] = {}
+        self.lock = Lock()  # we need to be thread-safe just in case, this is accessed from multiple clients
+
+    def request_binding(
+        self, guest_id: int, dst_ip: str, ssh_port: int, telnet_port: int
+    ) -> tuple[int, int]:
+        with self.lock:
+            # see if binding is already created
+            if guest_id in self.bindings:
+                # increase connected
+                self.bindings[guest_id][0] += 1
+
+                return (
+                    self.bindings[guest_id][1]._realPortNumber,
+                    self.bindings[guest_id][2]._realPortNumber,
+                )
+            else:
+                nat_ssh = reactor.listenTCP(  # type: ignore[attr-defined]
+                    0, ServerFactory(dst_ip, ssh_port), interface="0.0.0.0"
+                )
+                nat_telnet = reactor.listenTCP(  # type: ignore[attr-defined]
+                    0, ServerFactory(dst_ip, telnet_port), interface="0.0.0.0"
+                )
+                self.bindings[guest_id] = [1, nat_ssh, nat_telnet]
+
+                return nat_ssh._realPortNumber, nat_telnet._realPortNumber
+
+    def free_binding(self, guest_id: int) -> None:
+        with self.lock:
+            self.bindings[guest_id][0] -= 1
+
+            # stop listening if no one is connected
+            if self.bindings[guest_id][0] <= 0:
+                self.bindings[guest_id][1].stopListening()
+                self.bindings[guest_id][2].stopListening()
+                del self.bindings[guest_id]
+
+    def free_all(self):
+        with self.lock:
+            for guest_id in self.bindings:
+                self.bindings[guest_id][1].stopListening()
+                self.bindings[guest_id][2].stopListening()