Chore/docs (#84)

Author: Juliya Smith

CHANGELOG.md

@@ -60,6 +60,8 @@ how a consumer would use the library (e.g. adding unit tests, updating documenta
 
 - A progress bar that displays during bulk commands.
 
+- Short option `-u` added for `code42 high-risk-employee add-risk-tags` and `remove-risk-tags`.
+
 ### Fixed
 
 - Fixed bug in bulk commands where value-less fields in csv files were treated as empty strings instead of None.

CONTRIBUTING.md

@@ -122,3 +122,25 @@ See class documentation on the [Command](src/code42cli/commands.py) class for an
 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`.
+
+
+## Documentation
+
+`code42cli` uses [Sphinx](http://www.sphinx-doc.org/) to generate documentation.
+
+To build the documentation, run the following from the `docs` directory:
+
+```bash
+make html
+```
+
+To view the resulting documentation, open `docs/_build/html/index.html`.
+
+For the best viewing experience, run a local server to view the documentation.
+You can this by running the below from the `docs` directory using python 3:
+
+```bash
+python -m http.server --directory "_build/html" 1337
+```
+
+and then pointing your browser to `localhost:1337`.

README.md

@@ -25,21 +25,21 @@ $ python setup.py install
 
 First, create your profile:
 ```bash
-code42 profile create MY_FIRST_PROFILE https://example.authority.com security.admin@example.com
+code42 profile create --name MY_FIRST_PROFILE --server example.authority.com --username security.admin@example.com
 ```
 
-Your profile contains the necessary properties for logging into Code42 servers.
-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 profile contains the necessary properties for logging into Code42 servers. 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 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.
+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, use the `--disable-ssl-errors` option when creating your profile:
+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:
 
 ```bash
-code42 profile create MY_FIRST_PROFILE https://example.authority.com security.admin@example.com --disable-ssl-errors
+code42 profile create -n MY_FIRST_PROFILE -s https://example.authority.com -u security.admin@example.com --disable-ssl-errors
 ```
 
 You can add multiple profiles with different names and the change the default profile with the `use` command:
@@ -48,7 +48,12 @@ You can add multiple profiles with different names and the change the default pr
 code42 profile use MY_SECOND_PROFILE
 ```
 
-When the `--profile` flag is available on other commands, such as those in `security-data`, it will use that profile instead of the default one.
+When the `--profile` flag is available on other commands, such as those in `security-data`, it will use that profile 
+instead of the default one. For example,
+
+```bash
+code42 security-data print -b 2020-02-02 --profile MY_SECOND_PROFILE
+```
 
 To see all your profiles, do:
 
@@ -64,7 +69,8 @@ Using the CLI, you can query for security events and alerts and send them to thr
 * A file
 * A server, such as SysLog
 
-The following examples pertain to security events, but can also be used for alerts by replacing `security-data` with `alerts`:
+The following examples pertain to security events, but can also be used for alerts by replacing `security-data` with 
+`alerts`:
 
 To print events to stdout, do:
 

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/custom.css

@@ -0,0 +1,3 @@
+.wy-side-nav-search>div.version {
+    color: #404040;
+}

docs/commands.md

@@ -0,0 +1,8 @@
+# Commands
+
+* [Profile](commands/profile.md)
+* [Security Data](commands/securitydata.md)
+* [Alerts](commands/alerts.md)
+* [Alert Rules](commands/alertrules.md)
+* [Departing Employee](commands/departingemployee.md)
+* [High Risk Employee](commands/highriskemployee.md)

docs/commands/alertrules.md

@@ -0,0 +1,84 @@
+# Alert Rules
+
+## add-user
+
+Add a user to a given alert rule.
+
+Arguments:
+* `--rule-id`: Observer ID of the rule to be updated.
+* `--username`, `-u` The username of the user to add to the alert rule.
+
+Usage:
+```bash
+code42 alert-rules add-user --rule-id <rule-id> --username <username>
+```
+
+##  remove-user
+
+Remove a user to a given alert rule.
+
+Arguments:
+* `--rule-id`: Observer ID of the rule to be updated.
+* `--username`, `-u`: The username of the user to remove from the alert rule.
+
+Usage:
+```bash
+code42 alert-rules remove-user --rule-id <rule-id> --username <username>
+```
+
+## list
+
+Fetch existing alert rules.
+
+Usage:
+```bash
+code42 alert-rules list
+```
+
+## show
+
+Print out detailed alert rule criteria.
+
+Arguments:
+* `rule-id`: Observer ID of the rule.
+
+Usage:
+```bash
+code42 alert-rules show <rule-id>
+```
+
+## bulk generate-template
+
+Generate the necessary csv template for bulk actions.
+
+Arguments:
+* `cmd`: The type of command the template will be used for. Available choices= [add, remove].
+
+Usage:
+```bash
+code42 alert-rules bulk generate-template <cmd>
+```
+
+## bulk add
+
+Add users to alert rules. CSV file format: `rule_id,username`.
+
+Arguments:
+* `file-name`: The path to the csv file with columns 'rule_id,username' for bulk adding users to the alert rule.
+
+Usage:
+```bash
+code42 alert-rules bulk add <filename>
+```
+
+## bulk remove
+
+Remove users from alert rules. CSV file format: `rule_id,username`.
+
+Arguments:
+* `file-name`: The path to the csv file with columns 'rule_id,username' for bulk removing users to the alert rule.
+
+Usage:
+```bash
+code42 alert-rules bulk remove <filename>
+```

docs/commands/alerts.md

@@ -0,0 +1,81 @@
+# Alerts
+
+## Shared arguments
+
+Search args are shared between `print`, `write-to`, and `send-to` commands.
+
+* `advanced-query`: A raw JSON alerts query. Useful for when the provided query parameters do not satisfy your 
+    requirements. WARNING: Using advanced queries is incompatible with other query-building args.
+* `-b`, `--begin`: The beginning of the date range in which to look for alerts, can be a date/time in yyyy-MM-dd (UTC) 
+    or yyyy-MM-dd HH:MM:SS (UTC+24-hr time) format where the 'time' portion of the string can be partial 
+    (e.g. '2020-01-01 12' or '2020-01-01 01:15') or a short value representing days (30d), hours (24h) or minutes (15m) 
+    from current time.
+* `-e`, `--end`: The end of the date range in which to look for alerts, argument format options are the same as --begin.
+* `--severity`: Filter alerts by severity. Defaults to returning all severities. 
+    Available choices=['HIGH', 'MEDIUM', 'LOW']
+* `--state`: Filter alerts by state. Defaults to returning all states. Available choices=['OPEN', 'RESOLVED'].
+* `--actor`: Filter alerts by including the given actor(s) who triggered the alert. Args must match actor username 
+    exactly.
+* `--actor-contains`: Filter alerts by including actor(s) whose username contains the given string.
+* `--exclude-actor`: Filter alerts by excluding the given actor(s) who triggered the alert. Args must match actor 
+    username exactly.
+* `--exclude-actor-contains`: Filter alerts by excluding actor(s) whose username contains the given string.
+* `--rule-name`: Filter alerts by including the given rule name(s).
+* `--exclude-rule-name`: Filter alerts by excluding the given rule name(s).
+* `--rule-id`: Filter alerts by including the given rule id(s).
+* `--exclude-rule-id`: Filter alerts by excluding the given rule id(s).
+* `--rule-type`: Filter alerts by including the given rule type(s). 
+    Available choices=['FedEndpointExfiltration', 'FedCloudSharePermissions', 'FedFileTypeMismatch'].
+* `--exclude-rule-type`: Filter alerts by excluding the given rule type(s). 
+    Available choices=['FedEndpointExfiltration', 'FedCloudSharePermissions', 'FedFileTypeMismatch'].
+* `--description`: Filter alerts by description. Does fuzzy search by default.
+* `-f`, `--format` (optional): The format used for outputting file events. Available choices= [CEF,JSON,RAW-JSON]. 
+* `-i`, `--incremental` (optional): Only get file events that were not previously retrieved.
+
+## print
+
+Print file events to stdout.
+
+Arguments:
+* search args (note that begin date is often required).
+
+Usage:
+```bash
+code42 alerts print -b <begin-date> <args>
+```
+
+## write-to
+
+Write file events to the file with the given name.
+
+Arguments:
+* `output_file`: The name of the local file to send output to.
+* search args (note that begin date is often required).
+
+Usage:
+```bash
+code42 alerts write-to -b 2020-03-01 <rgs>
+```
+
+## send-to
+
+Send file events to the given server address.
+
+Arguments:
+* `server`: The server address to send output to.
+* `protocol` (optional): Protocol used to send logs to server. Available choices= [TCP, UDP].
+* search args (note that begin date is often required).
+
+Usage:
+```bash
+code42 alerts send-to <server> <optional-args> <args>
+```
+
+## clear-checkpoint
+
+Remove the saved file event checkpoint from 'incremental' (-i) mode.
+
+Usage:
+```bash
+code42 alerts clear-checkpoint
+```

docs/commands/departingemployee.md

@@ -0,0 +1,65 @@
+# Departing Employee
+
+## add
+
+Add a user to the departing-employee detection list.
+
+Arguments:
+* `username`: A Code42 username for an employee.
+* `--cloud-alias` (optional): An alternative email address for another cloud service.
+* `--departure-date` (optional): The date the employee is departing in format yyyy-MM-dd.
+* `--notes` (optional): Notes about the employee.
+
+Usage:
+```bash
+code42 departing-employee add <username> <optional-args>
+```
+
+## remove
+
+Remove a user from the departing-employee detection list.
+
+Arguments:
+* `username`: A Code42 username for an employee.
+
+Usage:
+```bash
+code42 departing-employee remove <username>
+```
+
+## bulk generate-template
+
+Generate the necessary csv template for bulk actions.
+
+Arguments:
+* `cmd`: The type of command the template will be used for. Available choices= [add, remove].
+
+Usage:
+```bash
+code42 departing-employee bulk generate-template <cmd>
+```
+
+## bulk add
+
+Bulk add users to the departing-employee detection list using a csv file.
+
+Arguments:
+* `filename`: The path to the csv file for bulk adding users to the departing-employee detection list.
+
+Usage:
+```bash
+code42 departing-employee bulk add <filename>
+```
+
+## bulk remove
+
+Bulk remove users from the departing-employee detection list using a file.
+
+Arguments:
+* `users-file`: A file containing a line-separated list of users to remove form the departing-employee detection
+    list.
+
+Usage:
+```bash
+code42 departing-employee bulk remove <users-file>
+```