working cmd pattern (#23)

Author: alanag13

CHANGELOG.md

@@ -8,18 +8,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 The intended audience of this file is for py42 consumers -- as such, changes that don't affect
 how a consumer would use the library (e.g. adding unit tests, updating documentation, etc) are not captured here.
 
+## Unreleased
+
+### Added
+
+- `code42 profile create` command.
+
+### Removed
+
+- `code42 profile set` command. Use `code42 profile create` instead.
+
 ## 0.4.4 - 2020-04-01
 
-###Added
+### Added
 
 - Added message to STDERR when no results are found
 
-###Fixed
+### Fixed
 
 - Add milliseconds to end timestamp, to represent end of day with milliseconds precision.
 
-## Unreleased
-
 ## 0.4.3 - 2020-03-17
 
 ### Added

CONTRIBUTING.md

@@ -19,7 +19,7 @@ $ pre-commit install
 ```
 
 This will set up a pre-commit hook that will automatically format your code to our desired styles whenever you commit.
-It requires python 3.6 to run, so be sure to have a python 3.6 executable of some kind in your PATH when you commit.
+It requires python 3.6+ to run, so be sure to have a qualifying python executable in your PATH when you commit.
 
 ## General
 
@@ -75,3 +75,49 @@ Example:
 ```python
 def test_add_one_and_one_equals_two():
 ```
+
+### Adding a new command
+
+See class documentation on the [Command](src/code42cli/commands.py) class for an explanation of its constructor parameters.
+
+1. If you are creating a new top-level command, create a new instance of `Command` and add it to the list returned
+    by `_load_top_commands()` function in `code42cli.main`.
+
+2. If you are creating a new subcommand, find the top-level command that this will be a subcommand of in
+    `_load_top_commands()` in `code42cli.main` and navigate to the function assigned to be its subcommand loader.
+     Then, add a new instance of `Command` to the list returned by that function.
+
+3. For commands that actually are executed (rather than just being groups), you will add a `handler` function as a constructor parameter.
+   This will be the function that you want to execute when your command is run.
+   * _Positional_ arguments of the handler will automatically become _required_ cli arguments
+   * _Keyword_ arguments of the handler will automatically become _optional_ cli arguments
+   * the cli argument name will be the same as the handler param name except with `_` replaced with `-`, and prefixed with `--` if optional
+
+    For example, consider the following python function:
+
+    ```python
+    def handler_example(one, two, three=None, four=None):
+        pass
+    ```
+
+    When the above function is supplied as a `Command`'s `handler` parameter, the result will be a command that can be executed as follows
+    (assuming `cmd` is the name given to the command):
+
+    ```bash
+    $ code42 cmd oneval twoval --three threeval --four fourval
+    ```
+
+4. To add descriptions to your cli arguments to appear in the help text, your command takes a function as the `arg_customizer` parameter.
+    The entire [`ArgConfigCollection`](src/code42cli/args.py) that was automatically created is supplied as the only argument to this function
+    and can be modified by it. See `code42cli.cmds.profile._load_profile_create_descriptions` for an example of this.
+
+5. If one of your handler's parameters is named `sdk`, you will automatically get a `--profile` argument available in the cli and the `sdk` parameter
+    will automatically contain an instance of `py42.sdk.SDKClient` that was created with the given (or default) profile.
+    - A cli parameter named `--sdk` will _not_ be added in this case.
+
+6. If you have an `sdk` parameter, a parameter named `profile` will automatically contain the info of the profile that was used to create the sdk.
+    - A parameter named `profile` behaves normally if you do not also have a parameter named `sdk`.
+
+7. Each command accepts a `use_single_arg_obj` bool in its constructor. If set to true, this will instead cause the handler to be called with a single object
+    containing all of the args as attributes, which will be passed to a variable named `args` in your handler. Since your handler will only contain the parameter `args`,
+    the names of your cli parameters need to built manually in your `arg_customizer` if you use this option. An example of this can be seen in `code42cli.cmds.securitydata.main`.

README.md

@@ -11,6 +11,7 @@ Additionally, you can choose to only get events that Code42 previously did not o
 - Code42 Server 6.8.x+
 
 ## Installation
+
 Install the `code42` CLI using:
 
 ```bash
@@ -19,39 +20,35 @@ $ python setup.py install
 
 ## Usage
 
-First, set your profile:
+First, create your profile:
 ```bash
-code42 profile set --profile MY_FIRST_PROFILE -s https://example.authority.com -u [email protected]
+code42 profile create MY_FIRST_PROFILE https://example.authority.com [email protected]
 ```
-The `--profile` flag is required the first time and it takes a name.
-On subsequent uses of `set`, not specifying the profile will set the default profile.
 
 Your profile contains the necessary properties for logging into Code42 servers.
-After running `code42 profile set`, the program prompts you about storing a password.
+After running `code42 profile create`, the program prompts you about storing a password.
 If you agree, you are then prompted to input your password.
 
-Your password is not stored in plain-text and is not shown when you do `code42 profile show`.
+Your password is not shown when you do `code42 profile show`.
 However, `code42 profile show` will confirm that a password exists for your profile.
 If you do not set a password, you will be securely prompted to enter a password each time you run a command.
 
-For development purposes, you may need to ignore ssl errors. If you need to do this, do:
-```bash
-code42 profile set --disable-ssl-errors
-```
+For development purposes, you may need to ignore ssl errors. If you need to do this, use the `--disable-ssl-errors` option when creating your profile:
 
-To re-enable SSL errors, do:
 ```bash
-code42 profile set --enable-ssl-errors
+code42 profile create MY_FIRST_PROFILE https://example.authority.com [email protected] --disable-ssl-errors
 ```
 
 You can add multiple profiles with different names and the change the default profile with the `use` command:
+
 ```bash
 code42 profile use MY_SECOND_PROFILE
 ```
-When the `--profile` flag is available on other commands, such as those in `securitydata`,
-it will use that profile instead of the default one.
+
+When the `--profile` flag is available on other commands, such as those in `securitydata`, it will use that profile instead of the default one.
 
 To see all your profiles, do:
+
 ```bash
 code42 profile list
 ```
@@ -62,6 +59,7 @@ Using the CLI, you can query for events and send them to three possible destinat
 * A server, such as SysLog
 
 To print events to stdout, do:
+
 ```bash
 code42 securitydata print -b 2020-02-02
 ```
@@ -72,67 +70,74 @@ To specify a time, do:
 ```bash
 code42 securitydata print -b 2020-02-02 12:51
 ```
+
 Begin date will be ignored if provided on subsequent queries using `-i`.
 
 Use different format with `-f`:
+
 ```bash
 code42 securitydata print -b 2020-02-02 -f CEF
 ```
+
 The available formats are CEF, JSON, and RAW-JSON.
 
 To write events to a file, do:
+
 ```bash
 code42 securitydata write-to filename.txt -b 2020-02-02
 ```
 
 To send events to a server, do:
+
 ```bash
 code42 securitydata send-to syslog.company.com -p TCP -b 2020-02-02
 ```
 
 To only get events that Code42 previously did not observe since you last recorded a checkpoint, use the `-i` flag.
+
 ```bash
 code42 securitydata send-to syslog.company.com -i
 ```
+
 This is only guaranteed if you did not change your query.
 
 To send events to a server using a specific profile, do:
+
 ```bash
 code42 securitydata send-to --profile PROFILE_FOR_RECURRING_JOB syslog.company.com -b 2020-02-02 -f CEF -i
 ```
 
 You can also use wildcard for queries, but note, if they are not in quotes, you may get unexpected behavior.
+
 ```bash
 code42 securitydata print --actor "*"
 ```
 
-
 Each destination-type subcommand shares query parameters
-* `-t` (exposure types)
-* `-b` (begin date)
-* `-e` (end date)
-* `--c42username`
-* `--actor`
-* `--md5`
-* `--sha256`
-* `--source`
-* `--filename`
-* `--filepath`
-* `--processOwner`
-* `--tabURL`
-* `--include-non-exposure` (does not work with `-t`)
-* `--advanced-query` (raw JSON query)
+
+- `-t` (exposure types)
+- `-b` (begin date)
+- `-e` (end date)
+- `--c42username`
+- `--actor`
+- `--md5`
+- `--sha256`
+- `--source`
+- `--filename`
+- `--filepath`
+- `--processOwner`
+- `--tabURL`
+- `--include-non-exposure` (does not work with `-t`)
+- `--advanced-query` (raw JSON query)
 
 You cannot use other query parameters if you use `--advanced-query`.
 To learn more about acceptable arguments, add the `-h` flag to `code42` or any of the destination-type subcommands.
 
-
-# Known Issues
+## Known Issues
 
 Only the first 10,000 of each set of events containing the exact same insertion timestamp is reported.
 
-
-# Troubleshooting
+## Troubleshooting
 
 If you keep getting prompted for your password, try resetting with `code42 profile reset-pw`.
 If that doesn't work, delete your credentials file located at ~/.code42cli or the entry in keychain.

setup.py

@@ -1,6 +1,6 @@
+from codecs import open
 from os import path
 from setuptools import find_packages, setup
-from codecs import open
 
 here = path.abspath(path.dirname(__file__))
 
@@ -20,7 +20,12 @@
     packages=find_packages("src"),
     package_dir={"": "src"},
     python_requires=">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, <4",
-    install_requires=["c42eventextractor==0.2.2", "keyring==18.0.1","py42==0.6.0"],
+    install_requires=[
+        "c42eventextractor==0.2.2",
+        "keyring==18.0.1",
+        "keyrings.alt==3.2.0",
+        "py42==0.6.0",
+    ],
     license="MIT",
     include_package_data=True,
     zip_safe=False,

src/code42cli/args.py

@@ -0,0 +1,107 @@
+import inspect
+
+PROFILE_HELP = u"The name of the Code42 profile use when executing this command."
+
+
+class ArgConfig(object):
+    """Stores a set of argparse commands for later use by a command."""
+
+    def __init__(self, *args, **kwargs):
+        self._settings = {}
+        self._settings[u"action"] = kwargs.get(u"action")
+        self._settings[u"choices"] = kwargs.get(u"choices")
+        self._settings[u"default"] = kwargs.get(u"default")
+        self._settings[u"help"] = kwargs.get(u"help")
+        self._settings[u"options_list"] = list(args)
+        self._settings[u"nargs"] = kwargs.get(u"nargs")
+
+    @property
+    def settings(self):
+        return self._settings
+
+    def set_choices(self, choices):
+        self._settings[u"choices"] = choices
+
+    def set_help(self, help):
+        self._settings[u"help"] = help
+
+    def add_short_option_name(self, short_name):
+        self._settings[u"options_list"].append(short_name)
+
+
+class ArgConfigCollection(object):
+    def __init__(self):
+        self._arg_configs = {}
+
+    @property
+    def arg_configs(self):
+        return self._arg_configs
+
+    def append(self, name, arg_config):
+        self._arg_configs[name] = arg_config
+
+    def extend(self, arg_config_dict):
+        self.arg_configs.update(arg_config_dict)
+
+
+def get_auto_arg_configs(handler):
+    """Looks at the parameter names of `handler` and builds an `ArgConfigCollection` containing argparse
+    parameters based on them."""
+    arg_configs = ArgConfigCollection()
+    if callable(handler):
+        # get the number of positional and keyword args
+        argspec = inspect.getargspec(handler)
+        num_args = len(argspec.args)
+        num_kw_args = len(argspec.defaults) if argspec.defaults else 0
+
+        for arg_position, key in enumerate(argspec.args):
+            # do not create cli parameters for arguments named "sdk", "args", or "kwargs"
+            if not key in [u"sdk", u"args", u"kwargs"]:
+                arg_config = _create_auto_args_config(
+                    arg_position, key, argspec, num_args, num_kw_args
+                )
+                _set_smart_defaults(arg_config)
+                arg_configs.append(key, arg_config)
+
+        if u"sdk" in argspec.args:
+            _build_sdk_arg_configs(arg_configs)
+
+    return arg_configs
+
+
+def _create_auto_args_config(arg_position, key, argspec, num_args, num_kw_args):
+    default = None
+    param_name = key.replace(u"_", u"-")
+    difference = num_args - num_kw_args
+    last_positional_arg_idx = difference - 1
+    # postional arguments will come first, so if the arg position
+    # is greater than the index of the last positional arg, it's a kwarg.
+    if arg_position > last_positional_arg_idx:
+        # this is a keyword arg, treat it as an optional cli arg.
+        default_value = argspec.defaults[arg_position - difference]
+        option_names = [u"--{}".format(param_name)]
+        default = default_value
+    else:
+        # this is a positional arg, treat it as a required cli arg.
+        option_names = [param_name]
+    return ArgConfig(*option_names, default=default)
+
+
+def _set_smart_defaults(arg_config):
+    default = arg_config.settings.get(u"default")
+    # make a parameter allow lists as input if its default value is a list,
+    # e.g. --my-param one two three four
+    nargs = u"+" if type(default) == list else None
+    arg_config.settings[u"nargs"] = nargs
+    # make the param not require a value (e.g. --enable) if the default value of
+    # the param is a bool.
+    if type(default) == bool:
+        arg_config.settings[u"action"] = u"store_{}".format(default).lower()
+
+
+def _build_sdk_arg_configs(arg_config_collection):
+    """Add extra cli parameters that will always be relevant when a handler needs the sdk."""
+    profile = ArgConfig(u"--profile", help=PROFILE_HELP)
+    debug = ArgConfig(u"-d", u"--debug", action=u"store_true", help=u"Turn on Debug logging.")
+    extras = {u"profile": profile, u"debug": debug}
+    arg_config_collection.extend(extras)