Rules Manager¶
Rules Manager file.
This file contains the necessary methods in the RulesManager class to load, check and process the rules file.
The file rules should contain all the necessary information to execute a concrete analysis. However, multiple and independent analysis might be executed.
Each rules file should contain a complete analysis technique defined. If multiple modules are being used, this should be to reach the goal of execute a complex but concrete analysis.
- class rules_manager.RulesManager(rules_file)¶
RulesManager class.
This class defines the necessary methods to load, check and process the rules from a file.
- __init__(rules_file)¶
It initializes the necessary variables.
- Parameters
rules_file (str) – path to the rules file.
- __weakref__¶
list of weak references to the object (if defined)
- check_rules(save_args)¶
It checks if the rules file contains the mandatory rules. The checking is performed by name and elements quantity, so it has to match in both properties.
If self.rules is None, the checking fails.
- Parameters
save_args (bool) – it indicates that the arguments have to be saved while they are being checked.
- Returns
true if the rules are valid; false otherwise
- Return type
bool
- check_rules_arg(arg, father, grandpa, save_args, args_reference, sort_args)¶
It checks if the <args> elements are correct recursevely.
This method works recursively making the following calls:
check_rules_arg -> check_rules_arg_recursive
check_rules_arg_recursive -> check_rules_arg
What this method makes is checking if the <args> elements which are inside are correct and, optionally, save them to being used by the target module which is specified in the rules file.
If the arguments want to be saved, the order may not be the expected. If the <args> elements are mixed, the predefined order will be:
Dictionaries
Lists
Elements
If you want to have the elements in the correct order which you wrote, you can avoid mixing the elements or use the sort_args argument to have a partial sorting (this partial sorting makes worse the performance while checking). We say “partial” because the result will be that if you are mixing elements, all them will be grouped and will appear in the order which the first type of element appeared.
- Parameters
arg – current arg which is being checked (processed recursively).
father (str) – arg’s father.
grandpa (str) – arg’s grandpa; father’s father.
save_args (bool) – it indicates if you want to save the args while they are being checked.
args_reference – if save_args is True, this is the concrete arg reference which it changes while recursion is being processed. It changes the reference from call to call to save the concrete args here.
sort_args (bool) – it indicates if you want a partial sorting when you mix different type of elements.
Example
<args>
<dict>
<list name=”l1”></list>
<dict name=”d”></dict>
<element name=”e” value=”v” />
<list name=”l2”></list>
</dict>
</args>
Unsorted result: {“d”: {}, “l1”: [], “l2”: [], “e”: “v”}
Partial sorted result: {“l1”: [], “l2”: [], “d”: {}, “e”: “v”}
- Returns
true if the arguments are valid; false otherwise
- Return type
bool
- check_rules_arg_high_level(dict_tag, parent_tag_name, tag_prefix, save_args)¶
This is the method that should be invoked when you want to check, and optionally parse, the arguments from the rules file.
- Raises
BOARulesIncomplete – when the number of expected mandatory rules does not match with the actual number of rules or when a concrete rule is not found.
BOARulesUnexpectedFormat – when the format of a rule is not the expected.
BOARulesError – when an non-specific error happens.
- check_rules_arg_recursive(arg, element, father, arg_reference, args_reference, save_args, sort_args)¶
This method is used by check_rules_arg method.
This method wraps the common behaviour for saving the arguments references and makes the necessary recursive calls for each element. Moreover, it checks that the arguments, depending on the concrete element, contains the expected attributes (e.g. a dictionary’s element contains a name attribute).
For details, check check_rules_arg documentation.
- Parameters
arg – current arg which is being checked (processed recursively).
element (str) – the concrete type of element which is being given. It may be “dict”, “list” or None. If None, it indicates that the element is a “element”.
father (str) – arg’s father.
arg_reference – the new reference which will be appended to args_reference.
args_reference – if save_args is True, this is the concrete arg reference which it changes while recursion is being processed. It changes the reference from call to call to save the concrete args here.
save_args (bool) – it indicates if you want to save the args while they are being checked.
sort_args (bool) – it indicates if you want a partial sorting when you mix different type of elements.
- Returns
true if the arguments are valid; false otherwise
- Return type
bool
- check_rules_dynamic_analysis_runner(save_args, runner_module)¶
It makes the checks relative to the runner modules which are used in the dynamic analysis.
- Parameters
save_args (bool) – it indicates that the arguments have to be saved while they are being checked.
runner_module (str) – runner which is going to be processed in order to check the rules.
- Raises
BOARulesIncomplete – when the number of expected mandatory rules does not match with the actual number of rules or when a concrete rule is not found.
BOARulesError – when a semantic rule is broken. You have to follow the rules documentation to avoid this exception.
KeyError – if runner_module is not an expected runner.
- check_rules_init()¶
It makes the initial checks.
- Raises
BOARulesIncomplete – when the number of expected mandatory rules does not match with the actual number of rules or when a concrete rule is not found.
- check_rules_modules(save_args)¶
It makes the checks relative to the modules.
- Parameters
save_args (bool) – it indicates that the arguments have to be saved while they are being checked.
- Raises
BOARulesIncomplete – when the number of expected mandatory rules does not match with the actual number of rules or when a concrete rule is not found.
BOARulesUnexpectedFormat – when the format of a rule is not the expected.
BOARulesError – when an non-specific error happens.
- check_rules_parser()¶
It makes the checks relative to the parser.
- Raises
BOARulesIncomplete – when the number of expected mandatory rules does not match with the actual number of rules or when a concrete rule is not found.
- check_rules_report(save_args)¶
It makes the checks relative to the report.
- Parameters
save_args (bool) – it indicates that the arguments have to be saved while they are being checked.
- Raises
BOARulesIncomplete – when the number of expected mandatory rules does not match with the actual number of rules or when a concrete rule is not found.
BOARulesError – when a semantic rule is broken. You have to follow the rules documentation to avoid this exception.
- close()¶
It closes the rules file to release the resource.
- Returns
status code
- Return type
int
- get_args(module=None)¶
It returns the args for a concrete module.
- Parameters
module (str) – module from which args are going to be returned. The expected format is (without quotes): “module_name.class_name”. Check utils.get_name_from_class_instance. The default value is None.
- Returns
module args or all the modules args; None if a module were specified and could not find it
- Return type
dict
- get_dependencies(module=None)¶
It returns the dependencies for a concrete module.
- Parameters
module (str) – module from which args are going to be returned. The expected format is (without quotes): “module_name.class_name”. Check utils.get_name_from_class_instance. The default value is None.
- Returns
module dependencies or all the modules dependencies; None if a module were specified and could not find it, what means that the module does not have dependencies
- Return type
dict
- get_report_args()¶
It returns the args for the Report instance.
- Returns
report args
- Return type
dict
- get_rules(path=None, list_type=False)¶
It returns the rules.
The rules can be obtained with a concrete path, which means that you can obtain the rules you want directly, without go through them. The path is a string which will be splited with ‘.’.
- Parameters
path (str) – the returned rules will be from a starting point. If you to get all the modules rules, the path has to have the value “boa_rules.modules.module”. The default value is None.
list_type (bool) – the returned rules will be wrapped in a list. The default value is False.
- Returns
rules from the rules file. If list_type is True, the returning type will not be dict but list.
- Return type
dict
- get_runner_args(runner_module)¶
It returns the args of a runner module.
- Parameters
runner_module (str) – key of self.runner_args which is where the parameters are stored.
- Returns
args if they exist, but empty dict and logging warning if does not
- Return type
dict
- open()¶
It opens the rules file, checking if exists first.
- Returns
status code
- Return type
int
- read()¶
It reads the rules file and saves the necessary information.
- Returns
status code
- Return type
int
- set_args(module, arg)¶
It sets the arguments for a concrete module. This method should only be used for internal management.
- Parameters
module (str) – instance identification as string. The expected format is (without quotes): “module_name .class_name”. Check utils.get_name_from_class_instance.
arg (dict) – the new args for the module.
- Returns
True if the args could be set; False otherwise
- Return type
bool
- set_dependencies(module, dependencies)¶
It adds dependencies for a concrete module. This method should only be used for internal management.
- Parameters
module (str) – instance identification as string. The expected format is (without quotes): “module_name .class_name”. Check utils.get_name_from_class_instance.
dependencies (dict) – the new dependencies for the module.
- Returns
True if the dependencies could be apppended; False otherwise
- Return type
bool