Minor documentation + logging improvements

Author: brahmlower

CssefClient/cssef-cli

@@ -1,4 +1,5 @@
 #!/usr/bin/python
+import logging
 import sys
 from getpass import getpass
 from prettytable import PrettyTable
@@ -21,6 +22,7 @@ class Menu(object):
                     endpoint['rpc_name'],
                     endpoint['args'])
                 self.menu_dict[endpoint['menu_path']] = command_inst
+        logging.info("%d endpoints loaded" % len(self.menu_dict.keys()))
 
 
     def get_command(self, command_list):
@@ -40,7 +42,8 @@ class Menu(object):
         try:
             return self.menu_dict[menu_path]
         except KeyError:
-            print menu_path
+            #print menu_path
+            logging.error(menu_path)
             raise NonExistantCommand
 
 class ParseInput(object):
@@ -97,7 +100,8 @@ class ParseInput(object):
                     value = self.remaining_args[index + 1]
                 except IndexError:
                     # There is no next error. Complain and quit
-                    sys.exit("Expected value in for argument, but got none.")
+                    logging.error("Expected value in for argument, but got none.")
+                    sys.exit(1)
                 index += 1
             self.command_args[keyword] = value
             index += 1
@@ -115,12 +119,12 @@ def build_auth_dict(config):
         return tmp_dict
     # Add the username to the auth Dict
     if not config.username:
-        print "No username was provided."
+        logging.warning("No username was provided.")
         return None
     tmp_dict["username"] = config.username
     # Add the organization to the auth Dict
     if not config.organization:
-        print "No organization was provided."
+        logging.warning("No organization was provided.")
         return None
     tmp_dict["organization"] = config.organization
     # If a password is provided, we want to use that instead of the token
@@ -134,34 +138,30 @@ def build_auth_dict(config):
             tmp_dict["password"] = getpass()
         else:
             # Both values failed
-            print "Neither password nor token were provided."
+            logging.warning("Neither password nor token were provided.")
             return None
     return tmp_dict
 
 def print_output(output):
     if output.value != 0:
-        sys.stderr.write("The server is reporting the following error:\n")
-        sys.stderr.write("\n".join(output.message)+"\n")
+        logging.error("The server is reporting the following error:\n%s" % "\n".join(output.message))
     if output.table_headers:
         # Its a dictionary list, make a table and print it
         output_table = PrettyTable(output.table_headers)
         output_table.padding_width = 1
         for i in output.content:
             output_table.add_row(i.values())
-        print output_table
+        logging.info(output_table)
     else:
         # It's just a list of strings, print each one
         # TODO: Maybe I just shouldn't support this...
         for i in output.content:
-            print i
-
-if __name__ == "__main__":
-    # # Ensure user data directory exists
-    # if not os.path.exists(self.userDataDir):
-    #     os.makedirs(self.userDataDir)
+            logging.info(i)
 
+def main(cli_args):
+    logging.basicConfig(format='[%(levelname)s] %(message)s')
     # Set up and configure the client
-    user_input = ParseInput(sys.argv[1:])
+    user_input = ParseInput(cli_args)
     client = cssefclient.CssefClient()
     client.config.load_config_file(client.config.global_config_path)
     client.config.load_config_file(client.config.config_path)
@@ -185,9 +185,12 @@ if __name__ == "__main__":
 
     # Make sure our provided input matches what we were told to send to the client
     if not command.validate_input(user_input.command_args):
-        print "Invalid arguments"
+        logging.error("Invalid arguments")
         sys.exit()
 
     output_obj = client.call_endpoint(command, user_input.command_args)
     print_output(output_obj)
     sys.exit(output_obj.value)
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

CssefClient/cssefclient/__init__.py

@@ -4,6 +4,7 @@
 import sys
 import time
 import yaml
+import logging
 from jsonrpcclient.http_server import HTTPServer
 from cssefclient.tasks import RenewToken
 from cssefclient.tasks import AvailableEndpoints
@@ -37,8 +38,6 @@ def load_token(self, auth):
         token = load_token_file(self.config.token_file)
         if token:
             self.config.token = token
-        else:
-            print "[ERROR] Failed to load token"
         # Renew the token if it's enabled
         if self.config.token_renewal_enabled:
             return RenewToken(self.config).execute(auth=auth)
@@ -117,7 +116,7 @@ def load_config_file(self, config_path):
         try:
             config_dict = yaml.load(open(config_path, 'r'))
         except IOError:
-            print "[WARNING] Failed to load config file at '%s'." % config_path
+            logging.warning("Failed to load config file at '%s'." % config_path)
             return None
         if config_dict:
             self.load_config_dict(config_dict)
@@ -142,7 +141,7 @@ class will be ignored (this will be logged).
         if "verbose" in config_dict:
             setattr(self, "verbose", bool(config_dict.pop("verbose")))
             if self.verbose:
-                print "[LOGGING] Configuration 'verbose' set to 'True'."
+                logging.info("Configuration 'verbose' set to 'True'.")
         for i in config_dict:
             if hasattr(self, i.replace('-', '_')):
                 # Set the attribute
@@ -155,14 +154,14 @@ class will be ignored (this will be logged).
                     value = value.lower() == 'true'
                 setattr(self, setting, value)
                 if self.verbose:
-                    print "[LOGGING] Configuration '%s' set to '%s'." % (i, value)
+                    logging.info("Configuration '%s' set to '%s'." % (i, value))
             elif isinstance(config_dict[i], dict):
                 # This is a dictionary and may contain additional values
                 self.load_config_dict(config_dict[i])
             else:
                 # We don't care about it. Just skip it!
                 # if self.verbose:
-                print "[WARNING] Ignoring invalid setting '%s'." % i
+                logging.warning("Ignoring invalid setting '%s'." % i)
 
 class EndpointsLoader(object):
     def __init__(self, config):
@@ -181,8 +180,9 @@ def load(self):
             output = self.load_from_server()
             if not output:
                 # Raise an error since we failed to load the endpoints
-                print output.value
-                print output.message
+                logging.error("Value: %d, Message: %s" % (output.value, output.message))
+                #print output.value
+                #print output.message
                 raise Exception
             self.endpoints = output.content
             self.update_cache()
@@ -206,7 +206,7 @@ def determine_source(self):
             cache_last_mod_time = os.stat(self.config.endpoint_cache_file).st_mtime
         except OSError:
             # Failed to read from the file, load from server
-            print "Failed to read cache file: %s" % self.config.endpoint_cache_file
+            logging.warning("Failed to read cache file: %s" % self.config.endpoint_cache_file)
             # TODO: Libraries shouldn't print! (I thought this was a library,
             # not a printing press! :P)
             self.from_cache = False

CssefClient/cssefclient/tasks.py

@@ -1,3 +1,4 @@
+import logging
 from cssefclient.utils import RPCEndpoint
 from cssefclient.utils import save_token_file
 
@@ -30,7 +31,6 @@ def __init__(self, config):
         self.rpc_name = 'renewtoken'
 
     def execute(self, **kwargs):
-        print kwargs
         # # Populate the arguments to pass to the login
         # # Here we only need the username and the token
         # if not kwargs.get('username'):
@@ -57,9 +57,9 @@ def execute(self, **kwargs):
         if not self.config.token_auth_enabled:
             # Bail if token authentication is disabled
             if self.config.verbose:
-                print "[ERROR] Logging in requires that token authentication be \
+                logging.error("[ERROR] Logging in requires that token authentication be \
                     enabled. Set 'token_auth_enabled: True' in your \
-                    configuration."
+                    configuration.")
             return None
         # Attempt to log in
         return_dict = super(Login, self).execute(**kwargs.get('auth'))

CssefClient/cssefclient/utils.py

@@ -3,6 +3,7 @@
 import sys
 import stat
 import time
+import logging
 from datetime import datetime
 
 class CommandOutput(object):
@@ -75,11 +76,11 @@ def execute(self, **kwargs):
             created with values describing the encountered exception.
         """
         if self.config.verbose:
-            print "[LOGGING] Calling rpc with name '%s'."  % self.rpc_name
+            logging.info("Calling rpc with name '%s'."  % self.rpc_name)
         # "Serialize" datetime objects
         for i in kwargs:
             if isinstance(kwargs[i], datetime):
-                print "Found datetime object"
+                logging.debug("Found datetime object")
                 # Overwrite the datetime object to a unix timestamp representing the same time
                 kwargs[i] = time.mktime(kwargs[i].timetuple())
         # Try the api call
@@ -105,17 +106,15 @@ def load_token_file(token_file):
     """
     # Make sure the file exists
     if not os.path.isfile(token_file):
-        sys.stderr.write("[WARNING] Token file not found. Cannot use token authentication.\n")
-        sys.stderr.flush()
+        logging.warning("Token file not found. Cannot use token authentication.")
         return False
     # Now make sure that only we have access to it
     file_permissions = os.stat(token_file).st_mode
     permissions_denied = [stat.S_IRGRP, stat.S_IWGRP, stat.S_IXGRP,
                           stat.S_IROTH, stat.S_IWOTH, stat.S_IXOTH]
     for i in permissions_denied:
         if bool(file_permissions & i):
-            sys.stderr.write("Token file may not have any permissions for group or other.\n")
-            sys.stderr.flush()
+            logging.warning("Token file may not have any permissions for group or other.")
             return False
     # Now actually read in the file
     token = open(token_file, 'r').read()

CssefServer/cssefserver/tasks.py

@@ -8,17 +8,25 @@
 from cssefserver.taskutils import client_failed_login_output
 
 class AvailableEndpoints(CssefRPCEndpoint):
+    """RPC task to get all available RPC endpoints.
+
+    Attributes:
+        name (str): Human readable name of the endpoint. "Available Endpoints"
+        rpc_name (str): Name of the endpoint as registered with the HTTP api. "availableendpoints"
+        menu_path (none): Blank because this is not something a user will manually call
+        require_auth (bool): Authentication is not required to call this endpoint
+    """
+
     name = "Available Endpoints"
     rpc_name = "availableendpoints"
     menu_path = None
     require_auth = False
     def on_request(self):
-        """Celery task to get all available celery endpoints.
+        """Returns a response containing the RPC endpoints
 
         Returns:
-            A return_dict dictionary containing the results of the API call. The
-            content is a list of dictionaries containing information about the
-            available endpoints.
+            (dict): A return_dict where 'content' is a list of dictionaries containing
+            the available endpoints and relevant information about those endpoints.
         """
 
         # Stuff in here is not being copied properly, which is resulting in

docs/source/about.rst

@@ -0,0 +1,99 @@
+About
+=====
+
+.. attention::
+	The project is still undergoing heavy development. The state of the project
+	may change at any time - please be aware that some information here may be
+	out of date.
+
+The Cyber Security Scoring Engine Framework (CSSEF) is meant to be an easy to
+use framework for hosting various types of security competitions. By making
+competition scoring and management easier, the hope is that more time and
+energy may be spent setting up the competition environment itself. Many of the
+features and requirements were determined by the competitions hosted inhouse
+by the University of Alaska's Cyber Security Club, which attended the National
+Cyber Collegdet Defense Competition several years in a row. While initial
+development focused on providing utilities for CCDC-like competitions, the
+project evolved to facilitate other types of competitions, so it may be of use
+to other organizations, regardless of type of competition being conducted.
+
+Features
+--------
+Features include but are certainly not limited to the following. Please see
+the respective section of documentation for more inforation on any particular
+feature.
+
+- Multiple organizations
+- Easy to use command line interface
+- Modern(ish) web client
+- Plugin interface for multiple types of competitions
+- A prebuilt plugin for CCDC-like competitions (see the plugins section)
+
+How It Works
+------------
+
+.. attention::
+	At this time, the CTF plugin does not exist, so these particular endpoinds
+	do not exist. This scenario also assumes the server has been configured
+	and the users have all made appropriet changes to their local configurations.
+
+Lets say you want to host a capture the flag competition on your campus. You
+would install the plugin package for the CTF competition on the host running
+the CSSEF server. Then enable the plugin for the server, and configure a new
+competition for your organization.
+
+::
+	pip install -y cssef-ctf
+	echo "- cssefctf.CaptureTheFlag" >> /etc/cssef/cssefd.yml
+	cssefd restart
+	cssef-cli ctf add --name "My CTF"
+	cssef-cli ctf flag add --ctf "My CTF" --name "First Flag" --hint "This is a hint" --value "abc123"
+
+Assuming that was all you wanted in your competition, begin the competition,
+thus allowing the competitiors to submit guesses.
+
+::
+	cssef-cli ctf start --ctf "My CTF"
+
+::
+	cssef-cli ctf guess --ctf "My CTF" --flag "First Flag" --value "guess?"
+	cssef-cli ctf guess --ctf "My CTF" --flag "First Flag" --value "another try"
+
+If the competition plugin you are using supports web interface displays,
+you can manage the competition through a CSSEF web server. The web server runs
+as a separate service, and requires additional setup not covered here.
+
+Framework Components
+--------------------
+
+Server
+~~~~~~
+The server allows for management of "plugins", which provide resources for
+running competitions. These plugins consume the various endpoints and features
+provided by the framework in such a way that no two competitions collide with
+each other. This means you can host several capture the flag and a CCDC-like
+competitions on the same service. The server communicates with clients via HTTP
+RPC calls, and uses sqlalchemy for databasing. For additional information, see
+the `server documentation`_.
+
+.. _server documentation: server.rst
+
+Client
+~~~~~~
+The client package provides endpoints for client applications, as well as a
+basic command line tool. If you plan to install the web client, this package
+is a required depenancy. See the `client documentation`_ for more information,
+or the `command line`_ documentation for cli reference.
+
+.. _client documentation: client.rst
+.. _command line: cli.rst
+
+Web Client
+~~~~~~~~~~
+The web client is meant to be an easy and painless tool for interacting with
+the server, as well as the various features provided by competition plugins-
+especially when competitors may be submitting data during competition
+environments that don't actually have the cssef client available. The web
+client is currently using django, which itself simply consumes endpoints
+within the cssef client. For more information about the web client, see the
+cssef webui documentation.

docs/source/index.rst

@@ -10,7 +10,7 @@ Welcome to Cssef's documentation!
    :maxdepth: 2
    :caption: Overview
 
-   introduction
+   about
    getting-started
 
 .. toctree::