Metadata-Version: 2.4
Name: trellix-epo
Version: 2.2.0
Summary: Trellix ePolicy Orchestrator policies and Web API Python library
Author: Benjamin Marandel
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/bmarandel/trellix-epo
Project-URL: Source, https://github.com/bmarandel/trellix-epo
Project-URL: Changelog, https://github.com/bmarandel/trellix-epo#history
Project-URL: Issues, https://github.com/bmarandel/trellix-epo/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# Trellix ePolicy Orchestrator Python Library (trellix-epo)

![PyPI](https://img.shields.io/pypi/v/trellix-epo)
![Python](https://img.shields.io/badge/python-3.8%2B-blue)
![Status](https://img.shields.io/badge/status-stable-brightgreen)
![License](https://img.shields.io/github/license/bmarandel/trellix-epo)
![Top language](https://img.shields.io/github/languages/top/bmarandel/trellix-epo)

## Overview

This library was created on 2020-10-26 and published on PyPI as
`mcafee-epo-policies` (18 releases, 0.0.1 to 1.2.0, 2020-10-26 to
2026-10-05); it continues as `trellix-epo` (`pip install trellix-epo`,
`import trellix_epo`) from version 2.0.0, with the whole History below.

This package provides a set of Python classes to read, inspect, and modify policy
documents exported from the Policy Catalog of Trellix (formerly McAfee)
ePolicy Orchestrator (ePO),
without needing to know the underlying XML schema. Each supported policy is
exposed as an object with named properties (e.g. `policy.asci = 15`) instead of
raw Section/Setting XML lookups. Policies can also be exported as a Markdown
document (`to_markdown()` / `save_markdown()`, see [How to work with policies](https://github.com/bmarandel/trellix-epo/blob/main/HOW-TO-WORK-WITH-POLICIES.md)) to keep a
documentation of the enforced security policies. A client of the ePO Web API
(`EPOClient`, see [How to work with ePO](https://github.com/bmarandel/trellix-epo/blob/main/HOW-TO-WORK-WITH-EPO.md)) exports and imports the policies directly from the
ePO server and covers the other domains of the server.

## Supported policies

| Product | Policy | Status | Markdown report |
|---|---|---|---|
| Trellix Agent | General | Full read/write | Yes |
| Trellix Agent | Repository | Full read/write | Yes |
| Trellix Agent | Troubleshooting | Full read/write | Yes |
| Trellix Agent | Custom Properties | Full read/write | Yes |
| Trellix Agent | Product Improvement Program (Telemetry) | Full read/write | Yes |
| ENS Common | Options | Full read/write (passwords: see How to work with policies) | Yes |
| ENS Threat Prevention | On-Access Scan | Full read/write | Yes |
| ENS Threat Prevention | On-Demand Scan | Full read/write | Yes |
| ENS Threat Prevention | Exploit Prevention | Full read/write: signatures/expert rules, exclusions, Application Protection Rules (user-defined created/edited/removed, Trellix-defined status/inclusion/executables/notes) | Yes |
| ENS Threat Prevention | Access Protection | Full read/write: rules (user-defined created/edited/removed, Trellix-defined Block/Report/executables/notes), subrules, exclusions | Yes |
| ENS Threat Prevention | Options | Full read/write | Yes |
| ENS Firewall | Rules | Full read/write: rules, groups (sub groups, location, timed group), networks, applications, schedule | Yes |
| ENS Firewall | Options | Full read/write | Yes |
| ENS Storage Protection | ICAP Policies | Full read/write: connection list, ICAP server, scan items, performance, actions, reports | Yes |
| ENS Storage Protection | NetApp Policies | Full read/write: filers, filer account, scan items, exclusions, performance, actions, reports | Yes |
| ENS Adaptive Threat Protection | Options | Full read/write | Yes |
| ENS Adaptive Threat Protection | Dynamic Application Containment | Full read/write: containment rules (Block/Report), exclusions | Yes |
| ENS Web Control | Options | Full read/write (Web Reporter password: kept, never set) | Yes |
| ENS Web Control | Enforcement Messaging | Full read/write (15 languages) | Yes |
| ENS Web Control | Block and Allow List | Full read/write: sites, file download rating actions | Yes |
| ENS Web Control | Content Actions | Full read/write: web category blocking, rating actions | Yes |
| ENS Web Control | Browser Control | Full read/write | Yes |
| System Information Reporter | Collect Data - General | Full read/write: collected items, custom environment variable, registry queries, schedule, file and folder search | Yes |
| System Information Reporter | Set Registry - Registry General | Full read/write: registry values (create/delete), backup files, registry restore | Yes |
| Solidcore - General | Configuration (Client) | Full read/write (CLI password: raw hashes only) | Yes |
| Solidcore - General | Exception Rules (Windows/Unix) | Full read/write | Yes |
| Solidcore - Application Control | Application Control Options (Windows/Unix) | Full read/write | Yes |
| Solidcore - Application Control | Application Control Rules (Windows/Unix) | Full read/write (all tabs); Rule Groups added/removed | Yes |
| Solidcore - Change Control | Change Control Rules (Windows/Unix) | Full read/write (all tabs); Rule Groups added/removed | Yes |
| Solidcore - Integrity Monitor | Integrity Monitoring Rules (Windows/Unix) | Full read/write (all tabs); Rule Groups added/removed | Yes |
| Solidcore | Rule Groups (Application Control, Change Control, Integrity Monitor) | Full read/write of the `scor.rulegroup.export` / `import` files; Markdown of a group or of all the groups, with the policies using them | Yes |
| Trellix EDR with Forensics | General | Full read/write, "Show Advanced" settings included (passwords, Forensics(HX) server: see How to work with policies) | Yes |
| Trellix EDR with Forensics | Streaming | Full read/write: Trace, exclusions, Event streamer (event logs, file events, filters, OS events, DXL, Helix, syslog servers), Alerts, Process Tracker, Logon Tracker (S3 keys: see How to work with policies) | Yes |
| Trellix EDR with Forensics | Detection | Full read/write: events, exclusions, registry key exclusions | Yes |
| Trellix EDR with Forensics | Investigation | Full read/write: Real-Time Search, Network Flow, File Hashing, exclusions | Yes |
| Trellix EDR with Forensics | Remediation | Full read/write: Host Remediation, containment page (by hand with title and logo, or from URL), messages and exclusions, allowed IP addresses (password: see How to work with policies) | Yes |

The "Markdown report" column tells which policy types support the Markdown
export (`to_markdown()` / `save_markdown()`): all of them, and the Solidcore
Rule Groups too.

Trellix Agent policy coverage is complete - all 5 Trellix Agent policy types are implemented.

Endpoint Security (ENS) policy coverage is complete - all 15 ENS policy types
of the ePO Policy Catalog are implemented: Common (Options), Threat Prevention
(On-Access Scan, On-Demand Scan, Exploit Prevention, Access Protection,
Options), Firewall (Rules, Options), Adaptive Threat Protection (Options,
Dynamic Application Containment) and Web Control (Options, Enforcement
Messaging, Block and Allow List, Content Actions, Browser Control), in the
`es` subpackage (`es.cm`, `es.tp`, `es.fw`, `es.atp`, `es.wc`). ENS
Storage Protection, a separate product, is supported too (`es.sp`).

Solidcore (Trellix Application and Change Control) policy coverage is complete -
all 13 Solidcore policy types of the ePO Policy Catalog are implemented, in the
`sc` subpackage (`sc.gen`, `sc.awl`, `sc.cc`, `sc.fim`, named after the ePO
feature IDs SCOR_GEN, SCOR_AWL, SCOR_CC and SCOR_FIM).

Trellix EDR with Forensics (ePO product XCLIENT_META, extension 50.3) is
supported in the `edrf` subpackage: all policy types.

## Installation

```
pip install trellix-epo
```

## Usage

Edit a policy exported from the Policy Catalog:

```python
from trellix_epo import TAPolicies, TAPolicyGeneral

# Load a Policies export (XML) from the ePO Policy Catalog
with open('EPOAGENTMETA_policies.xml', 'rb') as f:
    policies = TAPolicies(f.read())

# List the policies contained in the export
print(policies)                 # <TAPolicies: 5 policies>
print(policies.list())

# Extract one policy and wrap it for editing
policy_xml = policies.get_policy('General', 'My Custom Policy')
policy = TAPolicyGeneral(policy_xml)
print(policy)                   # <TAPolicyGeneral 'My Custom Policy'>
policy.get_info()               # name, product, category, typeid, server (+ counts)

# Read and change a setting through a property, instead of raw XML
print(policy.asci)
policy.asci = 15

# Save the edited policy, ready to re-import into ePO
policy.save_to_file('My Custom Policy - edited.xml')
```

Work with the ePO server through its Web API:

```python
from trellix_epo import EPOClient

epo = EPOClient('https://epo.example.com:8443', 'admin', password)
policies = epo.export_policies('ENDP_AM_1000')   # ESTPPolicies, ready to edit
epo.systems.find('PC01')                          # [System...]
epo.tags.list()                                   # [Tag...]
epo.queries.run('Inactive Agents')                # rows of a saved query
```

## Learn more

- [How to work with policies](https://github.com/bmarandel/trellix-epo/blob/main/HOW-TO-WORK-WITH-POLICIES.md): policy objects
  of each product, setting checks, Markdown documentation, Solidcore Rule
  Groups, EDR with Forensics.
- [How to work with ePO](https://github.com/bmarandel/trellix-epo/blob/main/HOW-TO-WORK-WITH-EPO.md): the Web API client and
  every domain of the server (systems, tags, assignments, tasks, repository,
  users, events, queries and reports, agents, deployments, DXL/TIE, Solidcore
  server side, issues).

## Examples

The [`examples/`](examples/) directory has short, runnable scripts covering
Trellix Agent (General/Repository), ENS Threat Prevention (On-Access Scan,
On-Demand Scan, process exclusions), ENS Firewall (Rules reporting and editing), and
Solidcore (Application Control, Integrity Monitor and Change Control policies,
Rule Groups - some of them working directly against an ePO server), Trellix
EDR with Forensics (best practices and example exclusions applied to copies of
the policies) and client tasks (ENS deployment from the repository, product
update, Solidcore activation and a Solidcore maintenance window) and the
System Tree (groups and systems from a CSV list, Markdown report), the
policy assignments (Markdown report), the server tasks (run and wait) and
the purge of the logs.

## Documentation

The two guides above ("Learn more") show how to use the library; every
class and method also has a docstring describing which ePO console setting
or Web API command it maps to.

## Requirements

Python 3.8 or later.

## History

### 2.2.0 - 2026-10-24

**Added**
- Saved queries: `QueryDefinition`, `QueryDefinitionList` and `QueryURI`
  read the Queries & Reports "Export Definitions" file and write a file for
  "Import Definitions" (no Web API for it; the default exports of ePO 5.10
  Update 7 are written back byte for byte); `to_query()`, `where()` and
  `check_server()`.
- Reports: `ReportDefinition`, `ReportElement`, `ReportGrid`,
  `ReportDatabase` and `ReportDefinitionList` read and write the report
  definition files; `epo.queries.run_report()` runs the queries of a report
  and returns a `ReportResult` (JSON or Markdown), with the Runtime
  Parameters (`parameters=`, `tz=`) applied to the queries shown as a table.
- Criteria builder: `Criteria` and `CriteriaCondition`
  (`trellix_epo.criteria`), the criteria of the console builder with the
  SQUID the server makes of them and their XML; `TagCriteria` is built on
  it (`to_xml()`).
- Query results: `epo.queries.run(typed=True)` converts the values by the
  column types (dates, booleans, IPv4-mapped addresses, fast product
  versions) and the codes of 322 enumerated columns to the console labels
  (`squidenums`, `typed_rows()`, `value_label()`);
  `epo.queries.iter_rows()` reads a large table page by page (the Web API
  has no row limit). Example `query_export.py` (CSV or Markdown).
- Queries by group (`group=` of `get`, `require`, `run`, `labels`: some
  default queries share a name) and `epo.queries.system_ids()`, the systems
  of a query.
- Events: ENS details (`ThreatEvent.ens`, `ENSEventDetails`), Adaptive
  Threat Protection details (`ThreatEvent.atp`, `ATPEventDetails`), the ENS
  descriptions and rule names as the console shows them
  (`events.ens_description()`, `trellix_epo.es.eventtexts`), Solidcore events
  (`SolidcoreEvent`, `solidcore_events_to_markdown()`), the Error Codes of
  the client events (`ClientEvent.error_label`) and the threat types.
- Permission sets: the console labels of the rights (`permissioncatalog`,
  `Role.section`, `Role.label`) and `PermissionSet.to_markdown()`.
- Product deployments: `epo.deployments` (list, create, stop, resume, mark
  finished, uninstall, delete), `NewDeployment`, `ProductDeployment`.
- DXL and TIE: `epo.dxl` (fabric, brokers, services, health) and `epo.tie`
  (enterprise reputations of files and certificates, GTI refresh, System
  Health Indicator).
- Solidcore server side: `epo.solidcore` (update windows, CPE values,
  inventory import, content update).
- `epo.server`: version, sharing of policies and client tasks, directory
  synchronization, LDAP cache, Support Center, CRL update.
- Issues: `epo.issues` (list, create, update, delete, purge of the closed
  issues before a date).
- ENS Adaptive Threat Protection Markdown: the rules of the policy's rule
  group (`trellix_epo.es.atp.rules`, ATP content 1807).

**Changed**
- `TagCriteria` refuses an "or" group next to a condition on the same
  property (the console builder can't show it).
- The README is split: `HOW-TO-WORK-WITH-EPO.md` (Web API client and server
  domains) and `HOW-TO-WORK-WITH-POLICIES.md` (policy objects and Markdown).

**Fixed**
- Report grids: the column widths are escaped and checked (a width could
  add XML to the import file).
- `squid.console_sexp()` with nested functions; the related tables of
  `core.listTables`.

### 2.1.0 - 2026-10-18

**Added**
- `get_info()` on every policy: name, product and category (console
  labels), typeid, featureid, ePO server and the counts of the policy type
  (Firewall groups and rules, Exploit Prevention signatures, application
  rules and exclusions, Access Protection and DAC rules and exclusions,
  On-Access Scan processes, On-Demand Scan locations, ENS Common
  exclusions, Web Control sites, Solidcore rules and Rule Groups, Trellix
  Agent repositories, SIR registry queries, files, folders and values), and
  on the policy exports (`Policies`): server, number of policies by type.
- One representation for every policy and every export, built from
  `get_info()`: `<ESFWPolicyRules 'Demo': 10 groups, 56 rules>`,
  `<ESTPPolicies: 12 policies>` (it replaces the three former styles).
- Markdown export of the Solidcore Rule Groups: one Rule Group
  (`to_markdown()` / `save_markdown()`) or all the Rule Groups of an export
  (`SCRuleGroups.to_markdown()`), laid out as the policy documents, with the
  tables of the policy tabs and, given the Solidcore policies, the policies
  using each Rule Group (`rule_group_users()`); `get_info()` and the same
  representation as the policies for the Rule Groups. Checked on the 272
  Rule Groups of the lab (all types and platforms, predefined ones
  included). Example `solidcore_rule_groups_report.py`.
- `md_document()` (`trellix_epo.policies`): the document layout shared by
  the policy and Rule Group documents.
- Audit Log, threat events, client events and Compliance History read as
  objects from any query (`events_from_rows()`, `epo.events.read()`), with
  the console labels of the values and the event descriptions; purges of
  these logs and of the Server Task Log (`epo.events.purge_*()`) with a
  mandatory age and a dry run. Example `purge_logs.py`.
- Agents: wake-up, deployment and transfer of the agents of systems
  (`epo.systems.wakeup()`, `deploy_agent()`, `transfer()`) and of a group
  (`epo.groups.wakeup()`, `deploy_agent()`), agent deployment URL of a
  group (`epo.groups.deployment_url()`).
- Server settings: `epo.server` (Agent Handlers, Virtual MAC Vendors,
  registered servers, custom agent install package), objects
  `AgentHandler` and `MacVendor`; `epo.repository.agent_package()` and the
  `deployment_path`, `hotfix` and `agent_platform` of a `Package`.

**Removed (breaking)**
- The display code written before the Markdown export, which the Markdown
  export now covers entirely: ENS Firewall Rules `print_info()`,
  `print_sequences()`, `get_sequences()`, `get_toc()` and `get_content()`
  (use `to_markdown()` / `save_markdown()`), ENS Exploit Prevention
  `print_info()` (use the representation or `get_info()`), and the
  text-table `__str__()` of `ExclusionList`, `OASProcessList`,
  `OASURLList`, `ODSLocationList` and `RepositoryList` (`print()` shows
  their representation; the lists are in the policy Markdown).

**Changed**
- Trellix Agent classes: the constructor parameter is
  `policy_from_tapolicies` and is optional, as in the other classes (create
  the object empty, then `load_from_file()`); the type error says "Trellix
  Agent".
- Examples `firewall_rules.py` and `agent_general_repository.py` use the
  representation and the Markdown export.

### 2.0.0 - 2026-10-17

**Moved** from `mcafee-epo-policies` (created 2020-10-26, last release 1.2.0)
to `trellix-epo`: PyPI project `trellix-epo`, import name `trellix_epo`,
GitHub repository `bmarandel/trellix-epo` (the old URLs redirect).
`mcafee-epo-policies` gets no new feature.

**Changed (breaking)**
- Package `mcafee_epo_policies` renamed `trellix_epo`.
- Trellix Agent: module `ma` renamed `ta` and its classes `McAfeeAgent*`
  renamed `TA*` (`TAPolicies`, `TAPolicyGeneral`, `TAPolicyRepository`,
  `TAPolicyTroubleshooting`, `TAPolicyCustomProps`, `TAPolicyTelemetry`),
  without aliases.
- ENS Common module `es/common` renamed `es/cm`.
- The `examples` extra (`mcafee-epo` package) is removed: the library has
  its own Web API client.

**Added**
- Trellix EDR with Forensics policies (`edrf`: General, Streaming,
  Detection, Investigation, Remediation; extension 50.3) with the Markdown
  export and `examples/edrf_best_practices.py`.
- Console field limits in every module: the length, number range and
  allowed characters of each console field are checked (the library refuses
  what the console refuses), with shared checks in `validators`.
- `EPOClient`, a client of the ePO Web API written with the standard
  library only (`call()`, `query()`, policy export and import, Solidcore
  Rule Groups), and on top of it one object per domain:
  - `epo.tags` and `epo.tags.groups`: tags with criteria written as in the
    console builder (`Tag`, `TagCriteria`);
  - `epo.client_tasks`: typed client tasks (Trellix Agent Product
    Deployment and Product Update, SIR, the 11 Solidcore tasks) with the
    console rules, run now, applied tasks;
  - `epo.repository`: packages of the Main Repository (check in, branch
    change, delete, pull, replicate) and repositories;
  - `epo.systems` and `epo.groups`: the System Tree (`System` with the
    properties of `system.find` and their console labels, `Group`; add,
    move, sort, delete, custom fields, group creation);
  - `epo.policies`: Policy Catalog, assignments to groups and systems,
    inheritance reset, applied policies (`PolicyRef`, `Assignment`,
    `AppliedPolicy`);
  - `epo.server_tasks`: server tasks (run and wait, enable, disable,
    cancel) and the Server Task Log, latest first;
  - `epo.queries`: SQUID queries built with `squid.Query`, saved queries
    of Queries & Reports, console labels of the columns;
  - `epo.users` and `epo.permission_sets`: users (password, Windows,
    certificate), permission sets exported and imported with their roles.
- Policy Assignment Rules (`assignmentrules`): the file of the console
  import and export (no Web API command), with `check_server()`.
- Trellix Agent 5.8.7: the agent-to-server TLS cipher lists (read only).
- Markdown tables for the new objects (systems, groups, assignments, tasks,
  task log, queries, users, permission sets).
- New examples: Web API connection, tags, assignment rule, client tasks
  (ENS deployment, product update, Solidcore enable and maintenance
  window), System Tree import, policy assignments report, server task run.
- Every server behaviour the library handles (silent "true" answers,
  hidden traps of the commands) was checked on an ePO 5.10 Update 7 lab and
  is written in the module docstrings.

**Fixed**
- Policies written with non-ASCII characters: written as XML character
  references (the Web API import reads UTF-8 as ISO-8859-1).
- Solidcore: the General_<n> sections (trusted directories saved by the
  8.4 console) are read as rules. SIR: odd-length REG_BINARY values are
  padded as the console does.

### 1.2.0 - 2026-10-05

**Added**
- Endpoint Security Common (ENS Common), new `es/common` module:
  `ESCommonPolicies` (`policy.export productId=ENDP_GS_1000`),
  `ESCommonPolicyOptions` (client interface, uninstallation, language, Self
  Protection and its process exclusions, AAC exclusions with `AACExclusion`,
  client logging, event and EDR levels, proxy, IPv6, default client update,
  managed tasks) with the Markdown export; ENS policy coverage is now
  complete. Checked on the ePO 5.10 lab (the policy changed by the library is
  identical to the one saved by the console). The passwords are not exported
  by ePO and are erased by an import (see "ENS Common" in How to work with
  policies). The trusted
  vendor Certificates list is not supported (no certificate on the lab).

### 1.1.0 - 2026-10-04

**Added**
- Solidcore exclusions (Exclusions tab, Exception Rules): Parent Process Name
  ("Allow uninstallations", "Exclude file from write-protection rules and
  allow script execution") and Library Name ("Disable ROP protection ...
  Forced Relocation (VASR)") in `get_exclusion_list()`, `add_exclusion()`,
  `contains_exclusion()`, `remove_exclusion()` and the Markdown export (new
  columns); new exclusion types `SCException.SKIP_REGISTRY` and
  `SCException.SKIP_CHANGE_TRACKING`. All the exclusion types of the console
  dialog checked on the ePO 5.10 lab.

**Changed**
- Solidcore certificates: comments on the Friendly Name column (always empty
  in the console, not exported) and on Issued To (the console cuts the name
  at the first comma, the export keeps the full certificate name).

### 1.0.1 - 2026-10-04

**Changed**
- Project status: Stable (README badge and PyPI classifier "Development
  Status :: 5 - Production/Stable").
- ENS Firewall Rules Markdown export: each rule or group detail card is one
  compact two-column table: "Status: Enabled | Action: Allow" (group:
  "Status | Direction") in its header line, then the other settings two per
  line as "**Label:** value" (e.g. Local networks | Local port), the group
  Location and number of Rules included; the platform notes (Windows & Linux
  only...) are given once before the cards. About 38 % fewer lines.

### 1.0.0 - 2026-10-04

**Added**
- System Information Reporter (SIR), new `sir` module: `SIRPolicies`
  (`policy.export productId=SIR_____1000`), `SIRPolicyCollectData` (Collect
  Data > General), `SIRPolicySetRegistry` and `SIRRegistryValue` (Set
  Registry > Registry General, with the registry backup bookkeeping of the
  console), with the Markdown export. Storage and labels checked on the ePO
  5.10 lab.
- `Policies.TYPE_ATTRIBUTE`: the EPOPolicyObject attribute used as policy
  type (`typeid`, or `featureid` for products whose categories share a
  typeid).

### 0.9.0 - 2026-10-04

**Added**
- Endpoint Security Web Control (ENS WC), new `es/wc` module:
  `ESWCPolicies` (`policy.export productId=ENDP_WP_1000`),
  `ESWCPolicyOptions`, `ESWCPolicyMessaging` (Enforcement Messaging),
  `ESWCPolicyBlockAllowList` and `WCSite`, `ESWCPolicyContentActions`,
  `ESWCPolicyBrowserControl` and `RatingActions` (Red/Yellow/Unrated
  actions), with the Markdown export. Storage and labels checked on the ePO
  5.10 lab (test policies changed in the console, then changed by the
  library and opened in the console).

### 0.8.0 - 2026-10-04

**Added**
- Endpoint Security Adaptive Threat Protection (ENS ATP), new `es/atp`
  module: `ESATPPolicies` (`policy.export productId=TIEClientMETA`),
  `ESATPPolicyOptions` (Options), `ESATPPolicyDAC` and `DACExclusion`
  (Dynamic Application Containment: containment rules, exclusions), with
  the Markdown export. Storage and labels checked on the ePO 5.10 lab (test
  policies changed in the console, then changed by the library and opened in
  the console).
- `Policies.new_policy()` also gives new IDs to the Dynamic Application
  Containment exclusions of a copy.
- Solidcore Rule Groups renaming: `SCRuleGroups.rename_rule_group()` (export
  files, user defined Rule Groups only) and `SCPolicy.rename_rule_group()`
  (reference in a policy export). Checked on the ePO 5.10 lab: a Rule Group
  renamed with `scor.rulegroup.rename` is renamed by ePO in the policies
  using it too.

### 0.7.0 - 2026-10-04

**Added**
- Markdown export of the Solidcore policies: Configuration (Client),
  Exception Rules, Application Control Options and Rules, Change Control
  Rules, Integrity Monitoring Rules (Windows and Unix), with the tabs,
  columns and labels of the ePO 5.10 console (exclusion types, filter
  conditions and events, Execution Control actions). The rules policies
  document their own rules (My Rules) and each shared Rule Group they use.
  Certificates show Issued To / Issued By / Expiration Date decoded from the
  PEM; the CLI password hashes are never written.
  `examples/policy_documentation.py` handles Solidcore exports too.

### 0.6.0 - 2026-10-04

**Added**
- Markdown export of the McAfee (Trellix) Agent policies: General (General,
  SuperAgent, Events, Logging, Updates, Peer-to-Peer, Deployment tabs),
  Repository (repository list, proxy - passwords are never written, only
  whether one is set), Troubleshooting, Custom Properties and Product
  Improvement Program, with the labels of the ePO 5.10 console. When a
  setting is stored twice, the value shown by the console is used (the
  section named after the console fields, e.g. AgentListenServer, rather than
  the "service" section, e.g. HttpServerService - checked on lab policies
  where they differ). `examples/policy_documentation.py` handles Trellix
  Agent exports too.

- Endpoint Security Storage Protection (ENSSP), new `es/sp` module: ICAP
  Policies (`ESSPPolicyICAP`: connection list, ICAP server configuration) and
  NetApp Policies (`ESSPPolicyNetApp`: filers list, administrator account,
  exclusions as `SPExclusion` by pattern/file type/file age), both with the
  Scan Items (file types to scan, options, heuristics), Performance, Actions
  and Reports tabs, and their Markdown export (console labels). The filer
  account must be defined in the console: ePO encrypts its password with
  the server key ("EPOAES128:..."), which the library can't decrypt nor
  produce; the library keeps it and can only enable/disable the account. Storage learnt from test policies changed in
  the ePO 5.10 console; a NetApp policy built by the library was imported
  and displayed as expected. `examples/policy_documentation.py` handles
  ENSSP exports too.

**Fixed**
- McAfee Agent General: 19 getters read the "service" section first (e.g.
  `get_relay_client()` read RelayService.EnableClient) and could return the
  opposite of what the console shows when the two sections differ; they now
  read the section of the console first (AgentListenServer, General,
  Network...). `set_sa_lazy_caching()` also writes
  AgentListenServer.bEnableLazyCaching (read by the console).
  `get_policy_enforcement_interval()` and `get_asci()` return an int.

**Security**
- Markdown export: `[` and `]` are now escaped too (`Policy.md_escape()`,
  `md_heading()`), and the ENS Firewall `get_content()`/`get_toc()` reports
  (used by `examples/firewall_rules.py`) escape the policy values (names,
  notes, networks, addresses, location criteria, ports). In 0.5.0 a policy
  value such as `![x](https://...)` or `[text](https://...)`, written in ePO
  by someone allowed to edit the policy, was rendered as a remote image
  (tracking pixel) or a link in the generated document.

### 0.5.0 - 2026-10-03

**Added**
- Exploit Prevention exclusions, full read/write: `EPExclusion` (one class
  method per Exclusion Type of the console: `illegal_api()`,
  `file_process_registry()`, `service()`, `network_ips()`, `linux()`, with
  the console checks) and `EPExecutable` (process / caller module: path, MD5,
  signer); `get_exclusions()`, `set_exclusions()`, `add_exclusion()`,
  `remove_exclusion()` on `ESTPPolicyExploitPrevention`. Every section kept
  by ePO for current and older clients is written. Storage learnt from
  exclusions created in the ePO 5.10 console; a policy built by the library
  was imported, displayed and exported back unchanged.
- Exploit Prevention Application Protection Rules, full read/write:
  `EPAppRule` (Name, Status, Inclusion Status, Executables as
  `APExecutable`, Notes) and `get_application_rules()`,
  `get_application_rule()`, `add_application_rule()`,
  `update_application_rule()`, `remove_application_rule()`. User-defined
  rules can be created and removed; for Trellix-defined rules, as in the
  console, everything but the name can be changed. Storage learnt from rules
  created in the ePO 5.10 console; a policy with a rule added and a
  Trellix-defined rule changed by the library was imported, displayed as
  expected and both rules were exported back unchanged (on import ePO gives
  new executable IDs and dates to the untouched Trellix-defined rules). See
  `examples/exploit_prevention.py`.
- ENS Firewall Rules, full read/write: the rule tree as objects (`FWRule`,
  `FWGroup` with its rules, location `FWLocation` and timed group setting,
  `FWNetwork` local/remote networks, `FWApplication` and `FWExecutable`,
  schedule, `FWAddress` for the console address forms) and `get_rules()`,
  `get_all_rules()`, `get_rule()`, `add_rule()`, `update_rule()`,
  `remove_rule()`, `move_rule()` on `ESFWPolicyRules`. Storage learnt from a
  rule, a group and a location created in the ePO 5.10 console; a policy
  built by the library (a group with a sub group, rules with networks,
  applications and schedule; console-made and Trellix rules changed, moved
  and removed) was imported, displayed as expected and exported back
  unchanged. The lengths are checked against the console fields (rule name
  100 characters...): ePO imports a longer rule name but the console then
  fails to open the policy. See `examples/firewall_rule_editing.py`.
- `examples/firewall_recon_detection.py`: adds network reconnaissance
  detection rules to an ENS Firewall Rules policy (MITRE ATT&CK T1046 /
  T1595.001): Block + "Treat match as intrusion" + Log rules at the end of the
  policy for the ports of the usual Windows Server, third-party and Linux
  services not already allowed, so that a port scan raises intrusion events
  in ePO without changing what the firewall blocks.
- Markdown export: the Exploit Prevention Exclusions table (console columns)
  and the details of each exclusion, instead of a count; the Executables
  column of the Application Protection Rules now shows the paths as the
  console does (`path;path;`).

**Fixed**
- ENS Firewall Rules: `load_policy()` crashed on an empty group (its sequence
  has no rule count); the schedule of the Markdown export and of
  `get_content()` showed Sunday when it wasn't selected (Sunday is the first
  bit of the WeekMask, not the last) and always 0:00 - 23:59 (the times are
  stored in ScheduleStart/End Hours/Minutes).
- `Policies.new_policy()`: a copy of an Exploit Prevention policy with
  exclusions kept their IDs, and the ePO console then failed to open the
  imported copy ("An unexpected error occurred."). The copy now gets new
  exclusion IDs.

**Security**
- Markdown export: policy, section, rule and subrule names written in headings
  are now escaped (new `Policy.md_heading()`), like the table cells already
  were. In 0.4.0 a name containing HTML (e.g. a rule named
  `<img src=x onerror=...>` by someone allowed to edit the policy in ePO)
  could be rendered as HTML by Markdown viewers that allow raw HTML.

### 0.4.0 - 2026-10-03

**Added**
- Markdown documentation of policies: `Policy.to_markdown()` /
  `save_markdown()` with Markdown helpers (`md_table`, `md_settings`...), for
  all ENS policy types; `examples/policy_documentation.py`.
- `ESTPPolicyAccessProtection` (ENS TP Access Protection) with an object model
  following the console workflow: `APRule`, `APSubRule`, `APTarget`,
  `APExecutable`, `APUserName` - rules are created, edited and removed
  (`add_rule()`, `update_rule()`, `remove_rule()`), exclusions too; checked end
  to end (built with the library, imported into ePO, shown as expected in the
  console, exported back unchanged); `examples/access_protection.py`.
  `ESTPPolicyOptions` (ENS TP Options: Quarantine Manager,
  Detection Exclusion, custom unwanted programs, Proactive Data Analysis) and
  `ESFWPolicyOptions` (ENS Firewall Options, including DNS Blocking, Defined
  Networks and Trusted Executables).
- `OASState` constants: the On-Access Scan "Disable and unregister with
  Windows Security Center" option (stored by ePO as `bOASEnabled` = 0 plus
  `bUnregisterWithWSC` = 1), supported by the `on_access_scan` property.

**Fixed**
- On-Demand Scan: the GTI sensitivity level getters/setters (`fs_`, `qs_`,
  `rs_gti_level`) looked for the setting in the wrong section (returned None,
  setter failed).
- ENS Firewall: `get_content()` crashed on ICMP rules without message type.
- Exploit Prevention: debug messages printed when loading a policy or applying
  a `SearchFilter`.

### 0.3.0 - 2026-10-03

**Added**
- Solidcore (Trellix Application and Change Control) support, in the new `sc`
  subpackage - all 13 Solidcore policy types:
  - `sc.gen`: `SCGENPolicyConfiguration` (Configuration (Client)) and
    `SCGENPolicyExceptionRules` (Exception Rules, Windows/Unix);
  - `sc.awl`: `SCAWLPolicyOptions` and `SCAWLPolicyRules` (Application
    Control Options and Rules, Windows/Unix);
  - `sc.cc`: `SCCCPolicyRules` (Change Control Rules, Windows/Unix);
  - `sc.fim`: `SCFIMPolicyRules` (Integrity Monitoring Rules, Windows/Unix);
  - `SCPolicies` (Solidcore export), whose `new_policy()` keeps the shared Rule
    Groups referenced by the template, and the `SCPolicy` base class giving
    generic access to Solidcore rules and Rule Groups;
  - `sc.rulegroups`: `SCRuleGroups` for the Solidcore Rule Groups files of the
    `scor.rulegroup.export` / `scor.rulegroup.import` API commands (create,
    copy, edit user defined Rule Groups), with `SCAWLRuleGroup`,
    `SCCCRuleGroup` and `SCFIMRuleGroup` sharing the policy tab methods, and
    `add_rule_group()` / `remove_rule_group()` to make a policy use a Rule Group.
- `SCException` and `SCReputation` constants classes.
- `SCPolicies.new_empty_policy()`: a new policy without any rule or Rule Group
  (the ePO "Blank Template" can't be exported).
- `examples/solidcore_application_control.py` and
  `examples/solidcore_rule_groups.py`, and three examples working directly
  against an ePO server with the "mcafee-epo" API client (optional dependency
  `pip install mcafee_epo_policies[examples]`): Application Control policy
  with one item per tab and a database Rule Group, Integrity Monitor policy
  with a "Windows Critical Config Files" Rule Group, and Change Control
  policy protecting some of those files.
- Tests built from real ePO 5.10 exports, each policy type also checked end to
  end: edited with the library, imported into ePO, exported back unchanged and
  displayed as expected in the ePO console.

### 0.2.0 - 2026-08-28

**Added**
- Full support for the remaining McAfee Agent policies: Troubleshooting,
  Custom Properties, and Product Improvement Program (Telemetry) - McAfee
  Agent policy coverage is now complete.
- `Language` constants class for the Troubleshooting policy's agent
  language selection (21 languages, LCID codes).
- Two new "Ransomware" options on the On-Access Scan policy:
  `detect_unknown_ransomware` and `ransomware_bait_files`.
- Read support and enable/disable control for Exploit Prevention
  Application Protection Rules (`application_rules_list`,
  `application_rule_get`, `get/set_application_rule_status`,
  `get/set_application_rule_inclusion_status`).
- `signatures_delete()` on the Exploit Prevention policy now actually
  removes an Expert Rule (previously a no-op).
- Validation when `signatures_add()` is called with an explicit `sig_id`:
  rejects IDs that are already in use or outside the valid range.
- Generic `get_indexed_list`/`set_indexed_list`/`get_indexed_table`/
  `set_indexed_table` helpers on the base `Policy` class, replacing eight
  independent hand-written implementations of the same
  "count + indexed settings" XML pattern.
- A `tests/` suite (pytest, 52 tests) built from real ePO policy exports,
  including two structural tests that check the whole package for
  property-wiring and mutable-default-argument mistakes.
- An `examples/` directory with runnable scripts for McAfee Agent,
  On-Access Scan, On-Demand Scan, and Firewall Rules reporting.

**Changed**
- Migrated packaging from `setup.py` to `pyproject.toml` (PEP 621), with an
  SPDX license expression.
- `mcafee_epo_policies.__version__` now reads the installed package
  version via `importlib.metadata`, instead of accidentally reporting the
  version of `setuptools`.

**Fixed**
- Six mismatched `property(getter, setter)` declarations in the McAfee
  Agent General policy that made several settings silently unreadable,
  unwritable, or both.
- `test_cert_authentication` is now correctly read-only, and its
  certificate files are located relative to the package instead of the
  caller's working directory.
- Shared mutable default arguments in `ExclusionList`, `OASProcessList`,
  `OASURLList`, and `ODSLocationList` that could leak state between
  unrelated instances.
- On-Access Scan `process_list`: a key mismatch (`TypeItem_x{row}` vs
  `TypeItem_{row}`) meant a process's risk level set via
  `set_process_list()` could never be read back.
- On-Access Scan `set_process_list([])` no longer leaves the policy in a
  state that crashes the next `get_process_list()` call.
- On-Demand Scan `fs_performance_level`/`qs_performance_level`: a typo
  (`_Performace`) meant the setting was never actually persisted.
- Saving a policy containing any non-ASCII character (accents, curly
  quotes, etc.) produced XML that neither this library nor ePO could
  reliably read back, due to an invalid encoding name.
- `signatures_get()` on the Exploit Prevention policy, previously
  non-functional for any signature.
- The indexed-list/table helpers could leave stale, duplicate settings
  behind when an ePO export already contained orphaned entries beyond
  their declared count - now cleaned up correctly on every write.

### 0.0.6 - 2020-11-25

Starting point for this changelog.

## Bugs and Feedback

For bugs, questions and discussions please use the [GitHub Issues](https://github.com/bmarandel/trellix-epo/issues).

## License

Copyright 2020 Benjamin Marandel

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. 
