Introduction

Trellix Drive Encryption 7.x.x introduces Web API commands that add scripting and automation capabilities to these management activities:

• Add or remove a user(s) from a system(s)

• Perform user directory management (Non LDAP)

• Change a user password

• Export disk encryption key(s) for a system

• Generate a Challenge Response Code

• Reset self recovery for a user

Note

In this document, Drive Encryption 7.x.x refers to Drive Encryption 7.1.x, 7.2.0, and above.

Purpose of this guide

This guide provides the Web API commands that you need to configure, use, and maintain Drive Encryption.

This guide is a companion document to the Trellix ePolicy Orchestrator - On-prem Scripting Guide.

Note

The scripting functionalities of Drive Encryption 7.2.x are supported only from version Trellix ePO - On-prem 5.3.x and above.

The Trellix ePO - On-prem Scripting Guide describes the Trellix ePO - On-prem Web API and how to use it. It also provides example scripts using the Python client.

For more information about Web API basics, see the Trellix ePO - On-prem Scripting Guide.

2 | Introduction

Web API commands for Drive Encryption

Scripts using the Web API can be run from any computer that can connect to the Trellix ePO - On-prem server. For security reasons, they should not be run on the same computer as the Trellix ePO - On-prem server itself.

The Web API is used primarily for two purposes:

• Scripting sequences of tasks

• Performing simple tasks without using the user interface

Referencing systems and branches

The commands available through the Drive Encryption Web API and Trellix ePO - On-prem Web API commands, commonly need to reference a system or a branch within the Trellix ePO - On-prem System Tree.

The following terms are used throughout this guide:

• Computer ID: This term refers to a number (also known as a leafNodeId) that identifies the system in the System Tree. You can identify this number by using the EPOComputerProperties.ParentID attribute. This attribute is part of the system.find command output.

• Branch ID: This term refers to a number that identifies a branch (also known as groupId) within the Trellix ePO - On-prem System Tree. You can identify this number by:        

  • Locating a system through the system.find command, and inspecting the EPOBranchNode.AutoID attribute

  • Locating a System Tree group through the system.findGroup command, and inspecting the groupId attribute

• systemNode: This is a Drive Encryption Web API command parameter that controls the meaning of nodeId. Its possible values are ‘True’ or ‘False’.

• nodeId: This is a Drive Encryption Web API command parameter. The meaning of nodeId changes depending on the value of the systemNode parameter:        

  • If systemNode = ‘True’: nodeId means Computer Id / leafNodeId

  • If systemNode = ‘False’: nodeId means Branch Id / groupId

The following examples show how the standard Trellix ePO - On-prem Web API commands are used to obtain the Computer ID or Branch ID:

Search by system

To find information about system TEST123, run this remote command: https://myeposerver:8443/remote/system.find?searchText=TEST123&:output=xml?>.

The output contains the following (among other output):

2 | Introduction

OK:

<result>

<list>

<row>

<EPOComputerProperties.ParentID>272</EPOComputerProperties.ParentID>

...

<EPOBranchNode.AutoID>58</EPOBranchNode.AutoID>

</row>

</list>

</result>

Locating System Tree branch / group ID

To find the System Tree group identifier, run this remote command: https://myeposerver:8443/remote/system.findGroups?searchText=?>.

The output contains a list of all System Tree groups, with their groupId:

OK:

groupId: 2

groupPath: My Organization

Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide

5

2 | Introduction

groupId: 3

groupPath: My Organization\Lost&Found

Using Web API commands for Drive Encryption

A few Web API commands are more commonly used than others. Being familiar with their syntax will help you create scripts quickly. The following tables list the commonly used commands with their syntax and description.

The examples in this guide are taken from different categories of tasks that show how scripting can help keep your Drive Encryption maintained and up-to-date.

Before running any commands, you must authenticate with an Trellix ePO - On-prem server.

⚠️        

Caution

If you use Python to change passwords or export machine keys, make sure that CREATE_LOG_FILE is not enabled in debug mode. When it is enabled, passwords and machine keys are logged to the file in plain text, making it a security risk. If you need to enable it, execute the command on a secure system, then make sure to shred the log file to prevent unauthorized users from accessing your passwords and machine keys.

Add a user or a user group to a system or branch

The Drive Encryption software can be activated on a client system only after adding a user and enforcing the required encryption policies correctly. Use the eeadmin.assignUser command to add a user or a user group to a system or branch in Trellix ePO - On-prem.

eeadmin.assignUser command

eeadmin.assignUser
systemNode=<>
nodeId=<>
dn=<>
[recursive=<>]
[ldapServerName=<>]

    6     Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide    

2 | Introduction

Remove a user or a user group from a system or branch

Use the eeadmin.deassignUser to remove a user or a user group from a system or branch in Trellix ePO - On-prem.

eeadmin.deassignUser command

2 | Introduction

Change a user password

Resetting or changing a remote user's password token requires an authorization from administrator. The eeadmin.changeUserPassword command allows the administrator to change the user password remotely.

eeadmin.changeUserPassword command

Export disk encryption key(s) for a system

The purpose of encrypting the client's data is to control access to the data by controlling access to the encryption keys. These keys are referred to as Machine Keys. Each system has its own unique Machine Key. The Machine Key is stored in Trellix ePO - On‑prem database to be used for client recovery when required. Use the eeadmin.exportMachineKey command to remotely export disk encryption key(s) for a system.

eeadmin.exportMachineKey command

2 | Introduction

Generate a Challenge Response Code

If the user's password or logon tokens have been lost, you need to perform administrator recovery on the client computer to recover the user or system.

User calls the administrator to perform the administrator recovery, and provides the Challenge Code. The administrator initiates the Trellix ePO - On-prem Scripting API to generate the Challenge Response Code. A valid Response Code is supplied by the scripting API to the administrator. When typing the Response Code, access is granted to the Client system. Use the eeadmin.administratorRecovery command to generate the Challenge Response Code.

There are four different administrator recovery types:

• machineRecovery='1'

• resetUserToken='2'

• unlockDisabledUser='3'

• reserUserToPasswordToken='4'

machineRecovery recovery type

2 | Introduction

    10     Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide

2 | Introduction

resetUserToken recovery type

Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide 11

2 | Introduction

R
e
c
o
v
e
r
y
c
h
a
l
l
e
n
g
e
C
o
d
e
=
<
>
u
r
e
c
o
v
e
r
y
T
y
p
e
=
<
>
u
                    

2 | Introduction

serverDn = <>

unlockDisabledUser recovery type

recoveryType='3'

Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide13

2 | Introduction

2 | Introduction

resetUserToPasswordToken recovery type

Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide 15

2 | Introduction

    16     Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide

2 | Introduction

Reset self recovery for a user

The client user's self-recovery details can be reset remotely, then the user can enroll the self-recovery details with new self-recovery answers. Use the eeadmin.resetSelfRecovery command to reset your self recovery details.

eeadmin.resetSelfRecovery command

eeadmin.resetSelfRecovery

2 | Introduction

3 | Introduction

User Directory Management (Non LDAP)

The User Directory feature utilizes the LDAP Sync extension and provides the ability for Drive Encryption to use users/groups from the User Directory (using the UserDirectory.zip extension).

Web API commands for the User Directory

Once you install the UserDirectory.zip extension into the Trellix ePO - On-prem server, you can create users and groups, and manage them using these Web API commands, without requiring to register an LDAP server in Trellix ePO - On-prem.

This allows the EEPC 5.1.x or above standalone users, who are not part of any LDAP server to be migrated to Drive Encryption 7.x.

Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide19

3 | Introduction

20Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide

3 | Introduction

s
=
<
>

3 | Introduction

3 | Introduction

Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide

23

3 | Introduction

    24          Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide

3 | Introduction

e
=
<
>

Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide25

3 | Introduction

26

Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide

3 | Introduction

Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide27

3 | Introduction

i
r
e
c
t
o
r
y
.
m
o
v
e
I
t
e
m
D
n
/
i
t
e
m
I
d
=
<
>
p
a
r
e
n
t
F

3 | Introduction

itemDn/itemId=<>

newName=<>

itemDn/itemId=<> — Refers to the item that needs to be renamed.

newName=<> — Refers to the new name for the item

    Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide     29

3 | Introduction

Note:

There are seven different scripts for the search item function.

3 | Introduction

.
s
e
a
r
c
h
I
t
e
m
s
r
o
o
t
I
d
/
r
o
o
t
D
n
=
<
>
s
e
a
r
c
h
S
t
r
i
n
g

Trellix Drive Encryption 7.4.x Web API Scripting Reference Guide31

3 | Introduction

= < >
recursive
= < >
                

Help command

You can use the Help command to get the structure for any command.

For example, to export disk encryption key for a system, use the command mc.help("eeadmin.exportMachineKey") to get the structure of the command.