app.service namespace

Submodules

app.service.app_svc module

class app.service.app_svc.AppService(application)

Bases: app.service.interfaces.i_app_svc.AppServiceInterface, app.utility.base_service.BaseService

property errors

Locate a given link by its unique property :param unique: :return:

Retrieves the operation that a link_id belongs to. Will search currently running operations first.

async load_plugin_expansions(plugins=())
async load_plugins(plugins)

Store all plugins in the data store :return:

async register_contacts()
async resume_operations()

Resume all unfinished operations :return: None

async retrieve_compiled_file(name, platform)
async run_scheduler()

Kick off all scheduled jobs, as their schedule determines :return:

async start_sniffer_untrusted_agents()

Cyclic function that repeatedly checks if there are agents to be marked as untrusted :return: None

async teardown(main_config_file='default')
async validate_requirement(requirement, params)
async validate_requirements()
async watch_ability_files()
class app.service.app_svc.Error(name, msg)

Bases: tuple

property msg

Alias for field number 1

property name

Alias for field number 0

app.service.auth_svc module

class app.service.auth_svc.AuthService

Bases: app.service.interfaces.i_auth_svc.AuthServiceInterface, app.utility.base_service.BaseService

class User(username, password, permissions)

Bases: tuple

property password

Alias for field number 1

property permissions

Alias for field number 2

property username

Alias for field number 0

async apply(app, users)

Set up security on server boot :param app: :param users: :return: None

async check_permissions(group, request)

Check if a request is allowed based on the user permissions :param group: :param request: :return: None

async create_user(username, password, group)
async get_permissions(request)
async login_user(request)

Log a user in and save the session :param request: :return: the response/location of where the user is trying to navigate

async static logout_user(request)

Log the user out :param request: :return: None

class app.service.auth_svc.DictionaryAuthorizationPolicy(user_map)

Bases: aiohttp_security.abc.AbstractAuthorizationPolicy

async authorized_userid(identity)

Retrieve authorized user id. Return the user_id of the user identified by the identity or ‘None’ if no user exists related to the identity.

async permits(identity, permission, context=None)

Check user permissions. Return True if the identity is allowed the permission in the current context, else return False.

app.service.auth_svc.check_authorization(func)

Authorization Decorator This requires that the calling class have self.auth_svc set to the authentication service.

app.service.auth_svc.for_all_public_methods(decorator)

class decorator – adds decorator to all public methods

app.service.contact_svc module

class app.service.contact_svc.ContactService

Bases: app.service.interfaces.i_contact_svc.ContactServiceInterface, app.utility.base_service.BaseService

async build_filename()
async get_contact(name)
async handle_heartbeat(**kwargs)
async register(contact)

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

app.service.contact_svc.report(func)

app.service.data_svc module

class app.service.data_svc.DataService

Bases: app.service.interfaces.i_data_svc.DataServiceInterface, app.utility.base_service.BaseService

async apply(collection)

Add a new collection to RAM :param collection: :return:

async static destroy()

Clear out all data :return:

async load_ability_file(filename, access)
async load_adversary_file(filename, access)
async load_data(plugins=())

Non-blocking read all the data sources to populate the object store :return: None

async load_objective_file(filename, access)
async load_source_file(filename, access)
async load_yaml_file(object_class, filename, access)
async locate(object_name, match=None)

Find all c_objects which match a search. Return all c_objects if no match. :param object_name: :param match: dict() :return: a list of c_object types

async reload_data(plugins=())

Blocking read all the data sources to populate the object store :return: None

async remove(object_name, match)

Remove any c_objects which match a search :param object_name: :param match: dict() :return:

async restore_state()

Restore the object database

Returns

async save_state()

Accept all components of an agent profile and save a new agent or register an updated heartbeat. :return: the agent object, instructions to execute

async search(value, object_name)
async store(c_object)

Accept any c_object type and store it (create/update) in RAM :param c_object: :return: a single c_object

app.service.event_svc module

class app.service.event_svc.EventService

Bases: app.service.interfaces.i_event_svc.EventServiceInterface, app.utility.base_service.BaseService

async fire_event(event, **callback_kwargs)

Fire an event :param event: The event topic and (optional) subtopic, separated by a ‘/’ :param callback_kwargs: Any additional parameters to pass to the event handler :return: None

async handle_exceptions(awaitable)
async notify_global_event_listeners(event, **callback_kwargs)

Notify all registered global event listeners when an event is fired.

Parameters

event (str) – Event string

async observe_event(event, callback)

Register a callback for a certain event. Callback is fired when an event of that type is observed.

Parameters

  • event (str) – Event string

  • callback (function) – Callback function

async register_global_event_listener(callback)

Register a global event listener that is fired when any event is fired.

Parameters

callback (function) – Callback function

app.service.file_svc module

class app.service.file_svc.FileSvc

Bases: app.service.interfaces.i_file_svc.FileServiceInterface, app.utility.base_service.BaseService

async add_special_payload(name, func)

Call a special function when specific payloads are downloaded

Parameters

  • name –

  • func –

Returns

async compile_go(platform, output, src_fle, arch='amd64', ldflags='-s -w', cflags='', buildmode='', build_dir='.', loop=None)

Dynamically compile a go file :param platform: :param output: :param src_fle: :param arch: Compile architecture selection (defaults to AMD64) :param ldflags: A string of ldflags to use when building the go executable :param cflags: A string of CFLAGS to pass to the go compiler :param buildmode: GO compiler buildmode flag :param build_dir: The path to build should take place in :return:

async create_exfil_sub_directory(dir_name)
async find_file_path(name, location='')

Find the location on disk of a file by name. :param name: :param location: :return: a tuple: the plugin the file is found in & the relative file path

async get_file(headers)

Retrieve file :param headers: headers dictionary. The file key is REQUIRED. :type headers: dict or dict-equivalent :return: File contents and optionally a display_name if the payload is a special payload :raises: KeyError if file key is not provided, FileNotFoundError if file cannot be found

get_payload_name_from_uuid(payload)
async read_file(name, location='payloads')

Open a file and read the contents :param name: :param location: :return: a tuple (file_path, contents)

read_result_file(link_id, location='data/results')

Read a result file. If file encryption is enabled, this method will return the plaintext content. :param link_id: The id of the link to return results from. :param location: The path to results directory. :return:

async save_file(filename, payload, target_dir, encrypt=True)
async save_multipart_file_upload(request, target_dir)

Accept a multipart file via HTTP and save it to the server :param request: :param target_dir: The path of the directory to save the uploaded file to.

write_result_file(link_id, output, location='data/results')

Writes the results of a link execution to disk. If file encryption is enabled, the results file will contain ciphertext. :param link_id: The link id of the result being written. :param output: The content of the link’s output. :param location: The path to the results directory. :return:

app.service.learning_svc module

class app.service.learning_svc.LearningService

Bases: app.service.interfaces.i_learning_svc.LearningServiceInterface, app.utility.base_service.BaseService

static add_parsers(directory)
async build_model()

The model is a static set of all variables used inside all ability commands This can be used to determine which facts - when found together - are more likely to be used together :return:

async learn(facts, link, blob)

app.service.planning_svc module

class app.service.planning_svc.PlanningService

Bases: app.service.interfaces.i_planning_svc.PlanningServiceInterface, app.utility.base_planning_svc.BasePlanningService

async add_ability_to_bucket(ability, bucket)

Adds bucket tag to ability

Parameters

  • ability (Ability) – Ability to add bucket to

  • bucket (string) – Bucket to add to ability

async check_stopping_conditions(stopping_conditions, operation)

Check operation facts against stopping conditions

Checks whether an operation has collected the at least one of the facts required to stop the planner. Operation facts are checked against the list of facts provided by the stopping conditions. Facts will be validated based on the unique property, which is a combination of the fact trait and value.

Parameters

  • stopping_conditions (list(Fact)) – List of facts which, if collected, should be used to terminate the planner

  • operation (Operation) – Operation to check facts on

Returns

True if all stopping conditions have been met, False if all stopping conditions have not been met

Return type

bool

async default_next_bucket(current_bucket, state_machine)

Returns next bucket in the state machine

Determine and return the next bucket as specified in the given bucket state machine. If the current bucket is the last in the list, the bucket order loops from last bucket to first.

Parameters

  • current_bucket (string) – Current bucket execution is on

  • state_machine (list) – A list containing bucket strings

Returns

Bucket name to execute

Return type

string

Apply links to operation and wait for completion

Optionally, stop bucket execution if stopping conditions are met

Parameters

  • planner (LogicalPlanner) – Planner to check for stopping conditions on

  • operation (Operation) – Operation running links

  • link_ids (list(string)) – Links IDS to wait for

  • condition_stop (bool, optional) – Check and respect stopping conditions

Returns

True if planner stopping conditions are met

Return type

bool

async execute_planner(planner)

Default planner execution flow.

This method will run the planner, progressing from bucket to bucket.

Will stop execution for these conditions:

  • All buckets have been executed.

  • Planner stopping conditions have been met.

  • Operation was halted from external/UI input.

NOTE: Do NOT call wait-for-link-completion functions here. Let the planner decide to do that within its bucket functions, and/or there are other planning_svc utilities for the bucket functions to use to do so.

Parameters

planner (LogicalPlanner) – Planner to run

async exhaust_bucket(planner, bucket, operation, agent=None, batch=False, condition_stop=True)

Apply all links for specified bucket

Blocks until all links are completed, either after batch push, or separately for every pushed link.

Parameters

  • planner (LogicalPlanner) – Planner to check for stopping conditions on

  • bucket (string) – Bucket to pull abilities from

  • operation (Operation) – Operation to run links on

  • agent (Agent, optional) – Agent to run links on, defaults to None

  • batch (bool, optional) – Push all bucket links immediately. Will check if operation has been stopped(by user) after all bucket links complete. ‘False’ will push links one at a time, and wait for each to complete. Will check if operation has been stopped (by user) after each single link is completed. Defaults to False

  • condition_stop (bool, optional) – Enable stopping of execution if stopping conditions are met. If set to False, the bucket will continue execution even if stopping conditions are met. defaults to True

Generate new links based on abilities

Creates new links based on given operation, agent, and abilities. Optionally, trim links using trim_links() to return only valid links with completed facts.

Parameters

  • operation (Operation) – Operation to generate links on

  • agent (Agent) – Agent to generate links on

  • abilities (list(Ability)) – Abilities to generate links for

  • trim (bool, optional) – call trim_links() on list of links before returning, defaults to True

Returns

A list of links

Return type

list(Links)

Generate cleanup links

Generates cleanup links for given operation and agent. If no agent is provided, cleanup links will be generated for all agents in an operation.

Parameters

  • operation (Operation) – Operation to generate links on

  • agent (Agent, optional) – Agent to generate links on, defaults to None

Returns

a list of links

Generate links for use in an operation

For an operation and agent combination, create links (that can be executed). When no agent is supplied, links for all agents are returned.

Parameters

  • operation (Operation) – Operation to generate links for

  • buckets (list(string), optional) – Buckets containing abilities. If ‘None’, get all links for given operation, agent, and trim setting. If a list of buckets if provided, then get links for specified buckets for given operation and trim setting. Defaults to None.

  • agent (Agent, optional) – Agent to generate links for, defaults to None

  • trim (bool, optional) – call trim_links() on list of links before returning, defaults to True

Returns

a list of links sorted by score and atomic ordering

Sort links by score and atomic ordering in adversary profile

Parameters

links (list(Link)) – List of links to sort

Returns

Sorted links

Return type

list(Link)

async update_stopping_condition_met(planner, operation)

Update planner stopping_condition_met property

Parameters

  • planner (LogicalPlanner) – Planner to check stopping conditions and update

  • operation (Operation) – Operation to check facts on

app.service.rest_svc module

class app.service.rest_svc.RestService

Bases: app.service.interfaces.i_rest_svc.RestServiceInterface, app.utility.base_service.BaseService

async construct_agents_for_group(group)
async create_operation(access, data)
async create_schedule(access, data)
async delete_ability(data)
async delete_adversary(data)
async delete_agent(data)
async delete_operation(data)
async display_objects(object_name, data)
async display_operation_report(data)
async display_result(data)
async download_contact_report(contact)
async find_abilities(paw)
async get_agent_configuration(data)
async list_payloads()
async persist_ability(access, data)

Persist abilities. Accepts single ability or bulk set of abilities. For bulk, supply dict of form {“bulk”: [{<ability>}, {<ability>},…]}.

async persist_adversary(access, data)

Persist adversaries. Accepts single adversary or bulk set of adversaries. For bulk, supply dict of form {“bulk”: [{<adversary>}, {<adversary>},…]}.

async persist_objective(access, data)

Persist objectives. Accepts single objective or a bulk set of objectives. For bulk, supply dict of form {“bulk”: [{objective}, …]}.

async persist_source(access, data)

Persist sources. Accepts single source or bulk set of sources. For bulk, supply dict of form {“bulk”: [{<sourc>}, {<source>},…]}.

async task_agent_with_ability(paw, ability_id, obfuscator, facts=())
async update_agent_data(data)
async update_chain_data(data)
async update_config(data)
async update_operation(op_id, state=None, autonomous=None, obfuscator=None)
async update_planner(data)

Update a new planner from either the GUI or REST API with new stopping conditions. This overwrites the existing YML file. :param data: :return: the ID of the created adversary