Scripting Guide

ePolicy Orchestrator 4.6.0

COPYRIGHT

Copyright 2011 McAfee, Inc. All Rights Reserved.

No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in any form or by
any means without the written permission of McAfee, Inc., or its suppliers or affiliate companies.

TRADEMARK ATTRIBUTIONS

AVERT, EPO, EPOLICY ORCHESTRATOR, FOUNDSTONE, GROUPSHIELD, INTRUSHIELD, LINUXSHIELD, MAX (MCAFEE SECURITYALLIANCE EXCHANGE),
MCAFEE, NETSHIELD, PORTALSHIELD, PREVENTSYS, SECURITYALLIANCE, SITEADVISOR, TOTAL PROTECTION, VIRUSSCAN, WEBSHIELD are registered
trademarks or trademarks of McAfee, Inc. and/or its affiliates in the US and/or other countries. McAfee Red in connection with security is distinctive of
McAfee brand products. All other registered and unregistered trademarks herein are the sole property of their respective owners.

LICENSE INFORMATION
License Agreement

NOTICE TO ALL USERS: CAREFULLY READ THE APPROPRIATE LEGAL AGREEMENT CORRESPONDING TO THE LICENSE YOU PURCHASED, WHICH SETS
FORTH THE GENERAL TERMS AND CONDITIONS FOR THE USE OF THE LICENSED SOFTWARE. IF YOU DO NOT KNOW WHICH TYPE OF LICENSE YOU
HAVE ACQUIRED, PLEASE CONSULT THE SALES AND OTHER RELATED LICENSE GRANT OR PURCHASE ORDER DOCUMENTS THAT ACCOMPANY YOUR
SOFTWARE PACKAGING OR THAT YOU HAVE RECEIVED SEPARATELY AS PART OF THE PURCHASE (AS A BOOKLET, A FILE ON THE PRODUCT CD, OR A
FILE AVAILABLE ON THE WEBSITE FROM WHICH YOU DOWNLOADED THE SOFTWARE PACKAGE). IF YOU DO NOT AGREE TO ALL OF THE TERMS SET
FORTH IN THE AGREEMENT, DO NOT INSTALL THE SOFTWARE. IF APPLICABLE, YOU MAY RETURN THE PRODUCT TO MCAFEE OR THE PLACE OF
PURCHASE FOR A FULL REFUND.

ePolicy Orchestrator 4.6.0 Scripting Guide

Contents

Preface

About this guide . . . . . .

Audience . . . . . .
Conventions . . . . .
Finding product documentation

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

.
.
.
.

Overview

5
5
5
6

Web API basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Discovering available commands through URLs . . . . . . . . . . . . . . . . . . . . . . 9
An example task with the Web API . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Python client basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Web API Python script requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Importing the McAfee Python client library . . . . . . . . . . . . . . . . . . . . 13
Authenticating with an ePolicy Orchestrator server . . . . . . . . . . . . . . . . . 13
Discovering available commands in Python . . . . . . . . . . . . . . . . . . . . . . . 14
Additional documentation included with the Web API . . . . . . . . . . . . . . . . . . . 15
Key commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Example Python scripts

Example
Example
Example
Example
Example
Example

1:
2:
3:
4:
5:
6:

19

Tagging systems from a list . . . . . . . . . . . . . . . . . .

Automating repetitive tasks on managed systems . . . . . . . . .
Automating user management . . . . . . . . . . . . . . . . .
Importing computers from external sources . . . . . . . . . . . .
Importing and exporting data . . . . . . . . . . . . . . . . . .
Automated maintenance of the System Tree . . . . . . . . . . . .

.
.
.
.

.
.
.
.
. .
. .

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.
.
.

.
.
.
.

19
20
21
22
23
. 23

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

Remote queries

25

Persistent queries . . . . . . . . . . . . . . . . . . . . . . . . .
Ad-hoc queries . . . . . . . . . . . . . . . . . . . . . . . . . .
Create an ad-hoc query from a query definition . . . . . . . . . .
Get information about registered databases and tables . . . . . . .
Queries with joins . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieve hierarchical query results . . . . . . . . . . . . . . . .
Limit query result depth . . . . . . . . . . . . . . . . . . . .
Remote query commands . . . . . . . . . . . . . . . . . . . . . .
Ad-hoc query reference . . . . . . . . . . . . . . . . . . . . . . .
General query datatypes . . . . . . . . . . . . . . . . . . .
General S-Expression operations . . . . . . . . . . . . . . . .
S-Expression operator and datatype combinations . . . . . . . . .
Special ePolicy Orchestrator data types . . . . . . . . . . . . . .
Special ePolicy Orchestrator operators . . . . . . . . . . . . . .
Special ePolicy Orchestrator operator and type combinations . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

Index

.
.
.
.
.
.
.
.

25
26
27
28
29
29
30
31
31
31
32
34
34
35
37

39

ePolicy Orchestrator 4.6.0 Scripting Guide

Preface

This guide provides the information you need to configure, use, and maintain your McAfee product.
Contents
About this guide
Finding product documentation

About this guide

This information describes the guide's target audience, the typographical conventions and icons used
in this guide, and how the guide is organized.

Audience
McAfee documentation is carefully researched and written for the target audience.
The information in this guide is intended primarily for:

Administrators People who implement and enforce the company's security program.

Users People who use the computer where the software is running and can access some or all of
its features.

Conventions
This guide uses the following typographical conventions and icons.
Book title or Emphasis Title of a book, chapter, or topic; introduction of a new term; emphasis.
Bold

Text that is strongly emphasized.

User input or Path

Commands and other text that the user types; the path of a folder or program.

Code

A code sample.

User interface

Words in the user interface including options, menus, buttons, and dialog
boxes.

Hypertext blue

A live link to a topic or to a website.

Note: Additional information, like an alternate method of accessing an option.
Tip: Suggestions and recommendations.
Important/Caution: Valuable advice to protect your computer system,
software installation, network, business, or data.
Warning: Critical advice to prevent bodily harm when using a hardware
product.

ePolicy Orchestrator 4.6.0 Scripting Guide

Preface
Finding product documentation

Finding product documentation

McAfee provides the information you need during each phase of product implementation, from
installation to daily use and troubleshooting. After a product is released, information about the product
is entered into the McAfee online KnowledgeBase.
Task
1

Go to the McAfee Technical Support ServicePortal at http://mysupport.mcafee.com.

Under Self Service, access the type of information you need:

To access...

Do this...

User documentation

1 Click Product Documentation.

2 Select a Product, then select a Version.
3 Select a product document.

KnowledgeBase

Click Search the KnowledgeBase for answers to your product questions.

Click Browse the KnowledgeBase for articles listed by product and version.

ePolicy Orchestrator 4.6.0 Scripting Guide

Overview

Version 4.6 of ePolicy Orchestrator introduces a Web API that adds scripting and automation
capabilities to common management activities such as user and System Tree maintenance and data
import and export.
In this guide, we will explain what the ePolicy Orchestrator Web API is, how to use it, and walk you
through a few exampls using a Python client. Finally, we will take a deeper look at some key
commands, including an extensive description of the query system.
Contents
Web API basics
Discovering available commands through URLs
An example task with the Web API
Python client basics
Web API Python script requirements
Discovering available commands in Python
Additional documentation included with the Web API
Key commands

Web API basics

While you will see examples in Python elsewhere in this guide, it is certainly not the only method of
using the Web API. First, we will explain using the Web API in general so you can develop your own
scripts in the language of your choosing.
Throughout this section, you will see examples using the command-line
tool wget (part of the GNU Project, 2009, Free Software Foundation,
Inc.), a utility commonly used for retrieving data from web servers. Each
example includes standard wget parameters followed by the actual
ePolicy Orchestrator Web API URL that executes a command on the
ePolicy Orchestrator server. These parameters will help you to
understand what the command does, although in practice you should
implement tighter security when it comes to trusting the site's certificate.

First, we will take a look at the syntax for the request URLs provided in ePolicy Orchestrator to
illustrate the core capabilities of the Web API.
> wget -q -O - --no-check-certificate --user=ga --password=ga "https://localhost:8443/remote/
core.help"

This wget command takes the following parameters:

ePolicy Orchestrator 4.6.0 Scripting Guide

Overview
Web API basics

Parameter

Description

-q

Quiet mode. Turns off wget's output.

-O -

Forces output to stdout. This is normally the screen.

--no-check-certificate

Tells wget to not check the server certificate.

--user

Identifies the user account interacting with the server.

--password

The password associated with the given user account.

In the examples provided in this document, you will see the ePolicy
Orchestrator server identifed as "localhost" and the destination port
identified as "8443" (the default). You need to replace these with the
server name and port number of your own installation.

The user in each example is "ga", a global administrator who has permission to execute all commands.
Web API commands follow all role-based permissions as enforced through the ePolicy Orchestrator
graphical interface.
The Web API is used primarily for two purposes:

Scripting sequences of tasks

Performing simple tasks without using the user interface

Scripts using the Web API can be run from any computer that can connect to the ePolicy Orchestrator
server. For security reasons, they should not be run on the same computer as the ePolicy Orchestrator
server itself.
Before any commands can be run, you must authenticate with an ePolicy Orchestrator server.

General syntax
The general syntax for a commend sent via HTTPS is:
https://<server>:<port>/remote/<command>?<arg1>=<val1>&<arg2>=<val2>

Additional arguments can be specified as needed.

Some commands require input in other formats, such as importing a file. This is best handled using a
tool like curl instead of wget or a URL. For example, importing an XML file containing permission sets
looks like this:
> curl -k -u ga:ga "https://localhost:8443/remote/core.importPermissionSets" -F
[email protected]

Output options
By default, commands return output in a human-readable format. When scripting, however, you
usually want commands to return data in a more machine-readable format. This is controlled with the :
output parameter.
https://localhost:8443/remote/core.help?:output=json

This returns data in JavaScript Object Notation (JSON) format. Other options include verbose
(default), terse, and xml. These arguments must be supplied as all lowercase text. In addition to :
output, :locale and :validation parameters are available.

ePolicy Orchestrator 4.6.0 Scripting Guide

Overview
Discovering available commands through URLs

Table 1-1 Output format parameters

Parameter Description

Values

:output

Specifies the output format.

verbose (default) terse, xml, json

:locale

Specifies the output locale.

Defaults to server's locale. Examples

values include en, de, cn-zh.

:validation

Specifies the validation level on the command.

Strict validation throws errors when an argument
is msising, loose validation ignores missing
arguments.

strict (default), loose

Discovering available commands through URLs

Since ePolicy Orchestrator extensions expose additional commands, you should first discover which
commands are available to you.
The core.help command tells you which commands you can access, and can also provide details on
specific commands. When invoked without any arguments, it provides a list of available commands.
> wget -q -O - --no-check-certificate --user=ga --password=ga https://localhost:8443/remote/
core.help

This returns a list that looks similar to the following. This exact list of commands will change
depending on your permissions and the extensions installed.
core.addPermSetsForUser userName permSetName - Adds permission set(s) to specified user
core.addUser userName password [fullName=<>] [email=<>] [phoneNumber=<>] [notes=<>]
[disabled=<>] [admin=<>] - Adds a user to the system
core.executeQuery queryId [database=<>] - Executes a SQUID query and returns the results
core.exportPermissionSets - Exports all permission sets.
core.help [command] [prefix=<>] - Displays a list of all commands and help strings.
core.importPermissionSets file [overwrite] - Imports permission sets.
core.listDatatypes [type] - Displays all registered datatypes and operations for those types
that the user is permitted to see.
core.listPermSets [userName] - List permission sets in the system
core.listQueries - Displays all queries that the user is permitted to see.
core.listTables [table] - Displays all SQUID tables that the user is permitted to see.
core.listUsers [permSetName] - List users in the system
core.purgeAuditLog [age] [unit] - Purge the audit log by age
core.removePermSetsForUser userName permSetName - Removes permission set(s) from a specified
user
core.removeUser userName - Removes a user from the system
core.updateUser userName [password=<>] [windowsUserName=<>] [windowsDomain=<>] [subjectDN=<>]
[newUserName=<>] [fullName=<>] [email=<>] [phoneNumber=<>] [notes=<>] [disabled=<>]
[admin=<>] - Updates an existing user
scheduler.cancelServerTask taskLogId - Terminates a currently running task
scheduler.getServerTask taskName - Gets details about a specific server task
scheduler.listAllServerTasks - Displays all server tasks
scheduler.listRunningServerTasks - Get the list of all running server tasks.
scheduler.runServerTask taskName - Runs a server task and returns the task log ID.
scheduler.updateServerTask taskName [status] - Enables or disables a server task (by default
status='enabled')
tasklog.listMessages taskLogId - Lists the messages for the specified task log entry
tasklog.listSubtasks taskLogId - Lists subtasks of a specified task log entry
tasklog.listTaskHistory [taskName] [taskSource] [maxRows] [age] [unit] - Lists task log
entries, optionally filtered by task name, task ID or task source
tasklog.listTaskSources - Lists the task sources
tasklog.purge [age] [unit] - Purges the Server Task Log beyond a given age and time unit

The object, command name, required and optional arguments, and a brief description are all included.
Optional arguments are enclosed in square brackets ("[" and "]").

ePolicy Orchestrator 4.6.0 Scripting Guide

Overview
An example task with the Web API

It can also be used to request more detailed information about specific commands. For example,
> wget -q -O - --no-check-certificate --user=ga --password=ga https://localhost:8443/remote/
core.help?command=core.listQueries

returns the following response:

OK:
core.listQueries
Displays all queries that the user is permittedto see. Returns the list of queries or throws
an error.
Requires permission to use queries.

An example task with the Web API

Before moving onto more complex scripting examples using the Python client, here is a sample task
illustrating what can be accomplished.
In this example, we use the Web API to assign a policy to a group.
Task
1

First, you need to know what the policy.assignToGroup command requires.

> wget -q -O - --no-check-certificate --user=ga --password=ga https://localhost:8443/remote/
core.help?command=policy.assignToGroup

This returns the following text:

OK:
policy.assignToGroup groupId productId objectId [resetInheritance]
Assigns policy to the specified group or resets group's inheritance for the specified
policy
Requires permission to at least one group in the System Tree and edit permission for at
least one product
Parameters:
groupId (param 1) - Group ID as returned by system.findGroups
productId (param 2) - Product ID as returned by policy.find
objectId (param 3) - Object ID as returned by policy.find
resetInheritance (param 4) - If true resets the inheritance for the specified policy on
the given group. Defaults to false.

There are three required arguments: the group ID, the ID for the product you want to assign, and
the object ID of the policy to be assigned. You could also reset the inheritance, but that argument
is not required, and we will not use it in this example.
2

Get the group ID using the system.findGroups command.

> wget -q -O - --no-check-certificate --user=ga --password=ga "https://localhost:8443/
remote/system.findGroups?searchText=My Group"

That command returns a result similar to this:

OK:
groupId: 7
groupPath: My Organization\My Group

10

ePolicy Orchestrator 4.6.0 Scripting Guide

Overview
Python client basics

Next, you need to retrieve the product ID and policy object ID by using policy.find.
> wget -q -O - --no-check-certificate --user=ga --password=ga "https://localhost:8443/
remote/policy.find?searchText=quarantine"

That command returns two results:

OK:
featureId: VIRUSCAN8700
featureName: VirusScan Enterprise
objectId: 296
objectName: McAfee Default
objectNotes:
productId: VIRUSCAN8700
productName: VirusScan Enterprise 8.7.0
typeId: 138
typeName: Quarantine Manager Policies
featureId: VIRUSCAN8700
featureName: VirusScan Enterprise
objectId: 307
objectName: My Default
objectNotes:
productId: VIRUSCAN8700
productName: VirusScan Enterprise 8.7.0
typeId: 138
typeName: Quarantine Manager Policies

Since policy.find returned two results, you need to choose one. For purposes of this example,
use the My Default policy. You've now obtained all the information you need to make the group
assignment. Finally, call policy.assignToGroup:
> wget -q -O - --no-check-certificate --user=ga --password=ga
"https://localhost:8443/remote/policy.assignToGroup?
groupId=7&productId=VIRUSSCAN8700&objectId=307"

This returns:
OK:
True

The policy has been assigned.

In general, the Web API returns three kinds of results from its commands:
1

Commands that retrieve data return that data.

Commands that operate on a single item will return True or False indicating the command's
success or failure.

Commands that operate on several items return the number of items that succeeded.

Python client basics

The supplied Python client library simplifies communication with, and exploration of, your ePolicy
Orchestrator Web API.
Using the commands in the context of a scripting language gives you a lot of flexibility, allowing you to
use the output of one command as the input to another, or conditionally perform actions based on
script input or command output.

ePolicy Orchestrator 4.6.0 Scripting Guide

11

Overview
Web API Python script requirements

Python client software requirements

The Python client requires Python version 2.5, 2.6, or 2.7, and the simplejson module must be in
your Python module search path. The source code is included in a file named mcafee.py. For your
scripts to function properly, this mcafee.py file must be placed in either the same folder as your
scripts, or in the Python module search path.

Using the client

The Python client can be used in two ways: imported into a .py script run at the command line, or in
Python interactive mode. In either case, you must follow the script requirements, which are
documented in Web API script requirements.
The client converts data returned from all commands into Python objects for ease in processing.
The source code to the client, which is included, can be used for educational purposes, in porting to
other languages, or for expanding on the client's capabilities.

Notes on parameters
Some commands such as system.clearTag can take a comma-delimited list of values as a parameter.
If you want to embed spaces in this list, you must enclose the entire list in quotes.
mysession.system.clearTag("System1, System2, System3","oldTag")

Any parameter requiring a file name uses the file:///c:\path\to\file format used in URLs.

Web API Python script requirements

Before a Python script can execute any commands, it must authenticate with an ePolicy Orchestrator
server, and retain the session value returned.

Python client script requirements

The supplied Python client includes code that makes communicating with an ePolicy Orchestrator
server easier and less error-prone. To use the client, however, you must first complete these tasks:
1

Import the McAfee library into your script.

Authenticate with the server.

After you complete these two tasks, the remainder of the script can function as desired.

12

ePolicy Orchestrator 4.6.0 Scripting Guide

Overview
Web API Python script requirements

Importing the McAfee Python client library

The client library should be imported into any script communcating with an ePolicy Orchestrator server.
Task
1

Make sure the mcafee.py file is stored in either the same folder as your script, or in the Python
module search path.

Import the client code into your script with the following command:
import mcafee

This command imports the client code, which includes a method that takes connection information,
establishes a session with the indicated server, and returns a session object.

Authenticating with an ePolicy Orchestrator server

Before any commands can be sent to an ePolicy Orchestrator server, you must authenticate with it and
store the returned session object.

Communicate with the server with the mcafee.client command and between four and six
parameters.
Table 1-2 mcafee.client parameters
Parameter Description
server

A string containing the name of the server. Do not include the https:// prefix. If
your server name is https://myserver, put myserver in this parameter.

port

A string containing the port the server uses. This is typically 443 for HTTPS
connections and 80 for HTTP connections, but can differ if your server is configured
differently.

username

A string containing the user name used for authentication.

password

A string containing the password to use for authentication.

A password used in this manner is stored in the script in clear text. Secure your
scripts appropriately. Alternatively, either prompt your user for a password, or store
the the password encrypted. Certificate authentication is not supported by the Web API.

protocol

[optional] A string containing the protocol. The default is HTTPS but HTTP is another
valid option.

outputtype [optional] A string containing the output type returned from commands. This value
defaults to json but verbose, terse, and xml are other valid values.
For example, if you normally log on to an ePolicy Orchestrator server named ourcompanyserver on
port 443 with the user name adminfred and a password of notmydOgsname37, your Python
command to log on to the same server in the same fashion would be:
mysession = mcafee.client("ourcompanyserver","443","adminfred","notmydOgsname37")

The mysession variable stores the session information used for all later commands in that script.
For example, if the next thing you wanted to do in the script was to list all the currently running
server tasks, the command would be:
mysession.scheduler.listRunningServerTasks()

ePolicy Orchestrator 4.6.0 Scripting Guide

13

Overview
Discovering available commands in Python

Discovering available commands in Python

Extensions can expose additional commands, so we have provided a way for you to determine which
commands are available on your server.
Before you begin
For these commands to work, the script must adhere to the script requirements.
Task
1

Determine the list of modules available to you using the Python dir() command.
>>> dir(mysession)

This returns a Python list that looks similar to this:

['__class__', '__delattr__', '__dict__', '__doc__', '__format__', '__getattr__',
'__getattribute__',
'__hash__', '__init__', '__module__', '__new__', '__reduce__', '__reduce_ex__',
'__repr__', '__setattr__',
'__sizeof__', '__str__', '__subclasshook__', '__weakref__', '_invoker', 'core', 'help',
'scheduler', 'tasklog']

There are a number of attributes in there, but what you should be looking for are the names at the
end without leading underscores. In this example, these are core, help, scheduler, and tasklog.
These are the objects available to you that contain commands you can execute. The names with
leading underscores are internal to either the client or Python itself.
2

To find out the list of commands in a given module, use the dir() command passing the module as
a parameter.
>>> dir(mysession.scheduler)

This returns a list of attributes and commands in the scheduler module. The list looks like this:
['__doc__', '__getattr__', '__init__', '__module__', '_invoker', '_module',
'cancelServerTask', 'getServerTask', 'listAllServerTasks', 'listRunningServerTasks',
'runServerTask', 'setServerTaskStatus']

As in the previous step, look for names without leading underscores. In this case, there are six
commands: cancelServerTask, getServerTask, listAllServerTasks, listRunningServerTasks,
runServerTask, and setServerTaskStatus.
3

Once you've found a command you're interested in, use help() and pass the command as a
parameter.
>>> mysession.help('scheduler.listRunningServerTasks')

This command returns a description like this:

scheduler.listRunningServerTasks
Get the list of all running server tasks. Returns the list of tasks or throws an error.
Requires permission to view server tasks.

This lists the command name and parameters (in this case there are none), a description of what it
does, and the permission required to execute it.
Performing similar steps for any command you find will help determine all the capabilities available for
your scripts.

14

ePolicy Orchestrator 4.6.0 Scripting Guide

Overview
Additional documentation included with the Web API

Additional documentation included with the Web API

Several HTML files are included with the Web API package that provide additional information.
All files are included in the pyclient/Python26/mcafee-docs folder contained in the package.
Table 1-3
File

Topic

FAQ.html

Contains common questions asked when using the Python client.

getting_started.html Contains a brief tutorial for writing Python scripts.

implementation.html

Contains Python client implementation details including response formats.

setup.html

Contains instructions for installing the included Python distribution, or

customizing an existing installation.

Key commands
Some commands are more commonly used than others. Being familiar with their syntax will help you
create scripts quickly.
The following tables list commonly used commands with their syntax and description. Each table
covers a different functional area.
Table 1-4 Commands for searching, querying, and listing
Command
core.executeQuery

core.help

core.listDatabases
core.listQueries
core.listTables
policy.find
repository.find
system.find

Syntax

Description

core.executeQuery queryId
[database=<>]
core.executeQuery target=<>
[select=<>] [where=<>]
[order=<>] [group=<>]
[database=<>] [depth=<>]
[joinTables=<>]

Executes a query and returns the results

as a list of objects.

Lists all registered commands, and

displays help strings.

core.help [command]
[prefix=<>]
core.listDatabases

Returns all databases the user is

permitted to see as a list of objects.

core.listQueries

Returns all queries the user is permitted

to see as a list of objects.

core.listTables [table=<>]

Returns all database tables the user is

permitted to see as a list of objects.

policy.find searchText

Finds all policies the user is permitted to

see that match the given search text.

repository.find searchText

Finds all repositories the user is permitted

to see that match the given search text.

system.find searchText

Finds systems in the System Tree.

ePolicy Orchestrator 4.6.0 Scripting Guide

15

Overview
Key commands

Table 1-5 Commands for creating, importing, and exporting

Command
core.addUser

core.importPermissionSets

core.exportPermissionSets
system.importSystem

repository.checkInPackage

Syntax
core.addUser userName password
[fullName=<>] [email=<>]
[phoneNumber=<>] [notes=<>]
[disabled=<>]
[

Description
Adds a user to the system.
Authentication parameters
are mutually exclusive:
either password,
windowsUserName/
windowsDomain, or
subjectDN can be specified.

core.importPermissionSets file
[overwrite]

Imports permission sets

from a file.

core.exportPermissionSets

Exports all permission sets.

system.importSystem fileName
branchNodeID [allowDuplicates]
[uninstallRemoved] [pushAgent]
[pushAgentForceInstall]
[pushAgentSkipIfInstalled]
[pushAgentSuppressUI]
[pushAgentInstallPath]
[pushAgentPackagePath]
[pushAgentDomainName]
[pushAgentUserName]
[pushAgentPassword]
[deleteIfRemoved]
[createNewInLostAndFound]
[flattenTreeStructure
repository.checkInPackage
packageLocation branch [option]
[moveToPrevious]
[allowUnsignedPackages]

Imports systems from a

text file or a supplied
comma-separated list.

Checks package into the

master repository.

Table 1-6 Commands for editing, assigning, and moving

Command
core.updateUser

core.addPermSetsForUser

system.applyTag
system.setUserProperties

16

Syntax
core.updateUser userName
[password=<>]
[windowsUserName=<>]
[windowsDomain=<>]
[subjectDN=<>] [newUserName=<>]
[fullName=<>]
[email=<>] [phoneNumber=<>]
[notes=<>]
[disabled=<>] [admin=<>]
core.addPermSetsForUser userName
permSetName
system.applyTag names tagName
system.setUserProperties name
[description] [customField1]
[customField2] [customField3]
[customField4]

ePolicy Orchestrator 4.6.0 Scripting Guide

Description
Updates an existing user.
Authentication parameters are
mutually exclusive: either
password, windowsUserName/
windowsDomain, or subjectDN
can be specified.

Adds the given permission set

to the specified user.
Assigns the given tag to a
supplied list of systems.
Sets user properties on the
given system.

Overview
Key commands

Table 1-6 Commands for editing, assigning, and moving (continued)

Command

Syntax

system.deployAgent

Description

system.deployAgent names username

[password]
[agentPackage] [skipIfInstalled]
[suppressUI]
[forceInstall] [installPath]
[domain]

policy.assignToSystem

policy.assignToSystem names
productId typeId objectId
[resetInheritance]

Deploys an agent to the given

list of systems.

Assigns the policy to a

supplied list of systems.

Table 1-7 Commands for running and aborting

Command

Syntax

clienttask.run

system.wakeupAgent

repository.pull

Runs the client task on

a supplied list of
systems.

clienttask.run names productId

taskID
[retryAttempts]
[retryIntervalInSeconds]
[abortAfterMinutes]
[useAllAgentHandlers]
[stopAfterMinutes]
[randomizationInterval]

scheduler.cancelServerTask
scheduler.runServerTask

Description

scheduler.cancelServerTask taskLogId

Terminates a currently
running task.

scheduler.runServerTask taskName

Runs the specified

server task.

system.wakeupAgent names [fullProps]

[superAgent] [randomMinutes]
[forceFullPolicyUpdate]
[useAllHandlers]
[retryIntervalSeconds]
[attempts] [abortAfterMinutes]
[includeSubgroups]
repository.pull sourceRepository
targetBranch [moveToPrevious]
[productList]

Wakes up the agent on

a supplied list of
systems.

Pulls packages from the

source repository.

Table 1-8 Commands for deleting and purging

Command
commonevent.purgeEvents

core.purgeAuditLog
system.delete

tasklog.purge

Syntax

Description

commonevent.purgeEvents queryId
[unit]
core.purgeAuditLog [age] [unit]
system.delete names [uninstall]

tasklog.purge [age] [unit]

Deletes threat events based on

age or a queryId. The query
must be table based.
Purges the audit log by age.
Deletes systems from an ePolicy
Orchestrator server by name or
ID.
Purges the task log by age.
Defaults to purging all entries.

ePolicy Orchestrator 4.6.0 Scripting Guide

17

Example Python scripts

There are a number of typical tasks easily completed with scripts.

These examples are taken from differing categories of tasks showing the various ways scripting can
help keep your ePolicy Orchestrator servers maintained and up-to-date.
Go through these scripts in the presented order. They slowly build on each other, and concepts
explained in the early scripts are used in later examples without repeating that explanation.
1

Tag systems from a list.

Take a tag as input and send an agent wakeup call to all systems with that tag.

Apply automation to cleaning up disabled ePolicy Orchestrator users.

Import computers from an external file and adding them to the System Tree.

Export policies and client tasks from one ePolicy Orchestrator server and import them into another.

Organize your System Tree.

Contents
Example 1: Tagging systems from a list
Example 2: Automating repetitive tasks on managed systems
Example 3: Automating user management
Example 4: Importing computers from external sources
Example 5: Importing and exporting data
Example 6: Automated maintenance of the System Tree

Example 1: Tagging systems from a list

This example teaches you the basics of writing Python scripts using the ePolicy Orchestrator Web API.
This script assumes you have a text file with a list of managed systems and you want to apply a
specific tag to every system in that list. After showing you the entire script, we'll examine individual
parts in detail.
#Example 1
import mcafee
mc = mcafee.client('localhost','8443','ga','ga')
file = open('C:/path/to/myfile.txt', 'r')
for line in file:
mc.system.applyTag(line, 'myTag')

ePolicy Orchestrator 4.6.0 Scripting Guide

19

Example Python scripts

Example 2: Automating repetitive tasks on managed systems

That's all there is to it. There are some assumptions made in this script: the input file exists, it lists
one system per line, the systems are listed by name or IP address, and the tag named myTag exists. A
more robust script would handle those assumptions, but that would complicate this example. Now, to
examine the various sections in detail.
import mcafee

This line imports the provided McAfee Python module (mcafee.py), which means that this file should
be kept in the same directory as your script.
mc = mcafee.client('localhost','8443','ga','ga')

Here is where you create the connection to the ePolicy Orchestrator server by specifying the server
name, connection port, username, and password, in that order. This initialization function can take up
to two more parameters that specify the protocol and the presentation of the output. The full
parameter list is:
mc = mcafee.client('yourservername','port','username','password', 'protocol',
'outputtype')
The protocol defaults to https but you may specify http if SSL is disabled on your ePolicy
Orchestrator server.
The outputtype determines the format of output from commands as described in Web API Basics.
With those two lines, you've established a connection to your server. Next, you need to create your file
handle in read-only mode.
file = open('C:/path/to/myfile.txt')

Finally, you need to iterate through the file and run the command system.applyTag to each system in
the file:
for line in file:
mc.system.applyTag(line, "myTag")

After finishing the loop, each system in the file should now have the tag myTag applied.

Example 2: Automating repetitive tasks on managed systems

This script takes a tag name for input and sends an Agent wakeup call to all systems having that tag.
#Example 2
import mcafee
mc = mcafee.client('localhost','8443','ga','ga', 'https','json')
input = sys.argv[1] #input to the script, our tag name
systems = mc.system.find(input)
# JSON data structures map to Python data types:
for system in systems:
id = system['EPOComputerProperties.ParentID']
result = mc.system.wakeupAgent(id)

This script takes a single argument as input. It then uses the system.find command to search for all
computers that have the corresponding tag. You could input something other than a tag, however, as
the system.find description reads: "Find Systems in the ePolicy Orchestrator tree by name, IP
address, MAC address, user name, AgentGUID or tag."

20

ePolicy Orchestrator 4.6.0 Scripting Guide

Example Python scripts

Example 3: Automating user management

By default system.find returns a list of JSON-formatted systems, but the script ensures this by
specifying JSON output in the ePolicy Orchestrator connection parameters. Because JSON data
structures map directly to Python data types, in Python you can simply assign the results of the find
command to a Python variable.
The script above uses the EPOComputerProperties.ParentID property to send to the
system.wakeupAgent command, but as that command also takes a name, that line could have been
written as:
id = system['EPOComputerProperties.ComputerName']

Also, since system.wakeupAgent also accepts a list of names or IDs as input, you could have built a
comma-delimited string and sent the list to the command directly.

Example 3: Automating user management

This script looks through all ePolicy Orchestrator users and deletes those marked as "disabled" if they
are not administrators.
This script also provides more detailed handling of actions, and provides success or failure feedback to
the user. It also handles an exception if user deletion is unsuccessful.
#Example 3
import mcafee
mc = mcafee.client('localhost','8443','ga','ga','https','json')
users = mc.core.listUsers();
for user in users:
if user['disabled'] == 'true' and user['admin'] == 'false':
id = user['id']
try:
mc.core.removeUser(id)
print 'Removed disabled user ' + user['name']
except Exception, e:
print 'Error removing user ' + user['name'] + ' Cause:' + str(e)

It helps to examine the output from the core.listUsers command to see the available properties.
This script uses the disabled, admin and name properties to achieve its purpose. Note that the
core.removeUser command needs administrator privileges to execute. Required privileges for each
command are listed in its detailed help.
The core.listUsers command returns different values for the authType in machine-readable formats
than it does in human-readable formats such as used in the user interface.
Human readable

Machine readable

MFS authentication

pwd

Certificate Based Authentication

cert

Windows authentication

ntlm

ePolicy Orchestrator 4.6.0 Scripting Guide

21

Example Python scripts

Example 4: Importing computers from external sources

Example 4: Importing computers from external sources

This script takes a comma-delimited file containing system information, and imports those systems
into an ePolicy Orchestrator server.
This script assumes there are two source files. One (myfile.txt) contains the group to which systems
are added, and the second (systemsToAdd.txt) contains one system per line with the following
comma-delimited properties in this order: MAC address, IP address, system name, and domain name.
#Example 4
import mcafee, sys
mc = mcafee.client('localhost','8443','ga','ga','https','json')
file = open('C:/path/to/myfile.txt', 'r')
for line in file:
#determine the ID of the group to add it to
groups = mc.system.findGroups('Lost&Found')
groupId = -1
for group in groups:
if group['groupPath'] == 'My Organization\\Lost&Found']:
groupId = group['groupId']
if groupId == -1:
error = 'Error finding the specified group.'
sys.exit(error)
#now that we have the group id, pull in the systems from file
sourceId = "12"
sourceType = "CLI"
file = open('C:/path/to/systemsToAdd.txt', 'r')
for line in file:
sysProps = line.split(',')
systemId = mc.detectedsystem.add(sourceId,sourceType,sysProps[0],sysProps[1],
dnsName=sysProps[2],domainName=sysProps[4])
detectedsystem.addToTree(systemId,groupId)

First, we need to know where to add the systems. The script uses the system.findGroups()
command to search for it by name, and from that obtain the group ID. The systems are added with
the detectedsystem.add command. This command has numerous optional parameters:
detectedsystem.add sourceID sourceType MAC IPAddress [IPSubnet][IPSubnetMask][dnsName]
[OSPlatform] [OSFamily] [OSVersion]
[domain] [netbiosName][netbiosComment] [users] [agentGUID] [detectedTime] [externalID]

You can add optional parameters in order (using non-sensical values for parameters you aren't
providing) which would look look like:
mc.detectedsystem.add(sourceId, sourceType,sysProps[0], sysProps[1], 0.0.0.0, 0.0.0.0,
sysProps[2], '', '',
'', sysProps[4])

Or you can assign parameters by name, as done for the dnsName and domainName parameters in the
script above. Note that the parameters sourceID and sourceType are arbitrary values defined by
whomever is adding the systems. These are stored in the database so that we can tell what source
detected or added any given system.
The return value of this command is the ID of the newly-added detected system. You use this ID as
input to the next command () which adds detected systems into the System Tree.
detectedsystem.addToTree UIDs branchNodeID [allowDuplicates] [dirSort]

By default, the system will not be added if it's a duplicate nor will it be automatically sorted, but you
can override these behaviors if desired. This script accepts the defaults and, using the newly-obtained
detected system ID and the group ID found earlier, moves this system into the System Tree.

22

ePolicy Orchestrator 4.6.0 Scripting Guide

Example Python scripts

Example 5: Importing and exporting data

Example 5: Importing and exporting data

This script shows how to export data from and import data to an ePolicy Orchestrator server.
Importing and exporting common settings for permissions, policies, or other ePolicy Orchestrator
objects is quite useful when performing server migrations, setting up a secondary ePolicy Orchestrator
server, or simply creating a test environment. Scripting can take advantage of the export options
ePolicy Orchestrator software has to offer. This script shows first how to export policies and client
tasks for a given product, then import them to a second server.
#Example 5
import mcafee
mc = mcafee.client('localhost','8443','ga','ga','https','json')
#find the product id
productId = None
policies = mc.policy.find('McAfee Agent')
for policy in policies:
productId = policy['productId']
if productId == None:
error = 'Error finding the product id.'
sys.exit(error)
tasks = mc.clienttask.export(productId=productId)
file = open('tasks.xml', 'w')
print >>file, tasks
file.close()
policies = mc.policy.export(productId=productId)
file = open('policies.xml', 'w')
print >>file, policies
file.close()
#import these into another server:
mc2 = mcafee.client('anotherEpoServer','8443','ga','ga','https','json')
mc2.clienttask.importClientTask(uploadFile='file:///tasks.xml')
mc2.policy.importPolicy(file='file:///policies.xml')

First, retrieve the product ID by searching for a policy containing the string 'McAfee Agent'. Using
that product ID, you can then export all of the client tasks and policies for that product. Finally, create
a connection to a second ePolicy Orchestrator server (mc2) and run the corresponding import
commands on that server.

Example 6: Automated maintenance of the System Tree

This script re-applies the System Tree sorting rules to any systems found in the Lost & Found group.
#Example 6
import mcafee
mc = mcafee.client('localhost','8443','ga','ga','https','json')
#first, as before, let's fetch the id of the Lost & Found group
groups = mc.system.findGroups('Lost&Found')
groupId = -1
for group in groups:
if group['groupPath'] == 'My Organization\\Lost&Found']:
groupId = group['groupId']
if groupId == -1:
error = 'Error finding the specified group.'
sys.exit(error)
#find all systems for this group
systems = mc.epogroup.findSystems(groupId,'true')
for system in systems:

ePolicy Orchestrator 4.6.0 Scripting Guide

23

Example Python scripts

Example 6: Automated maintenance of the System Tree

id = system['EPOComputerProperties.ParentID']
mc.system.resort(id)

This should be fairly straightforward given the previous scenarios. Here we introduce a new command
epogroup.findSystems which finds all systems in a given group. The last parameter determines
whether to search all subgroups as well. In this case, we set this parameter to true, iterating through
all systems found under Lost & Found and any of its subgroups and reapplying the sorting rules to
them.

24

ePolicy Orchestrator 4.6.0 Scripting Guide

Remote queries

ePolicy Orchestrator remote commands allow you to query for data remotely using the Web API. These
commands allow you to execute persistent queries that exist in the ePolicy Orchestrator database as
well as dynamic, customer-defined ad-hoc queries.
Contents
Persistent queries
Ad-hoc queries
Queries with joins
Remote query commands
Ad-hoc query reference

Persistent queries
A persistent query is a query that is accessible via the Queries and Reports page in the ePolicy
Orchestrator user interface.
Persistent queries include both pre-installed queries and queries created by users. To remotely execute
a persistent query, you must know the query's ID.
In all examples, the first two lines contain the URL and Python forms of
the command.

Find available queries

The core.listQueries command is used to obtain the ID of any persistent query that the user can
access.
URL: https://servername:port/remote/core.listQueries
Python: mysession.core.listQueries();
OK:
Id: 1
Name: Effective permissions for users
Description: Shows all the permissions for each user
Criteria: ( where ( ne EntitlementView.RoleUri "%%NOEPOROLES%%" ) )
Group Name: Permission Queries
Owner: ga
Database Type:
Target: EntitlementView
Created by: ga
Created on: 10/25/10 8:40:33 AM PDT
Modified by: ga
Modified on: 10/25/10 8:40:33 AM PDT
Id: 2
Name: Permission set details
Description: Shows the permissions associated with each permission set

ePolicy Orchestrator 4.6.0 Scripting Guide

25

Remote queries
Ad-hoc queries

Remotely execute the query

Once the ID of the query is known, run the core.executeQuery command with the queryId
parameter set to the appropriate value.
URL: https://servername:port/remote/core.executeQuery?queryId=5
Python: mysession.core.executeQuery('5');
OK:
User Name: ga
Action: Create Response
Success: true
Start Time: 10/26/10 9:00:24 AM PDT
User Name: ga
Action: Create Response
Success: true
Start Time: 10/26/10 9:00:24 AM PDT

Ad-hoc queries
Ad-hoc queries are performed entirely remotely, and do not rely on a query stored in an ePolicy
Orchestrator database.
In an ad-hoc query, you specify the target of the query and up to four parameters.
Table 3-1 Ad-hoc query parameters
Clause

Description

Behavior if omitted

select

Controls which columns from the target table (and

any joined tables) are returned by the query.

All columns in the target table are

returned.

condition The condition parameter filters results. Only

records in the database that satisfy the filtering
clause are returned.

All rows are returned.

group

Controls grouping of the returned data.

The returned data are not grouped.

order

Controls the order of the returned data (either

ascending or descending by columns).

The returned rows are ordered

according to the natural order of the
database.

IYou can use the core.listTables, core.listDatabases, and core.listDatatypes commands to

determine the names and types of target table columns. This information should make it easy to
determine which columns to select, and which operations are allowed in the condition.

Example Ad-hoc queries

This is a simple ad-hoc query against the OrionAuditLog table.
URL: https://servername:port/remote/core.executeQuery?target=OrionAuditLog&select=(select
OrionAuditLog.Username OriontAuditLog.CmdName)
Python: mysession.core.executeQuery(target="OrionAuditLog", select="(select
OrionAuditLog.UserName OrionAuditLog.CmdName)");
OK:
User Name:
Action: Server restart
User Name: ga
Action: Login attempt
User Name: ga

26

ePolicy Orchestrator 4.6.0 Scripting Guide

Remote queries
Ad-hoc queries

Action: Upload Extension

This query returns the CmdName and EndTime for all audit log entries. The results are grouped
alphabeticallyby the CmdName, then by the EndDate.
URL: https://servername:port/remote/core.executeQuery?target=OrionAuditLog&select=(select
OrionAuditLog.CmdName.OrionAuditLog.EndTime)&group=(group.OrionAuditLog.CmdName
OrionAuditLog.EndTime)
Python: mysessioncore.executeQuery(target="OrionAuditLog", select="(select
OrionAuditLog.CmdName OrionAuditLog.EndTime)",
group="(group OrionAuditLog.CmdName OrionAuditLog.EndTime)");

This query returns all the OrionTaskLog entries that were created by the GA user. The results are listed
in ascending order of the task StartDate.
URL: https://servername:port/remote/core.executeQuery?target=OrionTaskLogTask&where=(where
( eq ( OrionTaskLogTask .UserName "ga" ))) &order=(order (asc OrionTaskLogTask.StartDate) )
Python: mysession.core.executeQuery(target="OrionTaskLogTask", where="(where ( eq
( OrionTaskLogTask .UserName "ga" )))", order="(order (asc OrionTaskLogTask.StartDate) )");

ePolicy Orchestrator uses S-Expressions (S-Exps) internally as a portable and database-agnostic

schema to define queries and operations. Because of this, the values passed to each parameter must
be valid S-Exps.

Create an ad-hoc query from a query definition

Queries stored in ePolicy Orchestrator can be exported and duplicated in a script.
If you have an existing persistent query and you would like to define it in terms of an ad-hoc query
using core.executeQuery, you can use the Export Definitions action in ePolicy Orchestrator to obtain the
internal representation of the query. In almost all cases, the exported definition can be used to
construct the core.executeQuery method call. Following is an example of using an exported
persistent query to create an ad-hoc query.
A primary use for this technique is to start with an existing query as a model, then modify the
parameters, filtering, or sorting when executing the query from a script.

Example
A typical exported query definition:
<query>
<name language="en">My AuditLogQuery</name>
<description language="en"></description>
<property name="target">OrionAuditLog</property>
<property name="tableURI">query:table?orion.table.columns=OrionAuditLog.UserName
%3AOrionAuditLog.CmdName%3A
OrionAuditLog.Success
%3AOrionAuditLog.StartTime&amp;orion.table.order.by=OrionAuditLog.CmdName
&amp;orion.table.order=asc</property>
<property name="conditionURI">query:condition?orion.condition.sexp=%28+where+%28+olderThan+
OrionAuditLog.EndTime+3600000++%29+%29</property>
<property name="summaryURI">query:summary?
orion.sum.query=false&amp;orion.query.type=table.table</property>
</query>

You can dissect this definition as follows:

ePolicy Orchestrator 4.6.0 Scripting Guide

27

Remote queries
Ad-hoc queries

The target attribute is used directly as the target parameter of the ad-hoc query.

The tableURI attribute contains S-Expressions that can be used as part of the selection, as well as
part of the order parameter.

The conditionURI attribute contains the S-Expression that can be used as the where parameter.

Keep in mind that the exported form of the query contains strings that are url-encoded. To form a
valid query string, you will need to decode the url-encoded characters. For example, "+" is used for a
single space " ", %28 is an opening parenthesis "(", %29 is a closing parenthesis ")", and so on.
Thus the equivalent ad-hoc query would be this.
https://servername:port/remote/core.executeQuery?target=OrionAuditLog&select=(select
OrionAuditLog.UserName OrionAuditLog.CmdName OrionAuditLog.Success
OrionAuditLog.StartTime)&where=(where(olderThan OrionAuditLog.EndTime
36000000))&order=(order(asc OrionAuditLog.CmdName))

Or in Python, this.
mysession.core.executeQuery(target="OrionAuditLog",
select="(select OrionAuditLog.UserName OrionAuditLog.CmdName OrionAuditLog.Success
OrionAuditLog.StartTime)",
where="(where(olderThan OrionAuditLog.EndTime 36000000))",
order="(order(asc OrionAuditLog.CmdName))");

Get information about registered databases and tables

Registered database table information is frequently needed to create ad-hoc queries.
The core.listTables command can be used to obtain details about each table in the system,
including the names and types of the columns.

Example output
The following output is from the core.listTables command run on the OrionAuditLog table.
Name: Audit Log Entries
Target: OrionAuditLog
Type: target
Database Type:
Description: Retrieves information
Columns:
Name
Type
Select?
--------- ------------- ------AutoId
int
false
UserId
int
false
UserName string_lookup true
Priority enum
true
CmdName
string_lookup true
Message
string
true
Success
boolean
true
StartTime timestamp
true
EndTime
timestamp
true
Related Tables:
Name
---Foreign Keys: None

28

ePolicy Orchestrator 4.6.0 Scripting Guide

on changes and actions made by users of this server.

Condition?
---------false
false
true
true
true
true
true
true
true

GroupBy?
-------false
false
true
true
true
false
true
true
true

Order?
-----true
true
true
true
true
true
true
true
true

Number?
------true
true
false
false
false
false
false
false
false

Remote queries
Queries with joins

The command lists the columns, their types, whether or not the column can be used in the select,
condition, group, or order parameters, and whether the column is a number. It also lists any
registered related tables that can be joined with the joinTables parameter.

Get information on registered databases

The core.listDatabases command can be used to obtain details about each database in the system.
This information can then be used to formulate ad-hoc queries.
In general, when issuing queries against targets that are not part of the default schema, prepend the
database name to the target. For example, to reference an "OutsidePolicy" target that is part of an
"Outsider" database, you would use the identifier "target=Outsider.OutsidePolicy".

Queries with joins

Joins between two or more tables are handled automatically.
To take advantage of this functionality, you must specify the tables (targets) and the columns from
those tables that you want in the core.executeQuery select parameter. The underlying query
system computes the necessary join criteria transparently and the results are shown correctly.
If there is no join information registered for the tables, an error results when the query is issued.
You can use the core.listTables command to inspect the tables and determine which tables are
related and thus capable of participating in joins. The relatedTables table property contains this
information.

Example query with a join

This example executes a simple join between the OrionTaskLogTask and OrionTaskLogMessage tables.
URL: https://servername:port/remote/core.executeQuery?
target=OrionTaskLogTaskMessage&select=(select OrionTaskLogTask.Name
OrionTaskLogTaskMessage.Name)
Python: mysession.core.executeQuery(target="OrionTaskLogMessage", select="(select
OrionTaskLogTask.Name OrionTaskLogTaskMessage.Message)");
OK:
Name: New Task
Message: Purge audit log
Name: New Task
Message: Purge audit log (Purge log records older than: 1 days)

Retrieve hierarchical query results

Queries involving joined tables can return results in a hierarchy.
The core.executeQuery command can also be used in joinTables mode. In this mode, you specify
only the tables you want joined. The results of the query are used as keys to perform a subquery for
all related results from the joined table. This creates an hierarchical result set that can contain nested
results. The results are nested to a level that depends on how many join tables are specified.
To join tables using core.executeQuery, you specify a comma-separated list of tables to join as the
joinTables parameter. You do not specify a select parameter when joining tables. The results are
returned as a result hierarchy with each record of the parent table becoming the parent node of the
related records in each child table. This continues until all joined tables are considered.

ePolicy Orchestrator 4.6.0 Scripting Guide

29

Remote queries
Queries with joins

Example
The following is an example of executing a simple join between the OrionTaskLog and the
OrionTaskLogMessage tables. You can see from the output that the core.executeQuery command
returned each top-level object (the OrionTaskLogTask record) and its two associated message
records. For this example, the output is shown as xml to highlight the hierarchical arrangement of the
results.
OK:
<?xml version="1.0" encoding="UTF-8"?>
<result>
<list>
<row>
<OrionTaskLogTask.Name>New Task</OrionTaskLogTask.Name>
<OrionTaskLogTask.StartDate>2010-11-23T13:01:37-08:00</OrionTaskLogTask.StartDate>
<OrionTaskLogTask.EndDate>2010-11-23T13:01:37-08:00</OrionTaskLogTask.EndDate>
<OrionTaskLogTask.UserName>ga</OrionTaskLogTask.UserName>
<OrionTaskLogTask.Status>0</OrionTaskLogTask.Status>
<OrionTaskLogTask.TaskSource>scheduler</OrionTaskLogTask.TaskSource>
<OrionTaskLogTask.Duration>493</OrionTaskLogTask.Duration>
<OrionTaskLogTaskMessage>
<list>
<row>
<OrionTaskLogTaskMessage.Message>Purge audit log</OrionTaskLogTaskMessage.Message>
</row>
<row>
<OrionTaskLogTaskMessage.Message>Purge audit log (Purge log records older than: 1 days)</
OrionTaskLogTaskMessage.Message>
</row>
</list>
</OrionTaskLogTaskMessage>
</row>
</list>
</result>

Limit query result depth

Queries that join tables can return results with deep hierarchies. You can control this depth.
A query that doesn't use joins returns tabular results. Tabular results are defined as having a depth of
one. Queries that use the joinTable parameter return hierarchical results. Specifying more than one
table in a joinTable parameter can result in a multi-level result set. Each level of objects increases
the result depth by one. To prevent result sets from becoming too deep, the core.executeQuery
command defaults to a maximum depth of 5 levels. Should this default limit prove too restrictive for
the query being run, it can be changed by supplying a new value for the depth parameter.
Ad-hoc queries that return deep result sets can take a long time and can
consume a lot of system resources to generate. Keep this in mind when
joining more than two tables, or increasing the query result depth limit.

30

ePolicy Orchestrator 4.6.0 Scripting Guide

Remote queries
Remote query commands

Remote query commands

There are a small number of commands you can use when executing remote queries.
Table 3-2

Remote query commands

Command

Syntax

Description

core.executeQuery

core.executeQuery queryId
[database=<>]

Executes a query and returns the results

as a list of objects.

core.executeQuery target=<>
[select=<>] [where=<>] [order=<
>] [group=<>] [database=<>]
[depth=<>] [joinTables=<>]
core.listDatabases core.listDatabases

Returns all databases the user is

permitted to see as a list of objects.

core.listTables

core.listTables [table]

Returns all database tables the user is

permitted to see as a list of objects.

core.listQueries

core.listQueries

Returns all queries the user is permitted

to see as a list of objects.

core.listDatatypes core.listDatatypes

Returns a list of all types and their

supported operations.

Ad-hoc query reference

Ad-hoc queries require operators, datatypes, and other information that can be acquired
programmatically.
The following tables cover these basic elements and give examples of their use.
In general, operators that a particular column supports are dictated by the datatype in the column. For
example, string columns support the startsWith and endsWith operations, number columns support
the gt and lt operations. The types of columns in a target can be obtained by using the core
.listTables command.

General query datatypes

Data stored in ePolicy Orchestrator databases have specific types.
Table 3-3

General query datatypes

Type

Description

Int

An integer

string_lookup

A lookup string field

Enum

An enumerated value, generally stored in the database as an integer

Mac

A MAC address

Long

A long value

Float

A float value

Timespan

An SQL timespan

boolean

A Boolean value

string_enum

An enumerated value stored as a string instead of an integer

ePolicy Orchestrator 4.6.0 Scripting Guide

31

Remote queries
Ad-hoc query reference

Table 3-3

General query datatypes (continued)

Type

Description

ipv4

An IPv4 address

ipv6

An IPv6 address

General S-Expression operations

These operators can be used on s-expressions.
Table 3-4

32

General S-Expression Operations

Operator

Description

Example

and

Logical AND of two or more

S-Expressions.

(where (and (eq OrionAuditLog

.UserName "ga") (eq OrionAuditLog
.Priority 1)))

or

Logical OR of two or more S-Expressions. (where (or (eq OrionAuditLog

.UserName "ga") (eq OrionAuditLog
.UserName "admin")))

not

Logical negation of an S-Expression.

(where (not (eq OrionAuditLog

.UserName "ga")))

eq

Logical comparison for equality.

(where (eq OrionAuditLog.UserName

"ga"))

ne

Logical comparison for inequality.

(where (ne OrionAuditLog.UserName

"ga"))

gt

Logical comparison for greater than.

(where (gt OrionAuditLog.Priority

1))

lt

Logical comparison for less than.

(where (lt OrionAuditLog.Priority

3))

ge

Logical comparison for greater than or

equal.

(where (ge OrionAuditLog.Priority

2))

le

Logical comparison for less than or equal. (where (le OrionAuditLog.Priority

2))

is_Blank

Returns the row if the column value is

null or the trimmed value is empty.

(where (isBlank OrionAuditLog

.UserName))

not_isBlank

Returns the row if the column value is

not null or the trimmed value is not
empty.

(where (not_isBlank OrionAuditLog

.UserName)))

in

Returns the row if the following item

(usually a property or value) is in a
following list. This is similar to the SQL
IN directive.

(where (in OrionAuditLog.UserName

"ga" "bob"))

contains

Returns the row if the column value

contains the stubstring argument value.

(where (contains OrionAuditLog

.UserName "ga"))

notContains

Returns the row if the column value does (where (notContains OrionAuditLog
.UserName "ga"))
not contain the stubstring argument
value.

startsWith

(where (startsWith OrionAuditLog

Returns the row if the string starts with
the supplied string. Similar to column in .UserName "g"))
s% in SQL.

endsWith

Returns the row if the column ends with

the argument value.

ePolicy Orchestrator 4.6.0 Scripting Guide

(where (endsWith OrionAuditLog

.UserName "a"))

Remote queries
Ad-hoc query reference

Table 3-4

General S-Expression Operations (continued)

Operator

Description

Example

like

Returns the row if the column contains a (where (like OrionAuditLog.UserName

"ga"))
value that matches the pattern. Similar
to like in SQL.

newerThan

Returns the row if the first timestamp

parameter is newer than the second
timestamp parameter.

(where (newerThan OrionAuditLog

.EndTime 3600000))

olderThan

Returns the row if the first timestamp

parameter is older than the second
timestamp parameter.

(where (olderThan OrionAuditLog

.EndTime 36000000))

between

Returns the row if the timestamp or IP

address argument (column or value)
likes between the two values.

(where (between OrionAuditLog

.EndTime (timestamp 1288888320000)
(timestamp 1288888360000)))

beforeNow

Returns the row if the timestamp value

(column or value) is before the current
time.

(where (beforeNow OrionAuditLog

.EndTime))

match_any

Returns the row if the IP address

matches one in the following list.

(where(match_any
EPOComputerProperties.IPV4x (ipv4
"192.168.1.1")))

notBetween

Returns the row if the IP address is not

between the two argument addresses.

(where (notBetween
EPOComputerProperties.IPV4x (ipv4
"192.168.1.1")(ipv4 "192.168.255.
255")))

not_in_subnet

Returns the row if the address is not in

the given subnet.

(where (not_in_subnet
EPOComputerProperties.IPV4x (ipv4
"255.255.255.0" ) 25 ))

in_subnet

Returns the row if the address is in the

given subnet.

(where (in_subnet
EPOComputerProperties.IPV4x (ipv4
"255.255.255.0" ) 25 ))

in_ipv6_subnet Returns the row if the address is in an

IPv6 subnet.

(where (not_in_ipv6_subnet
EPOComputerProperties.IPV6 (ipv6 "0
.0.0.0") 1))

not_match_any Returns the row if the argument IPv6

address does not match one of the
argument addresses.

(where(not_match_any
EPOComputerProperties.IPV6 (ipv6
"fc00::/7")))

Table 3-5

Selection-only S-Expressions

Operator Description

Example

Distinct

(select (distinct) OrionAuditLog

.UserName)

Selects records that contain a distinct output

value in a given column. Similar to the SQL
distinct directive.

If you use an order clause with select distinct, you must include the order columns in
the selection.

Top N

Selects the first N records to display. N must be

an integer. Similar to the Microsoft SQL Top, or
the MySQL Limit clause.

(select (top 5) OrionTaskLogTask

.Name OrionTaskLogTask
.StartDate)

ePolicy Orchestrator 4.6.0 Scripting Guide

33

Remote queries
Ad-hoc query reference

S-Expression operator and datatype combinations

Only certain datatypes can be used with each operator.

Special ePolicy Orchestrator data types

ePolicy Orchestrator creates a number of special data types used for various objects.
Table 3-6

34

Special ePolicy Orchestrator data types

Type

Description

applied_tags

Used for the EPOLeafNode.AppliedTags column to determine which tags

are applied to a system.

byte

Used for memory storage units such as EPOComputerProperties

.TotalPhysicalMemory and EPOComputerProperties.FreeMemory.

eventID

Used for identifying events such as Threat Events.

group

Used for groups in the System Tree. For example Groups.L1ParentID.

multiselect_group

Used for selecting multiple System Tree groups.

managedState

A Boolean value used for the managed status of a device in the System
Tree.

Megabytes

Used for disk storage units such as EPOComputerProperties

.FreeDiskSpace and EPOComputerProperties.TotalDiskSpace.

optionGroup_enum

An enumeration of grouped lists such as policy categories.

Percentagefromstring

Used for percentages and is generally used for compliance columns.

ePolicy Orchestrator 4.6.0 Scripting Guide

Remote queries
Ad-hoc query reference

Table 3-6

Special ePolicy Orchestrator data types (continued)

Type

Description

Policycolumn

Used for policies.

productVersion

Used for version numbers. Behaves normally when using equality

functions, but handles numeric strings with more than one decimal point.

Rsdmac

Used for MAC addresses. Most often associated with detected systems.

Rsdoui

Used for OUIs associated with detected systems.

string_lookupWithResolver Used to allow the user to choose from a list of known string values.
Threatcategory

A grouped enumeration used for listing the available threat categories.

DATversion

Used for DAT version information.

engineVersion

Used for engine version information.

datVersion

Used for DAT version information. Identical to DATversion.

Special ePolicy Orchestrator operators

ePolicy Orchestrator defines a number of operators designed to operate on its own custom datatypes.
Table 3-7

ePolicy Orchestrator special operators

Operator

Description

Example

hasTag

Evaluates to true if the

specified tag is applied to
the system.

(hasTag EPOLeafNode.AppliedTags
'fullTagName')

containsTag

(containsTag EPOLeafNode
Evaluates to true if any
tags applied to the system .AppliedTags 'partialTagName')
contain the specified partial
tag name.

hasTagExcluded

(hasTagExcluded EPOLeafNode
Evaluates to true if the
specified tag is excluded on .AppliedTags 'excludedTagName')
the system.

doesNotHaveTag

Evaluates to true if the

specified tag is not applied
to the system.

(doesNotHaveTag EPOLeafNode
.AppliedTags 'fullTagName')

doesNotHaveAnyTag

Evaluates to true if the

system has no tags applied
to it.

(doesNotHaveAnyTag EPOLeafNode
.AppliedTags)

childOf

Returns rows that are direct (childOf EPOLeafNode.parentId

<nodeId1> <nodeId2> ...)
descendants of the given
nodes.

descendsFrom

Returns rows that are

descended from the given
nodes.

(descendsFrom EPOLeafNode
.parentId <nodeId1> <nodeId2> ...
)

stateEq

Evaluates to true if the

managed state of the
system matches either
"managed" or
"unmanaged".

(stateEq EPOLeafNode
.ManagedState
["managed"|"unmanaged"])

version_eq

Evaluates to true if the

versions are equal using
dotted version notation.

(version_eq EPOMasterCatalog
.ProductVersion '3.1.4.1')

ePolicy Orchestrator 4.6.0 Scripting Guide

35

Remote queries
Ad-hoc query reference

Table 3-7

ePolicy Orchestrator special operators (continued)

Operator

Description

Example

version_neq

Evaluates to true if the

versions are not equal
using dotted version
notation.

(version_neq EPOMasterCatalog
.ProductVersion '3.1.4.1')

version_ge

Evaluates to true if the first

version is greater or equal
to the second using dotted
version notation.

(version_ge EPOMasterCatalog
.ProductVersion '3.1.4.1')

version_lt

Evaluates to true if the first (version_lt EPOMasterCatalog

.ProductVersion '3.1.4.1')
version is less than the
second using dotted version
notation.

threatcategory_belongs

Returns the row if the

threat category belongs to
the given group.

(threatcategory_belongs
EPOEvents.ThreatCategory 'av')

threatcategory_not_belongs

Returns the row if the

threat category does not
belong to the given group.

(threatcategory_not_belongs
EPOEvents.ThreatCategory 'av')

withinRepositoryDatVersion

Evaluates to true if the DAT (withinRepositoryDatVersion

version is within a supplied EPOProdPropsView_VIRUSCAN.datver
number of versions to what 3)
is in the repository.

not_withinRepositoryDatVersion Evaluates to true if the DAT (not_withinRepositoryDatVersion

EPOProdPropsView_VIRUSCAN.datver
version is not within a
3)
supplied number of
versions to what is in the
repository.

36

ePolicy Orchestrator 4.6.0 Scripting Guide

Remote queries
Ad-hoc query reference

Special ePolicy Orchestrator operator and type combinations

The datatypes and operators defined by ePolicy Orchestrator can be used only in the specific
combinations illustrated in this table.

ePolicy Orchestrator 4.6.0 Scripting Guide

37

Index

A
about this guide 5
authentication 13

C
commands
clienttask.export 23
clienttask.importClientTask 23
clienttask.run 15
commonevent.purgeEvents 15
core.addPermSetsForUser 15
core.addUser 15
core.executeQuery 15, 25, 27, 2931
core.exportPermissionSets 15
core.help 9, 14, 15
core.importPermissionSets 15
core.listDatabases 15, 26, 28, 31
core.listDatatypes 26, 31
core.listQueries 15, 25, 31
core.listTables 15, 26, 28, 29, 31
core.listUsers 21
core.purgeAuditLog 15
core.removeUser 21
core.updateUser 15
detectedsystem.add 22
detectedsystem.addToTree 22
dir 14
epogroup.findSystems 23
help 14
mcafee.client 13
policy.assignToGroup 10
policy.assignToSystem 15
policy.export 23
policy.find 10, 15, 23
policy.importPolicy 23
repository.checkInPackage 15
repository.find 15
repository.pull 15
scheduler.cancelServerTask 15
scheduler.listRunningServerTasks 13
scheduler.runServerTask 15
system.applyTag 19
system.ApplyTag 15

commands (continued)
system.delete 15
system.deployAgent 15
system.find 15, 20
system.findGroups 10, 22, 23
system.importSystem 15
system.resort 23
system.setUserProperties 15
system.wakeupAgent 15, 20
tasklog.purge 15
conventions and icons used in this guide 5
curl 7

D
datatypes
ePolicy Orchestrator specific 34
ePolicy Orchestrator specific operator combinations 37
reference 31, 34
s-expression operator combinations 34
discover commands
Python client 14
URLs 9
documentation
audience for this guide 5
product-specific, finding 6
typographical conventions and icons 5

E
example
assigning policies 10
URL use 10
examples
automating repetitive tasks 20
automating user management 21
importing and exporting 23
importing computers 22
introduction 19
introductory 19
System Tree maintenance 23

H
help
retrieving command listings 9

ePolicy Orchestrator 4.6.0 Scripting Guide

39

Index

I
introduction
examples 19

K
key commands 15

M
McAfee ServicePortal, accessing 6

O
operators
ePolicy Orchestrator specific 35
ePolicy Orchestrator specific datatype combinations 37
reference 35
s-expression datatype combinations 34
s-expression reference 32
output type
JSON 7
terse 7
verbose 7
XML 7

P
parameter notes 11
password security 13
Python client
authenticating 13
discovering commands 14
importing into a script 13
script requirements 12
software requirements 11
using 11

Q
queries
ad-hoc 26
ad-hoc example created from query definition 27
ad-hoc reference 31
commands used in remote queries 31
datatype reference 31
example ad-hoc query 26
executing perisistent 25
joining tables 29

40

ePolicy Orchestrator 4.6.0 Scripting Guide

queries (continued)
joinTable argument 30
obtaining database information 28
obtaining table information 28
operator reference 31
operators used with s-expressions 32
order argument 27
performing ad-hoc 26
persistent 25
select argument 27, 29
specifying tables to join 29
trimming result sets 30
where argument 27

R
requirements
Python client 11
scripts 12

S
s-expressions
operator reference 32
operators used with datatypes 34
ServicePortal, finding product documentation 6

T
Technical Support, finding product information 6

U
URLs
discovering commands through 9

W
Web API
basics 7
calling with URLs 7
controlling output locale 7
introduction 7
output formats 7
overview 7
retrieving files with curl 7
return types 10
wget
example using 10