Ansible

An Ansible playbook for the Deep Security Agent. This playbook allows you to easily deploy the Deep Security Agent as well as take some common operations from the agent.

Support

This is a community project that is supported by the Trend Micro Deep Security team.

Tutorials, feature-specific help, and other information about Deep Security is available from the Deep Security Help Center.

For Deep Security specific issues, please use the regular Trend Micro support channels. For issues with the code in this repository, please open an issue here on GitHub.

Requirements

All of the tasks in this repository require a working Deep Security infrastructure. The key component is the Trend Micro Deep Security Manager. The Deep Security Agents (which these playbooks help you manage) do the heavy lifting but the Deep Security Manager gives the orders.

There are no specific technical requirements beyond a standard Ansible deployment.

Dependencies

There are no dependencies.

Usage

Below are sample usages for the playbook:

For deploying agents to a non-multi-tenant Deep Security Manager

- hosts: all
  roles:
    - role: deep-security.deep-security-agent
      operation: deploy
      dsm_agent_download_hostname: deep.security.manager.host
      dsm_agent_download_port: 4119
      dsm_agent_activation_hostname: deep.security.manager.host
      dsm_agent_activation_port: 4120
      policy_id: 1
      group_id: 1
      force_reactivation: false

For deploying agents to a multi-tenant Deep Security Manager (like Deep Security as a Service)

- hosts: all
  roles:
    - role: deep-security.deep-security-agent
      operation: deploy
      dsm_agent_download_hostname: app.deepsecurity.trendmicro.com
      dsm_agent_download_port: 443
      dsm_agent_activation_hostname: agents.deepsecurity.trendmicro.com
      dsm_agent_activation_port: 443
      tenant_id: 111A111A-1A1A-11AA-AAA-11AA11111111
      token | tenant_password: 111A111A-1A1A-11AA-AAA-11AA11111111
      policy_id: 1
      group_id: 1
      force_reactivation: false

Operations

Definition for possible operations to be performed in this role, for required variables please refer to Variables.

Operation	Description	Variables
deploy	The `deploy` task includes the `install` and `activate` playbooks internally.	dsm_agent_download_hostname dsm_agent_download_port dsm_agent_activation_hostname dsm_agent_activation_port policy_id (Optional) group_id (Optional) force_reactivation (Optional) For multi-tenancy only: tenant_id token/tenant_password
install	The install task downloads and installs the Deep Security Agent. The installation is skipped if an agent of the same version is already installed. If a newer version of Deep Security Installer is already installed, then the version is upgraded.	dsm_agent_download_hostname dsm_agent_download_port
activate	The activate task activates the Deep Security Agent by registering it in Trend Micro Deep Security Manager. By default, activation is skipped if the agent is already activated, unless the force_reactivation attribute is set to true.	dsm_agent_activation_hostname dsm_agent_activation_port policy_id (Optional) group_id (Optional) force_reactivation (Optional) For multi-tenancy only: tenant_id token/tenant_password
set-policy-by-name	Change the agent's policy via policy name	policy_id
set-policy-by-id	Change the agent's policy via policy id	policy_name
check-in-with-manager	Ask the agent to contact the manager now.	N/A
create-diagnostic-package	Generate an agent diagnostic package.	N/A
create-integrity-baseline	Rebuild the integrity monitoring baseline on the computer.	N/A
run-recommendation-scans	Initiate a recommendation scan on the computer.	N/A
scan-for-integrity-changes	Scan for changes for integrity monitoring	N/A
scan-for-malware	Initiate a manual anti-malware scan	N/A
update-configuration	Instruct the Deep Security Manager to perform a "Send Policy" operation.	N/A

Variables

Key	Type	Description	Sample
action	String	Name of the operation to be performed (deprecated—please use operation instead)	See Operations
operation	String	Name of the operation to be performed	See Operations
dsm_agent_activation_hostname	String	The hostname for the agents to communicate with once deployed. For Marketplace and software deployments, this is typically the same hostname as 'dsm_agent_download_hostname'.	agents.deepsecurity.trendmicro.com
dsm_agent_activation_port	Integer	The port used for the agent heartbeat (the regular communication). For Marketplace and software deployments, the default is 4120.	443
dsm_agent_download_hostname	String	The hostname of the Deep Security Manager.	app.deepsecurity.trendmicro.com
dsm_agent_download_port	Integer	The port to connect to the Deep Security Manager to download the agents. This is typically the same port as the one used to access the Deep Security Manager administration interface.	443
force_reactivation	Boolean	Force re-activation even if the Deep Security Agent has already been activated.	false
group_id	String	The Deep Security ID assigned to the computer group and applied to the agents on activation.	1
policy_id	String	ID of the Deep Security Policy to be assigned to the agents.	1
policy_name	String	Name of the Deep Security Policy to be assigned to the agents.	Base Policy
tenant_id	String	In a multi-tenant installation (like Deep Security as a Service), this identifies the tenant account to register the agent with. Multi-tenancy only	111A111A-1A1A-11AA-AAA-11AA11111111
token/tenant_password	String	In a multi-tenant installation (like Deep Security as a Service), this identifies the tenant account to register the agent with. In latest Deep Security Manager, "tenant_password" has been replaced with "token". "tenant_password" has been kept for backwards compatibility. Multi-tenancy only	111A111A-1A1A-11AA-AAA-11AA11111111

How to contribute

We're always open to PRs from the community. To submit one:

Fork the repo.
Create a new feature branch.
Make your changes.
Submit a PR with an explanation of your changes or additions.

We'll review your content and work with you to make sure the fix gets pushed out quickly. For further help, please contact the Trend Micro open source support team at deepsecurityopensource@trendmicro.com.

PhilippBehmer/ansible