Integrating C2s
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
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!
Last modified 8mo ago