Skip to content

Module Development Guide

rhino-xander edited this page Jun 26, 2018 · 2 revisions

Module Development

The file at modules/template.py can be used as a starting point for all new modules. It has examples, comments, and different options that you can use while developing a module for Pacu. This documentation aims to provide more information about the different functions available to you as a developer, and to overall to make your life easier when writing a new module for Pacu.

Table of Contents

  1. core/mixins.py

    • ModelUpdateMixin

      • update(self, database, commit=True, **kwargs)

        • Directly updates data to the database.
  2. core/models.py

    • PacuSession

      • get_active_aws_key(self, database)

        • Return the active AWS key for the current session.
  3. pacu.py

    • util

      • print(message, database)

        • Print data to the console and/or the output log (overrides print()).
      • input(message, database)

        • Accept input in the console and write it to the console and/or output log (overrides input()).
      • get_regions(service, database)

        • Given an AWS service, return valid regions for that service.
      • fetch_data(data, module, args, database, force=False)

        • Returns session data if available at runtime, or fetches it with the supplied module and arguments.
      • key_info(database)

        • Returns a variety of information about the active set of AWS keys.
      • install_dependencies(external_dependencies, database)

        • Install external module dependencies from GitHub or directly download files.
      • get_active_session(database)

        • Fetch the database session for the active set of AWS keys.
      • get_aws_key_by_alias(alias, database)

        • Given the key alias, fetch a variety of information about an AWS key pair stored in the current session.

Functions

  1. File: core/mixins.py

    • Class: ModelUpdateMixin

      • Method: update(self, database, commit=True, **kwargs)

        This method accepts the following arguments:

          * self: This does not need to be passed into this function as it is done automatically.
        
          * database (): A reference to the active database connection containing the PacuSession.
        
          * commit (boolean): Push the supplied changes to the database.
        
          * \*\*kwargs (arguments): An arbitrary number of fields to update in the database, supplied in the form of a normal argument (comma-separated key=value pairs).
        

        This method does this.

  2. File core/models.py

    • Class: PacuSession

      • Method: get_active_aws_key(self, database)

        This method accepts the following arguments:

          * self: This does not need to be passed into this function as it is done automatically.
        
          * database (): A reference to the active database connection containing the PacuSession.
        

        This method does this.

  3. File: pacu.py

    • Class: util

      • Method: print(message, database)

        This method accepts the following arguments:

          * message (\*): The message to print to the screen and/or write to the Pacu session log.
        
          * database (): A reference to the active database connection containing the PacuSession.
        

        This method overrides the native Python 3 print() method. It will print the given message to the screen, as well as write it to the Pacu session log.

      • Method: input(message, database)

        This method accepts the following arguments:

          * message (\*): The message to prompt the user with on the screen and/or write to the Pacu session log.
        
          * database (): A reference to the active database connection containing the PacuSession.
        

        This method overrides the native Python 3 input() method. It will prompt the user with the supplied message, while optionally logging the question and response to the Pacu session log.

      • Method: get_regions(service, database)

        This method accepts the following arguments:

          * service (str): The name of an existing AWS service.
        
          * database (): A reference to the active database connection containing the PacuSession.
        

        This method returns a list of valid regions for the supplied AWS service. If the user has set session regions, then this method will return regions that are both valid for the supplied AWS service and in the session region list.

      • Method: fetch_data(data, module, args, database, force=False)

        This method accepts the following arguments:

          * data (list of str): A list with the AWS service that required data belongs to and the name of that data.
        
          * module (str): The name of the Pacu module that can fetch that data if need be.
        
          * args (str): An argument string with the arguments to pass to the module to fetch the required data, as if it was being run from the Pacu command line.
        
          * database (): A reference to the active database connection containing the PacuSession.
        
          * force (boolean): Whether or not to prompt the user before and after the data is fetched (either from the database or by running the supplied module).
        
      • Method: key_info(database)

        This method accepts the following arguments:

          * database (): A reference to the active database connection containing the PacuSession.
        

        This method returns all relevant information for the currently active set of AWS keys, include data like the AWS keys, their user name, their user ID, their user ARN, permissions associated with them, their alias, and whether or not their permissions have been confirmed.

      • Method: install_dependencies(external_dependencies, database)

        This method accepts the following arguments:

          * external_dependencies (list): A list of URLs pointing to a GitHub repo (ending in .git) or a direct download link for a file required for the module using this.
        
          * database (): A reference to the active database connection containing the PacuSession.
        

        This method installs dependencies required for Pacu modules that are not a part of Pacu to the dependencies folder.

      • Method: get_active_session(database)

      • Method: get_aws_key_by_alias(alias, database)

        This method accepts the following arguments:

          * alias (str): The alias of a set of AWS keys already in the database.
        
          * database (): A reference to the active database connection containing the PacuSession.