Integrating C2s

Search…
The elements of Zuthaka are instances over implemented abstract classes that define the general behavior of a C2.
Class Handlers
Class handlers are the core of every new Zuthaka integration. These represent the base functionality and contract given by the integration. The attributes defined in the class handler frame the representation exposed in the web interface and the functions implemented in the class shape the service behavior.
Implementing C2 Type Class handler connections:
The handlers should only provide the basic C2 interaction while managing consistency. Error tracking tasks are done by Zuthaka's service.
Attributes and Options Descriptions
The attributes "name", "description", "documentation", and a list of "registered_options" is mandatory for the correct function of Zuthaka. This helps guide the user through the steps necessary to use the specific implementation.
template.py
1
from ..c2 import C2, Listener, ListenerType, Launcher, LauncherType, Options, OptionDesc
2
​
3
class TemplateC2Type(C2):
4
    # all this information is given to the user when using the interface
5
    name = 'template_c2'
6
    description = 'this is an example C2'
7
    documentation = 'https://super.awesome.c2/docs/'
8
    registered_options = [ 
9
        OptionDesc(
10
            name='url',
11
            description='Url of the corresponding API',
12
            example='https://127.0.0.1:31337',
13
            field_type='string',
14
            required=True
15
        ),  
16
        OptionDesc(
17
            name='username',
18
            description='user owner of the API',
19
            example='pucara',
20
            field_type='string',
21
            required=True
22
        ),  
23
        OptionDesc(
24
            name='password',
25
            description='Url of the corresponding API',
26
            example='p4ssw0rd',
27
            field_type='string',
28
            required=True
29
        ),  
30
    ]
31
​
32
​
33
   ...
34
​
Copied!
The descriptions of the integration helps to populate the user interface, for a guided experience.
 Behavior Abstract Methods
The behavior is defined through the implementation of abstract methods with an specific "contract".
health check method: is_alive
1
 ...
2
 async def is_alive(self) -> bool:
3
        """ 
4
            This method is used to collect latency from C2, and validate connection before
5
            perisisting the data to Zuthaka's DB.
6
            
7
            raises ConectionError in case of not be able to connect to c2 instance
8
            raises ConnectionRefusedError in case of not be able to authenticate
9
        """
10
        pass
11
​
12
...
Copied!
A good practice to implement "is_alive" is to query the API for a given response. For REST APIs, generating a token is a good way to guarantee the C2 is processing the requests given through the handler.
Implementing Listener Type Class
The Listeners are the services awaiting for connections from different Agents and generally delivering the instructions to be executed by them.
Listener Types are integrated with a similar logic that responds to the C2 API to handle Listeners.
Attributes and Options Descriptions
1
....
2
class TemplateListenerType(ListenerType):
3
    name = 'http'
4
    description = 'standard http listener, messages are delivered in enconded comment'
5
    registered_options = [
6
        OptionDesc(
7
            name='useSSL',
8
            description='ssl enabled communication between agent and listener',
9
            example='false',
10
            field_type='string',
11
            required=True
12
        ),
13
        OptionDesc(
14
            name='bindAdress',
15
            description='interfaces to which the listener is bind',
16
            example='0.0.0.0',
17
            field_type='string',
18
            required=True
19
        ),
20
        OptionDesc(
21
            name='connectAddresses',
22
            description='address to which the agent is going to try to connect',
23
            example='192.168.0.14',
24
            field_type='string',
25
            required=True
26
        ),
27
        OptionDesc(
28
            name='connectPort',
29
            description='port to which the agent is going to try to connect',
30
            example=80,
31
            field_type='integer',
32
            required=True
33
        ),
34
    ]
35
...
Copied!
Behavior Abstract Methods
Listeners must be able to be created and destroyed.
1
class ListenerType(ABC):
2
    """ Listener Factory """
3
​
4
    @abstractmethod
5
    async def create(self, options: Options) -> 'Listener':
6
        """
7
        creates an listener on the corresponding C2 and return a Listener with listener_internal_id for the corresponding API
8
​
9
           raises ValueError in case of invalid dto
10
           raises ConectionError in case of not be able to connect to c2 instance
11
           raises ResourceExistsError in case of not be able to create the objectdue it already exists
12
​
13
         """
14
        pass
15
        
16
    @abstractmethod
17
    async def delete(self, internal_id:str, options: Options) -> None:
18
​
19
        """
20
        removes a listener from a corresponding c2 instance
21
​
22
           raises ValueError in case of invalid dto
23
           raises ConectionError in case of not be able to connect to c2 instance
24
           raises ResourceNotFoundError in case of not be able to remove the object due to unfound resource
25
​
26
        """
27
        pass
28
​
29
​
Copied!
The creation or elimination of elements requires a consistency check by the class handler. This allows Zuthaka to catch at an early stage any consistency problem with the infrastructure handled.
Implementing Launcher Type Class
The Launchers represent the capabilities of a given C2 to encapsulate the implant for later execution on the victim's machine.
Attributes and Options Descriptions
1
....
2
class TemplateLauncherType(ListenerType):
3
    name = 'Powershell Launcher'
4
    description = 'Uses powershell.exe to launch Agent using [systemm.reflection.assemly::load()'
5
    registered_options = [
6
        OptionDesc(
7
            name='Dotnet Version',
8
            description='version of dotnet in which the launcher is going to take place',
9
            example='Net35',
10
            field_type='string',
11
            required=True
12
        ),
13
    ]
14
...
Copied!
 Behavior Abstract Methods
1
   ...
2
     async def create_launcher(self, dto: Dict[str, Any]) -> str:
3
        """
4
        creates a laucnher on the corresponding C2 and return an launcher_internal_id raises ValueError in case of invalid dto
5
           raises ConectionError in case of not be able to connect to c2 instance
6
           raises ResourceExistsError in case of not be able to create the objectdue it already exists
7
​
8
        """
9
        pass
10
        
11
    async def download_launcher(self, dto: Dict[str, Any]) -> bytes:
12
        """
13
        retrives a created launcher using an launcher_internal_id
14
           raises ValueError in case of invalid dto
15
           raises ConectionError in case of not be able to connect to c2 instance
16
           raises ResourceNotFoundError 
17
        """
18
...
Copied!
Implementing Agent Type Class
Agents are controlled victim's machines. The integration of Agents on Zuthaka allows the user to manage the computer through the UI.
 Behavior Abstract Methods
1
​
2
class TemplateAgent(AgentType):
3
​
4
    async def retreive_agents(self, dto: Dict[str, Any]) -> bytes:
5
        """
6
        retrives all available Agents on the  given C2
7
           raises ValueError in case of invalid dto
8
           raises ConectionError in case of not be able to connect to c2 instance
9
           raises ResourceNotFoundError 
10
​
11
        [*] EXAMPLES 
12
​
13
        dto = {
14
            'c2_type' :'EmpireC2Type',
15
            'c2_options': {
16
                    "url": "https://127.0.0.1:7443",
17
                    "username": "cobbr",
18
                    "password": "NewPassword!"
19
                },
20
              'listeners_internal_ids' : ['1','2','3'] 
21
              }
22
        """
23
​
24
        pass
25
​
26
    async def shell_execute(self, dto: Dict[str, Any]) -> bytes:
27
        """
28
        executes a command string on the 
29
           raises ValueError in case of invalid dto
30
           raises ConectionError in case of not be able to connect to c2 instance
31
           raises ResourceNotFoundError 
32
​
33
        """
34
        pass
35
​
Copied!
Usage
Last modified 5mo ago
Copy link
Contents
Class Handlers
Implementing C2 Type Class handler connections:
Implementing Listener Type Class
Implementing Launcher Type Class
Implementing Agent Type Class