/ansible_collection_s1agents

Ansible Collection

Primary LanguageMakefileGNU General Public License v3.0GPL-3.0

Ansible Collection - SentinelOne.s1agents

Release GitHub license

s1_agent_common s1_agent_info s1_agent_download s1_agent_install s1_agent_uninstall s1_agent_upgrade s1_agent_uuid s1_import_gpg_key s1_mgmt_get_passphrase

The SentinelOne.s1agents Ansible Collection is a collection of roles for managing the lifecycle of the SentinelOne Agent.

Included Roles

  • s1_agent_common loads common variables and configs used by all other roles.
  • s1_agent_info gathers basic info about the agent and can be used to determine if the agent is installed and operational.
  • s1_agent_download assists with downloading agent installation packages from the Management Console.
  • s1_agent_install installs agent packages on endpoints.
  • s1_agent_uninstall removes the agent from endpoints.
  • s1_agent_upgrade upgrades an existing agent installed on an endpoint.
  • s1_agent_uuid is used to generate a report of agent UUIDs.
  • s1_import_gpg_key ensures the SentinelOne GPG key is present on RPM based systems.
  • s1_mgmt_get_passphrase is used by other roles to retrieve the unique passphrase for each agent in the play, from the management console.

Dependencies

The SentinelOne.s1agents collection has dependencies upon the following collections.

The dependencies can be installed by using the ansible-galaxy command ansible-galaxy install -r requirements.yml and the requirements file found at the root of the project.

Using this collection

Using a requirements file

Create a requirements.yml and add the ansible_collection_s1agents git repository to it.

collections:
  - name: https://github.com/Sentinel-One/ansible_collection_s1agents.git
    type: git
    # version: release/v0.3.0

The collection can then be installed with the ansible-galaxy command

ansible-galaxy collection install -r requirements.yml

When using Ansible Tower to deploy the agents, if the requirements.yml file is placed within the project's roles folder <project-top-level-directory>/roles/requirements.yml Ansible Tower will automatically download the collection at the end of the Project Update cycle.

Using ansible-galaxy to download directly from GitHub

The ansible-galaxy command can be used to download this collection directly from the GitHub repo.

ansible-galaxy collection install git+https://github.com/Sentinel-One/ansible_collection_s1agents.git

This method maybe used to test a pre-release version. In this case append the branch or tag you wish to test to the end of the git URL. In the example below release/v0.3.0 is the branch to use for testing.

ansible-galaxy collection install git+https://github.com/Sentinel-One/ansible_collection_s1agents.git,release/v0.3.0

Required Permissions

Management Console

The various roles in this collection access the SentinelOne Management Console via API and an API token1 is required. It should be passed to the ansible role/playbook via the s1_api_token variable.

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

Then add your Service Users to the Ansible Service Accounts role and scope it to the appropriate Site/Account/Group.

Privileges on Endpoints

In order to successfully install and manage the agent, the Service Account used by Ansible to connect to each host must have elevated rights, sudo or su on Linux and Administrator on Windows. Ensure that your Ansible Service account is correctly configured on each endpoint.

Known Limitations

Using the s1_agent_version variable with mixed deployments

When deploying a specific version of the agent to an inventory that contains a mix of Linux and Windows endpoints, it is necessary to define the s1_agent_version variable so that it applies only to Linux or Windows hosts. This means the inventory must be structured so that Widows and Linux hosts are in separate groups. Alternatively, the set_fact module can be used to define s1_agent_version in the playbook with a conditional for the ansible_system.

Downgrading agent versions

This collection does not directly support downgrading agent versions. However, it can be used to achieve the same end result by building a playbook that first calls the s1_agent_uninstall role to uninstall the agent and then calls the s1_agent_install role to install the lower version. The endpoint will be assigned a new UUID and will appear as a new endpoint in the management console.

Fact Gathering

The collection uses the setup module to gather a minimum set of facts that is required for it a successful run. This behavior can be disabled by passing --skip-tags "s1_gather_facts" to the ansible-playbook command. If you do this, ensure that your playbook contains either gather_facts: yes or that the setup module is called prior to any Sentinel-One roles.

Linux Operating Systems

Upgrading older Linux Agents beyond version 22.2.2.2 when s1_install_gpg_signed_rpm is true

When upgrading to a Linux agent version that is newer than 22.2.2.2, using the GPG Signed packages, from an agent that is older than 22.2.2.2, you must first upgrade the agent to version 22.2.2.2. Once the agent has been upgraded to 22.2.2.2, you can upgrade to the desired version. Example Playbook.

Windows Operating Systems

Idempotence on Windows

To ensure idempotence, the s1_product_id variable must be defined with the Product ID (GUID) for the SentinelOne agent version being deployed. If the Product ID is not set, then the task will attempt to reinstall the same version. This variable is defined in the s1_agent_common role and will be updated periodically, but it is not guaranteed to have mappings for all releases. Steps for configuring s1_product_id specific to your deployment are provided in the s1_agent_common role role.

Additionally, this can occasionally cause testing these roles with molecule (molecule test) to fail on the idempotence step. If you see:

CRITICAL Idempotence test failed because of the following tasks:
*  => s1_agent_install : Install SentinelOne | Windows
*  => Flush handlers
WARNING  An error occurred during the test sequence action: 'idempotence'. Cleaning up.

This can indicate that the s1_product_id variable needs to updated with the latest agent versions.

Installing/Upgrading Windows Agents

If you attempt to install an agent version that is the same or lower than the currently installed Windows agent, the installer will do nothing and exit. Ansible will see this and consider the task OK and Unchanged. This is by design so that idempotence can be maintained when re-running a playbook with the same input parameters.

MacOS Operating Systems

MacOS is Unsupported

Managing the agent on MacOS is currently unsupported by this collection. This is due to security designs by Apple which limit authorizing the Full Disk Access and Network Extensions to an actual person or an authorized MDM solution. As Ansible and its service account is neither, it is impossible for Ansible to deploy a fully operational SentinelOne agent.

On-Premises Management Consoles

Ansible Controller Host

When using this collection with an on-prem management console with a self-signed certificate, it may be necessary to either add the certificate to the Ansible Controller's certificate store or set the s1_validate_certs variable to false.

Endpoints

Endpoints need to trust the management console's self-signed certificate before the agent can successfully communicate with. Distributing self-signed certificates to endpoints is out-of-scope for this collection.

  • Linux
    • Starting with Linux agent 22.43 custom certificates for on-prem management consoles can be saved to /opt/sentinelone/certificates/custom.crt on the endpoint and the agent will use it for agent to management console communications.
    • While there is no official Ansible module for managing certificates on a Linux endpoint, numerous third-party solutions exist, check https://galaxy.ansible.com/.
  • Windows
    • For domain joined systems, Group Policy can be used to add custom certificates to the trusted store.
    • The official ansible.windows.win_certificate_store module can manage certificates in the trusted store.

Footnotes

  1. See the SentinelOne KnowledgeBase article Generating API Tokens. ↩

  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. ↩

  3. See the Release Notes ↩