app.service namespace¶
Subpackages¶
- app.service.interfaces namespace
- Submodules
- app.service.interfaces.i_app_svc module
- app.service.interfaces.i_auth_svc module
- app.service.interfaces.i_contact_svc module
- app.service.interfaces.i_data_svc module
- app.service.interfaces.i_event_svc module
- app.service.interfaces.i_file_svc module
- app.service.interfaces.i_learning_svc module
- app.service.interfaces.i_planning_svc module
- app.service.interfaces.i_rest_svc module
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
¶
-
async
find_link
(unique)¶ Locate a given link by its unique property :param unique: :return:
-
async
find_op_with_link
(link_id)¶ 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
()¶
-
property
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
-
property
-
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
-
class
app.service.auth_svc.
DictionaryAuthorizationPolicy
(user_map)¶ Bases:
aiohttp_security.abc.AbstractAuthorizationPolicy
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.
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.
-
async
-
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_source_file
(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
-
async
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
observe_event
(event, callback)¶ Register an event handler :param event: The event topic and (optional) subtopic, separated by a ‘/’ :param callback: The function that will handle the event :return: None
-
async
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)¶
-
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:
-
async
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)¶
-
static
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.
-
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
-
async
execute_links
(planner, operation, link_ids, condition_stop)¶ 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
-
async
generate_and_trim_links
(agent, operation, abilities, trim=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
- Returns
A list of links
- Return type
list(Links)
-
async
get_cleanup_links
(operation, agent=None)¶ 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.
-
async
get_links
(operation, buckets=None, agent=None, trim=True)¶ 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
-
async static
sort_links
(links)¶ Sort links by score and atomic ordering in adversary profile
-
async
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
apply_potential_link
(link)¶
-
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_link_pin
(json_data)¶
-
async
get_potential_links
(op_id, paw=None)¶
-
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_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
-
async