initial implementation of install and config roles

Author: Ubuntu

README.md

@@ -41,67 +41,57 @@ The NGINX Ansible role supports all platforms supported by [NGINX Plus](https://
 **NGINX Plus**
 
 ```yaml
-Alpine:
-  versions:
-    - 3.8
-    - 3.9
-    - 3.10
-Amazon Linux:
-  versions:
-    - 2018.03
-Amazon Linux 2:
-  versions:
-    - LTS
 CentOS:
   versions:
-    - 6.5+
-    - 7.4+
-    - 8
-Debian:
-  versions:
-    - stretch
-    - buster
-FreeBSD:
-  versions:
-    - 11.2+
-    - 12
-Oracle Linux:
-  versions:
-    - 6.5+
-    - 7.4+
-RedHat:
-  versions:
-    - 6.5+
-    - 7.4+
-    - 8
-SUSE/SLES:
-  versions:
-    - 12
-    - 15
-Ubuntu:
-  versions:
-    - xenial
-    - bionic
+    - 7.4
 ```
 
 Role Variables
 --------------
 
-This role has multiple variables. The descriptions and defaults for all these variables can be found in the directory **`defaults/main`** in the following files:
+This role has multiple variables. The descriptions and defaults for all these variables can be found in the **[defaults/main.yml](./defaults/main.yml)`**.
 
--   **[defaults/main/main.yml](./defaults/main/main.yml):** NGINX installation variables
--   **[defaults/main/upload.yml](./defaults/main/upload.yml):** NGINX configuration/HTML/SSL upload variables
--   **[defaults/main/linux.yml](./defaults/main/linux.yml):** Linux installation variables
--   **[defaults/main/bsd.yml](./defaults/main/bsd.yml):** BSD installation variables
 
 Dependencies
 ------------
 
-None
+Since this role uses the [package_facts](https://docs.ansible.com/ansible/latest/modules/package_facts_module.html) module, on debian-based systems the `python-apt` package must be installed on targeted hosts.
 
 Example Playbook
 ----------------
 
+
+This is a sample playbook file for using the role to install NGINX App Protect on NGINX Plus and configure it using basic settings to all `wafs` inventory hosts.
+
+```yaml
+---
+- hosts: wafs
+  become: true
+  vars:
+    # Installs NGINX App Protect and all dependencies to the target host
+    app_protect_install: true
+
+    # Creates basic configuration files and enables NGINX App Protect on the target host
+    app_protect_configure: true
+
+    # For use with the app_protect_configure option to determine if the default security policy will be written to the target host
+    app_protect_security_policy_template_enable: true
+
+    # For use with the app_protect_configure option to determine if the default log policy will be written to the target host
+    app_protect_log_policy_template_enable: true
+
+    # For use with the app_protect_configure option to determine if the sample nginx.conf will be written to the target host. 
+    # Since this can be dangerous, this value is default to false in the role defaults
+    nginx_conf_template_enable: true
+
+    # For use with the app_protect_configure option to determine the syslog target to be injected 
+    # into the default log policy that will be written to the target host
+    log_policy_syslog_target: 10.1.1.8:5144
+
+  roles:
+    - role: ansible-role-nginx-app-protect
+```
+
 This is a sample playbook file for deploying the Ansible Galaxy NGINX App Protect role in a localhost and installing NGINX App Protect on NGINX Plus.
 
 ```yaml

defaults/main.yml

@@ -1,2 +1,43 @@
 ---
-# defaults file for ansible-role-nginx-app-protect
+# defaults file for ansible-role-nginx-app-protect
+
+app_protect_install: true
+app_protect_configure: true
+
+tmp_dir: /tmp/app-protect
+cleanup_when_done: true
+
+# Start NGINX service.
+# Default is true.
+nginx_start: true
+
+# populate this dictionary of lists with appropriate values from the ansible_os_family and ansible_distribution_version facts
+app_protect_linux_families:
+  RedHat:
+    - 7.4
+
+app_protect_security_policy_template_enable: true
+app_protect_security_policy_template:
+  template_file: app-protect-security-policy.j2
+  out_file_name: app-protect-security-policy.json
+  out_file_location: /etc/nginx/
+
+app_protect_log_policy_template_enable: true
+app_protect_log_policy_template:
+  template_file: app-protect-log-policy.j2
+  out_file_name: app-protect-log-policy.json
+  out_file_location: /etc/nginx/
+
+nginx_conf_template_enable: false
+nginx_conf_template:
+  template_file: nginx.conf.j2
+  out_file_name: nginx.conf
+  out_file_location: /etc/nginx/
+
+# possible values: transparent, blocking
+security_policy_enforcement_mode: transparent
+
+# possible values: TBD
+log_policy_filter_request_type: all
+
+log_policy_syslog_target: 127.0.0.1:514

handlers/main.yml

@@ -1,2 +1,19 @@
 ---
-# handlers file for ansible-role-nginx-app-protect
+# handlers file for ansible-role-nginx-app-protect
+- name: "(Handler: All OSs) Run NGINX"
+  block:
+
+    - name: "(Handler: All OSs) Start NGINX"
+      service:
+        name: nginx
+        state: started
+        enabled: yes
+
+    - name: "(Handler: All OSs) Reload NGINX"
+      service:
+        name: nginx
+        state: reloaded
+
+  when:
+    - nginx_start | bool
+    - not ansible_check_mode

meta/main.yml

@@ -11,10 +11,11 @@ galaxy_info:
   platforms:
     - name: EL
       versions:
-        - 7
+        - 7.4
 
   galaxy_tags:
     - waf
+    - security
     - nginx
     - oss
     - plus

tasks/configure-app-protect.yml

@@ -0,0 +1,40 @@
+---
+- name: "Ensure NGINX Main Directory Exists"
+  file:
+    path: "{{ nginx_conf_template.out_file_location}}"
+    state: directory
+  when: app_protect_security_policy_template_enable or app_protect_log_policy_template_enable or nginx_conf_template_enable
+
+- name: Backup existing nginx.conf
+  copy:
+    src: "{{ nginx_conf_template.out_file_location }}{{ nginx_conf_template.out_file_name }}"
+    dest: "{{ nginx_conf_template.out_file_location }}{{ nginx_conf_template.out_file_name }}.orig"
+    remote_src: yes
+  when: nginx_conf_template_enable
+
+- name: "Dynamically Generate NGINX App Protect security policy file"
+  template:
+    src: "{{ app_protect_security_policy_template.template_file }}"
+    dest: "{{ app_protect_security_policy_template.out_file_location }}{{ app_protect_security_policy_template.out_file_name }}"
+    backup: yes
+  when: app_protect_security_policy_template_enable
+
+- name: "Dynamically Generate NGINX App Protect log policy file"
+  template:
+    src: "{{ app_protect_log_policy_template.template_file }}"
+    dest: "{{ app_protect_log_policy_template.out_file_location }}{{ app_protect_log_policy_template.out_file_name }}"
+    backup: yes
+  when: app_protect_log_policy_template_enable
+
+- name: "Dynamically Generate NGINX conf file"
+  template:
+    src: "{{ nginx_conf_template.template_file }}"
+    dest: "{{ nginx_conf_template.out_file_location }}{{ nginx_conf_template.out_file_name }}"
+    backup: yes
+  when: nginx_conf_template_enable
+
+- name: "Reload NGINX"
+  debug:
+    msg: "trigger nginx reloaded if needed"
+  notify: "(Handler: All OSs) Reload NGINX"
+  changed_when: app_protect_security_policy_template_enable or app_protect_log_policy_template_enable or nginx_conf_template_enable

tasks/install-app-protect-linux.yml

@@ -0,0 +1,112 @@
+---
+- name: Check that the NGINX App Protect install zip exists locally
+  stat:
+    path: "{{ install_zip}}"
+  register: local_install_zip_stat
+  connection: local
+
+- name: Check preconditions
+  assert:
+    that:
+      - "local_install_zip_stat.stat.exists == true"
+    quiet: true
+
+- name: Copy NGINX App Protect install zip to host
+  copy:
+    src: "{{ install_zip }}"
+    dest: "{{ install_zip }}"
+
+- name: Get package facts
+  package_facts:
+    manager: "auto"
+
+- name: Set zip version number
+  set_fact:
+    key_value: "" # appeasing the linter
+    app_protect_version: "{{ install_zip | regex_search('(\\d+)') }}"
+
+- name: Set NGINX Plus version
+  set_fact:
+    key_value: "" # appeasing the linter
+    nginx_plus_version: "{{ ansible_facts.packages['nginx-plus'] | map(attribute='version') | list | first | regex_search('^(\\d{1,3})') }}"
+  when: "'nginx-plus' in ansible_facts.packages"
+
+- name: Fail if NGINX+ version preconditions fail
+  assert:
+    that:
+      - nginx_plus_version is defined
+      - nginx_plus_version | int >= 18
+    fail_msg: "'nginx_plus_version' release version must be a minimum of 18 for App Protect. Actual: {{ nginx_plus_version }}"
+    success_msg: "'nginx_plus_version' is {{ nginx_plus_version }}"
+    quiet: true
+
+- name: Fail if app protect zip doesn't not match detected NGINX+ version
+  assert:
+    that:
+      - app_protect_version is defined
+      - nginx_plus_version | int == app_protect_version | int
+    fail_msg: "'nginx_plus_version' {{ nginx_plus_version }} must match the NGINX App Protect version {{ app_protect_version }}"
+    success_msg: "'nginx_plus_version' is {{ nginx_plus_version }} and 'app_protect_version' is {{ app_protect_version }}"
+    quiet: true
+
+- name: Install epel-release, unzip and openssl packages
+  package:
+    name: epel-release, unzip, openssl
+    state: present
+
+- name: Create a directory if it does not exist
+  file:
+    path: "{{ tmp_dir }}"
+    state: directory
+
+- name: Unarchive the App Protect package file that is already on the remote machine
+  unarchive:
+    src: "{{ install_zip }}"
+    dest: "{{ tmp_dir }}"
+    remote_src: yes
+
+- name: Display paths of all .rpm files in dir; exclude NGINX+ installer
+  find:
+    paths: 
+      - "{{ tmp_dir }}"
+    file_type: file
+    use_regex: true
+    patterns:
+      - "^(?!.*nginx-plus-{{ app_protect_version }}).*\\.rpm$"
+  register: rpm_files
+
+- name: Install f5 packages
+  package:
+    name: "{{ rpm_files | select('match', '^f5.*.rpm$') | list }}"
+    state: present
+
+- name: Install app-protect dependency packages
+  package:
+    name: "{{ rpm_files | select('match', '^app-protect-[^\\d].*\\.rpm$') | list }}"
+    state: present
+
+- name: Install app-protect NGINX+ module package
+  package:
+    name: "{{ rpm_files | select('match', '^nginx-plus-module-appprotect-.*\\.rpm$') | list }}"
+    state: present
+
+- name: Install app-protect core package
+  package:
+    name: "{{ rpm_files | select('match', '^app-protect-\\d{2,3}.*\\.rpm$') | list }}"
+    state: present
+
+- name: Disable SELinux
+  selinux:
+    state: disabled
+
+- name: Recursively remove extracted directory
+  file:
+    path: "{{ tmp_dir }}"
+    state: absent
+  when: cleanup_when_done
+
+- name: Remove source zip
+  file:
+    path: "{{ install_zip }}"
+    state: absent
+  when: cleanup_when_done

tasks/main.yml

@@ -1,12 +1,31 @@
 ---
-# tasks file for ansible-role-nginx-app-protect
+- name: set supported_os when platform and version are in supported platforms dictionary
+  set_fact:
+    key_value: "" # appeasing the linter
+    supported_os: true
+  loop: "{{ query('dict', app_protect_linux_families) }}"
+  when: ansible_os_family in item.key and ansible_distribution_version | float in item.value
 
-- name: Get package facts
-  package_facts:
-    manager: "auto"
-- name: Set NGINX Plus version
+- name: set supported_os to false if fact not defined
   set_fact:
-    nginx_plus_version: "{{ ansible_facts.packages['nginx-plus']|
-                            map(attribute='version')|
-                            list }}"
-  when: "'nginx-plus' in ansible_facts.packages"
+    key_value: "" # appeasing the linter
+    supported_os: false
+  when: supported_os is not defined
+
+- name: debug supported os
+  debug:
+    msg: "supported_os {{ supported_os }}"
+    verbosity: 2
+
+- name: Abort if the OS/version combination is not supported
+  fail:
+    msg: "NGINX App Protect is not supported on os family {{ ansible_os_family }} version {{ ansible_distribution_version }}"
+  when: not supported_os
+
+- name: "(Install: Linux) Install NGINX Plus App Protect"
+  include_tasks: install-app-protect-linux.yml
+  when: supported_os and app_protect_install
+
+- name: "Configure NGINX Plus App Protect"
+  include_tasks: configure-app-protect.yml
+  when: supported_os and app_protect_configure

templates/app-protect-log-policy.j2

@@ -0,0 +1,10 @@
+{
+    "filter": {
+        "request_type": "{{ log_policy_filter_request_type }}"
+    },
+    "content": {
+        "format": "default",
+        "max_request_size": "any",
+        "max_message_size": "5k"
+    }
+}

templates/app-protect-security-policy.j2

@@ -0,0 +1,6 @@
+{
+    "name": "/Common/policy1",
+    "template": { "name": "POLICY_TEMPLATE_NGINX_BASE" },
+    "applicationLanguage": "utf-8",
+    "enforcementMode": "{{ security_policy_enforcement_mode }}"
+}