Merge pull request #21 from jamf/develop

JAWA - Version 3.0.0

.gitignore

@@ -10,3 +10,140 @@ security/*
 
 # ignore mac .DS_Store
 .DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# OS generated files #
+######################
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes

README.md

@@ -1,65 +1,111 @@
-# Jamf Automation and Webhook Assistant ("JAWA") Version 2.0
-The JAWA allows an IT Administrator to focus on providing the best end user experience through automation.
+# Jamf Automation and Webhook Assistant ("JAWA") Version 3.0.0
 
-*[!] NOTE: Always test automations in a dev/eval environment before deploying to production.*
+JAWA allows an IT Administrator to focus on providing the best end user experience through automation.
+
+***[!]** NOTE: Always test automations in a dev/eval environment before deploying to production.*
 
 ## What is it?
 
-The Jamf Automation and Webhook Assistant, "JAWA", is a web server for hosting automation tools that interact with Jamf Pro, such as a webhook reciever, cron/timed exectution of scripts, and automated report generation.  JAWA makes it easier to implement automated workflows in Jamf Pro by providing a shared library of common tasks and also lets you use Webhooks and APIs of other SaaS products to automate multi-step or repetitive functions.  Scripts and workflows can be shared across organizations and teams. JAWA can reduce configuration time by reading and/or setting the Jamf Pro configurations required to run your automations. 
+Jamf Automation and Webhook Assistant, "JAWA", is a web server for hosting automation tools that interacts with Jamf
+Pro, Okta, and more. It includes a _webhook receiver_ for real-time if-this-then-that automation workflows and _crontab_
+for the timed execution of scripts and automated report generation. JAWA is intended to make webhooks and automation
+more accessible to admins of Jamf Pro by providing them with a simple framework with which they can design time-saving
+workflows and further integrate with other services owned by their organization.
 
-*Check out [screenshots.](https://github.com/jamf/JAWA/wiki/JAWA-Screenshots)*
+*Check out [JAWA on the Jamf Marketplace](https://marketplace.jamf.com/details/jawa/) for screenshots.*
 
 ## How it works?
 
-The JAWA runs on a Linux server and can be accessed via a GUI. Once installed, the IT Admin is able to use the JAWA as a one-stop shop/single pane of glass to upload, edit or adjust any automations they choose. The IT Admin gathers scripts or workflows they wish to implement, and using the GUI, they upload the scripts, name the scripts, and click go. The backend of the JAWA will make sure that based on event (time, webhook, etc.) the script/workflow runs and the desired action occurs. For webhooks, the JAWA utilizes a modified version of a the robust and open-source https://github.com/adnanh/webhook/. The webapp itself is built utilizing Python-Flask.
+JAWA is a Python Flask web app which runs on Linux and can be accessed via web-browser. Once installed, the IT Admin is
+able to use JAWA to upload, edit, or adjust webhook and timed automations managed by JAWA. Automation scripts can be
+uploaded by the IT admin and be configured to run when triggered (webhook), or run on a timer (cron). JAWA leverages
+Jamf and Okta APIs when creating webhooks in their respective services.
+
+## Server Requirements
 
-## Recommended Server Requirements
 General Server Requirements:
-• Ubuntu 18.04 or RHEL 7.x
-• 512MB RAM (2GB recommended)
-• 5GB Storage (20GB recommended)
-• 1 CPU Core (2 Cores recommended)
+
+- Ubuntu 18.04+ (coming soon: RHEL 7.x+)
+- Minimum: 512MB RAM (2GB recommended)
+- Minimum: 5GB Storage (25GB recommended)
+- Minimum: 1 CPU Core (2 Cores recommended)
+- Python 3.6+ (with pip)
+
 Network Requirements:
-• Inbound port 443 from JPS (for webhooks) and LAN (for web access) • Outbound port 443 to JPS and auxiliary services (Okta, WorkDay, etc.) Certificate Requirements
-• SSL/TLS certificate* and private key 
+
+- Inbound port 443 from JPS for
+  webhooks ([IPs for Jamf Cloud](https://docs.jamf.com/technical-articles/Permitting_InboundOutbound_Traffic_with_Jamf_Cloud.html))
+- Inbound port 443 from LAN (for web access)
+- Outbound port 443 to JPS and auxiliary services (
+  Okta, WorkDay, etc.)
+
+Certificate Requirements
+
+- SSL/TLS certificate (publicly trusted) and private key
+- A publicly trusted _full-chain certificate_ (bundle of root CA + intermediate + server cert) is preferred
+  for `jawa.crt`
 
 ## How do I use it?
 
-*See the "JAWA Administrators Guide" found in the [release](https://github.com/jamf/JAWA/releases) for more detailed installation and configuration instructions.*
+*See the "JAWA Administrators Guide" found in the [release](https://github.com/jamf/JAWA/releases) for more detailed
+installation and configuration instructions.*
 
 Installation Steps:
-1. Create server for JAWA with:
-1. Port 443 open inbound/outbound.
-2. Download JAWA installer (.run) from GitHub
-3. Gather your SSL/TLS certificate and key
-4. Rename certificate to jawa.crt and the private key to jawa.key
-5. Transfer (scp) the JAWA installer and the SSL/TLS cert & key to the server.
-6. Ensure you are in the same directory as your jawa.crt and jawa.key
-7. Run the JAWA installer:
-sudo ./install_jawa.run
-8. Follow the prompts for installing The JAWA and choose your destiny (Clean Install, Upgrade, Uninstall, or Cancel)
-9. After installation completes, navigate to your FQDN/IP (i.e., https://jawa.company.com) in your web browser to continue with the web-based setup.
+
+1. Complete server requirements
+2. Rename certificate to jawa.crt and the private key to jawa.key
+3. Ensure you are in the same directory as your jawa.crt and jawa.key
+4. Download and run JAWA installer:
+
+   `curl -O https://raw.githubusercontent.com/jamf/JAWA/develop/bin/ubuntu_installer.sh && sudo bash ./ubuntu_installer.sh`
+5. After installation completes, navigate to your FQDN/IP (i.e., https://jawa.company.com) in your web browser to
+   continue with the web-based setup
 
 Configuration Steps:
-1. Log in to The JAWA with your Jamf Pro URL and Jamf Pro Administrator Credentials
-2. Click the “Configure The JAWA” link in the Setup Options section
-3. Type in the FQDN you gave The JAWA (i.e: https://jawa.company.com) - this address needs
-to be resolvable by the Jamf Pro Server to send webhooks.
-4. Click Utinni!
-
-When scripting for webhooks, verifiy JSON structure sent from source:
-1. [Jamf Pro Webhook Event Info](https://developer.jamf.com/webhooks)
+
+1. Log in to JAWA with your Jamf Pro URL and Jamf Pro Administrator Credentials
+2. Click the “Configure JAWA” link in the JAWA Dashboard or click Setup in the top-nav
+3. Fill out the Server Setup form:
+    1. [required] JAWA Server Address FQDN (i.e: https://jawa.company.com) - this address needs to be resolvable by the
+       Jamf Pro Server to send webhooks
+    2. [recommended] Lock your JAWA to a primary Jamf Pro Server
+    3. [optional] Add an alternate Jamf Pro Server for
+4. Click Setup
+5. Set up your first webhook or timed automation
+
+When scripting for webhooks, verify JSON structure sent from source:
+
+1. [Jamf Pro Webhook Event Info](https://developer.jamf.com/developer-guide/docs/webhooks)
 2. [Okta Webhook Event Info](https://developer.okta.com/docs/reference/api/event-types/?q=event-hook-eligible)
 
-*NOTE: To ensure continuity, webhooks created via JAWA should be modified and deleted from JAWA as Jamf Pro (or source of webhook) will automatically be configured/adjusted appropriately.*
+*NOTE: To ensure continuity, webhooks created via JAWA should be modified and deleted from JAWA as Jamf Pro (or source
+of webhook) will automatically be configured/adjusted appropriately.*
+
+## Version 3.0.0
+
+- Refactored:
+    - Improved page views
+    - New webhook engine
+    - Relative paths
+- Webapp:
+    - New UI and nav
+    - Branding options
+    - Log view
+    - Files repo for script resources
+    - Switch between Jamf Pro Servers (to solve issue #11)
+- Webhooks:
+    - Basic authentication for webhooks (to solve issues #12 & #14)
+    - Custom webhook
+    - stdout/stderr logging
+- Backend:
+    - Leverages a service account for running the webapp and managing crontab
+    - Enhanced security with fail2ban, ufw requirements
+- Installer:
+    - Smaller payload (curl script from github)
+    - Choose installation path
+    - Progress bar w/ status message (`stdout`, `stderr`, and additional information about the installation can be found
+      at `/var/log/jawaInstall.log`)
+
 
-## Version 2.0
-- Second release!
-- Python 3 build
-- Moved Flask application to Waitress
-- SSL Termination with NGINX
-- JAWA and webhook moved to systemd
-- Create and Delete Timed Automations
-- Ability to lock authentication to specific Jamf Pro instance
+Find JAWA releases [here.](https://github.com/jamf/JAWA/releases)
 
-Find JAWA realeases [here.](https://github.com/jamf/JAWA/releases)