Implementacion de controladores

Para integrar nuestro C2 a la web GUI que ofrece Zuthaka deberemos implementar unas clases abstractas.

Dentro de la carpeta ClassHandlers podrán ver los controladores que actualmente se encuentran desarrollados junto a un archivo de plantilla para la implementación de nuestro controlador

template.py

from ..c2 import C2, Listener, ListenerType, Launcher, LauncherType, Options, OptionDesc

class TemplateC2Type(C2):
    # all this information is given to the user when using the interface
    name = 'template_c2'
    description = 'this is an example C2'
    documentation = 'https://super.awesome.c2/docs/'
    registered_options = [ 
        OptionDesc(
            name='url',
            description='Url of the corresponding API',
            example='https://127.0.0.1:31337',
            field_type='string',
            required=True
        ),  
        OptionDesc(
            name='username',
            description='user owner of the API',
            example='pucara',
            field_type='string',
            required=True
        ),  
        OptionDesc(
            name='password',
            description='Url of the corresponding API',
            example='p4ssw0rd',
            field_type='string',
            required=True
        ),  
    ]


   ...

Descripción de controladores

Las clases a implementar corresponden a cada uno de los componentes de los C2s: * C2s * Listeners - Launchers - Agents Dentro de las mismas deberán representarse atributos estáticos correspondientes a la información que Zuthaka expone a los usuarios y métodos que representaran la lógica de negocio necesaria para administrar el C2.

Los controladores deben proveer solo la interaccion basica con el Command & Control, mientras que el manejo de consistencia, excepciones y errores son tareas que maneja internamente Zuthaka.

Tipo de C2

Los atributos que se deben representar para la correcta representacion del C2 en zuthaka son:

class C2(ABC):
    name: str
    description: str
    documentation: str
    registered_options: List[OptionDesc]

    def __init__(self, options: Options) -> None:
        _is_valid = self.__class__.validate_options(options)
        if not _is_valid :
            raise ValueError('Invalid options')
        self.options = options

    @abstractmethod
    async def is_alive(self, name: str) -> bool:
        """
            tries to connect to the corresponding c2 and returns bool
            raises ConectionError in case of not be able to connect to c2 instance
            raises ConnectionRefusedError in case of not be able to authenticate
        """
        pass
    
    @abstractmethod
    async def get_listener_types(self) -> Dict[str, 'ListenerType']:
        """
            Returns a dictionary with all the registered listener types 
        """
        pass

    @abstractmethod
    async def get_launcher_types(self) -> Iterable['LauncherType']:
        """
            Returns a dictionary with all the registered launcher types 
        """
        pass

    @abstractmethod
    async def retrieve_agents(self, dto: Dict[str, Any]) -> bytes:
        """
            retrives all available Agents on the  given C2
               raises ValueError in case of invalid dto
               raises ConectionError in case of not be able to connect to c2 instance
               raises ResourceNotFoundError 

            [*] EXAMPLES 

            dto = {
                'c2_type' :'EmpireC2Type',
                'c2_options': {
                        "url": "https://127.0.0.1:7443",
                        "username": "cobbr",
                        "password": "NewPassword!"
                    },
                  'listeners_internal_ids' : ['1','2','3'] 
                  }

            response_dto = {'agents': [{
                'last_connection' : '',
                'first_connection' : '',
                'hostname' : '',
                'username' : '',
                'internal_id' : ''
                'shell_type' : ''
                'listener_internal_id' : ''
                }, ]
                }
        """
        pass

Tipo de Listener

Los listeners, para zuthaka, son los servicios que esperan por la conexión de los Agentes.

class ListenerType(ABC):
    """ Listener Factory """

    @abstractmethod
    async def create_listener(self, options: Options) -> 'Listener':
        """
        creates an listener on the corresponding C2 and return a Listener with listener_internal_id for the corresponding API

           raises ValueError in case of invalid dto
           raises ConectionError in case of not be able to connect to c2 instance
           raises ResourceExistsError in case of not be able to create the objectdue it already exists

        [*] EXAMPLES 

        dto = {
            'c2_type' :'EmpireC2Type',
            'c2_options': {
                    "url": "https://127.0.0.1:7443",
                    "username": "cobbr",
                    "password": "NewPassword!"
                },
              'listener_type' :'HTTPEmpire',
              'listener_options' : {
                    "interface": "192.168.0.1",
                    "port": "139",
                    "default_delay": "10",
                }
            }
        """
        pass

    @abstractmethod
    async def delete_listener(self, internal_id:str, options: Options) -> None:

        """
        removes a listener from a corresponding c2 instance

           raises ValueError in case of invalid dto
           raises ConectionError in case of not be able to connect to c2 instance
           raises ResourceNotFoundError in case of not be able to remove the object due to unfound resource

        """
        pass

Tipo de Launchers

class LauncherType(ABC):
    """ Launcher Factory """

    @abstractmethod
    async def create_launcher(self, dto: Dict[str, Any]) -> str:
        """
        creates a laucnher on the corresponding C2 and return 
        an launcher_internal_id raises ValueError in case of invalid dto
        
           raises ConectionError in case of not be 
               able to connect to c2 instance
           raises ResourceExistsError in case of not be 
               able to create the objectdue it already exists

        """
        raise NotImplementedError
        
    @abstractmethod
    async def download_launcher(self, dto: Dict[str, Any]) -> bytes:
        """
        retrives a created launcher using an launcher_internal_id
           raises ValueError in case of invalid dto
           raises ConectionError in case of not be able to connect to c2 instance
           raises ResourceNotFoundError 
        """
        raise NotImplementedError

Los Launchers, para zuthaka, son los métodos para la ejecución de implantes disponibles en el Command & Control.

Tipos de Agents

Encargados de controlar los equipos de los usuarios

class AgentType(ABC):

    async def shell_execute(self, dto: Dict[str, Any]) -> bytes:
        """
        executes a command string on the 
           raises ValueError in case of invalid dto
           raises ConectionError in case of not be able to connect to c2 instance
           raises ResourceNotFoundError 

        """
        pass

    async def upload_file(self, dto: Dict[str, Any]) -> bytes:
            """
            Uploads a given file to a target directory with a given filename
            raises ValueError in case of invalid dto
            raises ConectionError in case of not be able to connect to c2 instance
            raises ResourceNotFoundError 

            [*] EXAMPLES 

            dto = {
                'c2_type' :'EmpireC2Type',
                'c2_options': {
                        "url": "https://127.0.0.1:7443",
                        "username": "cobbr",
                        "password": "NewPassword!"
                    },
                'listeners_internal_ids' : ['1','2','3'] 
                }
            """

            pass
    async def download_file(self, dto: Dict[str, Any]) -> bytes:
        """
        executes a command string on the 
            raises ValueError in case of invalid dto
            raises ConectionError in case of not be able to connect to c2 instance
            raises ResourceNotFoundError 
        dto = {'agent_internal_id':1234, 'command':'ls'}
        """
        pass