CovertMark.utils module

CovertMark.utils.check_write_permission(path)[source]

Check whether it is possible for the program to write to the path supplied. :returns: True if write permissible, False otherwise.

CovertMark.utils.execute_procedure(procedure, strategy_map, db_sub=False)[source]

Execute a validated procedure and preserve their strategy states in order.

Parameters:
  • procedure (dict) – a dict containing a CovertMark procedure.
  • strategy_map (dict) – a strategy map validated by covertmark.py.
  • db_sub (bool) – subsitute PCAP and input filters specified in the procedure with MongoDB-stored collection names, eliminating importing the same pcap file with same filters.
Returns:

a list of tuples each containing a strategy instances executed based on runs specified in the procedure, and the run specification. Returns empty list if execution fails. If db_sub is set, the updated procedure will also be returned as the second element of a tuple.

CovertMark.utils.format_pcap_filters(pcap_path, input_filters, reverse)[source]

Format the pcap path and its associated input filters into a dict key with consistent alphanumeric ordering for indexing same inputs to different strategy runs. Assumes path and input filters passed are all valid.

Parameters:
  • pcap_path (str) – the path to a pcap specified by a procedure run.
  • input_filters (list) – the associated input filters in the procedure run.
  • reverse (bool) – whether the procedure run reversed the input filters from its original direction, affecting PCAP importing.
Returns:

a tuple containing the above information in a consistent ordering.

CovertMark.utils.get_strategy_runs(strategy_map)[source]

Return a pretty print tabulate for showing the user all available runs in all procedures.

Parameters:strategy_map (dict) – the strategy map to draw these information from.
Returns:a tuple containing a tabulate.tabulate containing these information, and a list of tuples containing the strategy key and the run order specified for each row.
CovertMark.utils.import_procedure(import_path, strategy_map)[source]

Import from file a saved procedure and validate it.

Parameters:
  • import_path (str) – a qualified path leading to a json procedure file saved by CovertMark.
  • strategy_map (dict) – a strategy map validated by covertmark.py.
Returns:

the validated procedure if successfully imported, False otherwise or if procedure invalid.

CovertMark.utils.list_traces(traces)[source]

Fetch stored traces in MongoDB for user selection.

Parameters:traces (list) – a list of (un)filtered traces from list().
Returns:tuple of a pretty-printable tabulate containing information of traces, and a dictionary mapping displayed IDs to the internal collection name.
CovertMark.utils.printable_procedure(procedure, strategy_map)[source]

Provide a pretty-print tabulate of programmed strategy runs in the procedure.

Parameters:
  • procedure (dict) – an imported CovertMark procedure.
  • strategy_map (dict) – a strategy map validated by covertmark.py.
Returns:

a tabulate object containing the formatted procedure.

CovertMark.utils.printable_results(results, strategy_map)[source]

Provide a pretty-print tabulate of results.

Parameters:
  • results (dict) – a dictionary of results from the handler indexed by a global handler counter, containing strategy modules, run orders, and result instances.
  • strategy_map (dict) – a validated CovertMark strategy map.
Returns:

a tuple of a formatted tabulate of results.

CovertMark.utils.random_file_name(prefix, extension)[source]

Generate a random file name with fixed prefixes to be relatively collision-free.

Parameters:
  • prefix (str) – the fixed portion of the file name.
  • extension (str) – the filename extension of the file without dot.
Returns:

a valid UNIX file name containing the prefix and 8 random hexdigest characters.

CovertMark.utils.read_strategy_map()[source]

Read in the strategy map from strategy/strategy_map.json.

Returns:(succ, msg) – succ = strategy_map if valid strategy map, False otherwise – with msg containing the error found.
CovertMark.utils.save_csvs(results, out_path)[source]

Save CSVs to a qualified path.

Parameters:
  • results (dict) – a standard CovertMark results dictionary.
  • out_path (str) – a valid directory to export the CSVs.
Returns:

a list of successfully written CSV full paths.

CovertMark.utils.save_file(content, path)[source]

Save string-formatted content to the file specified.

Parameters:
  • content (str) – string-formatted content to be written.
  • path (str) – a fully qualified path for the content to be written to.
Returns:

True if successfully written, False otherwise.

CovertMark.utils.save_procedure(export_path, procedure, strategy_map, overwrite=False)[source]

Save a programmed CovertMark procedure into the path specified for later retrieval.

Parameters:
  • export_path (str) – a qualified system path for exporting the procedure.
  • procedure (dict) – a procedure generated by CovertMark.
  • strategy_map (dict) – a strategy map validated by CovertMark.
  • overwrite (bool) – set to True to overwrite the target file if it exists.
Returns:

True if successfully saved, False otherwise or if procedure invalid.

CovertMark.utils.valid_filename(proposed_file_name)[source]

Convert a proposed file name into a valid and readable UNIX filename.

Parameters:proposed_file_name (str) – a proposed file name in string, supports unicode in Python 3.
Returns:a valid file name in string.
CovertMark.utils.validate_procedure(procedure, strategy_map)[source]

Validate an imported CovertMark procedure.

Parameters:
  • procedure (dict) – an imported CovertMark procedure.
  • strategy_map (dict) – a strategy map validated by covertmark.py.
Returns:

(succ, msg) – succ = True if the procedure is semantically valid, False otherwise; with msg indicating errors found.

CovertMark.utils.width(text, width)[source]

Insert a new line character for each block of width characters into the input text.

Parameters:
  • text (str) – the input text for newlining.
  • width (int) – a positive integer for dividing input with new lines.
Returns:

the newlined text.