Documentation updates (#19)

* chore(docs): update RBAC permission names

* fix(win): molecule vm timing out during creation

* chore(win): add latest windows versions, update return codes

* chore(win): use agent versions defined in `s1_product_id` for automated tests

Author: s1-nathangerhart

README.md

@@ -80,19 +80,19 @@ The various roles in this collection access the SentinelOne Management Console v
 
 Create a `Ansible Service Accounts` role in the SentinelOne Management console and grant it the permissions:[^2]
 
-* Accounts View
-* Endpoints Show Passphrase
-* Endpoints Uninstall
-* Endpoints Update Software
-* Endpoints View
-* Groups View
-* Local Upgrade Authorization Edit
-* Local Upgrade Authorization View
-* Packages
-* Roles View
-* Sites View
-
-[^1]: See the SentinelOne KnowledgeBase article [Generating API Tokens](https://support.sentinelone.com/hc/en-us/articles/360004195934).
+* Endpoints > Show Passphrase
+* Endpoints > Uninstall
+* Endpoints > Update Software
+* Endpoints > View
+* Accounts > View
+* Agent Packages > View
+* Groups > View
+* Local Upgrade Authorization > Edit
+* Local Upgrade Authorization > View
+* Roles > View
+* Sites > View
+
+[^1]: See the SentinelOne KnowledgeBase article [Generating API Tokens](https://community.sentinelone.com/s/article/000005262).
 [^2]: This is a cumulative list of permissions required by the collection as a whole. If you wish to use a separate Service Account for each Ansible Role, see that role's README for a list of required permissions.
 
 Then add your Service Users to the `Ansible Service Accounts` role and scope it to the appropriate Site/Account/Group.
@@ -165,4 +165,4 @@ Endpoints need to trust the management console's self-signed certificate before
   * For domain joined systems, Group Policy can be used to add custom certificates to the trusted store.
   * The official [ansible.windows.win_certificate_store](https://docs.ansible.com/ansible/latest/collections/ansible/windows/win_certificate_store_module.html) module can manage certificates in the trusted store.
 
-[^3]: See the [Release Notes](https://support.sentinelone.com/hc/en-us/articles/10814416011543-22-4-Linux-Agent-Release-Notes)
+[^3]: See the [Release Notes](https://community.sentinelone.com/s/article/000005011)

extensions/molecule/common/templates/prepare-basic.yml

@@ -12,3 +12,9 @@
         file: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/molecule/common/templates/tasks/prepare_package_manager.yml"
       when:
         - ansible_system == 'Linux'
+
+    - name: Include tasks to set agent version | Windows
+      ansible.builtin.include_tasks:
+        file: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/molecule/common/templates/tasks/set_agent_version.yml"
+      when:
+        - ansible_os_family == 'Windows'

extensions/molecule/common/templates/prepare-install-agent.yml

@@ -13,6 +13,14 @@
       when:
         - ansible_system == 'Linux'
 
+    - name: Include tasks to set agent version | Windows
+      ansible.builtin.include_tasks:
+        file: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/molecule/common/templates/tasks/set_agent_version.yml"
+      vars:
+        s1_product_id_index: 1
+      when:
+        - ansible_os_family == 'Windows'
+
     - name: Include tasks to install agent
       ansible.builtin.include_tasks:
         file: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/molecule/common/templates/tasks/install_s1_agent.yml"

extensions/molecule/common/templates/tasks/set_agent_version.yml

@@ -0,0 +1,26 @@
+---
+- name: Include Windows vars | Windows
+  ansible.builtin.include_vars:
+    file: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/../roles/s1_agent_common/vars/windows.yml"
+
+- name: Set s1_agent_version to a version supported by the collection | Windows
+  set_fact:
+    s1_agent_version: >-
+      {{
+        (
+          s1_product_id
+          | dict2items
+          | selectattr('key', 'search', ansible_facts.architecture | replace('-','_'))
+          | map(attribute="key")
+          | map('regex_replace', '^v', '')
+          | map('regex_replace', '_(64|32)_bit$', '')
+          | map('regex_replace', '_', '.')
+          | sort(reverse=true)
+          | list
+        )[s1_product_id_index | default(0)]
+      }}
+    cacheable: true
+
+- name: Desired Agent Version | Windows
+  ansible.builtin.debug:
+    var: s1_agent_version

extensions/molecule/default/molecule.yml

@@ -20,6 +20,8 @@ platforms:
     box: ${S1_VAGRANT_REPO:-roboxes}/${S1_VAGRANT_DISTRO:-rocky8}
     memory: 4096
     cpus: 2
+    instance_raw_config_args:
+      - "vm.boot_timeout = 1800"
     config_options:
       synced_folder: false
     provider_options:

extensions/molecule/upgrade/prepare.yml

@@ -15,6 +15,20 @@
       when:
         - ansible_system == 'Linux'
 
+    - name: Include tasks to set agent version | Windows
+      ansible.builtin.include_tasks:
+        file: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/molecule/common/templates/tasks/set_agent_version.yml"
+      vars:
+        s1_product_id_index: 1
+
     - name: Include tasks to install agent
       ansible.builtin.include_tasks:
         file: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/molecule/common/templates/tasks/install_s1_agent.yml"
+
+    - name: Include tasks to set agent version | Windows
+      ansible.builtin.include_tasks:
+        file: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/molecule/common/templates/tasks/set_agent_version.yml"
+      vars:
+        s1_product_id_index: 0
+      when:
+        - ansible_os_family == 'Windows'

roles/s1_agent_common/vars/windows.yml

@@ -11,12 +11,15 @@ s1_reboot_handler_name: Reboot Node | {{ ansible_os_family }}
 s1_agent_win_file_ver: '{{ "v" + (s1_agent_version + "_" + ansible_facts.architecture) | regex_replace("[\.-]", "_") }}'
 
 # Return codes from SentinelOneInstaller.exe that indicate a successful install or upgrade (a reboot may still be required)
+# See: https://community.sentinelone.com/s/article/000008704
 s1_new_exe_return_codes:
   - 0
   - 12
   - 100
   - 101
+  - 102
   - 103
+  - 104
   - 1000
 
 s1_msi_return_codes:
@@ -25,6 +28,13 @@ s1_msi_return_codes:
 
 # The same Product ID is used for MSI and SentinelOneInstaller packages
 s1_product_id:
+  v24_2_3_471_64_bit: "{A5AF5827-A2A0-4C8B-8ED1-48A148346399}"
+  v24_1_5_277_64_bit: "{38CCB1A1-E333-4D19-A6FA-C4CE60A2EAD3}"
+  v24_1_4_257_64_bit: "{EA080DF7-C45B-4BAF-AAD7-16FB66D11F92}"
+  v23_4_6_347_64_bit: "{9627E5DD-DA35-4A04-B2D6-A996A5A112C9}"
+  v23_4_6_347_32_bit: "{33FBF92A-8041-42F8-84EE-985FC9E4F418}"
+  v23_4_5_337_64_bit: "{7A1543A2-CF5C-45B2-855F-EA52A2D96B39}"
+  v23_4_5_337_32_bit: "{8D06246A-6F57-470F-83D0-F26048983874}"
   v23_4_4_223_64_bit: "{40CB8880-CA0E-416E-8C0D-9C3015E0EEA8}"
   v23_4_4_223_32_bit: "{5EAD8636-B65F-469B-BB60-E1FB33B1C8DC}"
   v23_3_4_320_64_bit: "{25F6C9CB-D50A-474B-9358-E94A6C444BAC}"

roles/s1_agent_download/README.md

@@ -14,11 +14,11 @@ A valid SentinelOne license, access to the SentinelOne Management Console and an
 
 In order to successfully query and download packages via the API, the account associated with the API token, `s1_api_token`, must be granted the permissions:
 
-* Accounts View
-* Groups View
-* Packages
-* Roles View
-* Sites View
+* Accounts > View
+* Groups > View
+* Agent Packages > View
+* Roles > View
+* Sites > View
 
 Best practice is to create a new "Download packages via API" role with these permissions. Then create a **Service User** and add them to the role.
 
@@ -36,7 +36,7 @@ s1_api_token:
 
 This is mandatory and is the API token[^1] associated with the user which will running the role.
 
-[^1]: See the SentinelOne KnowledgeBase article [Generating API Tokens](https://support.sentinelone.com/hc/en-us/articles/360004195934).
+[^1]: See the SentinelOne KnowledgeBase article [Generating API Tokens](https://community.sentinelone.com/s/article/000005262).
 
 ### Configuring the version of the agent
 

roles/s1_agent_install/README.md

@@ -9,7 +9,7 @@ The `s1_agent_install` role installs the SentinelOne Agent on endpoints.
 
 A valid SentinelOne license, access to the SentinelOne Management Console and access to the SentinelOne installation packages are required.
 
-Inventory hosts on which the agent is being installed must be running on a supported Operating System and meet its [minimum system requirements](https://support.sentinelone.com/hc/en-us/articles/360004196614-System-Requirements).
+Inventory hosts on which the agent is being installed must be running on a supported Operating System and meet its [minimum system requirements](https://community.sentinelone.com/s/topic/0TO69000000as1iGAA/system-requirements).
 
 ## Role Variables
 
@@ -25,7 +25,7 @@ s1_api_token:
 
 This is mandatory and is the API token[^1] associated with the user which will running the role.
 
-[^1]: See the SentinelOne KnowledgeBase article [Generating API Tokens](https://support.sentinelone.com/hc/en-us/articles/360004195934).
+[^1]: See the SentinelOne KnowledgeBase article [Generating API Tokens](https://community.sentinelone.com/s/article/000005262).
 
 ```yaml
 s1_agent_site_token:
@@ -112,7 +112,8 @@ s1_no_config_failures: false
 Set the SentinelOneInstaller package `--dont_fail_on_config_preserving_failures` flag for the upgrade.
 
 When set to true set the installer packages VDI flag to true and install the SentinelOne agent for a "cold clone".
-Note: See [https://support.sentinelone.com/hc/en-us/articles/360035087333](https://support.sentinelone.com/hc/en-us/articles/360035087333.).
+Note: See [https://community.sentinelone.com/s/article/000005519](https://community.sentinelone.com/s/article/000005519.).
+Note: See [https://community.sentinelone.com/s/article/000005519(https://community.sentinelone.com/s/article/000005519).
 
 ### Variables from dependencies
 

roles/s1_agent_install/defaults/main.yml

@@ -51,7 +51,7 @@ s1_agent_site_token: "{{ undef(hint='You must specify your agent Site Token') }}
 # s1_no_config_failures: no
 
 # If true set the installer's VDI flag to true and install the SentinelOne agent for a "cold clone".
-# Note: See https://support.sentinelone.com/hc/en-us/articles/360035087333.
+# Note: See https://community.sentinelone.com/s/article/000005519
 # Default: False
 # Windows Only
 # s1_enable_vdi: false