Endpoint Checks File Format

This page is the reference for writing an importable Endpoint Checks file by hand or with an AI assistant. A file contains check groups and checks, not a policy's name, schedule, tags, alerts, or remediation settings.

File structure

The top-level JSON object has exactly four fields. Other fields are refused.

Field	Type	Required values
format	string	tridentstack-endpoint-checks
version	number	1
platform	string	windows or linux
groups	array	1 to 50 groups

Each group has a name field, which is a string or null and can be at most 255 characters, and a non-empty checks array. A group's checks are combined with AND: every check in that group must pass. Groups are combined with OR: at least one group must pass. See Criteria Groups. Group objects accept only name and checks.

Each check has a non-empty name string (at most 255 characters), a checkType id from this page, and a config object containing the settings for that type. It may also have recheckMinutes, a whole number from 0 to 1440. It overrides the policy's Recheck before failing setting for that check, and every check type accepts it except agent_tag. The file holds checks only, not policy settings, so a policy created by importing a file starts with the new-policy recheck of 5 minutes. Check objects accept only name, checkType, config, and recheckMinutes; config objects accept only the keys listed for that check type.

A file can contain at most 200 checks total and must be no larger than 256 KB. The import checks the whole file before adding anything.

Check types

In the tables, required means the key must be present. Empty strings and empty lists are accepted where their type permits them; they may still describe a check that will not pass on an endpoint. Operators are written in the operator config field.

Application Catalog (application_catalog)

Windows only. Requires the listed catalog applications.

Config key	Type	Required?	Allowed values
packages	array of package objects	Yes	Each object has a text id, a text name, and an optional source of winget or custom. For a winget package, id is its winget package identifier, such as Mozilla.Firefox. A custom package is found by its name in the tenant you import into, so its id can be any text when you write the file yourself.
minimumVersion	string	Yes	A minimum version, or an empty string for any version.

{"name":"Firefox installed","checkType":"application_catalog","config":{"packages":[{"id":"Mozilla.Firefox","name":"Mozilla Firefox","source":"winget"}],"minimumVersion":""}}

Windows Service / systemd Unit (service)

Windows and Linux. serviceName is the service or unit name.

Config key	Type	Required?	Allowed values
serviceName	string	Yes	Any text.
operator	string	Yes	running, not_running, exists, not_exists, startup_type_equals
value	string	Yes	Text value used with startup_type_equals; otherwise it can be an empty string.

{"name":"SSH service","checkType":"service","config":{"serviceName":"sshd","operator":"running","value":""},"recheckMinutes":5}

Registry Key/Value (registry)

Windows only.

Config key	Type	Required?	Allowed values
keyPath	string	Yes	Registry key path.
valueName	string	Yes	Registry value name; an empty string checks the key.
operator	string	Yes	exists, not_exists, equals, not_equals, contains, not_contains, version_gte
value	string	Yes	Compared text; can be empty for existence checks.

{"name":"Defender key exists","checkType":"registry","config":{"keyPath":"HKLM\\SOFTWARE\\Microsoft\\Windows Defender","valueName":"","operator":"exists","value":""}}

File / Path (file_path)

Windows and Linux. path is the full path of one file or folder. Wildcards are not expanded: a * is read as part of the name.

For contains, not_contains, matches_regex and not_matches_regex, value must hold the text or pattern to look for, up to 4096 characters. A regular expression cannot use lookahead, lookbehind or backreferences. These rules are checked when you save the policy.

Config key	Type	Required?	Allowed values
path	string	Yes	A platform path.
operator	string	Yes	exists, not_exists, version_gte, hash_equals, modified_within_days, contains, not_contains, matches_regex, not_matches_regex
value	string	Yes	The expected version for version_gte, the SHA-256 hash for hash_equals, the number of days for modified_within_days, or the text or pattern for the content conditions. An empty string for exists and not_exists.

{"name":"Agent config exists","checkType":"file_path","config":{"path":"/etc/tridentstack/agent.toml","operator":"exists","value":""}}

Log Content Poll (log_poll)

Windows and Linux. logPath can name one log file, or use one * in the file name to poll every matching file in a folder, such as /var/log/app/app-*.log. A path with * must be absolute (on Windows, start with a drive letter such as C:\ or a UNC path), can be at most 4096 characters, cannot contain ?, cannot end in a path separator, and can use * only in the file name, not in a folder.

Config key	Type	Required?	Allowed values
logPath	string	Yes	Log file path.
pattern	string	Yes	Text or regular expression to find.
isRegex	boolean	Yes	true or false.
failOn	string	Yes	match or no_match.
lookbackHours	number	Yes	How many hours back to look in the log.
threshold	number	Yes	Number of matches that triggers failOn: a whole number of at least 1.
pollIntervalMinutes	number	Yes	How often, in minutes, the endpoint polls the log.

{"name":"No repeated errors","checkType":"log_poll","config":{"logPath":"/var/log/syslog","pattern":"connection failed","isRegex":false,"failOn":"match","lookbackHours":6,"threshold":3,"pollIntervalMinutes":60}}

Process Running (process)

Windows and Linux. processName is the process name.

Config key	Type	Required?	Allowed values
processName	string	Yes	Any text.
operator	string	Yes	running, not_running
value	string	Yes	Text value; normally empty.

{"name":"Agent process running","checkType":"process","config":{"processName":"tridentstack-agent","operator":"running","value":""},"recheckMinutes":5}

Scheduled Task / Cron Entry (scheduled_task)

Windows and Linux.

Config key	Type	Required?	Allowed values
taskName	string	Yes	Scheduled task or cron entry name.
operator	string	Yes	exists, not_exists, enabled
value	string	Yes	Text value; normally empty.

{"name":"Backup schedule enabled","checkType":"scheduled_task","config":{"taskName":"daily-backup","operator":"enabled","value":""}}

Certificate Presence (certificate)

Windows and Linux. store is a Windows certificate store or Linux certificate directory.

Config key	Type	Required?	Allowed values
store	string	Yes	For example, LocalMachine\\My on Windows or /etc/ssl/certs on Linux.
operator	string	Yes	thumbprint_equals, subject_contains, not_expired
value	string	Yes	Thumbprint or subject text when required by the operator; can be empty for not_expired.

{"name":"Company certificate present","checkType":"certificate","config":{"store":"/etc/ssl/certs","operator":"not_expired","value":""}}

Agent Tag (agent_tag)

Windows and Linux. Passes when the endpoint has the tag, or, with negate set to true, when it does not have it.

Name the tag with tagName. The import finds the tag with that name in the tenant you import into, ignoring case and surrounding spaces. If no tag has that name, or more than one does, nothing is imported. Use tagName whenever you write a file yourself or move it to another tenant. tagId is only needed when tagName is left out, and then it must be the id of a tag in the same tenant.

Config key	Type	Required?	Allowed values
tagName	string	Yes, unless tagId is given	Name of an existing tag in the tenant.
tagId	positive integer	Only without tagName	An existing tag id in the same tenant.
negate	boolean	No	true or false. Defaults to false.

{"name":"Endpoint is in production","checkType":"agent_tag","config":{"tagName":"Production","negate":false}}

Complete example files

The Windows example has two groups. An endpoint passes the policy when every check in either group passes.

{
  "format": "tridentstack-endpoint-checks",
  "version": 1,
  "platform": "windows",
  "groups": [
    {
      "name": "Security agent running",
      "checks": [
        {
          "name": "Agent service is running",
          "checkType": "service",
          "config": { "serviceName": "TridentStackAgent", "operator": "running", "value": "" },
          "recheckMinutes": 5
        },
        {
          "name": "Production tag is present",
          "checkType": "agent_tag",
          "config": { "tagName": "Production", "negate": false }
        }
      ]
    },
    {
      "name": "Backup agent process running",
      "checks": [
        {
          "name": "Backup process is running",
          "checkType": "process",
          "config": { "processName": "backup-agent", "operator": "running", "value": "" }
        }
      ]
    }
  ]
}

The Linux example checks a service and the presence of its configuration file.

{
  "format": "tridentstack-endpoint-checks",
  "version": 1,
  "platform": "linux",
  "groups": [
    {
      "name": "Monitoring agent",
      "checks": [
        {
          "name": "Monitoring service is running",
          "checkType": "service",
          "config": { "serviceName": "monitoring-agent", "operator": "running", "value": "" },
          "recheckMinutes": 5
        },
        {
          "name": "Agent config exists",
          "checkType": "file_path",
          "config": { "path": "/etc/tridentstack/agent.toml", "operator": "exists", "value": "" }
        }
      ]
    }
  ]
}

Writing a file with an AI assistant

Give the assistant this page and describe the checks you want. Tell it the target platform and any tag names that should be checked. Before importing, create matching tags and custom packages in the tenant. Import is all-or-nothing and lists every problem it finds, so you can correct the file and try again. The Endpoint Checks page header can import the finished file into a new policy; name the policy and save it after reviewing the checks.