"""
Example target plugin for SetecMITM.

A plugin is just a Python module under `targets/<name>/plugin.py` that
exposes a `Plugin` class. The Controller imports it on startup if
`target_plugin = "<name>"` is set in the config.

A plugin can do anything: register custom DNS spoof rules, install extra
HTTP request handlers, add a known-endpoint list to the fuzzer, register
its own CVE verifiers, or extend the protocol fingerprinter. The simplest
useful plugin is the one that knows the device's expected cloud
hostnames + the device's UDP P2P port — that's enough to bootstrap
intruder detection and traffic decoding.

Copy this directory to `targets/<your_brand>/` and edit.
"""

from utils.log import log, C_INFO


class Plugin:
    NAME = "example"
    DESCRIPTION = "Skeleton plugin showing the expected interface."

    # Expected outbound destinations the target talks to. Anything
    # outside this list gets flagged in the Intruders tab.
    KNOWN_CLOUD_NETS = [
        # ("8.8.8.0", 24),    # example: Google DNS
    ]

    # Hostnames to spoof in DNS interception. Empty = spoof all.
    DNS_SPOOF_HOSTS = [
        # "api.example.com",
    ]

    # UDP ports the target uses for P2P / push notifications.
    UDP_PORTS = [
        # 10240,
    ]

    # Known API endpoints (for the future fuzzer module).
    KNOWN_API_ENDPOINTS = [
        # "/api/v1/login",
        # "/api/v1/devices",
    ]

    def __init__(self, cfg):
        self.cfg = cfg
        log(f"plugin '{self.NAME}': initialized", C_INFO)

    # ── Optional hooks (Controller calls these if defined) ──

    def on_start(self):
        """Called once when MITM services are about to start."""
        pass

    def on_stop(self):
        """Called once when MITM services have stopped."""
        pass

    def custom_http_handler(self, request):
        """
        Optional: handle an intercepted HTTP request that the framework
        otherwise wouldn't know what to do with. Return a (status, body)
        tuple, or None to fall through.
        """
        return None

    def detect_protocol(self, payload_first_bytes):
        """
        Optional: extend the built-in protocol fingerprinter. Return a
        short label (e.g. "MyVendor-P2P") or None to fall through to
        the framework's default detection.
        """
        return None