mrxcavator API documentation
Description: mrxcavator.py: CLI client for CRXcavator.io

# Module `mrxcavator`

mrxcavator.py: CLI client for CRXcavator.io

## Functions

`def build_config(filename: str) ‑> bool`

  Builds a default configuration and says it to the passed-in filename.

  ## Args

  `filename`
    The mrxcavator configuration filename as a string.

  ## Returns

  A boolean result.

`def build_parser() ‑> Any`

  Returns a configured object for argparse functionality.

  ## Args

  None

  ## Returns

  An object for argparse.

`def call_api(end_point: str, method: str, values=None, headers=None) ‑> dict`

  Calls an API endpoint with a passed-in HTTP method and an optional dict of values for APIs that required parameters to be sent in the request.

  ## Args

  `end_point`
    An API endpoint path string.
  `method`
    The HTTP method string to use for the API call.
  `values`
    An optional dict of values to pass as API parameters.
  `headers`
    An optional dict of headers to pass to the API.

  ## Returns

  A dict of API results or an empty dict.

`def chunker(seq: list, size: int) ‑> Generator`

  Returns a list of items in groups based on the passed-in size.

  ## Args

  `seq`
    A list of items
  `size`
    An integer for the number of items to "chunk" at a time.

  ## Returns

  A list of items.

`def error(message: str, fatal=False) ‑> bool`

  Prints a passed-in message and then exits with False or a failure exit.

  ## Args

  `message`
    A message string.

  ## Returns

  False or exits the application with a failure status code.

`def export_report(id: str, report: str, filename: str) ‑> bool`

  Exports a report summary to a file.

  ## Args

  `id`
    An extension identifier string.
  `report`
    A string of the report summary.
  `filename`
    The chosen filename as a string.

  ## Returns

  A boolean result for exporting the report summary to a file.

`def extension_is_ignored(id: str) ‑> bool`

  Returns a boolean to designate if a passed-in extension ID is within the ignored list or not. These ignored extensions are ones that get installed by Google and normally "hidden" from view (i.e. chrome:///extensions)

  ## Args

  `id`
    An extension identifier string.

  ## Returns

  A boolean result.

`def extensions_from_file(filename: str) ‑> list`

  Returns a list of extension dicts based on the passed-in file.

  ## Args

  `filename`
    A file containing a list of extension identifiers.

  ## Returns

  A list of extensions.

`def find_extension_directories(path: str) ‑> list`

  Return all valid Chrome extension directories from a passed-in path.

  ## Args

  `path`
    The filesystem path to Chrome extensions.

  ## Returns

  A list containing Chrome extension directories.

`def get_crx_path(id: str = '') ‑> str`

  Returns a filesystem path to the system's Chrome Extension directory. An optional extentension ID may be passed in to append to the retuned path.

  ## Args

  `id`
    An optional extension identifier string.

  ## Returns

  A string with the appropriate filesystem path for a(n) extension(s).

`def get_extcalls(results: list) ‑> list`

  Returns a list of unique, valid URIs based on the passed-in list.

  ## Args

  `results`
    A list of "external calls" from a CRXcavator report.

  ## Returns

  A list of items.

`def get_extension_messages_name(name: str, messages: dict) ‑> str`

  Returns the 'name' of a Chrome extension via a messages.json file.

  ## Args

  `name`
    The canonical reference string for a messages.json value.
  `messages`
    A dict representation for a represented messages.json file.

  ## Returns

  A string for the 'name' of a Chrome extension via a messages.json file.

`def get_extension_messages_path(path: str) ‑> str`

  Return the path to an extension's most appropriate messages.json file.

  ## Args

  `path`
    The filesystem path to a specific Chrome extension.

  ## Returns

  A string to the most appropriate messages.json file.

`def get_extension_name(id: str, version: str) ‑> str`

  Returns the 'name' of a Chrome extension by finding the correct source.

  ## Args

  `id`
    An extension identifier string.
  `version`
    The extension version that is used to search file paths.

  ## Returns

  A string for the 'name' of a Chrome extension.

`def get_extensions_table(extensions: list, path: str) ‑> NoneType`

  Prints a table of installed extensions.

  ## Args

  `extensions`
    A list of installed extension meta data.
  `path`
    A string for the path to installed Chrome extensions.

  ## Returns

  None.

`def get_installed_extensions(path: str) ‑> list`

  Returns a list of installed extensions based on a passed-in path.

  ## Args

  `path`
    A string for the path to installed Chrome extensions.

  ## Returns

  A list of extension identifiers that are locally installed for Chrome.

`def get_latest_local_version(extension_dir: str) ‑> str`

  Returns the latest local version for a passed-in extension path.

  ## Args

  `extension_dir`
    A string for the path to a given local extension.

  ## Returns

  A string for the version of the most recent local version available.

`def get_report(id: str) ‑> dict`

  Requests the CRXcavator report (in JSON) for the given extension ID.

  ## Args

  `id`
    An extension identifier string.

  ## Returns

  A dict of report results.

`def get_report_dir() ‑> str`

  Returns a string for the filesystem path of where to store reports.

  ## Args

  None

  ## Returns

  A string for the filesystem path for storing reports.

`def get_report_summary(report: dict) ‑> str`

  Prints a formatted report of information for the given extension.

  ## Args

  `report`
    A dict of a CRXcavator extension report.

  ## Returns

  A string of the report summary.

`def get_reports(extensions: list, export: bool) ‑> NoneType`

  Retrieves a report summary for each passed-in extension ID in a list.

  ## Args

  `extensions`
    A list of extension identifier strings.
  `export`
    A boolean for whether to export each report to a file.

  ## Returns

  None.

`def get_reports_table(extensions: list) ‑> NoneType`

  Builds a table of installed extension details from CRXcavator.

  ## Args

  `extensions`
    A list of extension identifier strings.

  ## Returns

  None.

`def get_risk_graph(id: str) ‑> NoneType`

  Prints a graph of an extension's risk scores over time.

  ## Args

  `id`
    An extension identifier string.

  ## Returns

  None.

`def get_root_dir() ‑> str`

  Returns a string for the filesystem path for a local mrxcavator content.

  ## Args

  None

  ## Returns

  A string for the filesystem path for storing local mrxcavator content.

`def get_virustotal(report: dict, key: str) ‑> list`

  Returns a list of VirusTotal results for the passed-in hostnames.

  ## Args

  `report`
    A dict of a CRXcavator extension report.
  `key`
    The VirusTotal API key as a string.

  ## Returns

  A list of VirusTotal results for passed-in hostnames.

`def get_virustotal_reports(hosts: list, key: str) ‑> dict`

  Returns a dict of VirusTotal results for the passed-in hostnames.

  ## Args

  `hosts`
    A list of hostnames for the "external calls" of an extension.
  `key`
    The VirusTotal API key as a string.

  ## Returns

  A dict of VirusTotal results for passed-in hostnames.

`def get_virustotal_table(results: list) ‑> NoneType`

  Builds a table of VirusTotal results of an extension's "external calls."

  ## Args

  `results`
    A list of VirusTotal results for passed-in hostnames.

  ## Returns

  None.

`def load_config(filename: str) ‑> bool`

  Loads ConfigParser with configuration data from the passed-in filename.

  ## Args

  `filename`
    The mrxcavator configuration filename as a string.

  ## Returns

  A boolean result.

`def main() ‑> NoneType`

  Executes mrxcavator's essential functionality.

  ## Args

  None

  ## Returns

  None

`def save_report(filename: str, content: str) ‑> bool`

  Writes passed-in content to the passed-in filename.

  ## Args

  `filename`
    The chosen filename as a string.
  `content`
    The chosen content to write as a string.

  ## Returns

  A boolean result.

`def select_extension(extensions: list) ‑> str`

  Returns an extension identifier from the passed-in list via PyInquirer.

  ## Args

  `extensions`
    A list of extension identifier strings.

  ## Returns

  A string of an extension identifier.

`def set_crxcavator_key(filename: str, key: str) ‑> bool`

  Configures the CRXcavator API key into the passed-in filename.

  ## Args

  `filename`
    The mrxcavator configuration filename as a string.
  `key`
    The CRXcavator API key as a string.

  ## Returns

  A boolean result.

`def set_crxcavator_uri(filename: str, uri: str) ‑> bool`

  Configures the CRXcavator API URI into the passed-in filename.

  ## Args

  `filename`
    The mrxcavator configuration filename as a string.
  `uri`
    The CRXcavator URI for API calls as a string.

  ## Returns

  A boolean result.

`def set_extension_path(filename: str, path: str) ‑> bool`

  Configures the system's directory path to Chrome extensions.

  ## Args

  `filename`
    The mrxcavator configuration filename as a string.
  `path`
    The system's directory path to Chrome extensions as a string.

  ## Returns

  A boolean result.

`def set_virustotal_key(filename: str, key: str) ‑> bool`

  Configures the VirusTotal API key into the passed-in filename.

  ## Args

  `filename`
    The mrxcavator configuration filename as a string.
  `key`
    The VirusTotal API key as a string.

  ## Returns

  A boolean result.

`def submit_extension(id: str) ‑> bool`

  Submits an extension (by ID) for CRXcavator to process.

  ## Args

  `id`
    An extension identifier string.

  ## Returns

  A boolean result.

`def submit_extensions(extensions: list, path: str) ‑> NoneType`

  Submits many extensions (by ID) for CRXcavator to process.

  ## Args

  `extensions`
    A list of extension identifier strings.
  `path`
    The system's directory path to Chrome extensions as a string.

  ## Returns

  None.

`def submit_virustotal(hosts: list, key: str) ‑> bool`

  Returns a boolean for the state of submitting hostnames to VirusTotal.

  ## Args

  `hosts`
    A list of hostnames for the "external calls" of an extension.
  `key`
    The VirusTotal API key as a string.

  ## Returns

  A boolean.

`def test_crxcavator_key() ‑> bool`

  Performs an API call to CRXcavator to test the configured API key.

  ## Args

  None

  ## Returns

  A boolean result.

`def test_crxcavator_uri() ‑> bool`

  Performs an API call to CRXcavator to test the configured URI.

  ## Args

  None

  ## Returns

  A boolean result.

`def test_virustotal_key() ‑> bool`

  Performs a VirusTotal API call to test the configured API key.

  ## Args

  None

  ## Returns

  A boolean result.

`def version_count(report: dict) ‑> int`

  Returns a count of CRXcavator-tracked versions for an extension.

  ## Args

  `report`
    A dict of a CRXcavator extension report.

  ## Returns

  An integer count of versions.

`def write_config(filename: str) ‑> bool`

  Writes the state of ConfigParser to the passed-in filename.

  ## Args

  `filename`
    The mrxcavator configuration filename as a string.

  ## Returns

  A boolean result.