# TridentStack Control Documentation > Customer documentation for TridentStack Control, the patch management, vulnerability detection, compliance, and policy platform from TridentStack. This file is the entire docs site as one Markdown document. The companion `llms.txt` is the short index. --- # Welcome URL: https://docs.tridentstack.com/ Description: TridentStack Control documentation. Patch management, vulnerability detection, compliance scoring, and policy enforcement for Windows, macOS, and Linux fleets. # TridentStack Control Documentation TridentStack Control is an enterprise patch management platform that gives you full visibility and control over Windows, macOS, and Linux endpoints. Manage system updates, application patches, vulnerability remediation, and compliance baselines from a single dashboard. ## What you can do with TridentStack Control - **Manage Endpoints** - Monitor agent health, system information, and patch status across your fleet - **Deploy System Updates** - Create policies to approve, schedule, and install Windows and Linux patches - **Manage Applications** - Keep third-party applications up to date using the integrated package catalog - **Detect Vulnerabilities** - Automatically scan endpoints for known CVEs and track remediation progress - **Enforce Compliance** - Measure your fleet against CIS, DISA STIG, Microsoft, and NIST baselines - **Configure Policies** - Apply ADMX-based configuration policies to standardize device settings - **Report and Audit** - Build custom reports with the visual query builder or SQL editor ## Quick navigation ### Getting Started New to TridentStack Control? Start here: - [**Agent Enrollment**](getting-started/agent-enrollment) - Install agents on Windows, macOS, and Linux endpoints - [**First Steps**](getting-started/first-steps) - Navigate the UI and set up your first policy ### Platform Guide Learn how each feature works: - [**Dashboard**](platform-guide/dashboard) - Customize widgets and monitor your fleet at a glance - [**Agents**](platform-guide/agents/endpoints) - Manage endpoints, tags, and automation rules - [**Update Management**](platform-guide/update-management/system-updates) - System patches, app updates, and deployment rings - [**Configuration Policies**](platform-guide/configuration-policies) - ADMX policy management - [**Vulnerabilities**](platform-guide/vulnerabilities) - Vulnerability scanning and exception management - [**Compliance**](platform-guide/compliance) - Baseline frameworks and compliance scoring - [**Reporting**](platform-guide/reporting) - Custom reports and data exports ### Administration Platform configuration and access management: - [**Settings Overview**](administration/settings-overview) - All platform settings in one place - [**User Management**](administration/user-management) - Users, roles, and authentication - [**API Keys**](administration/api-keys) - Programmatic access to the TridentStack Control API - [**System Audit**](administration/system-audit) - Activity logs and change tracking --- :::tip Need help? Visit our [website](https://tridentstack.com) or [contact support](https://tridentstack.com/contact) if you have questions. ::: --- # Agent Enrollment URL: https://docs.tridentstack.com/getting-started/agent-enrollment Description: Install and enroll the TridentStack Control agent on Windows, macOS, and Linux endpoints so they appear in your tenant within minutes. # Agent Enrollment Agents are lightweight services that run on your endpoints (servers, workstations, laptops) and communicate with TridentStack Control over gRPC. Once enrolled, an agent continuously reports system information, software inventory, patch status, and vulnerability data back to the platform, and receives commands for update installation, policy enforcement, and compliance evaluation. Each agent maintains a persistent connection to the TridentStack Control gateway, so changes you make in the console (approving updates, assigning policies, triggering scans) are delivered to endpoints in real time. ## Prerequisites ### Supported operating systems | Platform | Minimum Version | |----------|----------------| | Windows Server | 2012 R2 and later | | Windows Desktop | 8.1 and later | | Ubuntu | 20.04 and later | | Debian | 12 and later | | RHEL / CentOS Stream | 8 and later | | Rocky Linux / AlmaLinux | 8 and later | | Fedora | Latest stable | | Amazon Linux | 2 and later | | macOS | 14.0 (Sonoma) and later | :::note All features, including application updates, are supported on all Windows versions listed above. The macOS agent provides system telemetry, software inventory, vulnerability detection, compliance evaluation, application updates, and Microsoft Office update management in the current release. Operating-system update management for macOS is in development. ::: ### Network requirements Agents require **outbound access on port 443/TCP** to reach TridentStack Control. No inbound ports need to be opened on the endpoint. The agent connects to two TridentStack Control hostnames, both on port 443: | Host | Purpose | |------|---------| | `gateway.tridentstack.com` | Persistent command channel (gRPC over HTTP/2) that delivers approvals, policy assignments, and scan requests in real time | | `control.tridentstack.com` | Enrollment, inventory and telemetry uploads, agent self-update downloads, and log collection (HTTPS/REST) | :::warning TLS inspection must be exempted for the command channel The connection to `gateway.tridentstack.com` requires **direct TLS passthrough**. As a security measure, the agent verifies that the certificate presented by the gateway chains to the expected public certificate authority and refuses any connection where the certificate has been replaced, including replacement by your own security appliance. Allowlisting the hostname is not enough on its own: if a firewall, secure web gateway, or cloud security service (for example Cisco Umbrella, Zscaler, or a UTM appliance) performs HTTPS/SSL inspection on this connection, the agent will reject it and the command channel will never come up. Add `gateway.tridentstack.com` to your inspection **exemption/bypass** list. The command channel also connects directly and does not use a configured web proxy, and it requires HTTP/2, which some older proxy appliances do not support. Traffic to `control.tridentstack.com` is ordinary HTTPS and tolerates inspection and proxies normally. **How this looks when it is misconfigured:** the endpoint enrolls successfully and appears in the console, but stays in the **Onboarding** state indefinitely and never shows as Online. Enrollment and check-ins use `control.tridentstack.com` (which works through inspection), while the command channel to `gateway.tridentstack.com` is silently broken. When TridentStack Control can determine the cause, the endpoint's detail page shows a banner naming the likely reason (for example, a security appliance intercepting the connection, including the certificate authority it presented) and what your network team needs to allow, and the Endpoints list flags the affected endpoint. To confirm manually, open `https://gateway.tridentstack.com` in a browser on the affected endpoint and view the certificate: if the issuer is anything other than Let's Encrypt, your network is intercepting the connection and an inspection exemption is needed. ::: ### Why the gateway connection cannot be inspected This is a deliberate security control, and it matches the posture used by other security-sensitive endpoint and management agents. If your team inspects all outbound traffic by policy, here is the reasoning to bring to a security review before granting the exemption. The command channel to `gateway.tridentstack.com` is the most sensitive connection the agent makes. It carries the instructions the agent carries out with system-level privileges, including the agent's own updates. If that channel could be impersonated, whoever impersonated it could direct agents across your fleet. To prevent that, the agent pins the connection to the public certificate authority the gateway actually uses and refuses any certificate that has been substituted, whether by a misissued or compromised public certificate or by an inspection appliance re-signing the traffic with its own authority. An SSL-inspection appliance presents its own certificate in place of the real one by design, so the agent treats it the same as any other substitution and declines to bring the channel up. This is what stops a network-positioned party from reading or injecting commands, or pushing a malicious update, on the one channel where that would matter most. The exemption is deliberately narrow. Only this single command channel is pinned. Everything else the agent sends, enrollment, inventory and telemetry uploads, update downloads, and log collection, goes to `control.tridentstack.com` over ordinary HTTPS and continues to pass through your inspection and proxy stack as usual. Exempting `gateway.tridentstack.com` therefore removes only one known vendor endpoint from inspection, not the bulk of the agent's traffic. The integrity of anything the agent downloads and installs is verified independently of the transport, so the exemption does not create a way to tamper with what the agent runs. In practice this is the same kind of single-hostname bypass most endpoint protection and management agents require for their own management channels. ## Enrollment tokens Each tenant has an enrollment token that is automatically created when your account is provisioned. The token is pre-filled into the quick install commands on the Agent Installers page, so in most cases you do not need to copy it manually. To view or regenerate your token: 1. Log in to TridentStack Control. 2. Navigate to **Settings** in the left sidebar. 3. Select the **Agent Installers** tab. 4. Your enrollment token and ready-to-use install commands are displayed on the page. :::warning Treat your enrollment token like a password. Anyone with the token can register agents to your tenant. If you suspect a token has been compromised, regenerate it from the Agent Installers page. ::: ### Download a pre-filled install script If you would rather review the install script before running it, or you are installing on a machine where piping a command straight into a shell is not an option, use the **Download Script** button on each platform's card. The downloaded script comes pre-filled with your enrollment token, so you can copy it to the endpoint, run it, and the agent installs and registers automatically without passing the token by hand. ## Enrollment flow The following diagram shows what happens when you install and start an agent: ```mermaid flowchart LR A[Agent installed on endpoint] --> B[Reads enrollment token] B --> C[Connects to gateway via gRPC] C --> D[Authenticates with server] D --> E[Registers in database] E --> F[Appears in Endpoints list] ``` ## Windows installation ### Quick install (recommended) The fastest way to install the agent is the PowerShell one-liner shown on the Agent Installers page. Open PowerShell **as Administrator** and run the command displayed there. It downloads the MSI, installs silently with your enrollment token, and cleans up. The command is pre-filled with your enrollment token, so no manual token entry is needed. :::tip The quick install command is ready to copy from **Settings > Agent Installers**. Just click the copy button next to the PowerShell command. ::: :::note Installing on Windows Server 2016, Windows Server 2012 R2, or Windows 8.1? Turn on the **Older Windows** toggle next to the Quick Install command first. Those systems need an extra step to connect securely, and the toggle adds it for you. Without it, the command fails with "Could not create SSL/TLS secure channel." ::: ### MSI installer (scripted or GPO) For SCCM, Intune, Group Policy, or other management tools, download the MSI from the Agent Installers page and deploy with `msiexec`: ```powershell msiexec /i TridentStack-Control.msi ENROLLMENT_TOKEN="" /qn /norestart ``` The `/qn` flag runs the installer silently with no UI. The `/norestart` flag prevents automatic reboots. :::warning If you regenerate your enrollment token, any previously distributed install commands using the old token will fail to enroll new agents. Update your deployment scripts with the new token after regeneration. Existing agents already enrolled are not affected. ::: ## Linux installation Run the following one-liner as root (or with `sudo`): ```bash curl -fsSL https://control.tridentstack.com/api/agent-packages/installer/linux/install | sudo bash -s -- --key ``` This script will: 1. Detect your distribution and architecture. 2. Download the appropriate `.deb` package. 3. Install the TridentStack Control agent as a systemd service. 4. Configure the agent with your enrollment token. 5. Start the service immediately. :::tip Agents automatically update to the latest version. No manual updates are needed after initial enrollment. ::: ## macOS installation :::note macOS support requires macOS 14.0 (Sonoma) or later. Both Apple Silicon (M-series) and Intel Macs are supported via a universal binary. ::: Run the following one-liner with `sudo`: ```bash curl -fsSL https://control.tridentstack.com/api/agent-packages/installer/macos/install | sudo bash -s -- --key ``` This script will: 1. Download the latest macOS agent package. 2. Verify the download's SHA256 hash before installing. 3. Configure the agent with your enrollment token. 4. Install the agent using macOS's standard installer (`.pkg` format). 5. Register the agent with TridentStack Control automatically. :::tip Agents automatically update to the latest version. No manual updates are needed after initial enrollment. ::: The macOS package is signed and notarized, so Gatekeeper installs it without warnings or manual approval steps. ### Enabling macOS update installation (Apple Silicon) On Apple Silicon Macs, Apple requires authentication by a local administrator account before the system will install macOS updates or OS upgrades. The TridentStack Control agent passes these credentials to Apple's installer when it runs a macOS update on your behalf. Without them, macOS update and upgrade installations fail immediately with a message that installer credentials are not configured. To enable macOS update installation, add a local administrator account to the agent configuration file at `/Library/Application Support/TridentStack/agent.json`. Add these two keys to the existing JSON (do not replace the file): ```json { "installerAdminUser": "localadmin", "installerAdminPassword": "account-password" } ``` Then restart the agent so it picks up the change: ```bash sudo launchctl kickstart -k system/com.tridentstack.agent ``` A few notes on this configuration: - The account must be a local administrator on the Mac. On Apple Silicon this account authorizes the update at the firmware level, so it must be a regular local admin (accounts created during macOS setup qualify), not a network-only account. - `agent.json` is owned by root with `0600` permissions, so the credentials are readable only by root. - The password is automatically redacted from any diagnostic logs collected through TridentStack Control. - Intel Macs do not require these credentials; setting them there is harmless. ### Verifying the agent is running After installation, confirm the agent service is active: ```bash sudo launchctl list | grep tridentstack ``` You can also follow the live agent log: ```bash tail -f /var/log/tridentstack/agent.log ``` ### Uninstalling To remove the agent from a macOS endpoint, run: ```bash curl -fsSL https://control.tridentstack.com/api/agent-packages/installer/macos/install | sudo bash -s -- --uninstall ``` ## Verifying enrollment After installation, the agent should appear in TridentStack Control within 60 seconds: 1. Navigate to **Agents > Endpoints** in the left sidebar. 2. Look for the new endpoint by hostname. 3. Confirm the **Status** column shows **Online**. Once online, the agent begins its first telemetry refresh, reporting system information, installed software, and applicable updates. This initial data collection typically completes within a few minutes. ## Troubleshooting ### Agent does not appear in Endpoints If the agent does not show up after 60 seconds, work through these checks in order: **1. Verify the agent service is running.** On Windows: ```powershell Get-Service 'TridentStack-ControlService' ``` The service status should be `Running`. On Linux: ```bash sudo systemctl status tridentstack-agent ``` The service should show `active (running)`. On macOS: ```bash sudo launchctl list | grep tridentstack ``` The entry should be present with a PID (not a dash) in the first column. **2. Check network connectivity.** Confirm the endpoint can reach the TridentStack Control gateway on port 443. Test with: ```bash curl -v https://gateway.tridentstack.com ``` If the connection times out or is refused, check your firewall rules and proxy configuration. If the endpoint enrolled and appears in the console but stays in the **Onboarding** state and never comes Online, the command channel to `gateway.tridentstack.com` is being blocked or intercepted while regular API traffic still works. This is almost always HTTPS/SSL inspection or a forced proxy on that connection: see the TLS inspection note under [Network requirements](#network-requirements). Check the endpoint's detail page first: when TridentStack Control can determine the cause, it shows a banner naming the specific reason and the fix. To confirm manually, open `https://gateway.tridentstack.com` in a browser on the endpoint and check the certificate issuer; anything other than Let's Encrypt means the connection is being intercepted and needs an inspection exemption. **3. Verify the enrollment token.** An expired or invalid token will prevent registration. Go to **Settings > Agent Installers** and confirm the token you used matches the one displayed. If in doubt, regenerate the token and reinstall the agent with the new value. **4. Check agent logs.** On Windows, logs are located at: ``` C:\ProgramData\TridentStack Control\logs\ ``` On Linux, use journalctl: ```bash sudo journalctl -u tridentstack-agent --no-pager -n 50 ``` On macOS, logs are located at: ```bash tail -n 50 /var/log/tridentstack/agent.log ``` Look for connection errors, authentication failures, or TLS handshake issues. ### Agent shows as Offline If an agent previously appeared but now shows Offline: - The endpoint may be powered off or disconnected from the network. - A firewall change may be blocking outbound traffic on port 443. - The agent service may have stopped. Restart it and check logs for errors. --- # First Steps URL: https://docs.tridentstack.com/getting-started/first-steps Description: Your first hour with TridentStack Control: your organization arrives pre-configured with default update policies and an all-endpoints tag, so you enroll your endpoints, watch updates appear, and create a deployment ring to install them. # First Steps Once you have logged in and enrolled at least one agent, this guide walks you through the TridentStack Control interface and the recommended steps to get your environment configured. ## Your organization comes ready to go When your organization is created, TridentStack Control sets it up with sensible defaults so you see results as soon as you enroll your first endpoint. Out of the box, your organization includes: - **A default system update policy** that automatically approves operating system updates older than 7 days with no unresolved known issues, then surfaces them for your review. - **A default application updates policy** covering more than 30 popular applications. It keeps those applications current if they are installed, and never installs an application that is not already present. - **An "all endpoints" tag** that every newly enrolled device joins automatically, so the default policies apply to your fleet from the moment a device checks in. Because of this, you do not need to create a policy or a tag before you get value. As soon as you enroll an endpoint, applicable operating system and application updates begin appearing for it. :::warning The default policies surface and pre-approve updates for your review, but nothing installs automatically. To actually install updates on your endpoints, you create and assign a [deployment ring](../platform-guide/update-management/deployment-rings). This keeps you in control of when and how patches roll out. ::: ## What you see after login After logging in, you land on the **Dashboard**. The default system dashboard provides a high-level view of your fleet: agent status, patch compliance, vulnerability counts, and recent activity. The system dashboard is read-only, but you can clone it or create your own custom dashboards where widgets can be freely added, removed, and rearranged. The dashboard system is highly modular, allowing you to build visualizations for essentially any data within the platform. ## Navigation overview The left sidebar is your primary way to move between sections. It is organized into these areas: | Section | Pages | Purpose | |---------|-------|---------| | **Dashboard** | Dashboard | Fleet overview with customizable widgets | | **Agents** | Endpoints, Tags, Automation | Manage enrolled devices, organize them with tags, create automation rules | | **Update Management** | System Updates, Application Updates, Deployment Rings | Create patch policies, manage third-party app updates, configure phased rollouts | | **Configuration Policies** | Configuration Policies | Apply and enforce device configuration settings | | **Vulnerabilities** | Vulnerabilities | View detected CVEs across your fleet, manage exceptions | | **Compliance** | Compliance | Measure endpoints against CIS, DISA STIG, Microsoft, and NIST baselines | | **Reporting** | Reporting | Build custom reports with the visual query builder or SQL editor | At the bottom of the sidebar: | Section | Purpose | |---------|---------| | **System Audit** | Activity logs and change tracking | | **Settings** | Platform configuration, user management, API keys, agent installers | :::tip The sidebar can be collapsed to icon-only mode by clicking the collapse button at the bottom. This gives you more screen space when working in detail views. ::: ## Recommended onboarding workflow Because your organization arrives pre-configured, getting to a fully managed environment is mostly a matter of enrolling endpoints and deciding how you want updates to roll out: ```mermaid flowchart LR A[Enroll endpoints] --> B[Updates start appearing] B --> C[Create and assign a deployment ring] C --> D[Review vulnerabilities] D --> E[Set up compliance baselines] ``` The default update policies and the "all endpoints" tag are already in place, so enrolled devices are covered immediately. The one action that actually installs updates is creating and assigning a deployment ring. From there, you can refine targeting with your own tags and add compliance baselines as your needs grow. ## How targeting works Understanding the relationship between agents, tags, and policies is key to managing your fleet effectively. ```mermaid flowchart TD A[Agents] -->|assigned to| B[Tags] B -->|targeted by| C[System Update Policies] B -->|targeted by| D[Application Update Policies] B -->|targeted by| E[Configuration Policies] B -->|targeted by| F[Compliance Baselines] C -->|can use| G[Deployment Rings] D -->|can use| G ``` The hierarchy works like this: - **Tags are the only thing directly associated with an agent.** You do not assign policies to individual endpoints. Instead, you assign tags to agents and then target policies at those tags. - **All policies target tags.** System update policies, application update policies, configuration policies, and compliance baselines are all associated with tags, not individual agents. When you add or remove an agent from a tag, it automatically gains or loses every policy targeting that tag. - **Deployment rings are associated with update policies, not tags or agents.** Both system update policies and application update policies can use deployment rings. Rings control the rollout pace of a specific policy and determine what percentage of the targeted agents receive updates at each stage. :::note Linux updates are managed exclusively through system update policies. Application update policies apply to Windows and macOS endpoints. ::: :::info This design means you manage your fleet by organizing agents into the right tags. Once your tags are set up, adding a new endpoint is as simple as assigning its tags - all relevant policies apply automatically. ::: :::note Your organization's default update policies are already targeted at the built-in "all endpoints" tag, and every newly enrolled device joins that tag automatically. That is why updates begin appearing without any setup. You can create additional tags and policies whenever you want finer-grained control. ::: ## Step 1: Verify your agents Before configuring anything, confirm your agents are communicating properly. 1. Navigate to **Agents > Endpoints** in the left sidebar. 2. Check that each enrolled endpoint shows a **Status** of **Online**. 3. Review the **Last Seen** column to confirm agents are actively reporting. If any agents show as Offline, refer to the [Agent Enrollment troubleshooting section](./agent-enrollment#troubleshooting) before proceeding. ## Step 2: Confirm updates are appearing Thanks to the default policies and the "all endpoints" tag, you do not need to create anything to start seeing results. Once an endpoint is online and has completed its first telemetry refresh, applicable updates show up automatically. 1. Navigate to **Update Management > System Updates** to see operating system updates the default policy has surfaced and pre-approved for your endpoints. 2. Navigate to **Update Management > Application Updates** to see third-party application updates for the popular applications that are installed on your fleet. 3. Open an individual endpoint from **Agents > Endpoints** to see the updates applicable to that specific device. Remember that surfaced and pre-approved updates are ready for installation, but they do not install on their own. The next step puts them into action. :::note The default application updates policy only updates applications that are already installed. It will not add new software to an endpoint. ::: ## Step 3: Create and assign a deployment ring to install updates A deployment ring is what actually rolls out approved updates to your endpoints. It also lets you control the pace: you can install to a small test group first, watch the results, and then expand to the rest of your fleet in phases. 1. Navigate to **Update Management > Deployment Rings**. 2. Click **Create Ring** and give it a descriptive name (for example, "Standard Rollout"). 3. Define the rollout phases, or start from a built-in preset. A common pattern is a small canary group first, followed by progressively larger waves until every targeted endpoint is covered. 4. Assign the ring to an update policy. You can attach it to the default system update policy, the default application updates policy, or any policy you create. 5. Save the ring. Once a ring is assigned to a policy, approved updates begin installing on the targeted endpoints according to the ring's schedule and phase settings. For a full walkthrough of phases, advancement rules, and presets, see [Deployment Rings](../platform-guide/update-management/deployment-rings). :::warning When trying out a new rollout, start with a small phase so updates reach a handful of non-critical endpoints first. Confirm the results, then let the ring expand to the rest of your fleet. ::: ## Step 4: Organize with your own tags (optional) The built-in "all endpoints" tag covers your whole fleet, which is perfect for getting started. As your environment grows, you will likely want to group endpoints more precisely so you can apply different policies to different sets of devices. 1. Navigate to **Agents > Tags**. 2. Create tags that reflect your environment. Common examples: - **Production** and **Development** (by environment) - **Windows Servers** and **Linux Servers** (by platform) - **Finance**, **Engineering**, **HR** (by department) - **US-East**, **EU-West** (by location) 3. Assign tags to endpoints from the **Agents > Endpoints** page by selecting one or more agents and using the tag assignment action. 4. Target a policy at your new tags by editing the policy and choosing those tags under **Targets**. :::note A single endpoint can have multiple tags. For example, a server might be tagged as both "Production" and "Windows Servers". When a policy targets either tag, that server receives the policy. ::: :::tip To create your own update policy, navigate to **Update Management > System Updates** or **Update Management > Application Updates**, click **Create Policy**, choose which updates to include and how they are approved, and select the tags it targets. See [System Updates](../platform-guide/update-management/system-updates) and [Application Updates](../platform-guide/update-management/application-updates) for details. ::: ## Step 5: Review vulnerabilities TridentStack Control automatically scans your fleet for known vulnerabilities based on installed software and missing patches. 1. Navigate to **Vulnerabilities** in the left sidebar. 2. Review the list of detected CVEs, sorted by severity (Critical, High, Medium, Low). 3. Click any CVE to see which endpoints are affected and whether a patch is available. 4. For vulnerabilities that cannot be patched immediately (due to compatibility requirements or other constraints), create an **exception** with a justification and expiration date. Vulnerability data updates automatically as agents report new software inventory and as new CVE information becomes available. No manual scans are required. You can also view vulnerabilities for a specific endpoint by navigating to its details page in **Agents > Endpoints** and selecting the **Vulnerabilities** tab. This gives you a per-agent view of all detected CVEs affecting that individual endpoint. ## Step 6: Check compliance Compliance baselines measure your endpoints against industry-standard security frameworks. Unlike vulnerabilities (which are detected automatically), compliance evaluation requires you to assign a baseline to your endpoints first. 1. Navigate to **Compliance** in the left sidebar. 2. Review the available frameworks: CIS Benchmarks, DISA STIGs, Microsoft Security Baselines, and NIST controls. 3. Assign a baseline to one or more tags. Endpoints with those tags will begin compliance evaluation on their next check-in. 4. Once evaluation completes, select a baseline to see your fleet's compliance score and which specific controls are passing or failing. 5. Drill into individual controls to see affected endpoints and remediation guidance. :::info Compliance evaluation only runs on endpoints that have a baseline assigned through their tags. If you do not see compliance data for an endpoint, verify that its tags are associated with at least one compliance baseline. ::: ## Next steps With endpoints enrolled, updates appearing through your default policies, and a deployment ring installing them, you have a working environment. From here, explore these areas: - **Application Updates** - Review and tune the third-party application patches that the default policy surfaces, or create your own application policies. - **Deployment Rings** - Refine your phased rollouts so patches reach test groups before production. - **Configuration Policies** - Enforce device settings (security configurations, feature toggles) across your fleet. - **Automation** - Create rules that automatically tag, patch, or notify based on endpoint conditions. - **Reporting** - Build custom reports to share patch compliance and vulnerability status with stakeholders. --- # Connect your AI assistant URL: https://docs.tridentstack.com/getting-started/connect-your-ai Description: Add the TridentStack Control documentation MCP server to Claude, Cursor, or any MCP-compatible AI assistant so it can answer questions from our docs. # Connect your AI assistant TridentStack Control publishes a Model Context Protocol (MCP) server for its documentation. Add it to an MCP-compatible AI assistant, such as Claude or Cursor, and the assistant can search and read the TridentStack Control documentation directly. Its answers stay grounded in our current guides, API reference, changelog, and roadmap. The server is read-only and public. It exposes no account or fleet data, and it needs no sign-in or API key. ## Server URL ``` https://docs.tridentstack.com/mcp ``` The transport is Streamable HTTP. ## Add it to your assistant ### Claude Code ```bash claude mcp add --transport http tridentstack-docs https://docs.tridentstack.com/mcp ``` ### Claude Desktop 1. Open Settings, then Connectors. 2. Add a custom connector. 3. Set the URL to `https://docs.tridentstack.com/mcp`. 4. Save, then start a new chat. ### Cursor Add the server to your `mcp.json`: ```json { "mcpServers": { "tridentstack-docs": { "url": "https://docs.tridentstack.com/mcp" } } } ``` ### Other assistants Any client that supports a remote MCP server over Streamable HTTP can use the same URL. ## What the assistant can do Once connected, the assistant has three tools: - `search_docs`: full-text search across the documentation. Returns ranked results with titles, links, and snippets. - `get_doc`: read a specific documentation section in full. - `list_docs`: browse the documentation catalog. Ask a normal question, such as "How do deployment rings work in TridentStack Control?" or "Which API endpoint lists agents?" The assistant searches the docs, reads the relevant sections, and answers with links back to the source pages. ## Prefer a plain file? If your tool does not speak MCP, the same content is published as plain text: - [llms.txt](https://docs.tridentstack.com/llms.txt): a short index of the documentation. - [llms-full.txt](https://docs.tridentstack.com/llms-full.txt): the entire documentation as a single Markdown file. --- # Endpoints URL: https://docs.tridentstack.com/platform-guide/agents/endpoints Description: Manage every enrolled Windows, macOS, and Linux endpoint from the Endpoints page in TridentStack Control: search, filter, tag, and bulk-action. # Endpoints The Endpoints page (**Agents > Endpoints**) is the central hub for managing all enrolled agents. Every Windows, macOS, and Linux endpoint running the TridentStack Control agent appears here, giving you a single view of your entire fleet. --- ## Endpoint list ### Data table The endpoint list is a full-featured data table with sortable columns, search, and filtering. Available columns include: | Column | Description | |--------|-------------| | Status | Current connection state (Online, Offline, Onboarding) | | Hostname | The endpoint's computer name | | IP Address | Last reported internal IP address | | Operating System | OS name (e.g., Windows Server 2022, Ubuntu 24.04) | | Agent Version | Installed TridentStack Control agent version | | Current User | Currently logged-in user on the endpoint | | Tags | Assigned tag labels | | Uptime | Time since the endpoint was last restarted | | Last Check-in | Timestamp of the most recent heartbeat | | Registered | When the agent first enrolled | | System Updates | Count of pending system updates | | App Updates | Count of pending application updates | | System Update Policy | The system update policy the endpoint effectively follows (resolved from its tags) | | App Update Policy | The application update policies the endpoint effectively follows (resolved from its tags; an endpoint can inherit more than one, see [Application Updates - Multiple policies per endpoint](/platform-guide/update-management/application-updates#multiple-policies-per-endpoint)) | | OS Build | Operating system build number | | Platform | Endpoint platform (Windows, Linux) | | Health Score | Calculated health metric based on patch status and compliance | | Update Health | A per-endpoint readiness badge for update installs (Blocked, Action recommended, Healthy, or Unknown) | | Vulnerabilities | Total number of detected CVEs | | Critical Vulns | Count of critical-severity CVEs | | High Vulns | Count of high-severity CVEs | | Medium Vulns | Count of medium-severity CVEs | | Low Vulns | Count of low-severity CVEs | | Disk Free | Available disk space on the system drive | ### Column customization Click the **column manager** dropdown in the toolbar to show or hide columns, reorder them by dragging, or reset to the default layout. Column widths can be adjusted by dragging the border between column headers. ### Update Health column The **Update Health** column gives you a per-endpoint readiness badge that tells you, at a glance, whether an endpoint is ready to install updates or has an issue that needs attention first. It surfaces the same pre-flight readiness signal you see on an individual endpoint's [System State](/platform-guide/agents/system-state) view, brought up to the fleet level so you can scan your whole list at once. Each endpoint shows one of these states: - **Blocked** - A critical issue, such as low disk space, will cause update installs to fail until it is resolved. - **Action recommended** - A warning worth addressing, though installs can still proceed. - **Restart pending** - The only thing holding the endpoint back is a pending restart needed to finish applying updates. Restart the endpoint to clear it. - **Healthy** - The endpoint passed its readiness checks and is ready for updates. Endpoints with no readiness data yet show a dash (`--`) rather than a status. This is normal for macOS and Linux endpoints today, while their pre-flight checks are still being rolled out, and for any endpoint that has not reported yet. If a Windows endpoint that was previously reporting stops sending readiness data, it shows **Unknown**. Add the column from the **column manager** dropdown. To find every endpoint in a given state, expand any endpoint row and use the include and exclude filter buttons next to its Update Health value (see [Quick filtering from expanded rows](#quick-filtering-from-expanded-rows) below). For example, filter to **Blocked** to see only the endpoints where updates cannot install until you act. The set of checks behind this badge is most comprehensive on Windows today, and is expanding to macOS and Linux endpoints (disk space and pending restarts). ### Status indicators Each endpoint displays one of the following status indicators: - **Online** (green) - Agent is connected and actively reporting - **Offline** (gray) - Agent has not checked in recently - **Onboarding** (yellow) - Agent has registered but has not yet completed its first telemetry refresh ```mermaid stateDiagram-v2 [*] --> Onboarding: Agent installed Onboarding --> Online: First telemetry complete Online --> Offline: No heartbeat Offline --> Online: Heartbeat received ``` ### Expanded row details Click any row in the table to expand it and see detailed system information without leaving the list view. The expanded section includes: - **OS details** - Full operating system name, version, and build number - **Hardware specs** - CPU, memory, and disk information - **Agent version** - Currently installed agent version - **Assigned tags** - All tags applied to the endpoint - **Pending updates** - Count and summary of updates awaiting installation ### Search and filter Use the **search bar** at the top of the table to filter endpoints by hostname, IP address, current user, operating system, tag name, or assigned update policy name. Type part of any of these and the list narrows as you type. #### Active filters When filters are applied, they appear as tagged pills in the filter bar below the toolbar. Each filter shows its field and value, and can be removed individually by clicking the **X** button. A **Clear All** button removes all active filters at once. #### Quick filtering from expanded rows When you expand an endpoint row, each field in the detail panel displays **+** and **-** filter buttons: - **+** (include) filters the table to show only endpoints matching that value (for example, clicking **+** next to an OS version shows only endpoints running that version) - **-** (exclude) filters the table to hide endpoints matching that value This lets you quickly drill into or exclude groups of endpoints without manually constructing filters. :::tip Combine search with column sorting to quickly find problem endpoints. For example, sort by "System Updates" descending and search for a specific tag to find the most out-of-date machines in a group. ::: ### Bulk actions Select multiple agents using the checkboxes on the left side of the table. Once you have a selection, the bulk action bar appears with the following options: - **Restart agents** - Send a restart command to all selected endpoints - **Install pending updates** - Trigger immediate installation of approved updates - **Assign tags** - Add one or more tags to the selected endpoints - **Remove tags** - Remove a specific tag from the selected endpoints :::note Bulk actions are dispatched to agents immediately over the persistent gRPC connection. Online agents begin processing the command right away. Offline agents will receive the command when they reconnect. ::: --- ## Agent detail page Click an agent's **hostname** in the endpoint list to navigate to the full agent detail page. This dedicated view combines always-visible summary sections with tabbed detail views, providing complete visibility into a single endpoint. ### Page layout The agent detail page is divided into sections that are always visible regardless of which tab is selected, followed by a tab bar for deeper views. #### Header The top bar displays the agent's **hostname**, **status badge** (Online, Offline, Onboarding), **agent ID**, and any **assigned tags**. If the agent replaced a previously retired endpoint (same hardware re-enrolled), a "Replaced Retired Endpoint" badge links to the retired record's history. An **Actions** dropdown menu provides: - **Manage Tags** - Add or remove tags from this agent - **Install System Updates** - Trigger installation of all approved pending system updates. Shows a "No Policy" indicator and is disabled when no system update policy is assigned, or "Disabled" when the assigned policy does not allow manual installation - **Install Application Updates** - Trigger installation of all approved pending application updates (Windows and macOS). Shows a "No Policy" indicator and is disabled when no application update policy is assigned, or "Disabled" when none of the pending applications are covered by an assigned policy - **Install Office Updates** - Update Microsoft Office if an update is available (Windows and macOS, appears only when Office is installed) - **Push Policies** - Push all assigned configuration policies to the agent - **Restart Agent** - Send a restart command to the agent service - **Request Restart** - Request a system restart (when a reboot is pending after updates) - **Collect Logs** - Trigger agent log collection for troubleshooting - **Retire Endpoint** - Retire this agent record #### Status bar Below the header, a status bar shows key metrics at a glance: - **System** - Count of pending system updates with last check time - **Applications** - Count of pending application updates with last check time (Windows and macOS) - **Heartbeat** - Timestamp of the most recent heartbeat - **Uptime** - Time since the endpoint was last restarted - **Disk** - Free disk space on the system drive with a color indicator (green, yellow, or red based on usage) - **Registered** - When the agent first enrolled A **Live** indicator shows that the page auto-refreshes every few seconds. #### System Information An always-visible panel organized into five columns: | Column | Fields | |--------|--------| | **Agent Identity** | Hostname, Status, Agent Version, Current User, Directory Join Status | | **Activity & Network** | Last Check-in, Registered, External IP, Internal IP | | **System** | Operating System, OS Build, Architecture, System Model | | **Update Policies** | Assigned system update policy and application update policy or policies with their target tags | | **Configuration Policies** | Assigned configuration policies with their target tags | #### Hardware Details A collapsible section (collapsed by default) showing detailed hardware information: CPU model, core count, clock speed and cache sizes, memory modules with capacity and speed, disk partitions with usage, baseboard details, and hardware UUID. #### Pending Updates Always visible above the tab bar. Displays pending updates in two side-by-side panels: - **Pending System Updates** (left) - Approved system updates awaiting installation. Shows KB number, title, severity, estimated install time, Install Stats, and scheduled deployment time. A count badge shows the total. Right-click any update to trigger installation. - **Pending Application Updates** (right) - Third-party application updates with the app name, installed version, target version, Install Stats, and scheduled deployment time (Windows and macOS). Each row also shows the application update policy currently governing that application. When the endpoint inherits more than one policy for the same application, an info icon explains which policy won and why. An application not covered by any assigned policy is labeled "No Policy" (no application update policy assigned) or "Not in Policy" (the assigned policies do not cover that application) and cannot be installed manually until a policy covers it. - **Pending Linux Updates** (Linux agents) - Package updates with name, current and available versions, Install Stats, and estimated install time. The **Install Stats** column shows fleet-wide installation success metrics (deployment count and success rate). Hover or click for details including confidence level and common errors. See [System Updates - Install Stats](/platform-guide/update-management/system-updates#install-stats) for more information. Each panel has its own refresh button and shows the time since the last check. **Held-back system updates.** If a system update repeatedly fails to install on an endpoint (for example, one Windows rejects while applying it during a restart), TridentStack Control stops attempting it automatically so it does not restart the endpoint over and over. The update stays listed as needed, and in the Pending System Updates panel its scheduled deployment column shows a **Held back** label instead of a deployment time. Select the label to read why the update was held back, and use the **Retry** button next to it, once you have resolved the underlying endpoint issue, to queue the update again for the next deployment window. ### Tabs Below the always-visible sections, the tab bar provides access to detailed views: | Tab | Description | |-----|-------------| | [Health](/platform-guide/agents/health-score) | Overall health score with vulnerability, compliance, update, and network dimensions | | [System State](/platform-guide/agents/system-state) | OS details, installed updates/packages, endpoint protection, and Windows Defender status | | [Software Inventory](/platform-guide/agents/software-inventory) | All installed software with version and update status | | [Vulnerabilities](/platform-guide/agents/vulnerabilities) | CVEs detected on this endpoint with severity and remediation options | | [Network](/platform-guide/agents/network-exposure) | Listening ports, firewall state, and exposure assessment | | [Compliance](/platform-guide/agents/compliance) | Compliance framework scores and per-control evaluation results | | [Effective Policy](/platform-guide/agents/effective-policy) | Resolved policy settings from all sources with conflict detection (Windows only) | | [History](/platform-guide/agents/history) | Chronological log of all operations, tasks, and telemetry events | --- # Dashboard URL: https://docs.tridentstack.com/platform-guide/dashboard Description: The TridentStack Control dashboard gives you a customizable, at-a-glance picture of fleet health, update posture, vulnerabilities, and recent activity. # Dashboard The dashboard is the first page you see after logging in. It provides a customizable overview of your fleet's health, update status, and activity, giving you an at-a-glance picture of what matters most. ## Widget system The dashboard uses a panel-based widget system. You can add, remove, and rearrange widgets to create a view that fits your workflow. Each widget is an independent panel that displays a specific metric, chart, or data feed. ### Available widget types | Widget Type | Description | |-------------|-------------| | Time series chart | Track metrics over time (e.g., patch compliance trending) | | Bar chart | Compare categories side by side (e.g., updates by status) | | Pie chart | Visualize proportions (e.g., OS distribution across your fleet) | | Stat panel | Display a single key number (e.g., total agents, online count) | | Gauge panel | Show progress toward a target (e.g., compliance percentage) | | Heatmap | Spot patterns by time of day (e.g., activity by hour) | | Activity log | Stream recent events as they happen | | Table | List ranked data (e.g., top vulnerable agents) | | Header panel | Add section dividers to organize your layout | ## Edit mode Click the **Edit** button in the top-right corner to enter edit mode. The built-in default dashboard is a read-only template, so it does not offer an Edit button: to customize it, clone it first and edit your copy. While in edit mode you can: - **Add new panels** from the widget catalog - **Drag panels** to rearrange their position on the grid - **Resize panels** by dragging the bottom-right corner handle - **Remove panels** by clicking the delete button on any widget Click **Save** to apply your changes, or **Cancel** to discard them and revert to the previous layout. ```mermaid flowchart LR A[View mode] -->|Click Edit| B[Edit mode] B --> C[Add / Move / Resize / Remove widgets] C -->|Click Save| A C -->|Click Cancel| A ``` ## Time range picker Use the time range selector in the top-right toolbar to control the period displayed across all dashboard widgets. Available options include: - **Last 24 hours** - **Last 7 days** - **Last 30 days** - **Custom range** (select a specific start and end date) Changing the time range updates every widget on the current dashboard simultaneously. ## Multiple dashboards You are not limited to a single dashboard. Create multiple dashboards for different audiences or workflows: - **Executive Overview** with high-level compliance gauges and fleet health stats - **Security Team** with vulnerability counts, CVE trends, and top-risk endpoints - **Operations** with update deployment status, agent connectivity, and activity logs Set any dashboard as your **favorite** to have it load automatically when you log in. :::tip Start by cloning the default dashboard, then customize your copy over time as you learn which metrics matter most to your team. ::: --- # System Updates URL: https://docs.tridentstack.com/platform-guide/update-management/system-updates Description: Build system update policies in TridentStack Control to deploy Windows, macOS, and Linux patches with deployment rings, schedules, and approval gates. # System Updates System update policies control how Windows and Linux patches are deployed to your endpoints. Each policy defines which updates to install, which agents to target, and when installations should occur. You can run multiple policies in parallel to handle different groups of endpoints with different patching strategies. ## How TridentStack Control manages Windows Update When the TridentStack Control agent is installed on an endpoint, it automatically suppresses native Windows Update. This ensures that the platform is the sole provider for system updates, preventing conflicts between Windows Update and your managed patching policies. - On modern systems (Windows 10 2004+, Windows 11, Server 2022+), the agent blocks quality, feature, and other updates while allowing driver updates through Windows Update. - On older systems (Server 2019, Server 2016), all update categories are blocked and managed exclusively through TridentStack Control. The agent verifies this configuration on every startup and reapplies it if it has been changed. No manual configuration is required. For full technical details, see the [Agent Reference](/reference/agent-reference#windows-update-management). ## Creating a policy Navigate to **Update Management > System Updates** in the left sidebar and click **Create Policy**. The policy creation form walks you through these sections: ### Name and description Give the policy a descriptive name that reflects its purpose and audience. For example, "Production Servers - Monthly Security Patches" or "Dev Workstations - Weekly All Updates". The description field is optional but recommended for documentation. ### Target agents Choose which endpoints receive this policy. You can target agents in two ways: - **By tag** - Select one or more tags. Any agent with a matching tag receives the policy. This is the recommended approach because new agents automatically pick up the policy when tagged. - **By individual assignment** - Select specific agents from the list. Useful for one-off policies or testing on a specific machine. ### Schedule Define a maintenance window that controls when updates are installed: - **Day of week** - Select one or more days (e.g., Tuesday and Thursday) - **Time window** - Set a start time and duration (e.g., 2:00 AM for 4 hours) - **Recurrence** - Weekly, biweekly, or monthly Agents only install updates during their assigned maintenance window. Outside the window, agents download and stage updates but do not install them. ### Pre-staging When enabled, agents download approved updates ahead of the maintenance window. This means the actual installation phase is shorter because the files are already on disk. Pre-staging is especially useful for large cumulative updates that take significant time to download. ### Restart behavior After updates are installed, some patches require a restart to complete. Configure how restarts are handled: | Option | Behavior | |--------|----------| | **Restart immediately** | Agent restarts as soon as installation completes, within the maintenance window | | **Schedule restart** | Agent waits until a configured time to restart (e.g., next morning at 6:00 AM) | | **User decides** | A notification is shown to the logged-in user, who can restart now or defer | | **No restart** | No automatic restart. The update remains in a pending-restart state until the machine is manually restarted | :::tip Use pre-staging to download updates ahead of the maintenance window. This reduces the time agents spend in the installation phase and keeps maintenance windows short. ::: ## Update approval workflow By default, updates are not approved for installation. You control exactly which patches reach your endpoints through the approval workflow. ### Browse available updates Open the policy detail page and use the update browser to see all patches that are available for the targeted endpoints. The browser shows update title, KB number, classification, severity, release date, and whether the update supersedes older patches. ### Approve updates Select individual KBs or approve in bulk by classification. Approved updates are eligible for installation during the next maintenance window. You can approve updates at any time, and they will be picked up by agents on their next check-in. ### Deny updates Explicitly deny updates you do not want installed. Denied updates are hidden from the available list and are never offered to agents. This is useful for known-problematic patches or updates that conflict with specific software in your environment. ### Auto-approve rules Set rules to automatically approve updates by classification after a configurable delay. For example: | Rule | Effect | |------|--------| | Auto-approve **Critical Updates** after **3 days** | Critical patches are approved 3 days after release | | Auto-approve **Security Updates** after **7 days** | Security patches are approved after a 1-week observation period | | Auto-approve **Definition Updates** immediately | Antivirus definitions are approved with no delay | Auto-approve rules are evaluated when an update policy is modified and when new updates are synced into the catalog. When an update matches a rule and the delay period has elapsed, it is approved automatically. You can combine auto-approve rules with manual review: auto-approve routine classifications and manually review higher-risk categories like Feature Packs or Service Packs. You can also filter by update name. Add an "Update Name / Title" condition and use `*` (any text) and `?` (single character) wildcards, for example `*Preview*` or `KB5034*`. Choose **matches** to include updates whose title fits the pattern, or **does not match** to exclude them (for example, approve all security updates except previews). Matching is case-insensitive. ## Update classifications Updates are organized by classification. Each classification represents a different type of patch: | Classification | Description | |----------------|-------------| | **Critical Updates** | Non-security fixes for critical bugs | | **Security Updates** | Patches that address security vulnerabilities | | **Definition Updates** | Antivirus and anti-malware signature updates | | **Feature Packs** | New product functionality distributed outside a full release | | **Service Packs** | Cumulative collections of hotfixes, security updates, and critical updates | | **Update Rollups** | Cumulative sets of hotfixes packaged together for easier deployment | | **Driver Updates** | Updated device drivers published through the update catalog | The classifications above describe Windows updates. Linux updates are organized by distribution security advisory instead, as described next. ## Linux updates The same policy framework deploys patches to your Linux fleet. Targeting by tag, maintenance windows, pre-staging, restart behavior, deployment rings, and deployment monitoring all work the same way as for Windows. What differs is where Linux updates come from and how you approve them. ### Supported distributions TridentStack Control manages updates on: - Ubuntu 20.04 LTS and later - Debian 12 and later - RHEL 8 and later, plus the RHEL-compatible Rocky Linux 8 and later and AlmaLinux 8 and later - Fedora (latest stable) - Amazon Linux 2 and later The agent uses each system's native package manager (APT on Debian and Ubuntu, DNF on the RHEL family), so updates install exactly as the distribution intends. ### How Linux updates are detected The agent queries the system package manager for available package updates and reports them, flagging which ones are security updates. TridentStack Control enriches those against published distribution security advisories (Ubuntu Security Notices, Debian Security Advisories, and Red Hat advisories) to attach CVE references and severity. This lets you prioritize security-relevant updates consistently across a mixed Linux fleet. ### Approving Linux updates Linux updates use the same approval workflow described above: nothing installs until it is approved, and approved updates install during the targeted endpoints' next maintenance window. Because distributions publish a continuous stream of updates, auto-approve rules are the practical way to manage Linux at scale. Linux auto-approve rules can match on: - **Distribution and release** - for example, only Ubuntu 22.04, or every Debian release. - **Severity** - for example, auto-approve advisories rated High or Critical. - **Update age** - approve only after an update has been available for a set number of days, giving you a built-in soak period. You can combine these conditions (for example, "Ubuntu 22.04, security advisories rated High or above, at least 3 days old") and apply different rules to different endpoint groups by using separate policies targeted at different tags. ### Install all available updates By default, a Linux system update policy assigned to a deployment ring automatically deploys only updates tied to a published security advisory. The Linux Update Behavior section of the policy editor includes an option, **Install all available updates**, that changes this: when it is turned on, the ring deploys every pending Linux package update instead, not just the security-advisory ones. This option is off by default. Turning it on includes non-security updates and updates from third-party software repositories, applied automatically during deployment ring windows without security-advisory review. Enable it only when you want fully automated, comprehensive Linux patching and are comfortable with updates being applied without that review step. ### Restarts and kernel updates Most Linux package updates apply without a reboot. Kernel updates are the exception: the new kernel is installed but only takes effect after a restart. The policy's [restart behavior](#restart-behavior), and for ring-driven rollouts the ring's automatic-restart settings, control when that reboot happens, so kernel updates follow the same maintenance-window rules as the rest of your fleet. ## Microsoft Office updates System update policies can manage Microsoft Office versions on both Windows and macOS endpoints. Office is managed alongside system updates because the update channel is a policy decision, not a per-app one. On Windows, Office is delivered through the Click-to-Run service (`OfficeC2RClient.exe`) and channels follow Microsoft 365's standard channel names: Current, Monthly Enterprise, Semi-Annual Enterprise, Beta, and the long-term-servicing channels (LTSC 2021, LTSC 2024). On macOS, Office updates are delivered through Microsoft AutoUpdate (MAU) via the `msupdate` CLI. MAU has three channels: Production (the default for most users), Beta (the InsiderSlow ring), and Current Channel (Preview) (the InsiderFast ring). Channel names match exactly what `defaults read /Library/Preferences/com.microsoft.autoupdate2.plist ChannelName` returns on the endpoint. ### Enabling Office management on a policy In the policy edit screen, open the **Office Update Management** section and toggle **Enable Office Updates** on. With management enabled you can configure: - **Target Update Channel (Windows)** - which Microsoft 365 Click-to-Run channel Windows agents should track. Leave unset to keep each Windows agent on its existing channel. - **Target Update Channel (macOS)** - which MAU channel macOS agents should track. Leave unset to keep each macOS agent on its existing channel. - **Defer Updates (Days)** - delay between a channel release and when this policy considers it deployable, 0 to 365 days. Applies to both platforms. - **Auto-update Office when non-compliant** - whether the agent should self-trigger an Office update when it observes itself below the target version. - **Enable ring deployment for Office updates** - whether deployment rings dispatch Office as a stage in the ring's update chain (see below). A policy can apply to a mixed fleet. Each agent is evaluated against the channel selection for its own platform; an unset selection for one platform does not disable Office for the other. ### How Office updates are dispatched Office updates reach an endpoint in two ways: - **Through a deployment ring** - When the policy has both **Enable Office Updates** and **Enable ring deployment for Office updates** enabled, deployment rings dispatch Office as the stage between application updates and system updates. The ring evaluates each agent's Office version against the policy's target for that agent's platform and skips agents that are already compliant. See [the deployment ring dispatch order](./deployment-rings#dispatch-order-within-a-window) for where Office sits in the chain. - **Manual trigger from the agent detail page** - On a Windows or macOS agent's detail page, administrators can trigger an Office update directly. The manual trigger is gated on the same compliance check: if the agent is already at the policy's target version, or the policy has Office updates disabled, the manual trigger is refused with an explanation. There is no override for the manual path. To force a re-install, use a one-shot tag-based policy assignment with a different target instead. ### macOS-specific behavior - **Five apps are managed**: Word, Excel, PowerPoint, Outlook, and OneNote. Teams and OneDrive ship their own auto-updaters and are not part of the Office bundle for compliance purposes. - **Compliance uses the lowest installed version**: an agent is compliant only when every detected Office app is at or above the policy's target version. A single out-of-date app reports the agent as non-compliant. - **Cross-channel changes are best-effort**: MAU honours channel changes only when it next launches. A policy that switches a macOS agent's channel may not take effect until the user re-opens an Office app or MAU itself. - **MAU CLI prerequisite**: the agent invokes `msupdate` at `/Library/Application Support/Microsoft/MAU2.0/Microsoft AutoUpdate.app/Contents/MacOS/msupdate`. Microsoft has shipped this path since MAU 4.0 (2019); endpoints predating that will not have current Office at all. ### Why Office runs before system patches in the ring System patches often require a reboot. Running Office ahead of system patches in the ring chain means the Office update completes against the still-current OS state and does not have to wait for a reboot cycle. Both Click-to-Run on Windows and MAU on macOS handle their own in-place updates without rebooting the endpoint, so the chain can advance into system updates immediately after the Office stage's settle window expires. ### What Office updates look like in the history A ring-driven Office update appears in the agent's Activity History tab as **Office Update Install** with the trigger source **Deployment Ring**. A manual trigger uses the same task title with trigger source **Web Portal** or **API** depending on how it was launched. In both cases the expanded view shows the task's phases (Preflight, Check, Install, Verify on macOS; Preflight and Install on Windows) with their durations and outcome details, plus the Office version Before/After and the channel. ## Feature upgrades Feature upgrades move a Windows endpoint from one feature version to another (for example, Windows 11 23H2 to 24H2, or 24H2 to 25H2). TridentStack Control handles them as a distinct flow from monthly cumulative updates because they change the underlying build number and require a restart to complete. ### How feature upgrades are dispatched Feature upgrades can reach an endpoint in two ways: - **Through a deployment ring** - When the update policy's feature upgrade settings have ring deployment enabled and a target version configured, the upgrade flows through the same phased rollout as other updates. The ring picks up eligible endpoints automatically as it reaches each phase. - **Manual trigger from the agent detail page** - On the agent's System State tab, administrators can open the pending feature upgrade and trigger it immediately. This path bypasses the ring. ### Install method Depending on the source and target version, TridentStack Control picks one of two install methods automatically: | Method | When it is used | |--------|-----------------| | **Enablement package** | Used for in-family upgrades where the target version is delivered by a small enablement package (~1 MB) that toggles features already staged by cumulative updates. Typical for upgrades like 24H2 to 25H2. Install takes under a minute. | | **Full upgrade** | Used for cross-generation upgrades (for example, Windows 10 to Windows 11), or when the endpoint's current build revision is below the minimum required for the enablement package. Downloads the full Windows installation media (~4 GB) and runs setup.exe. Takes approximately 15 to 20 minutes plus a restart. | If a manual enablement-package upgrade is attempted but the endpoint's build revision is below the prerequisite level, TridentStack Control automatically falls back to the full upgrade method rather than allowing a silent failure. ### Prerequisite updates Some feature upgrades require a specific cumulative update to be installed first (for example, the enablement package for 25H2 requires a recent revision of 24H2). If the prerequisite is not already installed, TridentStack Control automatically queues it ahead of the upgrade. The prerequisite installs during the next maintenance window, and the feature upgrade becomes eligible on a subsequent evaluation. ### Restart choice (enablement package) When triggering an enablement-package upgrade from the agent detail page, you choose one of two restart modes: | Mode | Behavior | |------|----------| | **Install Only** | Installs the enablement package but does not restart. The endpoint remains on the current build until you trigger the restart later from the pending upgrade banner. Best for production systems where restart timing is sensitive. | | **Install and Restart** | Installs the enablement package and restarts the endpoint automatically about 30 seconds after install completes. The full sequence (install, restart, post-restart verification) takes 2 to 3 minutes. | Full upgrades do not offer this choice because setup.exe manages the restart itself. ### Upgrade banners on the agent detail page While a feature upgrade is in progress, the System State tab displays a banner reflecting the current phase: | Banner | Meaning | Action available | |--------|---------|------------------| | **Upgrade Pre-Staged, Awaiting Maintenance Window** | The upgrade media has been downloaded and prepared. Finalization will run during the next maintenance window. | **Finalize Upgrade** to trigger immediately | | **Enablement Package Installed, Restart Required** | The enablement package installed successfully. A restart is required to activate the new version. | **Restart Now** to restart the endpoint | | **Upgrade Finalizing** | Setup.exe or the enablement finalization is running on the endpoint. | None (waiting for completion) | | **Upgrade Rebooting** | The endpoint is restarting to apply the upgrade. The agent will reconnect and validate the new build. | None (waiting for agent to reconnect) | Once the upgrade completes and the agent reports a new build, the banner clears and the new feature version appears in the Operating System section of the System State tab. When a Windows feature update fails, TridentStack Control now shows the specific reason it did not complete (for example, a rollback caused by a device driver, an incompatible application, or insufficient disk space) directly in the agent's history, without needing to collect logs. If the same upgrade fails repeatedly for the same reason, it is automatically paused after two attempts to avoid re-downloading the multi-gigabyte installer on every maintenance window, and resumes on its own once the underlying issue clears. ## Install time estimates TridentStack Control displays estimated installation times next to each update in the catalog browser and on each agent's pending updates list. Estimates appear as approximate durations (for example, "~15 min" or "~1h 30m"). Estimates are calculated from historical installation durations recorded across your fleet. New tenants see catalog-based estimates initially. As more updates are installed in your environment, the estimates become more accurate and are tailored to endpoints with similar hardware profiles when enough data is available. Click the info icon next to any estimate to see the confidence level (High, Moderate, or Low), the number of recorded installs, and a statistical breakdown including median, average, and 95th percentile durations. High confidence means the estimate comes from 5 or more installs on similar hardware. Moderate means 3 or more installs are recorded. Low means fewer than 3 data points are available. When selecting multiple updates to install, the confirmation dialog shows an aggregated estimated total install time. :::tip Estimates use the median duration to avoid skew from occasional slow installs. For conservative maintenance window planning, check the 95th percentile in the estimate detail popover. ::: ## Install Stats The **Install Stats** column appears in the update catalog browser and on each agent's pending system updates list. It shows fleet-wide installation success metrics for each update, helping you identify problematic patches before approving them. ### What Install Stats show Hover over or click the Install Stats badge on any update to see: | Field | Description | |-------|-------------| | **Total deployments** | Number of times this update has been installed across all endpoints in your fleet | | **Success rate** | Percentage of installations that completed successfully, color-coded: green (95%+), amber (80-94%), red (below 80%) | | **Confidence** | Data quality indicator based on deployment count: High (50+), Moderate (10-49), or Limited (fewer than 10) | | **Common errors** | Top 3 most frequent error codes from failed installations, with occurrence counts | ### How Install Stats are populated Install Stats are computed from actual installation outcomes recorded by the TridentStack Control agent on your endpoints. Every time an update is installed (whether it succeeds or fails), the agent reports the result back to the platform. These results are aggregated periodically (approximately every 15 minutes) into the stats you see in the UI. **New tenants and newly synced updates will show empty Install Stats ("--") initially.** Stats appear only after updates have been installed on at least one endpoint in your environment. The more updates your fleet installs, the more data points are available, and the more useful the stats become. ### Install Stats in the catalog expanded row When you click on a system update in the catalog browser to expand its detail row, an **Install Intelligence** section appears showing the same deployment count, success rate, and common errors in a larger format. This complements the existing install time estimates and known issues sections to give you a complete picture of each update's installation track record. ## Policy lifecycle A typical policy follows this progression from creation to reporting: ```mermaid flowchart LR A[Create Policy] --> B[Configure Targets] B --> C[Approve Updates] C --> D[Set Schedule] D --> E[Pre-stage Downloads] E --> F[Install During Window] F --> G[Report Results] ``` Each stage builds on the previous one. You can return to any stage at any time to adjust the policy. Changes take effect on the next agent check-in. ## Monitoring deployment After a maintenance window runs, check the policy detail page for deployment results. The results view shows each targeted agent with the following information: | Column | Description | |--------|-------------| | **Agent** | Endpoint hostname | | **Updates installed** | Count of successfully installed patches | | **Updates failed** | Count of patches that failed to install, with error details | | **Restart status** | Whether a restart was performed, is pending, or was not required | | **Duration** | Total time the agent spent in the installation phase | Click any agent row to expand it and see per-update details, including individual KB results, error codes, and timing. :::warning Always test update policies on a small group of endpoints before deploying fleet-wide. Use [deployment rings](./deployment-rings) to implement phased rollouts and catch issues before they affect production systems. ::: --- # Tags URL: https://docs.tridentstack.com/platform-guide/agents/tags Description: Use tags in TridentStack Control to group endpoints into logical sets and target update policies, compliance baselines, and configuration policies. # Tags Tags let you organize agents into logical groups. Use tags to target specific sets of endpoints for update policies, compliance baselines, and configuration policies. ## Creating tags Navigate to **Agents > Tags** and click **Create Tag**. Give the tag a descriptive name (e.g., `production-servers`, `finance-department`, `windows-11`). Tag names must be lowercase, use only letters, numbers, and dashes, and cannot start or end with a dash. Tags appear immediately and are ready to be assigned to agents. ## Assigning tags to agents You can assign tags in three ways: ### Manual assignment Go to **Agents > Endpoints**, select one or more agents using the checkboxes, and use the bulk action **Assign Tag**. Pick one or more tags from the dropdown and confirm. The tags are applied to all selected agents immediately. ### Automation rules Set up rules that automatically tag agents based on matching criteria such as OS type, hostname pattern, or IP range. See the [Automation](automation) section for details on creating and managing rules. ```mermaid flowchart TD A[Agent needs tags] --> B{How?} B -->|Automatic| C[Automation rule evaluates conditions] B -->|Manual| D[Admin assigns tags from Endpoints page] C -->|Match| E[Tags applied automatically] C -->|No match| D E --> F[Agent is now targeted by policies] D --> F ``` Automation rules can be configured to run on new agent enrollment, on a schedule, or triggered manually. See [Automation](automation) for details on configuring rule triggers. ### Microsoft Entra groups If you connect Microsoft Entra, you can map an Entra device group to a tag so the group's membership is mirrored onto the tag automatically. Endpoints in the group receive the tag and lose it when they leave the group, keeping your tags aligned with the groups you already maintain in Entra. See [Microsoft Entra Group Sync](../../administration/entra-group-sync) for setup. ## Tag details page Click a tag name in the list to view its detail page. From here you can see: - **Agent count** - Total number of endpoints assigned to this tag - **Status breakdown** - How many tagged agents are online, offline, or pending - **Agent list** - All endpoints with this tag, with the same sort and filter controls as the main Endpoints page You can also remove agents from the tag directly on this page by selecting them and choosing **Remove from Tag**. ## Using tags for targeting Tags are the primary mechanism for targeting agents when creating: - **System update policies** - Control which OS patches and security updates endpoints receive - **Application update policies** - Manage third-party application updates on Windows and macOS endpoints - **Compliance baselines** - Evaluate a set of endpoints against CIS, DISA STIG, or other frameworks - **Configuration policies** - Apply settings to a group of machines When you target a policy to a tag, the policy automatically applies to any new agents that receive that tag in the future. This means you define the policy once and let tag membership control who it affects. ```mermaid flowchart LR A[Tag: production-servers] --> B[System Update Policy] A --> B2[Application Update Policy] A --> C[Compliance Baseline] A --> D[Configuration Policy] B --> E[All agents tagged production-servers] B2 --> E C --> E D --> E ``` Unlike system update policies, an endpoint can inherit more than one application update policy at once when it carries multiple tags that each bring their own policy. See [Multiple policies per endpoint](/platform-guide/update-management/application-updates#multiple-policies-per-endpoint) for how TridentStack Control resolves overlapping application update policies. ### Disabled policies A disabled update policy can still be assigned to a tag. It appears in the tag editor with a Disabled status, and endpoints that carry it show the same Disabled status on their details page. While disabled, the policy applies nothing: no updates are approved, staged, or installed on its behalf. For system update policies, a disabled policy also keeps its place in the priority order. If the highest-priority system update policy on an endpoint is disabled, that endpoint has no effective system update policy, and updates pause until you re-enable the policy or change the assignment. A lower-priority policy carried by another tag does not take over. This prevents an endpoint from unexpectedly inheriting a different update schedule the moment you disable a policy. ## Favorite tags Mark the tags you use most as favorites so they are always easy to find. Anywhere you pick tags (assigning an update policy, deployment ring, compliance baseline, or configuration policy to a tag), select the star next to a tag to favorite it. Favorited tags are pinned to the top of the tag picker, ahead of the rest, so your go-to tags are the first ones you see. Select the star again to remove the favorite. Favorites are shared across your organization: a tag one administrator stars is pinned for everyone on your team. ## Best practices Follow these guidelines to build a tagging strategy that scales with your fleet: - **Use a consistent naming convention.** A prefix-based scheme makes tags easy to filter and understand at a glance. For example: `env-production`, `os-windows-11`, `dept-finance`, `role-web-server`. Tag names must be lowercase, alphanumeric, and can only use dashes to separate words. - **Create tags for both organizational and technical grouping.** Organizational tags reflect your business structure (department, location, cost center). Technical tags reflect the endpoint's role or platform (OS, server type, application stack). Having both gives you flexibility when targeting policies. - **Combine tags with automation rules.** Manual tagging works for small fleets, but automation keeps grouping accurate as agents change properties or new endpoints enroll. See [Automation](automation) for setup instructions. - **Avoid overly specific tags.** A tag for every individual machine defeats the purpose of grouping. If you find yourself creating tags with a single agent, consider whether a broader grouping would serve the same goal. :::tip Tags are the foundation of policy targeting. Invest time in a good tagging strategy early to simplify management as your fleet grows. ::: --- # Application Updates URL: https://docs.tridentstack.com/platform-guide/update-management/application-updates Description: Deploy third-party application updates across your fleet in TridentStack Control via integrated package manager support: discover, install, and pin versions. # Application Updates Application update configurations manage third-party software on your endpoints using integrated package manager support. Define which applications should be installed or updated, and TridentStack Control handles discovery, installation, and version management across your fleet. ## How it works TridentStack Control integrates with package managers on your endpoints to install and update third-party applications. The platform maintains a catalog of available packages synced from public repositories. When you add an application to a configuration, TridentStack Control ensures the correct version is installed on every targeted endpoint and keeps it updated according to your settings. The application update workflow is separate from system update policies. System updates handle OS-level patches (KB articles, security updates), while application updates handle third-party software (browsers, runtimes, utilities, developer tools). :::note Application updates are supported on Windows (all versions, including Windows Server 2016 and older) and macOS. On Windows systems without a native package manager, TridentStack Control uses direct installer downloads from the synced catalog. On macOS, applications are installed and updated through the macOS package manager integration. A catalog application that has both a Windows and a macOS package is managed on each targeted endpoint according to that endpoint's platform. ::: ## Creating a configuration 1. Navigate to **Update Management > Application Updates** in the left sidebar. 2. Click **Create Configuration**. 3. Enter a **name** and **description** for the configuration. Choose a name that reflects the group of applications it manages (for example, "Developer Tools", "Security Software", or "Standard Desktop Apps"). 4. Save the configuration. The configuration is now created but empty. The next step is to add applications to it. ## Adding applications From the configuration detail page, click **Add Application**. This opens the package catalog browser. ### Search the catalog Type an application name or package ID in the search bar. The catalog returns matching packages with their publisher, description, and available versions. Results are pulled from the synced package repository and stay current as new versions are published upstream. ### Select a package Click a package from the search results to select it. The detail panel shows: - **Package name and publisher** - **Available versions** (latest and historical) - **Package ID** (the canonical identifier used by the package manager) - **Description and homepage link** ### Configure version Choose how the application version is managed: | Option | Behavior | |--------|----------| | **Latest** | Always install the newest available version. When a new version appears in the catalog, the agent upgrades automatically on its next check-in. | | **Pinned version** | Install a specific version and do not upgrade beyond it. Useful for applications that require version compatibility with other software. | All installations run silently in the background with no user interaction. Applications are installed machine-wide by the system service, not per-user. All users on the endpoint have access to the installed application. ### Adding from agent software inventory You can also add applications to an application update policy directly from an agent's detail page. Navigate to **Agents > Endpoints**, select an agent, and open the **Software Inventory** tab. Right-click any installed application (or use the context menu) to add it to an existing application update policy. This is a convenient way to build policies based on software that is already deployed in your environment. ## Managing applications in a configuration The configuration detail page lists all applications that have been added. For each application you can: - **Edit version settings** - Switch between latest and pinned, or change the pinned version number - **Remove** - Remove the application from the configuration (this does not uninstall it from endpoints) - **Check deployment status** - See which agents have the correct version, which need updates, and which have failed ## Deployment status Each application in a configuration shows its per-agent status: | Status | Meaning | |--------|---------| | **Installed** | The correct version is installed on the endpoint | | **Update Available** | A newer version exists and will be installed on the next check-in | | **Not Installed** | The application has not been installed yet (pending first check-in or download) | | **Failed** | Installation was attempted but failed. Click the status to see error details. | ## Targeting Like system update policies, application configurations are targeted to agents by tag. When you assign a configuration to a tag, any agent with that tag receives the configuration's applications. An endpoint can inherit more than one application configuration at a time through its tags. See [Multiple policies per endpoint](#multiple-policies-per-endpoint) below for how TridentStack Control handles that. :::tip Group related applications into the same configuration. For example, create a "Developer Tools" configuration with your IDE, version control client, and runtime environments. Create a separate "Security Software" configuration for antivirus and VPN clients. This keeps your configurations organized and makes it easy to assign the right software bundles to the right teams. ::: ## Multiple policies per endpoint Endpoints often carry more than one tag, and each tag can bring its own application configuration. TridentStack Control lets you build focused, single-purpose configurations, for example "Browsers," "Java Runtimes," and "Developer Tools," and assign each to a different tag. An endpoint that carries all three tags inherits all three configurations at once. Each configuration only manages the applications it lists. Updates for those applications roll out within that configuration's own [deployment ring](deployment-rings) window, so a "Browsers" configuration on a fast-moving ring and a "Developer Tools" configuration on a cautious ring can both govern the same endpoint without interfering with each other. ### When two policies target the same application If an endpoint inherits two or more configurations that both include the same application, TridentStack Control automatically resolves the conflict so exactly one configuration governs that application. It applies the following rules, in order, until one configuration wins: 1. **A pinned version always wins.** A configuration that pins a specific version for the application takes precedence over any configuration set to install the latest version or a fixed number of versions behind latest. 2. **The lowest pinned version wins.** If more than one configuration pins the application, the configuration with the lower pinned version governs. 3. **The most conservative target wins.** When no configuration pins the application, the configuration with the more conservative version target (further behind the latest release) governs. 4. **The oldest configuration wins.** If configurations still tie after the rules above, whichever configuration was created first governs. Only the winning configuration's deployment ring window controls when that application updates on that endpoint. The losing configurations are unaffected for every other application they manage on the same endpoint. A pinned version never uninstalls or downgrades an application that is already newer than the pin. On an endpoint's pending application updates list, each application shows which configuration currently governs it. When more than one configuration applied to that application, an info icon next to it explains which rule decided the winner. :::tip You do not need to plan around overlaps when designing your configurations. Layer them freely by tag, TridentStack Control always resolves conflicts using the most conservative option, so an endpoint never ends up on a newer version than the most cautious configuration targeting it intended. ::: ## Manual installs require policy coverage Manually installing an application update, from an endpoint's Actions menu or its pending application updates list, is only available for applications covered by an assigned application update configuration. On an endpoint with no application update configuration assigned, install actions show a "No Policy" indicator and are disabled. When configurations are assigned but a pending application is not covered by any of them, that application is labeled "Not in Policy" and is excluded from manual installs until a configuration covers it. On macOS, an application is covered when a configuration lists it, or when a configuration enables that application's update source for automatic approval. ## Dismissing updates You can dismiss a pending application update on a specific agent to remove it from that agent's update list. Dismissals are per-agent and do not affect other endpoints. To dismiss an update, navigate to an agent's detail page (**Agents > Endpoints**, then select an agent). In the available applications section, hover over an application row to reveal the dismiss icon. Click it to open a dialog with the following fields: | Field | Required | Description | |-------|----------|-------------| | **Reason** | Yes | Select from: OS Incompatible, Not Applicable, or Other | | **Note** | No | Optional explanation, up to 500 characters | After dismissing, the update disappears from the agent's pending list. A collapsible **"N dismissed updates"** section appears at the bottom of the applications list, showing each dismissed app with its name, target version, and reason. To restore a dismissed update, expand the dismissed updates section and click **Restore** next to the application. It immediately returns to the pending list. :::tip Use the notes field to document why an update was dismissed. This helps other administrators understand the decision when reviewing the agent later. ::: :::info Dismissal is done per-agent from the agent detail page, not from the Application Update Configurations page. Configurations define which applications are targeted across your fleet. Dismissal manages exceptions for individual endpoints. ::: ## OS compatibility TridentStack Control automatically checks each application version's minimum OS requirements against the agent's reported operating system version. Only versions compatible with the agent's OS appear as available updates. If an application's latest version requires a newer OS than the agent has, it does not appear in the agent's pending update list. No configuration is required. The platform handles compatibility filtering automatically based on the metadata in the application catalog. ## Install time estimates TridentStack Control displays estimated installation times next to applications in the catalog browser and on each agent's available updates list. Estimates appear as approximate durations (for example, "~5 min" or "~2h 15m"). ### How estimates work Estimates are calculated from historical installation durations recorded across your fleet. Each successful installation contributes a data point. New tenants start with catalog-based estimates, and accuracy improves as more installations are recorded in your environment. When enough data exists from endpoints with similar hardware profiles (CPU, memory, and disk characteristics), estimates are tailored to that hardware class. Otherwise, the estimate uses tenant-wide averages. ### Viewing estimate details Click the info icon next to any estimate to see a detailed breakdown: | Field | Description | |-------|-------------| | **Confidence** | High (hardware-matched with 5+ recorded installs), Moderate (3+ installs), or Low (fewer than 3 installs) | | **Source** | Whether the estimate comes from similar hardware or tenant-wide data | | **Installs recorded** | Number of successful installations used to calculate the estimate | | **Median** | The middle value across all recorded durations | | **Average** | The mean duration | | **95th percentile** | The duration at which 95% of installs completed, useful for conservative planning | When selecting multiple applications to install, the confirmation dialog shows an aggregated estimated total install time across all selected applications. :::tip Estimates use the median duration rather than the average to avoid skew from occasional outliers. For conservative planning (for example, sizing a maintenance window), check the 95th percentile in the detail popover. ::: ## Install Stats The **Install Stats** column appears in the application catalog browser and on each agent's pending application updates list. It shows fleet-wide installation success metrics for each application, helping you identify problematic packages before deploying them. ### What Install Stats show Hover over or click the Install Stats badge on any application to see: | Field | Description | |-------|-------------| | **Total deployments** | Number of times this application has been installed or updated across all endpoints | | **Success rate** | Percentage of installations that completed successfully, color-coded: green (95%+), amber (80-94%), red (below 80%) | | **Confidence** | Data quality indicator based on deployment count: High (50+), Moderate (10-49), or Limited (fewer than 10) | | **Common errors** | Top 3 most frequent error codes from failed installations, with occurrence counts | ### How Install Stats are populated Install Stats are computed from actual installation outcomes recorded by the TridentStack Control agent. Every successful or failed application install reports its result back to the platform. These results are aggregated periodically (approximately every 15 minutes) into the stats displayed in the UI. **New tenants will see empty Install Stats ("--") initially.** Stats appear only after applications have been installed on at least one endpoint in your environment. As your fleet installs more applications, the data becomes richer and more informative. --- # Package Catalog URL: https://docs.tridentstack.com/platform-guide/update-management/package-catalog Description: Browse the built-in application catalog and deploy your own custom software packages to Windows, macOS, and Linux endpoints in TridentStack Control. # Package Catalog The Package Catalog is where you browse the third-party applications TridentStack Control already keeps updated on Windows and macOS, and where you upload and manage your own custom software packages. Custom packages let you deploy internal tools, licensed software, or any installer that isn't in the built-in catalog, through the same policies and deployment rings you already use for everything else. ## How it works Navigate to **Update Management > Package Catalog** in the left sidebar (also available from the mobile navigation). The page has a switch at the top for **Windows**, **macOS**, and **Custom**. - The **Windows** and **macOS** views are read-only, browsable catalogs of the third-party applications TridentStack Control already keeps updated across your fleet. Each entry shows the application's name, package ID, publisher, category, latest version, and how many versions are tracked. These are the same catalogs used by [Application Updates](application-updates) configurations, they aren't managed from this page. - The **Custom** view lists the packages your organization has uploaded: your own installers for internal tools, licensed software, or anything not covered by the built-in catalogs. ## Creating a custom package From the **Custom** view, click **New Package**. This button is always visible on the page. 1. Enter a **name** for the package. 2. Optionally add a **description**. 3. Choose the **platform**: Windows, macOS, or Linux. The platform is fixed once the package is created. It determines which installer file types the package's versions can accept. You can also give the package an icon; on Windows, an icon can be picked up automatically from the first installer you upload. ## Adding a version Every custom package can hold multiple versions. Open the package and click **Add Version** to upload an installer straight from your browser. ### Installer types | Platform | Accepted installer types | |----------|---------------------------| | Windows | MSI, EXE | | macOS | PKG, DMG | | Linux | DEB, RPM | Each installer file can be up to **2 GB**, and your organization has **25 GB** of total storage for custom package installers. ### Install settings When you add a version, you also configure how it installs. These settings can be changed later on any Available version. | Setting | Description | |---------|--------------| | **Install arguments** | Command-line arguments passed to the installer | | **Success exit codes** | Exit codes that count as a successful install. Defaults to 0 and 3010 on Windows, 0 on macOS and Linux | | **Install timeout** | How long to allow the install to run before it's considered failed. Defaults to 60 minutes | | **Detection** | How TridentStack Control confirms the application actually installed | Detection is automatic for MSI, PKG, DEB, and RPM installers, TridentStack Control reads the installer's own metadata and needs no extra input from you. - **EXE installers** need a detection rule that matches the application's name as it appears in Apps and Features, using an exact match, "starts with," or "contains" comparison. - **DMG installers** need the app bundle identifier, and optionally a minimum version. ## Security scanning and version lifecycle After you upload a version, it goes through automatic processing before it can be deployed. TridentStack Control verifies the file and runs an automatic security scan to check for malware. A version only becomes available to deploy once processing finishes clean. | Status | Meaning | |--------|---------| | **Uploading** | The installer file is being received | | **Processing** | The file is being verified and scanned | | **Available** | Processing finished successfully; the version can be deployed | | **Failed** | Verification or scanning found a problem. Open the version to see the reason | | **Archived** | The version has been retired and can no longer be deployed or downloaded | :::tip If a version shows **Failed**, check the reason before re-uploading. A corrupted file, a mismatched installer type, or a flagged file are the most common causes. ::: ## Deploying custom packages Custom packages deploy the same way as everything else in TridentStack Control: through policies for ongoing management, or on demand for a one-time push. ### Through application update policies When adding an application to an [application update configuration](application-updates), a **Custom** tab lets you pick one of your custom packages alongside the Windows and macOS catalogs. Once added, the package is targeted to endpoints by tag like any other application, and its rollout honors the configuration's assigned [deployment ring](deployment-rings). This path works for Windows, macOS, and Linux packages. ### On-demand deploy To push a custom package to specific endpoints immediately, open the **Deploy Application** dialog, either from an endpoint's actions menu or as a bulk action on the Endpoints list, and select the **Custom** tab. Choose the package and whether to deploy its latest version or a specific pinned version, then confirm. :::note On-demand custom deploys currently support Windows and macOS endpoints. Linux custom packages deploy through application update policies. ::: You'll be asked to verify your identity before the deploy runs, the same quick verification step used elsewhere in TridentStack Control for sensitive actions. Either way, install progress and results appear in the endpoint's history alongside every other install, so you can track a custom package deployment the same way you track a system or application update. ## Managing versions Open a custom package to see its details and all of its versions. From here you can: - **Edit install settings** on an Available version, install arguments, success exit codes, timeout, and detection, without re-uploading the installer. - **Archive** an Available or Failed version. Archived versions can no longer be deployed or downloaded. - **Delete** the package once every version has been archived and no application update policy still references it. Deleting a package permanently removes its uploaded installer files and frees the storage they used. Editing a package's details or archiving a version requires the same identity verification used for on-demand deploys. ## Limits | Limit | Value | |-------|-------| | Max installer file size | 2 GB | | Max total storage per organization | 25 GB | | Success exit codes (Windows default) | 0, 3010 | | Success exit codes (macOS/Linux default) | 0 | | Default install timeout | 60 minutes | --- # Automation URL: https://docs.tridentstack.com/platform-guide/agents/automation Description: Use automation rules in TridentStack Control to auto-tag agents based on OS, hostname, hardware, or any agent property as endpoints enroll. # Automation Automation rules automatically apply tags to agents based on matching criteria. Instead of manually tagging every new endpoint, define rules that evaluate agent properties and assign tags when conditions are met. ## How automation works Each rule defines a set of **conditions**, a **target tag**, and one or more **triggers** that control when the rule runs. When a rule is triggered and the agent matches all conditions, the target tag is applied automatically. ### Trigger types Every automation rule can be configured with any combination of these triggers: | Trigger | Description | |---------|-------------| | **Run on new agent enrollment** | Evaluates the rule automatically when a new agent registers. This is a per-rule toggle, not a global setting. | | **Scheduled execution** | Runs the rule on a cron schedule (e.g., every 30 minutes, hourly, every 4 hours). Useful for catching agents whose properties have changed since last evaluation. | | **Manual** | Run the rule on demand using the **Apply Rule** action from the rule list or detail page. Evaluates the rule against all existing agents immediately. | A single rule can have multiple triggers active at the same time. For example, a rule might run on new enrollment and also on an hourly schedule. ```mermaid flowchart TD A[Trigger fires] --> B[Evaluate rule conditions against agents] B --> C{Conditions match?} C -->|Yes| D[Apply target tag] C -->|No| E[No change] F[New agent enrolls] -->|Rules with enrollment trigger| A G[Cron schedule fires] -->|Rules with schedule trigger| A H[Admin clicks Apply Rule] -->|Selected rule| A ``` ## Creating a rule Navigate to **Agents > Automation** and click **Create Rule**. Configure the following fields: ### Name A descriptive name for the rule (e.g., "Tag Windows Servers", "Mark Linux Production Hosts"). This appears in the rule list and in audit logs when the rule applies a tag. ### Conditions Rules use **condition groups** to build flexible matching logic. Each group contains one or more conditions, and you choose whether a group requires **all** conditions to match (AND logic) or **any** condition to match (OR logic). Multiple groups are combined with OR logic between them. Available condition fields: | Field | Description | Example | |-------|-------------|---------| | Hostname | Computer name | `Hostname contains prod` | | Operating System | OS name | `Operating System equals Windows` | | OS Version | Specific version string | `OS Version contains Server 2022` | | IP Address | Internal IP | `IP Address starts with 10.0.1` | | Manufacturer | Hardware manufacturer | `Manufacturer equals Dell Inc.` | | Model | Hardware model | `Model contains PowerEdge` | | Domain | Active Directory domain | `Domain equals corp.example.com` | | Status | Agent connection state | `Status equals online` | Available operators: `equals`, `does not equal`, `contains`, `does not contain`, `starts with`, `ends with`, `matches regex`. ### Target tag The tag to apply when conditions are met. Select an existing tag from the dropdown, or create a new one inline. ### Triggers Configure when the rule should run: - **Run on new agent registration** - Toggle this on to evaluate the rule automatically whenever a new agent enrolls. - **Scheduled execution** - Enable a cron schedule and choose a frequency. Quick presets are available: every 30 minutes, hourly, every 2 hours, or every 4 hours. You can also enter a custom cron expression. If neither trigger is enabled, the rule only runs when you manually click **Apply Rule**. ### Priority A numeric value that controls the order in which rules are evaluated. Lower numbers are evaluated first. Priority is relevant when you want certain rules to run before others, though in practice all matching rules apply their tags regardless of order. ## Rule evaluation order Rules are evaluated by priority (lowest number first). If multiple rules match the same agent, all matching tags are applied. There is no conflict between rules. Tags from different rules accumulate on the agent. For example, if Rule A assigns "os-windows" and Rule B assigns "env-production", an agent matching both rules receives both tags. :::info Automation rules only add tags. They do not remove tags that were manually assigned or added by other rules. ::: ## Managing rules The **Agents > Automation** page displays all rules in a data table with columns for name, target tag, status, match count, and last applied timestamp. Click any row to expand it and see the rule's full condition logic. From this page you can: - **Enable/disable** - Toggle a rule on or off without deleting it. Disabled rules are skipped during all evaluation (enrollment, scheduled, and manual). - **Edit** - Open the rule detail page to modify conditions, triggers, target tag, or priority. - **Apply Rule** - Manually evaluate the rule against all existing agents immediately. - **Duplicate** - Create a copy of the rule with the schedule disabled, useful for creating variations of existing rules. - **View match count** - See how many agents currently match the rule's conditions. - **Delete** - Permanently remove a rule. Tags that were already applied by the rule remain on agents. ## Applying rules manually Click **Apply Rule** from the rule's action menu to evaluate it against all existing agents immediately. A confirmation dialog shows: - How many agents match the rule's conditions - How many agents will receive a new tag (agents that already have the tag are skipped) This is useful when: - You created a new rule and want it applied to your current fleet right away. - You changed conditions on an existing rule and want to see updated results. - The rule has no automatic triggers (no enrollment trigger and no schedule). :::warning For large fleets, applying a rule evaluates every agent against the rule's conditions. This is a lightweight operation, but the resulting tag assignments may take a few moments to propagate across all endpoints. ::: --- # Deployment Rings URL: https://docs.tridentstack.com/platform-guide/update-management/deployment-rings Description: Deployment rings in TridentStack Control turn fleet-wide rollouts into phased, monitored waves: canary, expanding, and complete with auto-promotion. # Deployment Rings Deployment rings implement phased rollouts for update policies. Instead of deploying patches to your entire fleet at once, rings let you gradually expand coverage while monitoring for issues at each stage. ## Ring concept A deployment ring is a staged rollout strategy. Instead of deploying patches to every endpoint simultaneously, you define a sequence of rollout phases that gradually expand coverage. Updates flow through each phase in order, and if problems surface at any stage, you can halt the rollout before it reaches the rest of your fleet. This approach reduces risk. A patch that causes application compatibility issues or performance degradation is caught early, where the impact is limited to a small number of non-critical endpoints. ## Rollout phases Each deployment ring has a customizable set of rollout phases. You define how many phases the ring uses, what percentage of agents each phase targets, and how the rollout advances between them. There is no fixed number of phases: a simple ring might use two phases, while a cautious enterprise rollout might use five or more. A typical ring configuration might look like this: ```mermaid flowchart LR A["Canary (5%)"] --> B["Early Adopters (25%)"] B --> C["Broad (75%)"] C --> D["Complete (100%)"] ``` But you can define any number of phases with any target percentages. The final phase is always a **Complete** phase fixed at 100% and pinned to the end of the pipeline, so every rollout finishes by covering your entire targeted fleet. You add, remove, and reorder the phases that come before it; the Complete phase stays last. ### Presets To help you get started, TridentStack Control provides built-in presets that populate a ring with a recommended set of phases: | Preset | Phases | Best for | |--------|--------|----------| | **Conservative** | Canary (3%) -> Early Adopters (15%) -> Broad (50%) -> Complete (100%) | Production-critical environments. Longer wait times and manual approval gates at the Early Adopters and Broad phases | | **Moderate** | Canary (3%) -> Early Adopters (30%) -> Complete (100%) | Most environments. Balanced phase count with automatic advancement | | **Aggressive** | Pilot (10%) -> Complete (100%) | Environments that need rapid patching with minimal staging | | **Immediate** | All Agents (100%) | No staging. Deploys to every targeted agent at once | | **Custom** | Define your own | Start from scratch when none of the presets fit | Selecting a preset populates the ring's phases automatically. You can then customize individual phases or add and remove phases as needed. When you modify any phase after applying a preset, the ring switches to Custom mode. ### Phase configuration Each phase in a deployment ring has the following settings: | Setting | Description | |---------|-------------| | **Name** | A label for the phase (for example, "Canary", "Early Adopters", "Full Fleet") | | **Target percentage** | The cumulative percentage of agents this phase covers. The final phase must be 100% | | **Minimum agents** | The minimum number of agents that must be targeted before this phase can execute | | **Advancement type** | **Automatic** (advances after wait time and success conditions are met) or **Manual** (requires an administrator to click Advance) | | **Wait time** | Hours to wait after the phase completes before advancing to the next phase. Gives you time to observe results. Not shown for the final 100% phase since there is nothing to advance to. | | **Success rate** | The minimum percentage of successful installations required before the rollout can advance (automatic mode only) | | **Max failures** | The maximum number of failures allowed before the rollout auto-halts (automatic mode only) | For how a rollout moves from one phase to the next relative to your deployment windows, see [How a rollout advances](#how-a-rollout-advances). ### Targeting modes Each phase can target endpoints in one of two ways: - **Percentage-based** (default) - TridentStack Control automatically selects a percentage of endpoints from the policy's target groups. Simple to set up but gives you less control over exactly which endpoints are in each phase. - **Tag-based** - Target the endpoints that carry specific tags (for example, "Canary Ring" or "Early Adopters"). This is the recommended approach for maintaining consistent phase membership over time, because membership follows the tag rather than a recalculated percentage. ## Deployment windows Deployment windows control when updates are allowed to install. Each ring can have its own schedule independent of the update policy's maintenance window. You define a window by a **start time** and a **duration**, rather than by separate day-of-week and time-of-day rules: - **Timezone** - Set the timezone the window's start time is measured in. - **Start time** - The day and time the window opens (for example, Wednesday at 10:00 PM). - **Duration** - How long the window stays open (for example, 6 hours). A window that runs past midnight is handled correctly: "Wednesday 10:00 PM for 6 hours" opens Wednesday at 10:00 PM and stays open until 4:00 AM Thursday, all as one continuous window. A window can be up to 23 hours long. Each selected day opens its own occurrence of the window, so a longer duration would overlap the next day's occurrence. If you want a ring that can deploy at any time, remove its windows instead (see [Always-active rings](#always-active-rings)). You can also block specific date ranges with **exclusion dates** (for example, company-wide code freezes, holidays, or change blackout windows). Each exclusion includes a reason for documentation, and no deployments run during an excluded range even if a window would otherwise be open. ### Always-active rings If you do not define a window, the ring is **always active**: deployments can happen at any time, around the clock. The ring editor flags this so it is never a surprise, and when you save an always-active ring it asks you to confirm, showing how many endpoints would be affected. Use an always-active ring only when unrestricted, around-the-clock deployment is intentional, for example on a dedicated pilot ring or test environment. When a ring is always active, its status on the agent detail page shows **Always open** in place of a next-window time. Because pre-staging, automatic safety halt, and per-window execution limits all depend on having a scheduled window to work against, those settings are unavailable on an always-active ring (see [Additional ring settings](#additional-ring-settings)). ### What happens during and outside windows TridentStack Control only performs disruptive actions during active deployment windows: - **Application update deployment** - only dispatched when the window is open - **Microsoft Office update deployment** - dispatched after application updates complete and before system updates begin, when the window is open and the assigned policy has Office ring deployment enabled - **System update deployment** - only dispatched when the window is open - **Feature upgrade dispatch** - Windows build upgrades (for example, 24H2 to 25H2) are dispatched through the same ring phases as other updates when the update policy has feature upgrades enabled. See [Feature upgrades](./system-updates#feature-upgrades) for how the upgrade itself runs on the endpoint. - **Driver update deployment** - only dispatched when the window is open - **Scheduled restarts** - only executed when the window is open If an application deployment finishes and the system update phase is ready, but the deployment window has closed, the system updates will wait until the next window opens. Similarly, if a scheduled restart time arrives but the window is closed, the restart will wait. Non-disruptive actions (settle timer countdown, timeout cleanup, failure marking) continue regardless of window state. These are housekeeping operations that do not affect the endpoint. ### Dispatch order within a window When a ring fires for an agent during an active window, updates are dispatched in a fixed order. Each stage runs to completion (with a configurable settle time between stages) before the next stage begins: 1. **Application updates** - third-party application installs and upgrades through the agent's package manager integration. 2. **Microsoft Office updates** - Click-to-Run Office channel/version reconciliation through the agent's built-in Office updater. This stage runs for Windows and macOS endpoints whose assigned system update policy has both **Enable Office Updates** and **Enable ring deployment for Office updates** turned on, and only when the agent is not already at the policy's target version. Office is dispatched here, ahead of system patches, so it completes before any reboot the system stage triggers. 3. **System updates** - operating system patches. On Windows this is Windows Update content (security and quality cumulative updates, monthly rollups). On macOS this is Apple system updates (Safari, command-line tools, and security responses through Apple's update service). On Linux this is the configured package manager's available updates. 4. **Driver updates** - Windows driver content from Windows Update (only when the policy has driver updates enabled and ring deployment for drivers enabled). 5. **Feature upgrades** - major version transitions. On Windows this is build upgrades (for example 24H2 to 25H2). On macOS this is major OS upgrades (for example Sonoma to Sequoia, when policy permits). Feature upgrades always run last because they typically require a reboot. 6. **Automatic restart** - if any of the above stages indicates a reboot is required and the ring permits auto-restart, the reboot is dispatched after all install stages complete. Restarts are staggered across the ring to avoid simultaneous reboots. If a stage produces no applicable updates for a specific agent, that stage is skipped silently and the chain advances to the next stage. For example, an agent with no applicable Office update simply moves from the application settle into the system stage without an intervening Office dispatch. If a stage fails for an agent, the execution halts at that stage and the agent is excluded from further work in the current window. The next window starts fresh. ### Window lifecycle states Each deployment ring tracks its window lifecycle to provide clear visibility into what the ring is doing at any given time: | State | Meaning | |-------|---------| | **Scheduled** | The deployment window is closed. No deployments are occurring. The ring is waiting for the next window to open. | | **Active** | The deployment window is open and the ring is actively deploying updates to agents. | | **Idle** | The deployment window is open, but the ring has no remaining actions to perform. All eligible agents have been deployed, and there are no pending system update dispatches or reboots. | **How transitions work:** When a deployment window opens, the ring enters the **Active** state. As agents receive their updates and no more work remains, the ring transitions to **Idle**. If a new agent comes online or becomes eligible during the window, the ring moves back to **Active**. When the window closes, the ring returns to **Scheduled** regardless of its current state. The Idle state does not mean the rollout is complete. It means the ring has done everything it can during this window. Agents that were offline, in cooldown, or not yet eligible may receive updates in the next window. If an individual endpoint cannot install updates because of a problem on the device itself (most often low free disk space), that endpoint shows an amber **Updates blocked** indicator on its detail page in place of its normal deployment status. Select it to see the specific cause and how to resolve it. The indicator clears on its own once the underlying issue is fixed, and the ring resumes deploying to that endpoint automatically. ### Next Dispatch and Next Window On the Rollout Status tab, each ring shows one of two timing indicators so you always know what the ring will do next: | Indicator | When it appears | What it means | |-----------|-----------------|---------------| | **Next Dispatch** | The window is open **and** the ring has real work to send to endpoints: updates queued to install, an install still in progress, or a phase that is ready to widen to its next group of endpoints. | A short countdown to the next moment the ring acts on an endpoint. This only appears when an install will actually happen soon. | | **Next Window** | The window is closed, or the window is open but the ring has finished everything it can do this window (it has gone **Idle**). | The next time the ring's maintenance window opens, which is the next time installs begin again. It shows that upcoming window's real start and end times. | The two are mutually exclusive: if there is nothing left to install in the current window, **Next Dispatch** disappears and you see **Next Window** instead. In short, Next Dispatch answers "when will the ring next touch an endpoint?" (and only shows when the honest answer is "soon, with real work to send"), while Next Window answers "when do installs start again?" A detail that sometimes causes confusion: **Next Window always points to the next window that has not started yet.** If a ring's window is open right now but the ring is Idle (no more work this window), Next Window shows the *following* window's real opening time, not the one currently open. To confirm a window is open at this moment, use the ring's lifecycle state (**Active** or **Idle**) or the **Active** indicator on the agent detail page, described above. Always-active rings have no scheduled window, so they show **Always open** in place of a next-window time. ### How a rollout advances A rollout moves from one phase to the next on its own observation schedule, while installs stay inside your deployment windows. - A phase **widens** to the next stage as soon as that stage's wait time finishes and its success criteria are met. Wait times are measured in wall-clock hours, so a 24-hour wait always means 24 real hours. - The actual **installs** for a stage happen during your next open deployment window. If a stage becomes ready while the window is closed, it waits until the window opens. - If a ring is **always active** (no window), installs can happen at any time, so a rollout simply widens and deploys as each stage's wait completes. This means a phased rollout finishes promptly even when your windows are sparse. With a weekly maintenance window and multi-day waits, for example, the rollout widens through its stages over a few days and installs each stage at the next window, rather than waiting a full week for every single stage. Each phase card in the ring editor shows the projected date and time that phase is expected to begin, under your current schedule, stages, and wait times, with the projected completion time for the whole rollout shown beneath the phases. The projections update live as you adjust the ring, so you can see the whole rollout before you save. A phase set to **manual** advancement is the exception: instead of widening automatically when its wait completes, it waits for an administrator to approve the next stage. Installs still happen during the next open window. ### Per-update-type canary validation When a ring's early (canary) phase rolls out, TridentStack Control validates each kind of update on its own. If the early endpoints include both application updates and system updates, the rollout confirms each kind succeeds before widening to more endpoints. If a kind of update is failing its early validation, the rollout pauses widening that ring and the Rollout Status page shows which kind of update is holding it, instead of letting other successful updates hide the problem. ## Safety controls Each ring includes configurable safety mechanisms to automatically halt a rollout if something goes wrong: - **Auto-halt by failure count** - Halt the rollout if the number of failures exceeds a defined limit - **Auto-halt by failure rate** - Halt the rollout if the failure percentage exceeds a defined threshold - **Manual override** - Allow or block administrators from manually overriding an auto-halt to continue the rollout ### Failed agent cooldown When an agent fails during a deployment, it enters a **per-window cooldown**. The agent is excluded from further deployment attempts for the remainder of the current deployment window. When the next window opens, the agent gets a fresh start and is eligible for deployment again. This prevents the scheduler from repeatedly retrying a failing agent every five minutes within the same window, while ensuring the agent is not permanently blocked. If the underlying issue is resolved (for example, a bug fix is deployed to the server), the agent will succeed on its next window. If you need to retry a failed agent immediately within the same window, use the **Re-deploy** button on the Rollout Status tab to reset the ring's phase state and restart the deployment cycle. ## Additional ring settings :::note Always-active rings Pre-staging, automatic safety halt, and execution limits all rely on a scheduled deployment window to work against, so they are unavailable on an always-active ring (one with no window). They become available as soon as you give the ring a window. ::: ### Pre-staging When pre-staging is enabled, agents download update files in advance during a separate download window, before the deployment window opens. This ensures updates are ready to install immediately when the deployment window starts, reducing the time agents spend in the maintenance window. Pre-staging settings include download windows, retry attempts, bandwidth limits, and file retention period. Because pre-staging downloads ahead of an open window, it is only available on rings that have a deployment window. ### Auto-restart Configure whether agents automatically restart after installing updates. Settings include a prompt timeout (how long to wait for user acknowledgement before restarting), maximum postpone time, and reprompt interval. ### Execution limits Cap how many times a ring deploys to a single endpoint within one deployment window. Each deployment cycle (installing application updates, system updates, and any required restarts) counts as one execution. Once an endpoint reaches the limit, no further deployments are scheduled for it until the next window opens. This prevents an endpoint from repeatedly installing, restarting, and redeploying within the same window. Because the limit is counted per window, it is only available on rings that have a deployment window. ## Calendar view The Deployment Rings page includes a calendar view that shows all scheduled deployment windows across your rings in a monthly grid. Each deployment window appears as an event on the calendar with a color-coded status indicator: | Status | Description | |--------|-------------| | **Scheduled** | The window is upcoming and has not started yet | | **In Progress** | The window is currently active and deployments are running | | **Completed** | The window finished and all deployments in that window are done | | **Awaiting Approval** | The rollout reached a manual-advance phase and is waiting for administrator approval | | **Paused** | The rollout was paused by an administrator | | **Halted** | The rollout was automatically halted due to safety controls | | **Failed** | The deployment window encountered errors | | **Skipped** | The window was manually skipped by an administrator | | **Unassigned** | The ring is not applied to any endpoints (shown with a gray dashed border). Check that the ring's target tags match active agents | Click any event on the calendar to see details including the ring name, current phase, time window, execution breakdown (completed, in-progress, pending, and failed counts), and phase advancement type. From the event detail view, you can: - **Skip** a scheduled window to exclude it from the rollout - **Restore** a previously skipped window The calendar refreshes automatically to reflect the latest rollout status. ## Notifications Deployment ring lifecycle events can trigger notifications to your team via Email, Slack, Microsoft Teams, Discord, or custom webhooks. Events include deployment started, phase advanced, approval pending, deployment completed, emergency halt, and phase failure. Configure which events trigger alerts and who receives them in **Settings > Notifications**. See [Notifications](/administration/notifications) for full setup instructions. :::tip Enable notifications for **Approval Pending** and **Emergency Halt** at minimum. These are the two ring events most likely to require immediate action. ::: ## Monitoring ring progression The deployment rings list view shows each ring's status at a glance, including the current phase, success and failure counts, success rate, and time remaining before the next phase advancement. ```mermaid flowchart TD A[Rollout starts] --> B{Current phase} B -->|Success >= threshold| C{Wait period elapsed?} C -->|Yes| D{Auto-advance enabled?} D -->|Yes| E[Widen to next phase] D -->|No| F[Wait for manual approval] F --> E C -->|No| G[Continue waiting] G --> C B -->|Success < threshold| H[Rollout halted] B -->|Failures > max| H E --> I{Final phase?} I -->|No| B I -->|Yes| J{Agents still have pending updates?} J -->|Yes| K[Remain active, continue deploying] K --> B J -->|No| L[Rollout complete] L --> M{New updates arrive during window?} M -->|Yes| A M -->|No| N[Ring stays completed until next window] ``` Installs for each phase still happen during your next open deployment window; the diagram above shows how the rollout widens between phases. ## Rollout completion and automatic restart When a ring reaches its final phase and all targeted agents have been deployed, the ring checks whether any agents still have pending updates. If pending updates remain (for example, an agent was offline during the rollout or new updates became applicable), the ring stays active and continues deploying. It only marks itself as complete when no pending updates remain for any agent in the ring. Once a rollout completes, the ring does not stop permanently. If new applicable updates arrive for agents in the ring while a deployment window is active, the ring automatically starts a new rollout cycle. This means rings with broad deployment windows (such as daily or continuous schedules) behave as perpetual rollout engines: any time a new patch is approved or a new update becomes applicable, the ring picks it up and deploys it through the configured phases without manual intervention. For rings with narrower windows (for example, a weekly Wednesday 2:00 AM - 6:00 AM window), the ring waits in a completed state until the next window opens. If agents have new pending updates at that time, the rollout restarts automatically. If you need to restart a completed rollout immediately without waiting for new updates to arrive, click the **Re-deploy** button on the Rollout Status tab. This resets the ring's phase state and begins a fresh rollout cycle on the next scheduler evaluation. ## Controlling a rollout ### Halting If issues are detected at any phase, you can halt the rollout. Halting: - Prevents advancement to the next phase - Stops any pending installations on agents that have not yet started - Does **not** roll back updates that have already been installed - Keeps the rollout in a halted state until you take action Rollouts can also halt automatically when safety controls are triggered (for example, when the failure count or failure rate exceeds the configured threshold). When an auto-halt occurs, a banner displays the halt reason on the ring's detail view. :::warning Rollback is not automatic. If a rollout is halted, updates that were already installed on earlier phases remain in place. If a patch needs to be removed, create a separate remediation plan for the affected endpoints. ::: ### Un-halting To resume a halted rollout, click **Un-halt** from the ring's action menu or the table row. A dialog appears showing the halt reason and two options: | Option | Behavior | |--------|----------| | **Continue deploying, skip failed agents** | Failed agents are left in their current state. Deployment resumes with the remaining agents only | | **Retry failed agents and continue deploying** | Failed agents are re-queued for another attempt. Recommended when the original failure was transient (for example, a network timeout that has since been resolved) | The dialog shows the count of failed agents in each option label so you can assess the scope before choosing. An optional **notes** field lets you document what corrective action was taken. These notes are recorded for audit purposes. :::info If the ring is also paused, you must resume it separately after un-halting. The un-halt dialog displays a warning when this applies. ::: ### Pausing vs halting | | Pause | Halt | |---|-------|------| | **Trigger** | Manual (administrator clicks Pause) | Automatic (safety controls) or manual | | **Resume** | Click Resume at any time | Requires un-halt with a decision about failed agents | | **Pending installs** | Stopped | Stopped | | **Completed installs** | Not rolled back | Not rolled back | Use **Pause** for temporary stops (planned maintenance, investigation). Use **Halt** when failures need to be addressed before continuing. :::tip Assign your least critical endpoints to the earliest phases. Development machines, test servers, and lab systems are ideal candidates. If a patch causes issues, the impact is minimal and you catch the problem before it reaches production. ::: ## Cancelling pending executions To stop a rollout entirely, you can cancel all pending executions. Right-click the ring and select **Cancel Pending**. A confirmation dialog warns that this action cannot be undone. Cancelling immediately removes all agents in "pending" status from the rollout. Installations that are already in progress complete normally. Use this when you need an emergency stop, when a configuration error is discovered, or when you want to prevent remaining agents from being updated. ## Viewing agent details To see per-agent execution status for a rollout, click the ring's name on the Rollout Status page. This opens a dedicated rollout detail page. At the top of the page, each rollout phase appears as a card matching the phase pipeline you configured in the ring editor. Each card shows the phase's live status, how many endpoints in that phase have completed or failed, and what the phase is currently waiting on: a soak countdown with its projected advancement time, the specific criterion holding it (for example, a success rate below the required minimum), or when it completed. On multi-phase rings, clicking a card filters the agents table below to that phase. When every phase has finished, a banner confirms the rollout is 100% complete and shows when it will automatically restart for the next update cycle. Below the phases is a searchable table of all agents in the ring: | Column | Description | |--------|-------------| | **Hostname** | The agent's system name | | **Phase** | Which deployment phase the agent belongs to | | **Status** | The endpoint's latest execution state in this ring | | **App** / **System** | The per-channel result of the latest execution | | **Last Execution** | When the endpoint's most recent execution started | | **Duration** | How long the installation took | The info icon on the Status column opens a key defining every state. Most are self-explanatory (Completed, Failed, In Progress, Pending, Cancelled); two deserve special mention. **Not Converged** means the endpoint reported that an update installed successfully, but a later check found the update is still needed. TridentStack Control treats this as neither a success nor a failure: it automatically retries the update at the next deployment window, up to three attempts. **Retry scheduled** means the endpoint failed but the ring will automatically retry it at the next deployment window, so it is not a stopping point; its info popover shows the next attempt time and how many attempts have been made. Ordinary failures keep retrying every deployment window until they succeed. If the ring itself is paused or halted, a failed endpoint shows plain **Failed** instead, with an explanation that retries are on hold until the ring resumes. Use the **status filters** at the top of the table to filter by state; filters for the rarer states (Retry scheduled, Not Converged, Abandoned) appear only when endpoints are actually in them. Type in the **hostname search** field to find a specific endpoint. The table is paginated for rings targeting large numbers of agents. Click a row to expand it for attempt history, installed updates, and the restart timeline, or click a hostname to jump straight to that endpoint's page. ### Scheduled column indicators The Scheduled column on the agent detail page shows the agent's current deployment ring status: | Indicator | Meaning | |-----------|---------| | **Active** (green pulsing dot) | Deployment window is open and the ring is actively deploying | | **Idle** (gray badge) | Deployment window is open but no actions are pending for this ring | | **Cooldown** (amber badge) | This agent failed during the current window and will retry in the next window | | **Completed** (green check) | The ring's rollout has finished | | **Halted** (red badge) | The ring has been halted due to excessive failures | | **Paused** (amber badge) | The ring has been manually paused | | **Next window time** (blue clock) | The deployment window is closed; shows when the next window opens | | **Manual** (gray badge) | No deployment ring is assigned; approved updates require manual installation (policy still controls what gets approved) | ## Managing rings From the deployment rings list page you can: - **Duplicate** a ring to create a copy with all settings (starts inactive) - **Export** a ring as JSON for backup or sharing - **Import** a ring from a JSON file (creates an inactive copy) - **Delete** a ring that is not assigned to any policies --- # Health Score URL: https://docs.tridentstack.com/platform-guide/agents/health-score Description: How TridentStack Control's 0-100 agent health score blends vulnerability exposure, compliance state, patch currency, and network exposure into one metric. # Health Score The health score provides a single metric (0-100) that summarizes each agent's overall security posture. It combines vulnerability exposure, compliance status, update currency, and network exposure into a weighted score that helps you prioritize remediation efforts. ## How the Score Is Calculated The overall health score is a weighted average of four independent category scores: | Category | Default Weight | What It Measures | |----------|---------------|------------------| | **Vulnerabilities** | 50% | Known CVEs in installed software and OS | | **Compliance** | 25% | Adherence to assigned compliance frameworks | | **Pending Updates** | 15% | Outstanding system and application updates | | **Network Exposure** | 10% | Open ports, firewall state, and attack surface | Each category produces its own score from 0 to 100, and the overall score is the weighted combination: ``` Overall = (Vulnerability x 0.50) + (Compliance x 0.25) + (Updates x 0.15) + (Network x 0.10) ``` Weights are configurable per-tenant in **Settings > Health Scoring**. ## Score Ranges | Score | Status | Meaning | |-------|--------|---------| | 80-100 | Healthy | System is secure and compliant | | 60-79 | Needs Attention | Action required but not critical | | 0-59 | Critical | Immediate attention required | ## Category Scoring Details ### Vulnerability Score Starts at 100 and deducts points based on open vulnerabilities: | Factor | Penalty | |--------|---------| | CISA KEV (Known Exploited Vulnerability) | -15 per vulnerability | | KEV past its remediation due date | -25 additional per overdue KEV | | Critical severity (CVSS 9.0-10.0) | -10 per vulnerability | | High severity (CVSS 7.0-8.9) | -5 per vulnerability | | Medium severity (CVSS 4.0-6.9) | -2 per vulnerability | | Low severity (CVSS 0.1-3.9) | -0.5 per vulnerability | | Fix available but not applied | -1 per vulnerability | KEV vulnerabilities and critical CVEs have the largest impact because they represent the highest real-world risk. ### Compliance Score Weighted average of all compliance framework scores assigned to the agent through its tags. If no frameworks are assigned, the score defaults to 100. Frameworks with critical failures are weighted more heavily. A framework reporting multiple critical failures counts more in the average than one with only minor non-compliance. ### Update Score Starts at 100 and deducts points for pending updates and stale check-in data: | Factor | Penalty | |--------|---------| | Pending Windows/system update | -4 per update | | Pending application update | -2 per update | | Software needing updates | -1 per package | | No update check in 7+ days | -5 | | No update check in 14+ days | -10 additional | | No update check in 30+ days | -20 additional | Agents that have not checked for updates recently receive escalating penalties. ### Network Exposure Score Starts at 100 and deducts points based on exposed ports and firewall state. **If the firewall is disabled, the network score is automatically 0.** This reflects the critical importance of having a host firewall active. When the firewall is enabled, points are deducted per exposed port based on risk level: | Port Risk Level | Penalty | |-----------------|---------| | Critical (e.g., Telnet, FTP) | -25 per port | | High (e.g., RDP, SMB internet-exposed) | -15 per port | | Medium | -5 per port | Port risk is context-aware. A port that is only accessible on localhost or blocked by the firewall has no impact. The same port exposed to the internet is penalized based on the service type. ## Viewing Health Scores ### Agent Detail Page Navigate to any agent and select the **Health** tab to see: - **Overall score gauge**: Circular gauge showing the 0-100 score with status label - **Category cards**: Four cards for Vulnerabilities, Compliance, Updates, and Network, each showing their individual score and key metrics - **30-day trend chart**: Area chart showing score history with toggleable series for overall and each category - **Fix These First**: A prioritized list of the most impactful remediation actions, ranked by severity. Items link directly to the relevant tab for that agent. - **History panel**: Timeline of score-impacting events over the last 30 days (e.g., "New critical vulnerability detected", "3 pending updates installed") ### Fleet Summary The agent list shows each agent's health score, allowing you to sort and filter by health status. The endpoints table includes a health score column to quickly identify agents that need attention. ## Trend Analysis The system tracks daily health scores for 30 days and calculates a trend: | Trend | Condition | |-------|-----------| | **Improving** | Score increased by more than 0.5 points over the period | | **Stable** | Score changed by less than 0.5 points | | **Declining** | Score decreased by more than 0.5 points | | **New** | Agent has less than 7 days of history | Trends require at least 7 days of data to avoid false signals during the initial assessment period. ## Configuring Weights Navigate to **Settings > Health Scoring** to adjust how much each category contributes to the overall score. - **Weight sliders**: Adjust the weight of each category. Weights automatically balance to total 100%. - **High-risk port configuration**: Define which ports are considered critical, high, or medium risk for the network exposure calculation. For example, if your organization prioritizes compliance over vulnerability patching, you could increase the Compliance weight and decrease the Vulnerability weight. The default weights reflect a security-first posture where known vulnerabilities carry the most impact. ## Prioritized Actions The "Fix These First" section on the Health tab generates up to 7 actions ranked by impact: 1. **CISA KEV vulnerabilities** (sorted by remediation due date) 2. **Critical CVEs** without KEV designation 3. **Critical and high-severity compliance failures** 4. **High-risk network port exposures** Each action includes a severity indicator and links directly to the relevant section of the agent detail page where you can take corrective action. ## Servicing Health Servicing Health, on the endpoint Health tab, runs pre-flight checks that look at the system state Windows cumulative updates depend on. When one of these checks fails, the next cumulative update will install, reboot, then roll back at 98% with errors like `0x800f0922` and revert to the prior state. The Servicing Health section surfaces the failing check up front so you can fix the underlying cause before triggering an install, instead of troubleshooting the failure afterward. This section appears on Windows endpoints only. The status badge in the section header summarizes the endpoint's overall readiness: | Badge | Meaning | |---|---| | **Ready for updates** | All checks passed. The endpoint is in a state where cumulative updates can install successfully. | | **Action recommended** | One or more checks returned a warning. The next update may still install, but the warned-on subsystem (for example, free space approaching its threshold) is worth addressing. | | **Update install blocked** | One or more checks returned a critical finding. Cumulative updates that try to install in this state are expected to fail. The fix is shown inline along with the relevant Microsoft KB article. | When everything is healthy, the section displays a single line confirming all checks passed and the timestamp of the most recent measurement. When a check fails, only the failing checks are listed, each with a plain-language summary, the recommended fix, and a link to the Microsoft KB article that documents the supported repair procedure. ### Checks performed | Check | What it looks at | Why it matters | |---|---|---| | **WinRE Configuration Consistency** | The `reagentc /info` output, `C:\Windows\System32\Recovery\ReAgent.xml`, and the WinRE entry in the Boot Configuration Data store. The check passes when WinRE is disabled, or when WinRE is enabled and the BCD identifier in `ReAgent.xml` matches what `reagentc` reports. | Cumulative updates refresh `winre.wim` when WinRE is enabled. When `ReAgent.xml` references a partition or BCD entry that no longer exists (a common state on long-lived imaged systems), the install reaches the post-reboot commit phase and reverts. The Microsoft-supported reset script in [KB5034957](https://support.microsoft.com/help/5034957) is the standard repair. | | **EFI System Partition Free Space** | The total and free bytes on the GPT EFI System Partition (mounted briefly via `mountvol`). | Post-April 2026 cumulative updates ship larger boot files than the legacy 100 MB ESPs common on older Windows 10/11 systems can absorb. The check warns at <100 MB free and flags critical at <50 MB free. Resize procedure is documented in [KB5028997](https://support.microsoft.com/help/5028997). | | **Recovery Partition Size** | The total size of the partition that holds `winre.wim`, identified by parsing the WinRE location reported by `reagentc /info` and looking up the partition with `Get-Partition`. | `winre.wim` has grown across recent feature updates; recovery partitions sized to the legacy 500 MB no longer fit the current image. The check warns at <750 MB and flags critical at <500 MB. The resize procedure is documented in [KB5034957](https://support.microsoft.com/help/5034957). | | **CBS Pending Operations** | `HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Component Based Servicing\PendingRequired` and `RebootPending` registry keys, plus `C:\Windows\WinSxS\pending.xml`. | Pending Component-Based Servicing operations from a previous failed update or feature change block subsequent cumulative updates from installing. The check warns when any indicator is present and recommends `dism /online /cleanup-image /restorehealth` followed by a reboot. | | **C: Free Space** | The free bytes on the C: drive (queried directly via Win32 `GetDiskFreeSpaceExW`). | Cumulative updates download and stage content under `C:\Windows\SoftwareDistribution` and `C:\$WinPE_Boot` before installing. Recent CUs need 8-10 GB of headroom at peak. The check warns at <20 GB free and flags critical at <10 GB free. | | **CheckSUR Errors** | The last 256 KB of `C:\Windows\Logs\CBS\CheckSUR.log`, counting `(f)` lines that are not followed by a `(fix)` line on the next non-blank row. | Unrepaired entries in the CheckSUR log strongly correlate with cumulative update failures. The check warns when any unrepaired errors are present and recommends `dism /online /cleanup-image /restorehealth` and `sfc /scannow`. | ### Frequency Probes run shortly after the agent connects to the server (on agent startup, restart, or reconnect). Findings are stored as the latest known state, one row per check per endpoint, so the section reflects the most recent measurement rather than a history. To re-run probes manually, restart the TridentStack Control agent service on the endpoint. ### What to do when a check fails 1. Read the **Fix** line on the failing check for a one-sentence summary of the supported repair. 2. Click the linked Microsoft KB article for the full procedure. 3. After running the repair on the endpoint, the next probe submission will clear the finding (or, if the issue persists, re-flag it with details that help narrow down the cause). ### Dismissing a warning You can dismiss a specific Servicing Health warning for a single endpoint. A dismissed warning stops counting toward that endpoint's Update Health and is shown as "Exempted". The warning details, the check, the plain-language summary, the recommended fix, and the Microsoft article link, are selectable text with a "Copy details" action, so you can send them to whoever owns the endpoint. Dismissing hides the warning from your dashboards; it does not change the endpoint itself, so the endpoint may still defer the update until the underlying issue is resolved. You can restore a dismissed warning at any time. The same details and Dismiss action are also reachable from the Update Health status on the Endpoints list. Clicking a flagged Update Health status opens the details. --- # Configuration Policies URL: https://docs.tridentstack.com/platform-guide/configuration-policies Description: Manage Windows device settings with ADMX-based Group Policy templates in TridentStack Control. No Active Directory required, versioning and rollback built in. # Configuration Policies Configuration policies let you manage Windows device settings using ADMX-based Group Policy templates. Define settings once and deploy them to targeted groups of endpoints. ## What Are ADMX Policies? ADMX (Administrative Template XML) policies are the same Group Policy settings used in Active Directory environments. They control everything from Windows Update behavior to BitLocker encryption, Defender settings, and user restrictions. TridentStack Control brings this capability to cloud-managed endpoints without requiring Active Directory infrastructure. You get the same granular control over device configuration, delivered through the TridentStack Control agent instead of a domain controller. ## Creating a Policy Object 1. Navigate to **Configuration Policies** in the sidebar. 2. Click **Create Policy**. 3. Enter a descriptive name for the policy (e.g., "Security Hardening - Windows 11" or "Remote Desktop - Enable for IT"). 4. Optionally add a description to document the policy's purpose. 5. Click **Create** to open the policy editor. Choose names that clearly communicate what the policy does. When you have dozens of policies, descriptive naming makes management significantly easier. ## Configuring Settings Each policy object contains one or more settings from the ADMX template catalog. Use the setting browser to find and configure the settings you need. ### Available Categories The ADMX catalog organizes settings into categories that mirror the Group Policy Management Editor: - **Windows Components**: Windows Update delivery and deferral, BitLocker drive encryption, Microsoft Defender Antivirus, Microsoft Edge browser settings - **System**: Power management, Remote Desktop Protocol, audit and logging, device installation restrictions - **Network**: DNS client configuration, Windows Firewall profiles, Wi-Fi and wireless networking - **Security**: Password policies, account lockout thresholds, User Account Control (UAC) behavior ### Setting States Each setting in a policy object can be in one of three states: | State | Behavior | |-------|----------| | **Enabled** | The setting is actively enforced. Some settings accept additional configuration values when enabled (e.g., specifying a minimum password length). | | **Disabled** | The setting is explicitly turned off. This is different from "Not Configured" because it actively disables the feature. | | **Not Configured** | The default state. TridentStack Control does not manage this setting, leaving whatever value the endpoint currently has in place. | When you enable a setting that accepts values, the editor displays the relevant input fields. For example, enabling "Minimum password length" reveals a numeric input where you specify the required length. ### Built-in security hardening settings TridentStack Control ships with a built-in catalog of well-known Windows security hardening settings, so you can apply trusted endpoint hardening without tracking down each setting yourself. These appear under **Administrative Templates** alongside the standard categories and include: - **Microsoft Security Guide** settings such as Certificate Padding enforcement, SMB v1 client and server controls, and structured exception handling protections. - **MSS (legacy) network hardening** options covering IP source routing, ICMP redirects, and related network-stack protections. - Credential and authentication protections drawn from Microsoft's recommended security baseline. Each setting shows its **recommended value**, so you can match Microsoft's baseline guidance at a glance. Use the setting browser's search to find a setting by name, then set it to the recommended value (or your own) just like any other Administrative Template setting. ### Settings that accept a list of values Some settings take a list of entries rather than a single value, such as antivirus path, process, and file-type exclusions. For these, the editor provides a list editor where you add and remove individual entries. Every entry you add is applied on your endpoints, and removing an entry removes just that value while leaving the rest in place. ## Targeting Configuration policies are assigned to agents using **tags**, the same targeting mechanism used by update policies. This provides a consistent and flexible way to control which endpoints receive which settings. ```mermaid flowchart LR A[Configuration Policy] -->|assigned to| B[Tag: Windows Servers] B -->|matches| C[Server-01] B -->|matches| D[Server-02] B -->|matches| E[Server-03] ``` Tag-based targeting means: - **New agents** that receive the tag automatically get the policy applied on their next check-in. - **Removing a tag** from an agent removes that policy's settings from the endpoint, returning them to their unmanaged state. See [Removing or deleting a policy](#removing-or-deleting-a-policy) below. - **Multiple policies** can target the same tag, and a single agent can receive settings from multiple policies. ## Policy Evaluation Policies are evaluated during the agent check-in cycle. The process works as follows: 1. The agent checks in with the TridentStack Control server. 2. The server resolves which configuration policies apply to the agent based on its tags. 3. Any new or updated policy settings are sent to the agent. 4. The agent applies the settings locally using the Windows policy engine. 5. The agent reports the applied settings back to the server for verification. :::info Configuration policies complement your existing Group Policy infrastructure. They do not conflict with AD-delivered GPOs, but TridentStack Control-managed settings take precedence when there is overlap. ::: ## Removing or Deleting a Policy When a configuration policy stops applying to an endpoint, TridentStack Control removes that policy's settings from the endpoint automatically. You do not need to manually reverse anything or push a separate "undo." Cleanup happens whenever you: - **Remove the tag** that targeted the endpoint, or remove the policy's assignment to that tag, so the policy no longer applies. - **Delete the policy** from the Configuration Policies list. In both cases the settings the policy applied return to their unmanaged state, exactly as if the policy had never run. Settings managed by another policy, and settings that were already present on the endpoint before any policy applied them, are left untouched. ### Online and offline endpoints - **Online endpoints** remove the settings within seconds of the change. - **Offline endpoints** remove the settings the next time they reconnect. An endpoint that was powered off or disconnected when you deleted or unassigned the policy is cleaned up automatically on its next check-in, with nothing for you to do when it comes back online. To confirm cleanup, open the endpoint's **Effective Policy** tab. Once cleanup is complete, the removed policy's settings no longer appear there. ## Best Practices - **Start small.** Begin with a few critical settings (e.g., password policies, Windows Update configuration) and expand as you gain confidence. - **Use descriptive names.** A policy named "CIS L1 - Account Policies" is far more useful than "Policy 1." - **Test before broad deployment.** Assign new policies to a small test tag first, verify the settings apply correctly, then expand to production tags. - **Document your intent.** Use the policy description field to record why the policy exists and what compliance requirement it addresses. ## Custom Registry Settings In addition to Administrative Templates, policy objects can include custom registry settings for direct Windows Registry key and value management. Use custom registry settings for third-party application configuration, advanced Windows tuning, and any scenario not covered by the ADMX catalog. ### Where to find registry settings Open a policy object and look for the **Registry Settings** node in the left sidebar tree. This is a top-level node, separate from the Administrative Templates tree. Click it to view and manage all custom registry settings for that policy object. ### Creating a registry setting Click **Add Registry Setting** to open the configuration form. Fill in the following fields: | Field | Required | Description | |-------|----------|-------------| | **Hive** | Yes | The registry hive to target: HKEY_LOCAL_MACHINE (HKLM) or HKEY_CURRENT_USER (HKCU) | | **Action** | Yes | What to do with the registry value: Create, Replace, Update, or Delete | | **Key Path** | Yes | The registry key path without the hive prefix (e.g., `SOFTWARE\MyCompany\MyApp`). Intermediate keys are created automatically if they do not exist | | **Value Name** | Yes | The name of the registry value. Leave empty to target the (Default) value | | **Value Type** | Yes (except Delete) | The data type: REG_SZ, REG_DWORD, REG_QWORD, REG_BINARY, REG_MULTI_SZ, or REG_EXPAND_SZ | | **Value Data** | Yes (except Delete) | The data to write. The expected format depends on the value type (see below) | | **Description** | No | An internal note explaining why this setting exists. Not deployed to endpoints | | **Enabled** | Default: on | Toggle to enable or disable the setting without deleting it | ### Registry actions Each setting uses one of four actions: | Action | Behavior | |--------|----------| | **Create** | Creates the value only if it does not already exist. If the value is already present, no changes are made | | **Replace** | Deletes the existing value first, then writes the new value. Creates it if it does not exist. Use this when you need to change the value type | | **Update** | Writes the value directly, overwriting if it exists or creating if it does not. This is the recommended default for most use cases | | **Delete** | Removes the value entirely. Only requires Hive, Key Path, and Value Name. Value Type and Value Data are ignored | ### Value types and data entry | Type | Input Format | Example | |------|-------------|---------| | **REG_SZ** | Plain text string | `C:\Program Files\MyApp` | | **REG_EXPAND_SZ** | Text with environment variables (expanded on the endpoint) | `%SystemRoot%\System32` | | **REG_DWORD** | 32-bit integer in decimal or hexadecimal | `1` or `0x00000001` | | **REG_QWORD** | 64-bit integer in decimal or hexadecimal | `4294967296` | | **REG_BINARY** | Space-separated hex byte pairs | `0A FF 3C 00` | | **REG_MULTI_SZ** | Multiple strings, one per line | Each line becomes one entry in the multi-string array | ### HKLM vs HKCU **HKEY_LOCAL_MACHINE (HKLM)** settings are computer-wide. They are applied once per machine and affect all users. This is the recommended hive for most deployments. **HKEY_CURRENT_USER (HKCU)** settings are per-user. They are applied to all users on the endpoint, not to individual users. The agent reapplies HKCU settings on each policy sync to cover users who log in after the initial deployment. :::info HKCU registry settings apply to **all users** on the endpoint. Individual user targeting is not supported. If you need per-user configuration, consider using User Configuration Administrative Templates instead. ::: ### Safety protections TridentStack Control prevents modifications to sensitive registry paths: - **Blocked paths** cannot be saved. These include `SOFTWARE\Policies` (reserved for Administrative Templates) and system-critical paths such as SAM, SECURITY, and boot execution entries. The editor displays a red warning and prevents saving. - **Warned paths** can be saved but display an amber warning. These include system control settings, Windows service configurations, OS version keys, and startup program entries. Review these carefully before saving. All settings are validated before saving. Key paths are checked for length limits and invalid characters. Value data is validated against the selected type (for example, REG_DWORD values must be valid 32-bit integers). :::warning Do not use custom registry settings for paths under `SOFTWARE\Policies`. Those paths are managed by Administrative Templates. Use the ADMX editor for any setting in the Policies subtree. ::: ### Managing registry settings The registry settings table shows all settings for the policy object. Each row displays: - An **enabled/disabled toggle** to activate or deactivate the setting without removing it - The **action** as a color-coded label (Create, Replace, Update, or Delete) - The full **key path** including the hive prefix - The **value name**, **value type**, and a preview of the **value data** - **Edit** and **Delete** buttons Click the edit button to reopen the form with the setting's current values. Click delete to remove the setting permanently (a confirmation dialog is shown first). ### Viewing applied settings After a policy object is deployed, you can verify that registry settings were applied correctly. Navigate to an agent's detail page and open the **Effective Policy** tab. Custom registry settings appear with a "Custom Reg" type label. You can filter the effective policy list by this type to see only registry settings. Each entry shows the configured action and value data so you can confirm the setting matches your policy object. --- # Hotpatch (Windows 11 Enterprise) URL: https://docs.tridentstack.com/platform-guide/update-management/hotpatch Description: How TridentStack Control deploys Windows 11 Enterprise hotpatches - monthly security fixes that install live without restarting the device. # Hotpatch (Windows 11 Enterprise) Hotpatch is a Microsoft Windows 11 Enterprise feature that installs monthly security updates **without restarting the device**. The reboot-required quarterly baseline updates still happen on schedule, but the months in between get their security fixes through hotpatches that apply live to running processes. For a fleet where uptime matters, hotpatch cuts patch-related downtime by roughly two thirds. TridentStack Control surfaces hotpatch readiness on every Windows agent so you can see at a glance which endpoints can take advantage of it, and which ones still have a prerequisite to fix. ## When to read this guide You are reading this guide because TridentStack Control showed you a "Hotpatch Ready" status on one or more of your endpoints. This page explains how to: 1. Confirm the endpoint meets every Microsoft prerequisite (TridentStack Control checks this automatically). 2. Configure a hotpatch-enabled quality update policy in Microsoft Intune so Windows actually starts installing hotpatches. 3. Verify that hotpatches are being delivered. If you are running Windows 11 **Pro** or **Home**, this guide does not apply. Microsoft ships hotpatch as an Enterprise / Education / IoT Enterprise feature only. The Hotpatch Ready badge on TridentStack Control will show "Not eligible (edition)" on those endpoints, and there is no third-party tool that can change that. ## How Microsoft delivers hotpatches Hotpatch is part of Microsoft's Windows Update for Business (WUfB) delivery channel. It is **not** available through the standard Microsoft Update Catalog, WSUS, or any offline download. Delivery requires: - A Microsoft Entra ID tenant (the free tier is sufficient). - The device joined to that Entra tenant (or Entra-hybrid-joined). - The device enrolled in Microsoft Intune or co-managed via Configuration Manager. - An eligible Windows 11 Enterprise license per endpoint. - A WUfB quality update policy assigned to the device that has hotpatch enabled. When all of the above are in place, Windows automatically downloads and installs each month's hotpatch in the background as soon as Microsoft publishes it. The device keeps running. There is no install action to schedule, no maintenance window to negotiate, no reboot to coordinate. ## Prerequisites TridentStack Control reads each of these signals from the agent's telemetry and shows the first failing check on the **Hotpatch Ready** row of the agent's System State tab. The five prerequisites in the order Microsoft enforces them are: ### 1. Edition The device must be running one of the following Windows 11 editions: - Enterprise - Enterprise N - Enterprise S (LTSC) - Enterprise SN (LTSC N) - Education - Education N - IoT Enterprise - IoT Enterprise S (LTSC) Pro, Home, and Server editions are not eligible. This is a Microsoft licensing constraint enforced by Windows itself at install time; no patch management tool can bypass it. To check the edition on a single device locally, open **Settings → System → About** and look at the "Edition" line. The TridentStack Control System State tab also shows the edition. ### 2. Build The device must be running Windows 11, version 24H2 or 25H2, at or above the current hotpatch baseline build: - **24H2:** OS build **26100.4929** or later - **25H2:** OS build **26200.4929** or later Older feature versions (23H2 and earlier) do not support hotpatch, and devices below the baseline build need the latest quarterly cumulative update installed before hotpatches will apply. If the device is below the baseline, install the latest standard cumulative update through your existing TridentStack Control patch policy first. Once the device reports a build at or above the baseline, hotpatch becomes available. ### 3. Virtualization-Based Security (VBS) VBS must be enabled. Hotpatching modifies running kernel code, and Microsoft requires the kernel to be running in a VBS-protected environment so the patched code can be verified. To enable VBS: 1. Open **Windows Security** on the device. 2. Go to **Device security → Core isolation**. 3. Turn **Memory integrity** on. 4. Restart the device. After the restart, VBS will be running. TridentStack Control's Hotpatch Ready row will refresh on the next agent telemetry collection and show this prerequisite as passing. If the toggle is greyed out, the device's CPU is missing virtualization features in BIOS/UEFI. Enable Intel VT-x / AMD-V and SLAT in firmware, then try again. ### 4. Microsoft Entra join The device must be **Microsoft Entra joined** or **Microsoft Entra hybrid joined**. Workgroup-only and on-premises Active-Directory-only devices cannot receive hotpatches because WUfB delivery requires an Entra identity. To check the join state, run on the device: ```powershell dsregcmd /status ``` Look for `AzureAdJoined : YES` or both `AzureAdJoined : YES` and `DomainJoined : YES` (hybrid). To Entra-join a device: 1. On the device, open **Settings → Accounts → Access work or school**. 2. Click **Connect** and sign in with an Entra account that has device-join rights. 3. Choose **Join this device to Microsoft Entra ID**. For hybrid join at scale, configure Microsoft Entra Connect on your on-premises Active Directory. ### 5. Intune enrollment with a hotpatch-enabled policy The device must be enrolled in **Microsoft Intune** (or co-managed via Configuration Manager) with a Windows quality update policy that has hotpatch enabled and is targeted at this device. Enrollment alone is not enough. The policy must exist, have hotpatch turned on, and have this device's Entra group as a target. The next section walks through creating that policy. ## Step-by-step: enabling hotpatch in Microsoft Intune These steps assume you already have an Intune tenant and the devices you want hotpatched are enrolled. If you are still rolling Intune out, complete enrollment first. ### Step 1: Create an Entra group for hotpatch-eligible devices A dedicated group makes targeting and rollout control simpler than scattering device IDs across multiple policies. 1. Sign in to the [Microsoft Intune admin center](https://intune.microsoft.com) with an account that has at least the **Intune Administrator** role. 2. Go to **Groups → All groups → New group**. 3. Choose **Group type: Security**. 4. Name the group something like `Hotpatch Eligible Devices`. 5. Set **Membership type** to **Dynamic Device** (recommended) or **Assigned** if you want manual control. 6. For dynamic membership, use a rule that selects only eligible devices, for example: ``` (device.deviceOSType -eq "Windows") -and (device.deviceOSVersion -startsWith "10.0.26100") -and (device.deviceManagementAppId -ne $null) ``` Adjust the build prefix for your target version (`10.0.26100` for 24H2, `10.0.26200` for 25H2). 7. Click **Create**. Allow a few minutes for the dynamic rule to populate membership. ### Step 2: Create the quality update policy 1. In the Intune admin center, go to **Devices → Manage updates → Windows updates**. 2. Open the **Quality updates** tab. 3. Click **Create profile → Windows quality update policy**. 4. Give it a name like `Hotpatch Enabled - Win 11 Enterprise` and a description noting it is the hotpatch-enabled policy. 5. Continue to the **Update settings** page. 6. Under **Update approach**, set: - **Update approach:** `Hotpatch` - **Quality update deferral period (days):** `0` for fastest delivery, or higher if you want a deferred window for testing. :::note The "Hotpatch" option appears only when Microsoft has detected your tenant is eligible. If you do not see it, confirm your Intune licensing includes the Windows 11 Enterprise SKU and that your tenant region is supported. ::: 7. Leave other settings at defaults unless you have a specific reason to change them. 8. Continue to **Scope tags**, **Assignments**, and **Review + create**. ### Step 3: Assign the policy 1. On the **Assignments** page of the policy you just created, click **Add groups**. 2. Select the `Hotpatch Eligible Devices` group from Step 1. 3. Click **Select**, then **Next**, then **Create**. Devices in the group will start receiving the policy on their next WUfB sync cycle (typically within an hour). On the next monthly hotpatch release from Microsoft, Windows will download and install the hotpatch automatically. ### Step 4: Confirm in Intune Back on the policy's overview page, the **Device check-in status** counters update as devices receive and acknowledge the policy. A successful assignment shows the count under **Succeeded** matching your group membership. If you see devices stuck in **Pending** or **Failed** for more than a few hours, click into the row for per-device error detail. The most common causes are: - Device hasn't synced with Intune recently. Force a sync via **Settings → Accounts → Access work or school → Info → Sync** on the device. - Device hasn't yet rebooted after enabling VBS. Hotpatch requires VBS running, not just configured. - Device hasn't yet installed the current baseline cumulative update. Install it through your existing patch policy first. ### Step 5: Confirm in TridentStack Control On the agent's detail page, open the **System State** tab and find the **Hotpatch Ready** row. A green **Eligible** badge means TridentStack Control sees the device meeting every prerequisite. The first hotpatch will install on the next monthly Microsoft release; you do not need to take any further action. For deeper verification on the device itself, open **Settings → Windows Update → Update history**. Hotpatches appear with titles like "May 12, 2026—Hotpatch KB5089466 (OS Build 26100.8390)" and **do not** include the "Restart now" prompt that standard cumulative updates do. ## What you'll see on each agent The Hotpatch Ready row on the System State tab summarizes the state for each Windows agent: | Badge | What it means | Action | |---|---|---| | **Eligible** (green) | All five Microsoft prerequisites pass. If you have configured the Intune policy in Step 2, this device is receiving hotpatches. | None needed once Intune policy is configured. | | **Not eligible (edition)** | Device is running Pro, Home, or another non-Enterprise SKU. | Upgrade the device's Windows license to Enterprise / Education / E3 / E5 / F3. | | **Not eligible (build)** | Device is on an unsupported feature version or below the hotpatch baseline build. | Install the current quarterly cumulative update through TridentStack Control. | | **Not eligible (vbs)** | Virtualization-Based Security is not enabled. | Enable Memory integrity in Windows Security as described in Prerequisite 3. | | **Not eligible (entra_join)** | Device is not Microsoft Entra joined. | Entra-join the device as described in Prerequisite 4. | | **Not eligible (mdm)** | Device is not enrolled in Microsoft Intune (or its MDM provider is not Intune). | Enroll the device in Intune. | Click the **(i)** info icon next to the row label for a quick recap of the prerequisites without leaving the page. ## Troubleshooting ### The "Hotpatch" option doesn't appear in Intune The hotpatch update approach only appears for tenants Microsoft has flagged as eligible. Check: - Tenant licensing includes Windows 11 Enterprise E3 / E5 (or one of the eligible Microsoft 365 / Microsoft 365 Education plans). - Tenant region is one of the regions where hotpatch is generally available. - You are creating a **Windows quality update policy**, not a feature update policy or an expedited update. If all three are true and the option is still missing, contact Microsoft support; the issue is on the Intune side and TridentStack Control cannot affect it. ### A device shows Eligible but isn't receiving hotpatches Eligible means every prerequisite passes. It does not guarantee the Intune policy is assigned to the device. Check: 1. On the policy's Assignments page in Intune, confirm the device's group is listed and the device is a member. 2. On the device, run `gpupdate /force` to refresh policy. 3. In TridentStack Control's [agent history](/platform-guide/agents/history) view, check whether any hotpatches have been recorded under "Installed Updates" in the System State tab. If the agent has been online for over 24 hours after policy assignment and no hotpatches have appeared, the issue is almost always a stale Intune sync. Open **Settings → Accounts → Access work or school → Info → Sync** on the device to force a refresh. ### A hotpatch failed to install Hotpatch install failures appear in the device's Windows Update history with an error code. Common ones: - **0x80070003** - required baseline cumulative update is missing. Install the current quarterly cumulative. - **0x800f0922** - pre-flight check failure (this is what [Servicing Health](/platform-guide/agents/system-state#servicing-health) catches in advance). Fix the underlying servicing issue. - **0x80240438** - VBS was not running at install time. Confirm Memory integrity is on and the device has rebooted since enabling it. ## Related pages - [System State](/platform-guide/agents/system-state) for the full agent telemetry view that includes the Hotpatch Ready row. - [System Updates](/platform-guide/update-management/system-updates) for the broader cumulative update flow that delivers the quarterly baselines hotpatches build on. - [Deployment Rings](/platform-guide/update-management/deployment-rings) for phasing baseline updates across your fleet. ## External references - [Microsoft: Hotpatch updates with Windows Autopatch](https://learn.microsoft.com/en-us/windows/deployment/windows-autopatch/manage/windows-autopatch-hotpatch-updates) - Microsoft's authoritative documentation for hotpatch, including the current baseline build numbers and a list of supported product SKUs. - [Microsoft: KB5089466 (May 2026 hotpatch example)](https://support.microsoft.com/en-us/topic/may-12-2026-hotpatch-kb5089466-os-builds-26200-8390-and-26100-8390-8a0dd60b-c2fb-45d6-95f2-2609df309a9a) - sample of what a monthly hotpatch KB article looks like, listing CVEs addressed. --- # System State URL: https://docs.tridentstack.com/platform-guide/agents/system-state Description: Per-endpoint OS telemetry, installed-update history, Defender posture, and endpoint protection status in TridentStack Control's System State tab. # System State The System State tab on the agent detail page provides detailed operating system telemetry, installed update history, endpoint protection status, and Windows Defender health. This tab focuses on the endpoint's software state and security posture. :::note Pending updates and system summary information are displayed in the [always-visible sections](/platform-guide/agents/endpoints#page-layout) above the tab bar, not within this tab. The System State tab shows deeper telemetry data that complements those summary panels. ::: ## Operating System A detailed breakdown of the endpoint's OS configuration: | Field | Description | |-------|-------------| | Name | Full OS name (e.g., Windows 11 Pro, Ubuntu 24.04) | | Edition | OS edition (e.g., Pro, Enterprise, Server Standard) | | Version | Feature version (e.g., 24H2 for Windows, kernel version for Linux) | | Build | OS build number including UBR (e.g., 26200.7848) | | Architecture | System architecture (e.g., x64) | | Locale | System locale setting | | Restart Required | Whether a reboot is pending | | ESU License | Extended Security Updates license status, shown only for OSes past their end-of-support date (Windows Server 2012/2012 R2, Server 2016, Server 2019, Windows 10) | ## Version Components (Windows only) Tracks versions of key Windows platform components: - **MSRT Version** - Microsoft Malicious Software Removal Tool version - **Security App** - Windows Security app version (not applicable on Server editions) - **.NET Framework** - Installed .NET Framework versions - **.NET Runtimes** - Installed .NET runtime versions (e.g., NETCore.App 8.0.11, WindowsDesktop.App 6.0.36) ## Microsoft Office If Microsoft Office is installed, this section shows the endpoint's Office details. It appears on both Windows and macOS endpoints that have Office installed. - **Version** - Installed Office version number - **Architecture** - Office architecture (Windows: x86 or x64) - **Channel** - Update channel (Windows: Monthly Enterprise, Semi-Annual; macOS: the Microsoft AutoUpdate channel) - **Products** - Installed Office products (e.g., Word, Excel, Outlook) - **Update status** - Whether an Office update is available, with the target version displayed ## Installed Updates A scrollable table listing all updates currently installed on the endpoint. **Windows endpoints** show: - KB number, update name, and release date for each installed KB - KB details are enriched from the update catalog when available **Linux endpoints** show: - Package name and version for each installed security package **macOS endpoints** show: - Update name, version, and release date for each installed system update - Apple Security Advisory references are linked inline when the update was published with an associated advisory ## Servicing Health Servicing Health now appears on the endpoint Health tab. See [Health Score](./health-score.md#servicing-health). ## Endpoint Protection Shows the endpoint's EDR (Endpoint Detection and Response) and antivirus status: - **Status badge** - Active (green), Detected (yellow), Defender Only (default), or Not Detected (red) - **Primary EDR** - The primary endpoint protection product if detected - **Product list** - All detected security products with vendor, version, and running state - If a third-party EDR is active and has disabled Windows Defender, a note explains that Defender is disabled because the third-party product is providing protection ## Windows Defender (Windows only) Detailed Windows Defender health information: | Field | Description | |-------|-------------| | Status badge | Up to Date (green), Out of Date (yellow, signatures older than 24 hours), Critical (red, signatures older than 7 days), or Disabled | | Signature Version | Current definition signature version | | Signature Age | Hours or days since last signature update | | Engine Version | Defender engine version | | Product Version | Defender product version | | Last Updated | Timestamp of the most recent signature update | When a third-party EDR has disabled Windows Defender (engine version shows 0.0.0.0), all fields display "N/A" and the status shows "Disabled". ## Refresh The tab header includes a refresh button that triggers the agent to collect and send fresh system state telemetry. The button is disabled when: - The agent is offline - A system applicability refresh is already in progress (system state is collected as a sub-task) - A vulnerability scan is in progress (also includes system state collection) --- # Vulnerabilities URL: https://docs.tridentstack.com/platform-guide/vulnerabilities Description: Fleet-wide CVE detection in TridentStack Control: software inventory matched against NVD and Microsoft data, prioritized by CVSS, KEV, and EPSS. # Vulnerabilities The Vulnerabilities section provides automated vulnerability detection across your fleet. TridentStack Control correlates installed software and system update status against known CVE databases to identify exposed endpoints. ## How Vulnerability Detection Works TridentStack Control continuously evaluates your fleet for known vulnerabilities by combining data from your agents with external CVE databases. ```mermaid flowchart TD A[Agent reports installed software] --> B[Agent reports installed updates] B --> C[Server correlates with CVE database] C --> D[Identifies missing patches] D --> E[Calculates vulnerability exposure] E --> F[Results appear in Vulnerabilities page] ``` The process is fully automated. Each time an agent checks in and reports its software inventory and installed updates, the server re-evaluates that agent's vulnerability exposure. No manual scans are required. ## Navigating the Vulnerabilities Page The Vulnerabilities page is organized into five tabs, each providing a different perspective on your fleet's security posture. ### All A flat list of every detected vulnerability across all agents. Each row represents a unique CVE found on one or more endpoints. You can sort and filter by: - **Severity** (Critical, High, Medium, Low) - **CVE ID** - **Affected agents count** - **Discovery date** This view is useful when you need to find a specific CVE or want to see the complete picture of your exposure. ### Overview A high-level summary of your fleet's vulnerability status. This tab includes: - **Severity breakdown**: How many vulnerabilities fall into each severity category (critical, high, medium, low) - **Trend charts**: Visualize how your vulnerability count changes over time - **Top vulnerable endpoints**: Quickly identify which agents have the most exposure :::tip Review the Overview tab regularly to track your fleet's vulnerability trend. A downward trend means your patching strategy is working. ::: ### By Agent View vulnerabilities grouped by endpoint. This tab answers the question: "Which of my machines are most at risk?" Each row shows an agent with its total vulnerability count and severity breakdown. Click any agent to drill into its individual vulnerability list, where you can see every CVE affecting that endpoint. ### History Track vulnerability discovery and remediation over time. The History tab shows: - When each CVE was first detected in your environment - When vulnerabilities were resolved (the missing patch was installed) - Trends in time-to-remediation This view is particularly useful for audit and reporting purposes, where you need to demonstrate that vulnerabilities are being addressed within defined SLAs. ### Exceptions Manage vulnerability exceptions from this tab. Exceptions suppress specific CVEs from reports and dashboards when you have determined they are not applicable or have mitigating controls in place. See [Creating Exceptions](#creating-exceptions) below for details. ## Severity Levels TridentStack Control uses the industry-standard CVSS (Common Vulnerability Scoring System) to categorize vulnerability severity: | Severity | CVSS Score Range | Description | |----------|-----------------|-------------| | **Critical** | 9.0 - 10.0 | Exploitation is straightforward and leads to full system compromise. Patch immediately. | | **High** | 7.0 - 8.9 | Significant risk of exploitation or impact. Patch within your defined SLA. | | **Medium** | 4.0 - 6.9 | Moderate risk, typically requiring specific conditions for exploitation. | | **Low** | 0.1 - 3.9 | Limited risk or impact. Address during routine maintenance windows. | ## CVE Detail Page Click any CVE ID to open its detail page. The detail page provides: - **Description**: What the vulnerability is and how it can be exploited - **CVSS score**: The numeric score and severity rating - **Affected products**: Which software or OS components are vulnerable - **Exposed agents**: A list of every agent in your fleet that is affected - **Remediation guidance**: Which KB articles (patches) resolve the vulnerability - **External references**: Direct links to the NVD (National Vulnerability Database) entry and vendor advisories The remediation guidance is the critical piece: it tells you exactly which patch to deploy to eliminate the vulnerability. ## Creating Exceptions If a CVE is not applicable to your environment, you can create an exception to suppress it from reports. Common reasons for exceptions include: - The vulnerable feature or component is disabled on your endpoints - A compensating control is in place (e.g., network segmentation, firewall rules) - The vulnerability applies to a software version you do not run - A vendor has confirmed the vulnerability does not affect your configuration To create an exception: 1. Navigate to the CVE detail page or the **Exceptions** tab. 2. Click **Create Exception**. 3. Select the scope: fleet-wide or specific agents. 4. Enter a justification note explaining why the exception is warranted. 5. Optionally set an expiration date, after which the CVE will reappear in reports. 6. Click **Save**. :::warning Vulnerability exceptions hide CVEs from reports but do not eliminate the risk. Only create exceptions when you have verified that a compensating control is in place. ::: ## Remediation The fastest way to remediate vulnerabilities is to deploy the missing patches through your update policies. The recommended workflow: 1. Review the **Overview** tab to identify your highest-severity vulnerabilities. 2. Open the CVE detail page for a critical or high-severity CVE. 3. Note the **KB article** listed in the remediation guidance. 4. Navigate to your **Update Policies** and verify the relevant KB is approved for deployment. 5. If the KB is not yet approved, add it to the appropriate policy. 6. Agents will install the patch on their next maintenance window. After the patch is installed, the vulnerability is automatically marked as resolved during the agent's next check-in. No manual intervention is needed to clear remediated CVEs. You can also remediate directly from an endpoint's Vulnerabilities tab: apply a verified one-click fix, or use **Add to Policy** when the fix needs to deploy through a configuration policy. After remediating, a CVE shows as **awaiting re-scan** until the next check-in confirms it; click **Re-scan now** to confirm right away. See the [per-endpoint Vulnerabilities tab](./agents/vulnerabilities.md) for the full set of actions. --- # Software Inventory URL: https://docs.tridentstack.com/platform-guide/agents/software-inventory Description: Software Inventory in TridentStack Control lists every installed application per endpoint, what's TridentStack-managed, and what has updates available. # Software Inventory The Software Inventory tab lists every application installed on the endpoint. Use it to understand what software is deployed, which applications are managed through TridentStack Control, and which have updates available. ## Inventory Table The table displays all detected software with the following columns: | Column | Description | |--------|-------------| | Name | Application display name | | Version | Currently installed version | | Managed | Whether this application is managed by a TridentStack Control configuration | | Update Status | Whether an update is available for this application | ### Summary Bar At the top of the table, a summary bar shows: - **Total packages**: Count of all detected software - **Managed / Unmanaged**: How many applications are managed through TridentStack Control vs. unmanaged - **Up to Date / Needs Update**: How many applications are current vs. have available updates ### Searching and Filtering - **Search**: Type in the search bar to filter by application name in real time. - **Managed filter**: Show All, Managed only, or Unmanaged only. - **Update filter**: Show Any Status, Needs Update only, or Up to Date only. The table uses infinite scrolling, loading 50 items at a time as you scroll down. ## Actions - **Add to Policy**: Right-click any application and select "Add to Policy" to include it in an application update configuration. This opens a modal where you can select or create a configuration. - **Refresh**: Triggers the agent to re-enumerate installed software and send a fresh inventory. ## Platform Notes Software inventory is collected on Windows, macOS, and Linux endpoints. - **Windows**: inventory is read from the system package manager where available. On systems without one (Server 2016 and older), it is gathered from the Windows registry, and application updates use direct installer downloads from the synced catalog. - **macOS**: installed applications are enumerated from the system. Applications that have a match in the catalog can be managed and updated through an application update configuration. - **Linux**: installed packages are reported from the system package manager. Linux package updates are managed as [system updates](../update-management/system-updates#linux-updates) rather than through application configurations. --- # Compliance URL: https://docs.tridentstack.com/platform-guide/compliance Description: Fleet-wide compliance reporting in TridentStack Control against CIS Benchmarks (Windows, Linux, and macOS), DISA STIGs, Microsoft Security Baselines, and NIST. # Compliance The Compliance section measures your fleet against industry-standard security baselines. TridentStack Control supports multiple compliance frameworks and provides per-agent and per-control scoring. ## Supported Frameworks TridentStack Control includes built-in support for the following compliance frameworks: ### CIS Benchmarks (Level 1 and Level 2) The Center for Internet Security publishes hardening guidelines for Windows, Linux, and macOS. CIS benchmarks are widely adopted across industries and are often referenced by regulatory requirements. TridentStack Control evaluates a platform-specific benchmark on each agent automatically as it checks in: | Platform | Benchmark | |----------|-----------| | Windows | CIS Microsoft Windows Benchmark | | Linux | CIS Ubuntu Linux 22.04 LTS Benchmark | | macOS | CIS Apple macOS Sonoma Benchmark | Most benchmarks define two profiles: - **Level 1**: Designed for broad deployment with minimal impact on functionality. Suitable for most organizations as a starting baseline. - **Level 2**: Extended hardening for high-security environments. May restrict some functionality in exchange for stronger security posture. ### DISA STIG The Defense Information Systems Agency publishes Security Technical Implementation Guides. STIGs are mandatory for U.S. Department of Defense systems and widely used in government and defense contracting. TridentStack Control includes the DISA STIG for Microsoft Windows. ### Microsoft Security Baselines Microsoft's recommended security configurations for Windows operating systems. These baselines represent Microsoft's own guidance for hardening Windows, updated with each major OS release. ### NIST SP 800-53 The National Institute of Standards and Technology's comprehensive catalog of security and privacy controls. NIST 800-53 is referenced by FedRAMP, FISMA, and many private-sector compliance programs. ## Navigating the Compliance Page The Compliance page is organized into five tabs, each providing a different angle on your compliance posture. ### Overview The fleet-wide compliance dashboard. This tab shows: - **Overall compliance score**: An aggregate score across all active baselines and agents - **Framework-by-framework breakdown**: How your fleet scores against each active baseline - **Trend charts**: Compliance improvement (or regression) over time ```mermaid flowchart LR A[Agent checks in] --> B[Server evaluates controls] B --> C[Pass/fail per control] C --> D[Score calculated per baseline] D --> E[Results displayed in Compliance] ``` ### Per-Agent Each agent's compliance score across all active baselines. This tab answers the question: "How compliant is this specific machine?" Click any agent to drill into its detailed results, showing which controls pass and which fail for each assigned baseline. ### By Framework Detailed compliance results organized by framework. Select a framework to see the pass/fail status for every control it contains. This view is useful when preparing for an audit against a specific standard, as it shows your exact posture against every control in the framework. ### By Category Compliance results grouped by control category, such as: - Account Policies - Audit Policies - Security Options - User Rights Assignment - Windows Firewall This view is useful for identifying systemic gaps. For example, if most of your agents fail controls in the "Audit Policies" category, you know to focus your remediation efforts on audit configuration. ### Baselines Manage which compliance baselines are active and which agents they target. This is where you deploy new baselines and adjust targeting. ## Deploying a Baseline To start measuring compliance against a framework: 1. Navigate to **Compliance > Baselines**. 2. Select the framework you want to deploy (for example, CIS Level 1 for Windows, the CIS Ubuntu 22.04 Benchmark for your Linux servers, or the CIS macOS Sonoma Benchmark for your Macs). 3. Assign the baseline to one or more **agent tags**. 4. Click **Save**. Compliance evaluation begins on the next agent check-in. Results will appear in the other tabs as agents report their configuration state. :::info Compliance evaluation runs automatically during agent check-ins. No manual scans are needed. ::: ## Compliance Scoring Each agent receives a compliance percentage per baseline. For example, an agent might show: | Baseline | Score | Passing | Failing | Not Applicable | |----------|-------|---------|---------|----------------| | CIS Level 1 | 87% | 174 | 26 | 12 | | Microsoft Baseline | 92% | 138 | 12 | 5 | The score is calculated as: ``` Compliance % = (Passing Controls / Total Applicable Controls) x 100 ``` Controls that are **not applicable** to an agent (e.g., a BitLocker control on a machine without a TPM) are excluded from the calculation entirely. This prevents non-applicable controls from artificially lowering scores. ## Investigating Failures When an agent fails a compliance control, you need to understand what is wrong and how to fix it. Click any failing control to see: - **Control description**: What the control requires and why it matters - **Expected configuration**: The value or state the control expects to find - **Actual configuration**: What was found on the agent - **Remediation steps**: How to bring the agent into compliance For example, a failing "Minimum password length" control might show: | Field | Value | |-------|-------| | Expected | Minimum 14 characters | | Actual | 8 characters | | Remediation | Set the "Minimum password length" policy to 14 or greater | ## Remediation with Configuration Policies Many compliance failures can be remediated by deploying [configuration policies](./configuration-policies.md). When a compliance control maps to an ADMX policy setting, the control detail page includes a direct link to the relevant setting. The recommended workflow: 1. Identify failing controls in the **By Category** or **Per-Agent** view. 2. Click into a failing control to see the remediation guidance. 3. If the control links to an ADMX setting, navigate to **Configuration Policies**. 4. Create or update a policy to configure that setting with the expected value. 5. Assign the policy to the appropriate agent tags. 6. On the next check-in, the agent applies the setting and the compliance score updates. :::tip Start with CIS Level 1 as your baseline. Level 1 controls are designed to be applied broadly with minimal impact on functionality. Move to Level 2 for higher-security environments. ::: ## Best Practices - **Baseline before remediating.** Deploy a baseline and measure your current posture before making changes. This gives you a clear before/after comparison. - **Prioritize by category.** Use the By Category tab to find systemic issues that affect many agents, rather than fixing controls one agent at a time. - **Track trends.** The Overview trend charts show whether your compliance posture is improving. Share these with stakeholders to demonstrate progress. - **Document exceptions.** If a control cannot be met due to business requirements, document the reason and any compensating controls in place. - **Review after OS updates.** Major OS updates can change default settings. Re-evaluate compliance after deploying feature or version updates to catch any regressions. --- # importing-group-policy URL: https://docs.tridentstack.com/platform-guide/importing-group-policy # Importing Group Policy Objects TridentStack Control can import Group Policy Objects (GPOs) exported from an on-premises Active Directory environment. The import converts the GPO's settings into a configuration policy that you can review, enable, and assign to endpoints, so you do not have to recreate existing policies by hand when migrating off on-prem Group Policy. ## Step 1: Back up the GPO On a machine with the Group Policy Management Console (GPMC): 1. Open Group Policy Management. 2. Right-click the GPO you want to export and choose **Back Up**. 3. Choose an empty folder as the backup location and complete the wizard. Or with PowerShell: ```powershell Backup-GPO -Name "Workstation Hardening" -Path C:\GPOBackup ``` The backup is a folder named with a GUID, containing Backup.xml and a DomainSysvol folder. ## Step 2: Zip the backup Compress the backup folder into a single zip file. You can zip either the GUID folder itself or the parent folder that contains it. The zip must be 20 MB or smaller. ```powershell Compress-Archive -Path C:\GPOBackup\* -DestinationPath C:\WorkstationHardening.zip ``` ## Step 3: Import 1. In TridentStack Control, go to **Configuration Policies**. 2. Select **Import GPO** and upload the zip file. 3. Review the import preview. ## What the preview shows The preview groups the GPO's settings into three lists: - **Ready to import**: settings that map directly to TridentStack Control's policy catalog, with their values carried over. This includes Administrative Template settings with configured options such as dropdown selections, text fields, and numeric values. - **Needs review after import**: settings that were recognized, but where one or more values could not be converted automatically (for example, list-style policy entries, or options from administrative templates that are not part of Windows itself). These are imported with the values that could be converted and flagged in the setting notes so you can finish them in the policy editor. - **Not supported**: anything TridentStack Control does not enforce, such as Group Policy Preferences, scripts, software installation, and folder redirection. These are listed so you know exactly what was left behind; they are never silently dropped. A typical GPO export produces only a handful of entries here. You can deselect any setting you do not want to import, and edit the policy name before confirming. ## What gets imported | GPO area | Imported | |---|---| | Administrative Templates (Computer and User) | Yes | | Security Settings: password and lockout policy, user rights, security options | Yes | | Audit policy (classic and advanced) | Yes | | System services startup configuration | Yes | | Group Policy Preferences, scripts, software installation, folder redirection, firewall rules | No (listed as not supported) | If the GPO contains both Computer Configuration and User Configuration settings, the import creates two policies: one machine-scoped and one user-scoped (named with a "(User)" suffix). ## After the import Imported policies are always created **disabled and unassigned**. Nothing is applied to any endpoint until you: 1. Open the new policy and review its settings, especially any flagged for review. 2. Enable the policy. 3. Assign it to endpoints or tags. Settings that need attention carry a note explaining what to check. The policy works like any other configuration policy from this point on, including version history and rollback. --- # Vulnerabilities URL: https://docs.tridentstack.com/platform-guide/agents/vulnerabilities Description: Per-endpoint CVE detection in TridentStack Control: matched software versions, CVSS scoring, KEV and EPSS context, and exception management. # Vulnerabilities The Vulnerabilities tab on the agent detail page shows all CVEs detected on the endpoint. TridentStack Control continuously matches installed software versions and Windows build numbers against CVE databases to identify known vulnerabilities. ## Current View The default view shows all active vulnerabilities in a sortable, filterable table. ### Vulnerability Table | Column | Description | |--------|-------------| | CVE ID | The CVE identifier, linked to the NVD entry | | Software | The affected application or "Windows" for OS-level CVEs | | Severity | Critical, High, Medium, or Low (color-coded) | | CVSS Score | Numeric CVSS v3 base score | | Status | Open, Awaiting re-scan, Resolved, or Pending Restart | ### Summary Bar Above the table, a summary strip shows: - Total vulnerability count - Breakdown by severity: Critical / High / Medium / Low - KEV count (CISA Known Exploited Vulnerabilities) ### Source Tabs On Windows and macOS agents, vulnerabilities are categorized by source: - **All**: Every detected vulnerability - **System**: CVEs in the operating system itself (on Windows, based on build number and installed KBs) - **Software**: CVEs in installed third-party applications (based on software inventory) ### Filters - **Search**: Filter by CVE ID, software name, or CWE identifier - **Severity**: Show only Critical, High, Medium, or Low - **KEV only**: Toggle to show only CISA Known Exploited Vulnerabilities - **Fixable**: Toggle to show only vulnerabilities with an available fix (a missing update or a newer software version). On endpoints whose operating system is past its end-of-support date, this shows only the fixes you can apply without an Extended Security Update (ESU) license. - **ESU only**: Appears next to **Fixable** on endpoints past their end-of-support date that have fixes gated behind an Extended Security Update (ESU) license. Toggle it to show only those ESU-gated fixes. It is hidden on endpoints with no ESU-gated fixes. - **Group by Remediation**: Group vulnerabilities that share the same fix action (e.g., same update resolves multiple CVEs) ### Expanded Details Click any vulnerability row to see full details: - **CVSS v3 vector breakdown**: Attack Vector, Attack Complexity, Privileges Required, User Interaction, Scope, and Confidentiality/Integrity/Availability impact - **EPSS score**: Exploit Prediction Scoring System probability and percentile - **KEV status**: Whether this CVE is in the CISA Known Exploited Vulnerabilities catalog - **Fix information**: The KB number or package update that resolves the vulnerability - **Detection logic**: How the vulnerability was identified (version comparison, build number match, etc.) ### Actions From the expanded row, you can: - **Apply Fix**: Shown when a verified one-click fix is available (the fix is known to resolve the CVE and the affected software is confidently matched to a cataloged package). Clicking it triggers the remediation immediately. - **Add to Policy**: Shown when a precise fix exists but applicability is unconfirmed (for example, the installed software could not be matched to a cataloged package with certainty). Clicking it opens the remediation flow with a compatibility warning and adds the fix to an application update policy, so the update deploys on the next evaluation. If the endpoint inherits more than one application update policy, you are asked which policy should receive the application. - **Remediate**: The generic entry point to the remediation modal, available from the row's action menu. Use this when neither Apply Fix nor Add to Policy is surfaced, or when you want to review the full set of remediation options before dispatching. - **Create Exception**: Exempt this vulnerability from scoring and reporting, with a reason and optional expiration date. - **Investigate**: Open an investigation view for deeper analysis. If no policy currently covers the fix on this endpoint, you can still run a **one-off remediation** from the Remediate dialog. It installs the fix immediately on that single endpoint, outside any policy, and does not change your policies or affect other endpoints. The dialog shows exactly which application or update will install and the target version before you confirm. ### After you remediate When you apply a fix or the missing update installs, the vulnerability does not clear instantly. It moves to an **Awaiting re-scan** state, shown as "Update installed - refresh on next scan", because TridentStack Control confirms the fix the next time the agent reports its software inventory and patch status. - Confirmation happens automatically on the agent's next check-in, after which the CVE moves to **Resolved**. - To confirm immediately instead of waiting, click **Re-scan now** on the vulnerability. This asks the agent to re-report its state right away. This keeps a vulnerability from briefly looking unresolved after you have already fixed it. ## History View Toggle to **History** to see the vulnerability timeline for this agent: - When vulnerabilities were first detected - When they were resolved (by patch installation or software update) - Status transitions over time This helps you verify that remediation actions were effective and track how long vulnerabilities remained open. --- # Reporting URL: https://docs.tridentstack.com/platform-guide/reporting Description: Build custom fleet reports in TridentStack Control with the visual query builder or write SQL directly against your patch, vuln, and compliance data. # Reporting The Reporting page provides a built-in reporting engine for building custom queries against your fleet data. Use the visual query builder for simple reports or write SQL directly for advanced analysis. :::info Reports are read-only queries. They cannot modify data. ::: ## Visual Query Builder The visual query builder provides a filter-based interface for building reports without writing SQL. It generates SQL behind the scenes, so you get the power of custom queries with a guided workflow. To build a report: 1. **Select a data source** -- choose from Agents, Tasks, History, or Vulnerabilities. 2. **Add filters** -- narrow results by status, date range, operating system, or other fields relevant to the selected data source. 3. **Choose columns** -- select which columns to include in the output. Drag columns to reorder them. 4. **Sort the results** -- pick a column and direction (ascending or descending) to control result ordering. The builder updates the preview in real time as you adjust your selections. :::tip Start with the Visual Query Builder to explore your data. Switch to the SQL Editor when you need joins, aggregations, or complex filters. ::: ## SQL Editor For advanced analysis, the SQL Editor gives you a full Monaco-based editor with: - **Syntax highlighting** for SQL keywords, table names, and column references - **Autocomplete** that suggests table names, column names, and SQL functions as you type - **Error detection** that highlights syntax errors and invalid references before you run the query Write custom queries against the available tables for maximum flexibility, including joins across tables, aggregate functions, window functions, and subqueries. ## Schema Explorer The left panel displays all available tables and their columns. Click any table to expand its schema and see column names, types, and descriptions. Available tables include: | Table | Description | |-------|-------------| | **Agents** | Registered agents with hostname, OS, version, status, and health score | | **agent_tasks** | Tasks dispatched to agents with type, status, and result details | | **agent_history_events** | Historical record of all agent events and state changes | | **system_updates** | Windows and Linux updates in the catalog | | **vulnerabilities** | Known vulnerabilities with severity, CVE identifiers, and affected products | | **compliance_results** | Compliance evaluation results per agent and framework | ## Saved Reports Save frequently-used queries for quick access. Saved reports preserve: - The query (visual builder configuration or raw SQL) - Display settings (column widths, sort order) - Applied filters To save a report, click **Save Report** after running a query. Give it a descriptive name and an optional description. Saved reports appear in the **My Reports** section of the sidebar for quick access. Share saved reports with your team by toggling the **Shared** option. Shared reports are visible to all users in your organization. ## Pre-built Templates TridentStack Control includes report templates for common use cases. Select a template to load it into the editor, then customize it as needed. | Template | Description | |----------|-------------| | **Patch compliance summary** | Overview of update compliance across your fleet, broken down by OS and severity | | **Agents missing critical updates** | Lists agents that have not installed one or more critical-severity updates | | **Vulnerability exposure by severity** | Counts open vulnerabilities grouped by severity level (Critical, High, Medium, Low) | | **Compliance score by framework** | Average compliance scores per framework across all agents | | **Agent enrollment history** | Timeline of agent enrollments and de-enrollments over a selected period | | **Failed task summary** | All failed tasks with error details, grouped by task type and failure reason | ## Export Export report results for use in external tools or compliance audits. Two formats are available: - **CSV** -- compatible with spreadsheets and most data tools - **JSON** -- structured format for programmatic consumption and integration with other systems Click the **Export** button above the results table and select your preferred format. The export includes all rows matching your query, not just the currently visible page. --- # Network Exposure URL: https://docs.tridentstack.com/platform-guide/agents/network-exposure Description: See every listening port, owning process, and firewall posture per endpoint in TridentStack Control to find unauthorized services and shrink attack surface. # Network Exposure The Network Exposure tab on the agent detail page provides visibility into every listening port on the endpoint, the process behind it, and whether the firewall allows inbound connections. This helps you identify unauthorized services, assess attack surface, and verify firewall posture. ## What the Agent Collects The TridentStack Control agent performs a comprehensive port enumeration every hour (configurable, minimum 15 minutes). For each listening port, it reports: | Data Point | Description | |------------|-------------| | **Port** | Port number (1-65535) | | **Protocol** | TCP or UDP | | **Binding Address** | What the service listens on (0.0.0.0, 127.0.0.1, specific IP, or IPv6) | | **Process Name** | Name of the process holding the port | | **Process Path** | Full path to the executable | | **Process Signing** | Whether the executable is digitally signed and the signer identity (Windows and macOS) | | **Service Name** | Windows service name and display name, if the port is held by a service | | **Firewall Status** | Whether the firewall allows inbound traffic to this port. Windows reports the Windows Firewall rule name and active profile; macOS reports the Application Firewall decision for the owning app and stealth mode. | On Linux, the agent additionally enriches ports held by `docker-proxy` with the container name and image by querying the Docker Engine API. :::info Firewall state is reported on Windows (Windows Firewall) and macOS (the Application Firewall). Linux agents do not currently report firewall state (iptables/nftables); the firewall column shows as unknown for Linux endpoints. ::: ## Risk Assessment Each port receives a context-aware risk level based on its exposure characteristics, not just its port number: | Risk Level | Criteria | Examples | |------------|----------|----------| | **Critical** | Legacy dangerous protocols exposed to the network | Telnet (23), FTP (21) on LAN or internet | | **High** | Services that should not be internet-exposed | RDP (3389), SMB (445), databases exposed to the internet | | **Medium** | Services with moderate risk when exposed | SNMP (161), non-standard services on network interfaces | | **Low** | Common web services | HTTP (80), HTTPS (443) | | **Info** | Expected services on internal interfaces | Standard Windows services on localhost, internal-only ports | **Context matters.** The same port can have different risk levels depending on: - **Binding address**: A database on 127.0.0.1 is informational. The same database on 0.0.0.0 with the firewall open is high risk. - **Firewall state**: A port blocked by the firewall is lower risk than one the firewall allows. - **Process characteristics**: Signed executables from known vendors in standard paths carry lower risk than unsigned binaries in unusual locations. ## Viewing Network Exposure Navigate to any agent's detail page and select the **Network** tab. ### Summary Header At the top of the tab, a summary strip shows: - **Total listening ports** on the endpoint - **Externally exposed ports** (not bound to localhost) - **Risk breakdown** by level (critical, high, medium, low, info) - **Events in the last 24 hours** (ports opened, closed, or changed) - **Firewall status** (enabled or disabled) ### Port Table The main view displays all listening ports in a sortable, filterable table: | Column | Description | |--------|-------------| | Risk | Color-coded badge (red/orange/yellow/blue/gray) | | Port | Port number | | Protocol | TCP or UDP | | Binding | Address the service listens on | | Process | Process name holding the port | | Firewall | Whether inbound traffic is allowed | | Exposure | Calculated exposure level (localhost, LAN, internet, firewall blocked) | Click any row to expand and see: - Full process path and command line - Service name and display name (Windows) - Firewall details: rule name and profile (Windows), or the Application Firewall decision and stealth mode (macOS) - Process signing details (Windows and macOS) - Port timeline showing when it was first seen and any state changes ### Filtering - **Search**: Filter by port number, process name, process path, or service name - **Risk level**: Show only ports at a specific risk level - **Protocol**: Filter by TCP or UDP - **Exposed only**: Show only ports that are both bound to a non-localhost address and allowed by the firewall ### Port History Switch to the **History** view to see a timeline of all port state changes: - **Opened**: A new port started listening - **Closed**: A port stopped listening - **Changed**: The process or configuration behind a port changed Filter history by event type, risk level, or date range. ## On-Demand Refresh Click the **Refresh** button on the Network tab to trigger an immediate port scan from the agent. The agent collects fresh data and sends it back within seconds. The UI updates automatically when new data arrives. Refresh is rate-limited to prevent excessive collection (5 requests per minute per agent). ## Fleet-Wide Queries Two fleet-level views help you identify exposure across your entire environment: - **Fleet port search**: Find all agents with a specific port open (e.g., "show me every endpoint listening on port 3389") - **High-risk report**: View all high-risk exposed ports across all agents in one view ## macOS-Specific Behavior - **Firewall (Application Firewall)**: TridentStack Control reports whether the macOS Application Firewall is enabled, whether stealth mode is on, and, for each listening port, whether the firewall allows inbound connections to the owning app. The macOS firewall is application-based rather than port-based, so the inbound decision is resolved for the process that holds the port. - **Process signing**: each listening process is checked with macOS code signing, reporting whether it is signed, whether the signature is valid, and the signer identity. ## Linux-Specific Behavior - **Dual-stack consolidation**: When a service listens on both IPv4 (0.0.0.0) and IPv6 (::) on the same port and process, the agent consolidates them into a single row to reduce noise. - **Docker enrichment**: Ports held by `docker-proxy` are enriched with the container name and image for easy identification. - **No firewall data**: Linux agents do not currently collect iptables/nftables state. The firewall column shows as unknown for Linux endpoints. --- # Compliance URL: https://docs.tridentstack.com/platform-guide/agents/compliance Description: Review per-endpoint compliance scoring in TridentStack Control across CIS Benchmarks, DISA STIGs, Microsoft Security Baselines, and NIST controls. # Compliance The Compliance tab on the agent detail page shows how the endpoint scores against its assigned compliance frameworks. Each framework evaluates hundreds of individual controls, and this tab breaks down the results to the control level. ## Summary At the top, a summary strip shows aggregate counts: - **Passed**: Controls where the endpoint meets the requirement - **Failed**: Controls where the endpoint does not meet the requirement - **Manual Review**: Controls that require human judgment to evaluate - **Exempt**: Controls excluded from scoring - **Overall Score**: The compliance percentage (passed / total applicable controls) The score is color-coded: green at 90% and above, yellow at 70%, orange at 50%, and red below 50%. ## Framework Scores Each assigned compliance framework is listed as an expandable row showing: - **Framework name** (e.g., "CIS Windows 11 Enterprise L1") - **Compliance score** as a percentage - **Level breakdown**: Separate scores for L1 and L2 controls (for CIS frameworks) - **Trend indicator**: Whether the score is improving, stable, or declining compared to the prior evaluation Click a framework row to expand it and see all controls within that framework. ## Control Details Each control row shows: | Field | Description | |-------|-------------| | Control ID | The framework control number (e.g., "1.1.1") | | Title | The requirement description (e.g., "Ensure 'Enforce password history' is set to '24 or more password(s)'") | | Status | Passed, Failed, Manual Review, Not Applicable, or Unknown | | Level | L1, L2, or Next Gen (for CIS frameworks) | Click a control to expand and see the full evaluation: - **Evaluation method**: How the control was checked (registry value, security policy, service state, certificate, etc.) - **Expected value**: What the framework requires - **Actual value**: What was found on the endpoint - **Registry path**: The specific registry key checked (if applicable) - **Validation command**: A PowerShell command you can run manually to verify (Windows endpoints) - **Failure reason**: Why the control failed, when applicable ## Filtering - **Search**: Filter controls by ID or title text - **Level filter**: Show only L1, L2, or Next Gen controls - **Framework expansion**: Only the expanded framework's controls are loaded, keeping the view fast even with thousands of controls ## Actions - **Refresh**: Triggers a new compliance evaluation against the agent's current state. The agent collects fresh telemetry and the compliance evaluator re-scores all controls. - **Exempt controls**: Select multiple failing controls and click "Exempt Selected" to navigate to the compliance baseline page where you can create exemptions with documented reasons. - **Enforce**: For individual failing controls, click "Enforce" to open a remediation modal that can push the correct configuration to the agent. ## Framework Assignment Compliance frameworks are assigned to agents through tags, not directly. If no frameworks are assigned to any of the agent's tags, the Compliance tab shows an empty state explaining how to assign frameworks. To assign a framework: 1. Navigate to the fleet-wide [Compliance](/platform-guide/compliance) page 2. Select a baseline and assign it to a tag 3. All agents with that tag will be evaluated on the next compliance cycle ## Evaluation Schedule Compliance evaluations run automatically every 24 hours and can be triggered on-demand using the Refresh button. After system updates or configuration changes, a new evaluation runs automatically to reflect the updated state. --- # Effective Policy URL: https://docs.tridentstack.com/platform-guide/agents/effective-policy Description: The Effective Policy (RSoP) view in TridentStack Control resolves every policy setting applied to an agent and flags collisions between policy sources. # Effective Policy The Effective Policy view shows the resolved set of all policy settings applied to an agent, including collision detection across multiple policy sources. This is the Resultant Set of Policy (RSoP) for each endpoint. ## Conformance vs. Compliance The Effective Policy tab uses the term **conformance** (Conformant / Non-Conformant) rather than "compliance." This is intentional. In TridentStack Control, "compliance" refers specifically to security compliance frameworks (CIS Benchmarks, DISA STIGs, NIST controls) managed under the Compliance tab. Effective Policy conformance is a different concept: it measures whether the actual value of a policy setting on the endpoint matches the desired value configured by the winning policy source. Using distinct terminology avoids confusion between these two features. ## Why This Matters In real environments, policy settings can come from multiple sources simultaneously: - **TridentStack Control platform policies** you configure in the Configuration Policies page - **Active Directory Group Policy Objects (GPOs)** from your domain controllers - **Intune MDM policies** from Microsoft Endpoint Manager - **Local registry settings** applied manually or by scripts When the same setting is defined by more than one source, conflicts arise. The Effective Policy view shows you exactly which source wins for each setting and highlights any conflicts that were resolved. ## Viewing Effective Policy Navigate to any Windows agent's detail page and select the **Effective Policy** tab. :::info The Effective Policy tab is only available for Windows agents. Linux agents do not have the same multi-source policy model. ::: ### Summary Strip At the top, a summary shows: - **Settings per source**: Count of settings from each source (Platform, Domain GPO, Intune MDM, Local) - **Conformance rate**: Percentage of settings where the actual value matches the desired value - **Conflicts**: Total number of settings where multiple sources compete (highlighted in amber when greater than zero) - **Domain context**: The domain name if the agent is domain-joined ### Settings Table Each row in the table represents a single policy setting: | Column | Description | |--------|-------------| | Setting Name | Human-readable name (e.g., "Configure Automatic Updates") | | Type | Setting type: Registry, Security, Drive Mapping, or Service | | Policy | Which policy object defined this setting | | Desired Value | The configured value | | Actual Value | What the agent currently reports | | Conformance | Whether desired matches actual (Conformant / Non-Conformant / Unknown) | | Source | Which source provided the winning value (Platform, Domain GPO, Intune, Local) | ### Conflict Details Click any row to expand it and see three sections: 1. **Setting Details**: Registry key path, category, and state 2. **Conformance Check**: Side-by-side comparison of desired vs. actual values 3. **Policy Precedence**: Shows which sources competed for this setting and which one won When a setting has a conflict, the expanded view displays the full precedence chain. For example: ``` Policy Precedence [Winner] Server Hardening Policy (Platform) [Overridden] Default Domain Policy (Domain GPO) ``` ## How Conflicts Are Resolved ### Source Priority When the same setting is defined by multiple sources, the highest-priority source wins: | Priority | Source | Description | |----------|--------|-------------| | 4 (highest) | **Platform** | TridentStack Control configuration policies | | 3 | **Intune MDM** | Microsoft Endpoint Manager policies | | 2 | **Domain GPO** | Active Directory Group Policy | | 1 (lowest) | **Local** | Manual registry settings not claimed by any other source | TridentStack Control platform policies take precedence over all other sources. This ensures your TridentStack Control-managed settings are always enforced, even when GPOs or MDM policies target the same setting. ### Within-Platform Conflicts When an agent has multiple TridentStack Control platform policies targeting the same registry key (e.g., two policies both configure "Minimum password length"), the system resolves the conflict automatically and deterministically, and shows which policy won on the setting's detail. There is no per-policy priority for you to set; the resolution is handled for you. ### Detection, Not Manual Resolution Conflict resolution is automatic. You cannot manually pick a winner for individual settings. To change which policy wins: - Remove the conflicting setting from one of the competing policies - Reassign tags so the agent only receives one of the conflicting policies ## Filtering and Search - **Source filter**: Toggle buttons to show/hide settings from specific sources (Platform, Domain GPO, Intune, Local) - **Type filter**: Filter by setting type (Registry, Security, Drive Mapping, Service) - **Search**: Find settings by name or registry key path - **Sort**: By setting name, type, policy name, conformance status, or source ## Data Sources The Effective Policy tab combines data from multiple agent telemetry channels: | Source | How Data Is Collected | |--------|----------------------| | Platform policies | Agent receives desired state from TridentStack Control server during check-in | | Domain GPO | Agent runs `gpresult /xml` and sends the parsed output | | Intune MDM | Agent reads Configuration Service Provider (CSP) registry entries | | Local | Registry values detected that are not claimed by any of the above sources | | Actual values | Agent reports current registry values for comparison | The RSoP document is cached and refreshed when policy changes are detected. It uses ETag-based caching so the agent only re-downloads when something has changed. --- # History URL: https://docs.tridentstack.com/platform-guide/agents/history Description: Every operation TridentStack Control performs on an endpoint - install, refresh, scan, evaluate - appears on the agent History tab as a chronological log. # History The History tab on the agent detail page provides a chronological log of every operation performed on the endpoint. This includes update installations, telemetry refreshes, compliance evaluations, vulnerability scans, and all other agent activities. ## Event Timeline Events are displayed in reverse chronological order (newest first). Each event shows: | Field | Description | |-------|-------------| | Timestamp | When the event occurred | | Type | Event category icon and label | | Status | Current state of the event | | Summary | Brief description of what happened | | Duration | How long the operation took | | Reference ID | Hex-encoded identifier (e.g., EVT-04D2) | ### Event Types | Type | Icon | Description | |------|------|-------------| | **Task** | Play | Update installations, app installs, driver updates, log collections | | **Telemetry Refresh** | Refresh | System state, software inventory, or applicability data collection | | **Security Evaluation** | Shield | Vulnerability scan results | | **Compliance Evaluation** | Check | Compliance framework evaluation results | | **Compliance Check** | Clipboard | Individual compliance control checks | | **System Rollback** | Rotate | OS build version regression detected; applicability data invalidated and refreshed | ### Status Values | Status | Color | Meaning | |--------|-------|---------| | **Pending** | Gray | Operation queued, waiting to start | | **In Progress** | Blue | Currently executing (duration counter ticks in real time) | | **Success** | Green | Completed successfully | | **Partial** | Yellow | Completed with some items succeeding and others failing | | **Failed** | Red | Operation failed | | **Timeout** | Orange | Operation exceeded the allowed time | | **Disconnected** | Gray | Agent went offline during the operation | ## Expanded Event Details Click any event to expand it and see the full details. The content varies by event type: ### Task Events (Update Installation) Shows which updates were installed, with per-update results: - KB number and update title - Individual status (installed, failed, skipped) - Severity level - Duration per update - Error details for failures ### Task Events (App Installation) Shows which applications were installed or updated: - Application name and version - Installation status - Duration ### Telemetry Refresh Events Shows what data was collected, broken down by category: - System, Software, System Applicability, App Applicability, Network, Policy - Item counts per category ### Compliance Evaluation Events Shows framework-level results: - Passed, failed, and manual review counts per framework - Overall compliance score ### Vulnerability Scan Events Shows detection results: - New vulnerabilities found - Vulnerabilities resolved - Detection methodology ### System Rollback Events Displayed when the platform detects that an endpoint's OS build version has decreased (for example, a Windows feature update was rolled back). The expanded view shows: - Previous build number and version - Current build number and version - Count of invalidated items per data category (applicable updates, applicable applications, vulnerabilities) Rollback events are fully automatic. When a rollback is detected, the platform invalidates stale applicability and vulnerability data and triggers a fresh scan. A yellow "System Rollback Detected" banner appears on the agent's System State tab until the refresh completes. No user action is required. ## Reference IDs Every event displays a hex-encoded reference ID in the format **EVT-XXXX** (for events) or **TSK-XXXX** (for tasks). These IDs are useful for troubleshooting with TridentStack support, as they uniquely identify the event across the entire platform. ## Parent and Child Events Some operations create a parent event with child events. For example, a system update installation task (parent) may contain individual update installation events (children) for each KB that was installed. Expanding the parent event reveals the child events nested underneath. --- # Settings Overview URL: https://docs.tridentstack.com/administration/settings-overview Description: A map of every tab on the Settings page in TridentStack Control: authentication, notifications, integrations, licensing, audit, and platform behavior. # Settings Overview The Settings page contains all platform configuration options. Access it from the sidebar footer by clicking the gear icon. Settings are organized into tabs, each covering a specific area of platform behavior. :::info Settings changes take effect on the next agent check-in. There is no need to restart agents after changing platform settings. ::: ## Settings Tabs | Tab | Description | |-----|-------------| | **Timezone** | Set the default timezone for scheduling maintenance windows and displaying timestamps. All scheduled operations and log entries use this timezone for display | | **Client** | Control client-side behavior: manual update permissions, Windows update management, IT support information, tray icon visibility, reboot prompts, and policy visibility | | **Agent Installers** | Download agent installers for Windows, macOS, and Linux. Generate enrollment tokens for new agent deployments | | **Agent Updates** | Configure automatic agent updates: enable or disable auto-update, set the update schedule, and select the update channel | | **Agent Lifecycle** | Define agent retention policies: how long to keep offline agents before automatic cleanup | | **Health Scoring** | Configure how agent health scores are calculated: weights for update compliance, vulnerability count, and system health metrics | | **Diagnostic Logs** | Trigger log collection from agents and download collected log archives for troubleshooting | | **API Keys** | Generate and manage API keys for programmatic access to the TridentStack Control API. See [API Keys](api-keys) for details | | **Notifications** | Configure notification channels (Email, Slack, Teams, Discord, Webhooks) and control which platform events trigger alerts. See [Notifications](notifications) for details | | **Licensing** | View license assignments and assign or unassign licenses across your free and paid endpoints. See [Licensing](licensing) for details | | **Privacy** | Control whether TridentStack Control support staff can view your environment, create time-limited access grants, and review every staff access in the Vendor Access Log. See [Support Access](support-access) for details | | **Users** | Manage platform users: invite new users, assign roles, and remove access. Admin only | | **Roles** | Define custom roles with granular permissions for different platform modules. Admin only | | **Authentication** | Configure OAuth providers, SAML single sign-on, SCIM provisioning, and Force-SSO for your organization. See [Single sign-on (SAML)](single-sign-on) and [SCIM provisioning](scim-provisioning). Admin only | | **Integrations** | Connect Microsoft Entra to mirror device-group membership onto tags automatically. See [Microsoft Entra Group Sync](entra-group-sync). Admin only | ## Timezone The timezone setting controls how timestamps are displayed throughout the platform and when scheduled operations execute. This includes: - Maintenance window start and end times - Dashboard timestamps and charts - Report date filters and exported timestamps - Audit log entry times Select your organization's primary timezone from the dropdown. Individual users see all times converted to this timezone. ## Client The Client tab controls the behavior of the TridentStack Control agent on endpoints: - **Manual update installation** - Control whether a person at an endpoint can start installing pending updates themselves from the TridentStack Control client app on that endpoint, with separate choices for system updates and application updates. Options: always allowed, only during deployment windows, or never allowed. This setting only affects what a user can do in the client app; it does not change what your policies and deployment rings install automatically, and it does not affect the endpoint's built-in Windows Update (that is Windows update management, below). - **IT support information** - Display your organization's support contact details in the client application. Fields include company name, support team name, email, phone, URL, and a custom message. - **Policy visibility** - Control whether policy names are visible to users, and whether the manual "Refresh Now" button is available in the client. - **Windows update management** - Choose how the built-in Windows Update is controlled on your Windows endpoints, at the operating system level. This decides whether Windows itself may download, install, and restart for updates on its own, alongside the updates TridentStack Control deploys. Because a change reconfigures Windows Update on every Windows endpoint in your organization, saving a change to this setting asks for confirmation and spells out exactly what will happen before it is applied. - **Exclusive (recommended)** - TridentStack Control is the single source of Windows updates. The endpoint's built-in Windows Update is turned off, so Windows will not download, install, or restart for quality (monthly), feature (version), or other updates on its own. Every Windows update is delivered through TridentStack Control's approval and deployment ring process, so nothing installs or restarts outside the schedule and controls you set. This is the right choice for almost all fleets. - **Hybrid** - TridentStack Control stops taking over Windows Update, and the endpoint's built-in Windows Update returns to its normal behavior. Windows can then download and install updates on its own, on Microsoft's schedule, in addition to the updates TridentStack Control deploys. Choose this only if you specifically want native Windows Update to keep running. Important trade-offs in Hybrid: Windows may install the same update TridentStack Control is already deploying, and it may restart the device on its own schedule, outside your deployment ring maintenance windows and reboot controls. Switching back to Exclusive at any time re-establishes full TridentStack Control management. Note that Hybrid removes only what TridentStack Control itself configured: each Windows Update setting is returned to the value it had before TridentStack Control took over. Update restrictions from any other source (Active Directory or local Group Policy, Microsoft Intune or another MDM, another management tool, or manual configuration) stay in place. If an endpoint still shows "Some settings are managed by your organization" in **Settings > Windows Update** after switching to Hybrid, the remaining restriction comes from one of those sources, not from TridentStack Control. See [What Hybrid mode removes](/reference/agent-reference#what-hybrid-mode-removes) for details. - **Hide tray icon** - Hide the client tray icon on endpoints. The agent keeps running and managing the device in the background; only the icon (and the window users can open from it) is hidden. Applies to Windows and macOS. - **Show reboot prompts** - Control whether endpoints show a restart prompt before a managed restart. When turned off, Windows endpoints still restart automatically after updates but show no prompt and no chance to postpone (the restart still happens; this only hides the prompt). To prevent automatic restarts entirely, use the deployment ring reboot controls or set the endpoint's reboot policy. :::info When these changes take effect Client settings are pushed to connected endpoints within seconds of saving; there is no need to restart the agent. Endpoints that are offline receive the new settings the next time they reconnect. Most settings apply right away: hiding or showing the tray icon, and switching Windows update management between Exclusive and Hybrid, both take effect immediately on connected endpoints. **Show reboot prompts** is the exception - it changes what happens at the next managed restart, so there is no visible change on the endpoint until a restart occurs. Note that hiding the tray icon removes the icon, which can be easy to miss; on Windows the icon may briefly linger in the notification area until it is refreshed. ::: ## Agent Installers Download agent installers and copy ready-to-use install commands: - **Windows** -- MSI installer with PowerShell quick install command - **macOS** -- Universal `.pkg` installer with a one-line install command (macOS 14 Sonoma and later) - **Linux** -- Shell installer script (supports Ubuntu, Debian, and RHEL-family distributions) Install commands include your enrollment token, which automatically registers the agent with your platform instance. Regenerate the token if it is compromised. Existing enrolled agents are not affected by token regeneration. ## Agent Updates Control how agents update themselves: - **Auto-update** -- when enabled, agents automatically download and install new versions on their next check-in - **Update schedule** -- restrict auto-updates to specific maintenance windows - **Update channel** -- choose between stable (recommended) and preview channels - **Pilot group** -- choose a small set of endpoints to receive a new agent version first, before the rest of your fleet. Add individual devices, one or more tags (every endpoint carrying a selected tag becomes a pilot), or a combination of both. Pilots are evaluated per operating system: a new Windows agent version is validated on your Windows pilots, a Linux version on your Linux pilots, and so on, so a pilot on one operating system never holds back an update for another. Each platform's broader rollout waits until that platform's pilots update successfully, or until a timeout you set elapses. If an operating system has endpoints but no pilots of its own, its updates roll out governed by your update delay only. The Agent Updates page shows a per-operating-system breakdown of your pilot coverage so you can see this at a glance. ## Agent Lifecycle Define retention policies for agents that go offline: - **Retention period** -- how long an agent can remain offline before it is automatically marked for cleanup - **Cleanup behavior** -- whether offline agents are archived (preserving history) or fully removed ## Health Scoring Configure the weights used to calculate each agent's health score. The health score is a composite metric reflecting the overall state of a managed endpoint. Adjustable weights include: - **Update compliance** -- how heavily missing updates affect the score - **Vulnerability count** -- impact of open vulnerabilities on the score - **System health metrics** -- weight of hardware and OS health indicators ## Diagnostic Logs Trigger on-demand log collection from any online agent. Collected logs are packaged into a compressed archive and made available for download. Useful for troubleshooting agent connectivity issues, failed updates, or unexpected behavior. ## Users, Roles, and Authentication These tabs are restricted to administrators. - **User Management** controls who can sign in and what they can do. See [User Management](user-management). - **Authentication -> SAML Single Sign-On** lets your team sign in with their corporate credentials. See [Single sign-on (SAML)](single-sign-on). - **Authentication -> SCIM Provisioning** keeps the user list in sync with your identity provider automatically. See [SCIM provisioning](scim-provisioning). - **Authentication -> Force-SSO and Break-Glass Admins** lets you require SAML for everyone, with named admins as the safety net for misconfigured SSO. See the [Force-SSO section](single-sign-on#step-6-optional-require-sso) of the SSO guide. ## Privacy The Privacy tab controls whether TridentStack Control support staff can view your environment's data, lets you grant time-limited access for a specific support case, and shows the Vendor Access Log of every staff access. See [Support Access](support-access) for the full guide. --- # Support Access URL: https://docs.tridentstack.com/administration/support-access Description: Control whether TridentStack Control support staff can view your environment, grant time-limited access for a specific case, and review every staff access in your Vendor Access Log. # Support Access Support Access controls whether TridentStack Control support staff can view your environment's data when you need help. You manage it under **Settings > Privacy**. When you contact support about an issue, staff sometimes need to see your endpoints, policies, updates, or vulnerability data to understand and resolve the problem. Support Access lets you decide, on your terms, whether that is allowed by default or only for a specific, time-boxed request. Every access is recorded, so you always have a complete record of when your data was viewed. ## The Support Access setting The Support Access toggle has two states: - **Enabled (default).** TridentStack Control support staff can view your environment's data to provide support and troubleshoot issues. - **Disabled.** Support staff cannot view your data. To get help that requires looking at your environment, you grant a temporary, time-limited window of access for that specific case (see below). :::info Support Access governs only staff viewing your data for support purposes. It does not affect your own users' access, your agents, or any automated platform behavior. ::: ## Temporary access grants When Support Access is disabled, you can still get hands-on help for a specific issue by creating a temporary access grant. A grant opens a fixed window during which support staff can view your data, then closes automatically. To create a grant, go to **Settings > Privacy** and choose a duration: | Duration | Typical use | |----------|-------------| | **4 hours** | A live troubleshooting session | | **24 hours** | A single business day of investigation | | **48 hours** | An issue that spans a couple of days | | **7 days** | A longer, in-depth investigation | You can add a short reason for your own records. Only one grant can be active at a time. A grant expires on its own when the window ends, and you can revoke an active grant early at any time from the same page. ## Vendor Access Log The Vendor Access Log gives you a complete, timestamped record of every time TridentStack Control support staff viewed your environment. Find it under **Settings > Privacy**. Each entry records: | Field | Description | |-------|-------------| | **Date and time** | When the access occurred, in your configured timezone | | **Staff member** | The support staff member who viewed your data | | **Area accessed** | The part of your environment that was viewed | | **Access type** | Whether the access came from your standing Support Access setting or a temporary grant | Filter the log by date range to review a specific period. Entries are retained for one year. :::tip If you operate under a compliance program that requires you to track third-party access to your data, the Vendor Access Log is your authoritative record. Pair it with the [System Audit](system-audit) log for a full picture of activity in your environment. ::: --- # User Management URL: https://docs.tridentstack.com/administration/user-management Description: Invite users, assign roles, and manage OAuth/SSO access in TridentStack Control's role-based access control system. # User Management TridentStack Control supports role-based access control (RBAC) with OAuth/SSO authentication. Manage who has access to your platform and what they can do. ## Authentication TridentStack Control authenticates users via OAuth 2.0. Supported providers: - **Microsoft** (Entra ID / Azure AD) - **Google Workspace** Configure your provider in **Settings > Authentication**. Tenant administrators can restrict which providers are allowed for their organization. ```mermaid sequenceDiagram participant User participant TridentStack Control participant OAuth Provider User->>TridentStack Control: Click "Sign In" TridentStack Control->>OAuth Provider: Redirect to authorization OAuth Provider->>User: Prompt for credentials User->>OAuth Provider: Authenticate OAuth Provider->>TridentStack: Return authorization code TridentStack Control->>OAuth Provider: Exchange code for token OAuth Provider->>TridentStack: Return user profile TridentStack Control->>TridentStack: Resolve tenant from email domain TridentStack Control->>User: Session created, redirect to dashboard ``` ### How User Accounts Are Created TridentStack Control uses a self-registration model through OAuth. There is no manual user invitation flow. When a new user signs in for the first time: 1. The user clicks **Sign In** and authenticates through your configured OAuth provider. 2. TridentStack Control verifies the user's email address with the provider. 3. A tenant is resolved from the user's email domain. Corporate domains create shared multi-user tenants, so all employees with the same domain are grouped together. 4. A new user account is created in **Pending Access** status. 5. An administrator must approve the user and assign roles before they can use the platform. The first user to sign in from a new corporate domain is automatically granted Admin access. All subsequent users from that domain are placed in **Pending Access** until an existing Admin approves them. ### Approving Pending Users 1. Navigate to **Settings > Users**. 2. Filter by **Pending Access** to see users waiting for approval. 3. Click on a pending user. 4. Select the roles to assign. 5. Click **Approve**. Once approved, the user can sign in and access the platform according to their assigned roles. ## Roles and Permissions Roles define what a user can do across the platform. Each role grants a specific set of permissions organized by module. ### Built-in Roles TridentStack Control includes three system roles that cannot be deleted or modified: #### Admin Full access to all platform features, including: - All agent and policy management operations - User management (approve users, assign roles, deactivate) - Platform settings and configuration - API key management - Authentication provider configuration - Role management #### Policy Manager Can manage policies and updates alongside standard operations: - All Standard User permissions - Create and edit configuration policies - Assign policies to agent groups - Approve and deploy updates - Cannot modify platform settings, manage users, or configure authentication #### Standard User Read-only access to core platform modules: - View agents, policies, vulnerabilities, compliance results, and reports - View audit logs - Cannot create, edit, or delete resources - Cannot execute tasks or trigger actions ### Permission Categories Permissions are organized into 7 categories with granular controls: | Category | Permissions | Description | |----------|-------------|-------------| | **Agents** | View, Edit, Delete, Command | Manage agents and send commands (restart, scan, collect logs) | | **Policies** | View, Edit, Delete, Assign | Create and assign configuration policies | | **Updates** | View, Approve, Deploy | Manage the update approval and deployment workflow | | **Applications** | View, Edit | Manage application update configurations | | **Settings** | View, Edit | View and modify platform settings | | **Administration** | Users View/Edit, Roles View/Edit | Manage users and role definitions | | **Compliance & Reports** | Compliance View, Reports View, Reports Export | Access compliance data and export reports | ## Custom Roles Create custom roles in **Settings > Roles** to match your organization's access requirements. For example, you might create: - **Security Analyst**: view access to everything, plus edit access to vulnerability exceptions and compliance configurations - **Help Desk**: view agents and trigger log collection, but no access to policies or settings - **Compliance Officer**: view access to compliance results and reports, plus the ability to export data To create a custom role: 1. Navigate to **Settings > Roles**. 2. Click **Create Role**. 3. Enter a role name and description. 4. Toggle permissions for each module. 5. Click **Save**. Assign custom roles to users through **Settings > Users**. :::warning Always maintain at least two Admin users. If the sole Admin account is locked out, recovery requires direct database access. ::: ## User Lifecycle Users move through the following states: ```mermaid stateDiagram-v2 [*] --> PendingAccess: First OAuth sign-in PendingAccess --> Active: Admin approves and assigns roles Active --> Deactivated: Admin deactivates Deactivated --> Active: Admin reactivates ``` | State | Description | |-------|-------------| | **Pending Access** | User signed in via OAuth but has not been approved. Cannot access platform features. | | **Active** | User has been approved with assigned roles. Full access per role permissions. | | **Deactivated** | Access revoked. Cannot sign in. Roles are preserved for potential reactivation. | ### Deactivating Users To revoke a user's access: 1. Navigate to **Settings > Users**. 2. Find the user and click **Deactivate**. 3. Confirm the action. Deactivated users cannot sign in to the platform. Their activity history is preserved in audit logs for compliance and review purposes. Deactivation is reversible: reactivate the user at any time to restore their access with the same roles. --- # API Keys URL: https://docs.tridentstack.com/administration/api-keys Description: Create and manage API keys to integrate TridentStack Control with external tools, scripts, and automation workflows over the platform API. # API Keys API keys provide programmatic access to the TridentStack Control API. Use API keys to integrate TridentStack Control with external tools, scripts, and automation workflows. ## Generating a Key 1. Navigate to **Settings > API Keys**. 2. Click **Generate Key**. 3. Enter a descriptive name for the key (e.g., "CI/CD Pipeline", "Monitoring Integration", "SIEM Export"). 4. Click **Create**. The full API key is displayed once at creation. Copy it immediately and store it in a secure location. :::warning Treat API keys like passwords. Do not commit them to version control or share them in plaintext. Use environment variables or a secrets manager. ::: ## Key Format API keys use the format `keyId.secretKey`: ``` abc123def456.dc16834b217de9a4f3b2c1e8... ``` The `keyId` portion identifies the key in audit logs and the API Keys settings page. The `secretKey` portion is the secret used for authentication. ## Using the Key Include the API key in the `X-API-Key` header of your HTTP requests: ```bash curl -H "X-API-Key: your-api-key-here" \ https://control.tridentstack.com/api/agents ``` All API responses are JSON. Successful requests return a `2xx` status code. Error responses include a message describing the issue. ## Available Endpoints For the complete API reference with all endpoints, request/response schemas, and interactive examples, see the [API Reference](/api/). Here are a few commonly used endpoints to get started: | Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/api/agents` | List all agents with pagination | | `GET` | `/api/agents/:id` | Get detailed information for a specific agent | | `POST` | `/api/agents/:id/collect-logs` | Trigger log collection from an agent | ## Revoking Keys To revoke an API key: 1. Navigate to **Settings > API Keys**. 2. Find the key by name and click **Revoke**. 3. Confirm the action. Revocation is immediate. Any request using the revoked key will receive a `401 Unauthorized` response. Revoked keys cannot be restored. If access is needed again, generate a new key. :::tip Create separate API keys for each integration. This makes it easy to revoke access for a single integration without affecting others. ::: ## Best Practices - **Name keys descriptively.** Use names that identify the integration or automation using the key (e.g., "Splunk SIEM Export" rather than "Key 1"). - **Rotate keys periodically.** Generate a new key, update the integration, then revoke the old key. - **Use environment variables.** Store keys in environment variables or a secrets manager rather than hardcoding them in scripts. - **Audit key usage.** Review the System Audit log to monitor which keys are being used and how frequently. - **Limit key count.** Only maintain active keys for integrations currently in use. Revoke keys for decommissioned integrations. --- # Single sign-on (SAML) URL: https://docs.tridentstack.com/administration/single-sign-on Description: Configure SAML 2.0 single sign-on for TridentStack Control with Okta, Entra ID, Google Workspace, JumpCloud, or any SAML IdP. # Single sign-on (SAML) Configure SAML 2.0 single sign-on so your team signs into TridentStack Control with their corporate credentials. Access is managed in your identity provider, your security team enforces policies like multifactor authentication centrally, and offboarding a user in your IdP locks them out of TridentStack Control immediately. ## Before you begin You will need: - A TridentStack Control admin account. - An identity provider that supports SAML 2.0 (Okta, Microsoft Entra ID, Google Workspace, JumpCloud, OneLogin, ADFS, or any other compliant IdP). - Permission in your IdP to register a new SAML application. ## Setup overview The end-to-end flow is: 1. Copy the service-provider details from TridentStack Control. 2. Create a SAML application in your IdP using those details. 3. Copy the IdP details (entity ID, sign-on URL, X.509 certificate) back into TridentStack Control. 4. Map your IdP's groups to TridentStack Control roles. 5. Click **Test SSO** in TridentStack Control to verify everything is wired correctly. 6. Optional: turn on **Require SSO** after configuring at least one break-glass admin. ## Step 1: Get the service-provider details In TridentStack Control, go to **Settings -> Authentication -> SAML Single Sign-On**. The "Service Provider Metadata" panel shows three values: - **Entity ID** identifies TridentStack Control to your IdP. - **ACS URL** is where your IdP sends the sign-in response. - **Metadata URL** is a URL your IdP can fetch to import all of the above at once. Copy these or download the metadata XML if your IdP supports importing it directly. ## Step 2: Create the SAML application in your IdP Pick the section that matches your provider. ### Okta 1. Sign in to your Okta admin console. 2. **Applications -> Applications -> Create App Integration**. Choose **SAML 2.0**. 3. Name the app "TridentStack Control" and continue. 4. Paste the TridentStack Control **Entity ID** into Okta's **Audience URI (SP Entity ID)**. 5. Paste the TridentStack Control **ACS URL** into Okta's **Single sign-on URL**. 6. Set **Name ID format** to **EmailAddress**. 7. Add an attribute statement named `groups` with filter "Matches regex" and value `.*` (or whatever pattern matches the groups you want to send). 8. Save. On the **Sign On** tab, copy the **Identity Provider Single Sign-On URL**, **Identity Provider Issuer**, and **X.509 Certificate**. You will paste these into TridentStack Control next. ### Microsoft Entra ID (Azure AD) 1. **Azure portal -> Microsoft Entra ID -> Enterprise applications -> New application -> Create your own application**. 2. Name "TridentStack Control", then **Single sign-on -> SAML**. 3. Paste the TridentStack Control **Entity ID** into **Identifier**. 4. Paste the TridentStack Control **ACS URL** into **Reply URL**. 5. Under **User Attributes & Claims**, add a group claim with **Source attribute = Group ID** (or **Cloud-only group display names** if you'd rather match by name). 6. Download the **Federation Metadata XML** from the SAML Signing Certificate panel. ### Google Workspace 1. **Google Admin -> Apps -> Web and mobile apps -> Add app -> Add custom SAML app**. 2. Name "TridentStack Control". On the next screen, download the IdP metadata. 3. On the Service Provider Details screen, paste the TridentStack Control **ACS URL** and **Entity ID**. 4. Under Attribute mapping, map a group attribute (Google calls it a "Group membership" attribute) to `groups`. ### JumpCloud 1. **JumpCloud admin -> SSO -> Add Application -> Custom SAML App**. 2. Paste the TridentStack Control values into **SP Entity ID**, **ACS URL**, and **Login URL**. 3. Under **User Attribute Mapping**, add `groups` mapped to the user's group memberships. ### Other providers (generic SAML 2.0) Most providers expose the same five fields. Use the TridentStack Control SP details for the SP-side; provide your IdP's entity ID, sign-on URL, and X.509 certificate to TridentStack Control. The `groups` attribute must be present in the assertion for role mapping (Step 4) to work. ## Step 3: Configure TridentStack Control with the IdP details Back in **Settings -> Authentication -> SAML Single Sign-On**: - **IdP Entity ID** is your IdP's issuer URL. - **IdP Sign-On URL** is where TridentStack Control sends users to sign in. - **IdP X.509 Certificate** is the PEM-formatted certificate from your IdP. - **Groups attribute name** is `groups` for most providers; AD FS uses `http://schemas.xmlsoap.org/claims/Group`, some Microsoft setups use `memberOf`. If your IdP gave you metadata XML, use the **Paste IdP metadata XML** button to autofill all of the above at once. Click **Save**. The status shows **Pending** until you complete a successful test. ## Step 4: Map IdP groups to TridentStack Control roles In **Settings -> Authentication -> Group to Role Mappings**, click **Add mapping** and enter: - **IdP Group Name** is the exact group name your IdP sends in the assertion (case-sensitive). - **TridentStack Control Role** is the role users in that group should receive. For example, members of `acme-it-admins` get the `Admin` role, and members of `acme-helpdesk` get the `Policy Manager` role. Users not in any mapped group get the tenant's default role on first login. ## Step 5: Test SSO Click **Test SSO**. A new tab opens at your IdP. Sign in. You will be returned to a success page in TridentStack Control listing the NameID, email, and groups received. If the test fails, the error tells you what's wrong: - **Signature did not verify**: the X.509 certificate in TridentStack Control does not match the certificate your IdP is signing with. Re-copy the certificate. - **Audience mismatch**: your IdP is sending an Audience that does not match TridentStack Control's Entity ID. Check Step 1 was copied verbatim into your IdP. - **No groups attribute**: the assertion did not include the attribute name configured in Step 3. Check your IdP's attribute statements. After a successful test, the SAML status changes from **Pending** to **Active**. ## Step 6 (optional): Require SSO By default, users on tenants with SAML configured can choose between SSO and the OAuth (Microsoft / Google) providers. To require SSO, you must first add at least one break-glass admin. ### Why break-glass admins exist If your IdP certificate expires or is misconfigured, no one can sign in. A break-glass admin is a TridentStack Control user whose Microsoft or Google sign-in keeps working even when Require SSO is on. They are the safety net you use to fix the SSO config. Pick at least one trusted admin (typically yourself plus one other person). They must have already signed in with Microsoft or Google at least once so TridentStack Control has a valid OAuth identity to honor. ### Enabling Require SSO 1. **Settings -> Authentication -> Force-SSO and Break-Glass Admins -> Add break-glass admin**, pick one or two trusted admins. 2. Toggle **Require single sign-on (Force SSO)** on. Once enabled: - All non-break-glass users on this tenant must sign in via SAML. - Existing browser sessions for non-break-glass users are invalidated immediately. They will be redirected to your company sign-in on their next request. - Break-glass admins can still use Microsoft or Google. You cannot remove the last break-glass admin while Require SSO is on. To turn Require SSO off, toggle it off first. ## Troubleshooting **Login redirects in a loop**: the email you are signing in with is not in the tenant the SAML config belongs to. Check that the IdP is sending the email under the right domain. **"SSO is required" error message**: you tried to use Microsoft or Google on a tenant where Require SSO is on, and you are not a break-glass admin. Use SSO instead, or ask an admin to grant you break-glass access. **Test SSO worked but real logins fail**: confirm the SAML status is **Active** (not still **Pending**). The Test SSO button promotes Pending to Active automatically on first success; a fresh config that has not been tested will not accept real logins. **Certificate expiry warning email**: your IdP certificate is within 30 days of expiring. Rotate it in your IdP, then update the certificate in TridentStack Control. Until you do, only break-glass admins will be able to sign in once it expires. For anything not covered here, contact TridentStack support at [tridentstack.com/dashboard/support](https://tridentstack.com/dashboard/support). --- # System Audit URL: https://docs.tridentstack.com/administration/system-audit Description: Read the System Audit log to see who did what and when in TridentStack Control, for security reviews, change management, and compliance evidence. # System Audit The System Audit page records all significant actions performed in the platform. Use audit logs to track who did what and when, for both security review and compliance requirements. :::info Audit logs are immutable. They cannot be edited or deleted by any user, including administrators. ::: ## What Gets Logged The audit system captures three categories of events: ### User Actions Actions performed by authenticated users through the UI or API: - Login and logout events - Policy creation, modification, and deletion - Tag creation, assignment, and removal - Settings modifications (timezone, client configuration, health scoring weights) - Report creation and export - Manual task execution (update installs, log collection, scans) ### System Events Automated actions performed by the platform: - Agent enrollment and de-enrollment - Automated rule execution (e.g., auto-tagging rules, scheduled policies) - Scheduled task results (update installations, telemetry collection) - Agent health score changes - Vulnerability scan completions ### Administrative Changes High-privilege actions that affect platform access and configuration: - User invitations and role assignments - Role creation and permission modifications - User deactivation and reactivation - API key generation and revocation - Authentication provider configuration changes ### Support Access When TridentStack Control support staff view your environment to help with an issue, an entry is recorded in your audit log. The same access is also recorded in your Vendor Access Log, where you can review and filter all support access in one place. See [Support Access](support-access) to control whether this is allowed and to manage time-limited access grants. ```mermaid flowchart LR A[User Actions] --> D[Audit Log] B[System Events] --> D C[Admin Changes] --> D D --> E[Search and Filter] D --> F[Export] ``` ## Viewing Audit Logs Navigate to **System Audit** from the sidebar. The audit log displays entries in reverse chronological order. Each entry includes: | Field | Description | |-------|-------------| | **Timestamp** | When the action occurred, displayed in your configured timezone | | **User** | The user who performed the action, or "System" for automated actions | | **Action Type** | The category of action (create, update, delete, login, system) | | **Resource** | The type and identifier of the affected resource | | **Details** | A summary of what changed, including before and after values where applicable | Click any entry to expand it and view the full details of the action, including the complete set of changed fields and their previous values. ## Searching and Filtering Use the search bar and filter controls to find specific events: | Filter | Options | |--------|---------| | **Date range** | Select a start and end date to narrow results to a specific time window | | **User** | Filter by the user who performed the action, or select "System" for automated events | | **Action type** | Create, Update, Delete, Login, System | | **Resource type** | Policy, Agent, Tag, User, Setting, API Key, Role | Combine multiple filters to narrow results precisely. For example, filter by "Delete" action type and "Policy" resource type to see all policy deletions within a date range. ## Audit Log Retention Audit logs are retained according to your platform's data retention settings. The default retention period covers the full duration of your subscription. :::tip Review audit logs after making bulk changes to verify that all actions completed as expected. ::: For compliance purposes, export logs regularly if your retention policy is shorter than your audit requirements. Exported logs include all fields and can serve as an offline compliance record. ## Export Export audit log data for use in external security tools or compliance documentation: 1. Apply the desired filters to narrow the result set. 2. Click **Export**. 3. Select CSV or JSON format. 4. The export includes all matching entries, not just the entries currently loaded on screen. Exported audit logs are suitable for ingestion into SIEM platforms, compliance reporting tools, or long-term archival storage. --- # Licensing URL: https://docs.tridentstack.com/administration/licensing Description: How TridentStack Control's per-endpoint licensing works, including the 200-endpoint free tier and how to add seats as your fleet grows. # Licensing TridentStack Control uses per-endpoint licensing. Every account includes 200 free endpoints with full platform capabilities, no time limit, and no feature restrictions. You only pay for endpoints beyond the first 200. ## How Licensing Works Each registered agent is either **licensed** or **unlicensed**: - **Licensed** agents have full access to all platform capabilities: update management, vulnerability scanning, compliance evaluation, policy enforcement, telemetry collection, and log collection. - **Unlicensed** agents remain visible in your endpoint list and continue to report basic connectivity (hostname, IP address, online/offline status), but cannot receive management actions. Licensing is enforced at the platform level. When you attempt an action on an unlicensed agent, the platform will indicate that a license is required. ## Free Tier Every account includes 200 free endpoint licenses at no cost, with no time limit and no feature restrictions. A free license has identical capabilities to a paid license. If your fleet is 200 endpoints or fewer, you never pay anything. Free licenses are assigned automatically in registration order, starting with your oldest agents. Every free license is equal; none is special or singled out. Beyond 200 endpoints, additional licenses require a paid subscription at five dollars per endpoint per month. ## Managing Licenses Navigate to **Settings > Licensing** to view and manage your license assignments. ### Summary Cards The top of the page displays four summary cards: | Card | Description | |------|-------------| | **Licensed Agents** | How many of your available licenses are currently assigned, shown as "used / total" | | **Total Agents** | The total number of registered agents in your account | | **Available Slots** | Remaining license slots that can be assigned to agents | | **Subscription** | Your current subscription status and billing cycle | ### Agent License Table Below the summary, a table lists every registered agent with its current license status: | Badge | Meaning | |-------|---------| | **Licensed** | This agent has an active license (one of your 200 free licenses, or a paid one) | | **Unlicensed** | This agent does not have a license and cannot receive management actions | The table is searchable and sortable by any column (sorted by hostname by default). Use the **Columns** menu to show, hide, reorder, or resize columns. ### Assigning and Unassigning Licenses You can act on a single endpoint or on many at once: - **One endpoint** - Hover a row and use its **Assign** or **Unassign** action. - **Several endpoints** - Select endpoints with the checkboxes, then use the **Assign Licenses** or **Unassign Licenses** buttons that appear above the table. What each action does: - **Assign** - Give a license to an unlicensed endpoint. If you select more endpoints than you have free license slots, the platform licenses as many as it can, starting with your oldest endpoints, and tells you how many more licenses you would need to cover the rest. - **Unassign** - Remove a license from a licensed endpoint. The endpoint becomes unlicensed and stops receiving management actions. Data collected while it was licensed is preserved. ## Auto-Assignment When licenses are added to your account (through a new subscription or an increase in license count), the platform automatically assigns them to agents in registration order, starting with the oldest. You can manually reassign licenses at any time after auto-assignment completes. When licenses are removed (subscription downgrade or cancellation), the platform keeps your free licenses on the oldest agents and removes paid licenses starting from the most recently registered agents. ## Subscription Management To add licenses or manage your subscription, visit the billing portal at [tridentstack.com/dashboard](https://tridentstack.com/dashboard). From the billing portal you can: - Adjust the number of licensed endpoints - Switch between monthly and annual billing - Update payment methods - View invoices and payment history A link to the billing portal is also available directly on the Settings > Licensing page. :::info Changes to your subscription are reflected in TridentStack Control within a few minutes. License assignments update automatically when your licensed endpoint count changes. ::: ## Cancellation If you cancel your subscription, paid licenses are removed at the end of your current billing period. Your first 200 endpoints remain licensed and fully functional under the free tier. All data previously collected from licensed agents is retained and accessible in read-only form. --- # SCIM provisioning URL: https://docs.tridentstack.com/administration/scim-provisioning Description: Sync users and groups from Okta, Entra ID, or any SCIM identity provider so role assignments and offboarding stay aligned with your IdP automatically. # SCIM provisioning Sync user and group changes from your identity provider to TridentStack Control automatically. Disable a user in your IdP, they lose Control access immediately. No more manual offboarding. Group memberships sync, which keeps role assignments aligned with your IdP. ## Before you begin You will need: - SAML SSO configured first (see [Single sign-on (SAML)](/administration/single-sign-on)). SCIM and SSO work together: SSO authenticates users, SCIM keeps the user list in sync. - A TridentStack Control admin account. - Permission in your IdP to configure SCIM provisioning. ## Setup overview 1. Generate a SCIM token in TridentStack Control (shown once, save it). 2. Configure SCIM in your IdP using the SCIM base URL and the token. 3. Map IdP attributes to TridentStack Control fields. 4. Push your IdP groups (use the same group names you mapped in the SSO setup). 5. Test by deactivating a test user in the IdP and confirming they appear inactive in Control. ## Step 1: Generate a SCIM token In TridentStack Control, go to **Settings -> Authentication -> SCIM Provisioning**. Click **Generate token**, give it a descriptive name (e.g. "Okta SCIM"), and click **Generate**. The token is shown **once**. Copy it now and save it somewhere safe (your IdP's secret manager or a password manager). For security, TridentStack Control never displays the full token again. If you lose it, revoke the token and generate a new one. The same panel shows the **SCIM Base URL** you will need: `https://control.tridentstack.com/scim/v2`. ## Step 2: Configure SCIM in your IdP ### Okta 1. Open your TridentStack Control app in Okta admin. 2. **Provisioning -> Configure API Integration**. Check "Enable API integration". 3. Paste the **SCIM Base URL** into "Base URL". 4. Paste the SCIM token into "API Token". 5. Click **Test API Credentials** then **Save**. 6. **Provisioning -> To App**. Enable "Create Users", "Update User Attributes", and "Deactivate Users". 7. Under **Push Groups**, add the groups you want synced (typically the same ones you map to roles in TridentStack Control). ### Microsoft Entra ID 1. In your TridentStack Control enterprise application, **Provisioning -> Get started**. 2. Set **Provisioning Mode** to **Automatic**. 3. **Tenant URL**: paste the SCIM Base URL. 4. **Secret Token**: paste the SCIM token. 5. Click **Test Connection**, then **Save**. 6. Under **Mappings**, configure the User and Group attribute mappings (the defaults work for most setups). 7. Set provisioning scope to "Sync only assigned users and groups" (recommended) and turn provisioning **On**. ### JumpCloud 1. Open your TridentStack Control SSO app in JumpCloud admin. 2. **Identity Management -> Set up Identity Management**, choose **SCIM Version 2.0**. 3. Paste the **SCIM Base URL** as the API URL. 4. Paste the SCIM token as the bearer token. 5. Save and enable user/group provisioning. ## Step 3: Map attributes The default attribute mappings work for most setups: - **userName** maps to email. - **externalId** maps to your IdP's stable user ID (used to detect renames). - **active** maps to your IdP's user-status flag. - **displayName** maps to the user's full name. - **groups** maps to group memberships. The most important mapping is **groups**: the group names your IdP pushes must match the IdP group names you configured in the [SSO group-to-role mapping](/administration/single-sign-on#step-4-map-idp-groups-to-tridentstack-control-roles). ## Step 4: Push groups Push the groups your team uses in TridentStack Control. When a user joins or leaves an IdP group: - Their TridentStack Control role updates automatically (per the SSO group-to-role mapping). - Manual role assignments (granted directly in TridentStack Control, not via the mapping) are preserved. ## Step 5: Test deactivation The most important sync to verify is offboarding: 1. In your IdP, mark a test user as inactive (or unassign them from the TridentStack Control app). 2. Wait up to 60 seconds for your IdP to push the change. 3. In TridentStack Control, go to **Settings -> User Management** and confirm the test user shows inactive. 4. The user's existing browser sessions are invalidated; their next request returns to the sign-in page. 5. Reactivate them in your IdP and confirm they reactivate in TridentStack Control. ## What gets synced - **Users**: created, updated, deactivated, reactivated. - **Group memberships**: drive role assignments via the SSO group-to-role mapping. - **Display name and email**: kept in sync from your IdP. What does NOT sync: - **Passwords**: TridentStack Control does not store passwords. Authentication is via SAML SSO. - **Tenant settings, agent configurations, policies, deployment rings**: managed in TridentStack Control. ## What happens during deactivation When your IdP marks a user inactive (via SCIM `active=false` or by removing them from the app): - The user is marked inactive in TridentStack Control. - Their active browser sessions end immediately. - IdP-mapped roles are removed. - Manual role assignments are preserved in case you reactivate them later. - The user's audit history is preserved. ## Token rotation and revocation To rotate a token: 1. Generate a new token in TridentStack Control. 2. Paste the new token into your IdP's SCIM configuration. Save and test. 3. Once your IdP is using the new token, revoke the old one in TridentStack Control. To revoke without rotation: - Click **Revoke** next to the token. The token stops working immediately. Any IdP using it will need a new token to resume sync. ## Limits and troubleshooting **Rate limit**: 60 requests per minute per token (with a small burst allowance). This is well above what any standard IdP needs for normal sync. **Common errors**: - **401 Invalid or revoked token**: your IdP is using a stale or revoked token. Generate a new one and update the IdP. - **400 invalidFilter**: your IdP sent a SCIM filter that uses an unsupported attribute. Most IdPs work fine; if you hit this with a specific provider, contact support with the filter string. - **Sync stops working without errors**: check the **Last Used** column in the SCIM Provisioning panel; if it has not updated recently, your IdP is not pushing. Re-test the connection in your IdP's admin console. For anything not covered here, contact TridentStack support at [tridentstack.com/dashboard/support](https://tridentstack.com/dashboard/support). --- # Notifications URL: https://docs.tridentstack.com/administration/notifications Description: Configure email, webhook, and in-app notifications in TridentStack Control so the right people hear about deployments, failures, and security events. # Notifications TridentStack Control can notify your team when important platform events occur. Notifications support multiple delivery channels and give you granular control over which events trigger alerts and who receives them. ## Supported Channels | Channel | Integration Method | Description | |---------|-------------------|-------------| | **Email** | Built-in (Resend) | HTML-formatted emails sent to selected team members. Per-category recipient selection lets different teams receive different event types | | **Slack** | Incoming webhook URL | Block Kit formatted messages with color coding and action buttons linking back to TridentStack Control | | **Microsoft Teams** | Webhook URL | Adaptive Card formatted messages with field-based layouts | | **Discord** | Webhook URL | Embedded messages with color-coded severity levels | | **Custom Webhook** | HTTP endpoint URL | Raw JSON payloads signed with HMAC-SHA256 for verification. Supports custom headers | | **In-app** | Built-in | Alerts appear in the notification bell inside TridentStack Control, so your team sees them without leaving the platform | ## Event Categories Notifications are organized into four categories. Each category can be enabled or disabled independently, and individual events within a category can be toggled on or off. ### Deployment Rings Lifecycle events for phased deployment rollouts. These help you stay informed as updates progress through your ring phases without needing to watch the deployment rings page. | Event | Description | |-------|-------------| | **Deployment Started** | A deployment ring began deploying updates to agents | | **Phase Advanced** | A ring phase progressed to the next phase | | **Approval Pending** | A manual-approval phase is ready for administrator action | | **Deployment Completed** | All phases in the ring finished, with summary statistics | | **Emergency Halt** | A ring was auto-halted because the failure threshold was exceeded | | **Phase Failure** | A phase failed to meet its success criteria after the timeout period | :::tip At minimum, enable **Approval Pending** and **Emergency Halt** for deployment rings. These are the two events most likely to require immediate action from your team. ::: ### Security and Access User management and authentication events for audit awareness. | Event | Description | |-------|-------------| | **User Invited** | A new user was invited to the tenant | | **Role Changed** | A user was promoted or demoted (for example, granted or revoked admin access) | | **API Key Created** | A new API key was generated | | **API Key Deleted** | An API key was revoked | ### Agent Fleet Agent registration and removal events for fleet visibility. | Event | Description | |-------|-------------| | **Agent Registered** | A new agent enrolled with the platform | | **Agent Removed** | An agent was deleted from the tenant | ### Risk and Compliance Summary alerts for vulnerability and compliance posture changes across your fleet. | Event | Description | |-------|-------------| | **Critical Vulnerabilities Found** | New critical-severity vulnerabilities (CVSS 9.0+) were detected across the fleet. Includes affected agent count and top CVEs | | **Compliance Drift Detected** | Agents fell out of compliance with assigned frameworks. Includes drifted agent count and affected frameworks | ## Configuring Notifications Access notification settings from **Settings > Notifications** in the sidebar. ### Master Switch The master toggle at the top of the page enables or disables all notifications globally. When disabled, no notifications are sent regardless of individual channel or event settings. ### Email Configuration Email is a built-in channel that does not require a webhook URL: 1. Toggle **Email notifications** on 2. Optionally set a custom "From" display name (defaults to "TridentStack Control") 3. For each event category, choose who should receive those emails. Select team members from the directory, or, as an administrator, type any email address (such as a shared inbox or distribution list) and add it. Different categories can have different recipient lists, so deployment ring alerts go to your ops team while security events go to your security team ### Adding an External Channel To add Slack, Teams, Discord, or a custom webhook: 1. Click **Add Channel** 2. Select the channel type 3. Enter the webhook URL (and optionally custom headers for webhooks) 4. Give the channel a descriptive name 5. Click **Save** For custom webhooks, a signing secret is generated automatically and displayed once on creation. Store this secret securely. TridentStack Control signs every webhook payload with HMAC-SHA256 using this secret, allowing your endpoint to verify authenticity. ### Testing a Channel After adding a channel, click the **Test** button to send a sample notification. This verifies that the webhook URL is correct and that your receiving application processes the message format properly. ### Per-Channel Event Filtering Each event can be turned on or off independently for every channel. For example, you can send **Critical Vulnerabilities Found** alerts to email and the in-app bell while leaving them off in Slack, all from **Settings > Notifications**. Each external channel can also have its own event whitelist. For example, you might send all deployment ring events to Slack but only send emergency halts and phase failures to a PagerDuty webhook: 1. Click the channel in the channel list 2. Toggle individual events on or off for that channel 3. Save your changes Events that are disabled at the category level (in the main event settings) are never sent to any channel, regardless of per-channel filtering. ## Notification Delivery Most notifications are sent in near real-time when events occur. Each delivery attempt is logged internally with status (sent or failed) and error details if applicable. Failed deliveries are not automatically retried. ### Delivery mode for critical vulnerability alerts On a large fleet, new critical vulnerabilities can be detected on every scan, which used to mean an alert for every scan. To keep your inbox manageable, critical vulnerability alerts are grouped into a single digest by default instead of sending one alert per scan. You configure this from the **Critical Vulnerabilities Found** event in **Settings > Notifications**. When that alert type is enabled, a **Configure** button opens a panel where you choose how alerts are delivered: | Delivery mode | Behavior | |---------------|----------| | **Immediate** | Send an alert as soon as new critical vulnerabilities are found, on every scan. Best for small fleets or teams that want every finding surfaced right away | | **Hourly digest** | Group new critical vulnerabilities into one summary sent once per hour | | **Daily digest** (default) | Group new critical vulnerabilities into one summary sent once per day, at a send time you choose | For the daily digest, you pick the time of day the summary goes out and the time zone it is measured in. The time zone defaults to your account's time zone, so the digest lands at the same local hour for your team without any extra setup, and you can change it to any zone you prefer. Whichever mode you choose, actively exploited vulnerabilities always alert immediately, so the findings most likely to be attacked never wait for the next digest. You can also set a **severity threshold** so that any vulnerability at or above the score you pick bypasses the digest and alerts right away, giving you a fast lane for your most serious findings while everything else rolls up into the digest. :::warning If a webhook endpoint is unreachable or returns an error, the notification is marked as failed and the platform event proceeds normally. Notification failures never block platform operations. ::: ## Webhook Payload Format Custom webhook channels receive a JSON payload with the following structure: ```json { "eventType": "deployment.emergencyHalt", "timestamp": "2026-03-18T14:30:00.000Z", "tenantId": "your-tenant-id", "payload": { "ringId": "ring-uuid", "ringName": "Production Ring", "phase": "Canary", "reason": "Failure threshold exceeded", "failureCount": 3, "failureRate": 0.15 } } ``` The request includes an `X-Signature-256` header containing the HMAC-SHA256 signature of the request body. Verify this against your signing secret to confirm the payload originated from TridentStack Control. --- # Microsoft Entra Group Sync URL: https://docs.tridentstack.com/administration/entra-group-sync Description: Mirror Microsoft Entra (Azure AD) device group membership onto TridentStack Control tags, so your update, configuration, and compliance policies follow the groups you already maintain. # Microsoft Entra Group Sync Connect your Microsoft Entra tenant so device group membership flows automatically into TridentStack Control tags. Map an Entra group to a tag once, and every enrolled endpoint in that group carries the tag, now and as membership changes. Because tags drive policy targeting in TridentStack Control, your update policies, configuration policies, and compliance baselines follow the groups you already maintain in Entra without re-tagging endpoints by hand. The connection is read-only and inbound only: TridentStack Control reads group membership from Entra and never writes anything back to your directory. :::info This is separate from [single sign-on](./single-sign-on). SSO controls how administrators log in to TridentStack Control. Entra Group Sync mirrors your device groups onto endpoint tags. You can use either, both, or neither. ::: ## How it works 1. You connect your Entra tenant with a one-time administrator consent (read-only). 2. You create mappings, each pairing one Entra group with one TridentStack Control tag. 3. TridentStack Control reconciles membership on a schedule (about once an hour) and whenever you click **Sync now**. Enrolled endpoints that belong to the group receive the tag; endpoints that leave the group have that tag removed. Only endpoints already enrolled in TridentStack Control are affected. The sync matches Entra device group members against your enrolled endpoints. It does not enroll new devices or change anything in Entra. ## Prerequisites - A Microsoft Entra tenant with the device groups you want to mirror. - An account that can grant administrator consent for the tenant (for example, Global Administrator or Privileged Role Administrator). This is needed once, at connection time. Day-to-day mapping management afterward needs only TridentStack Control permissions. - The **Manage integrations** permission in TridentStack Control (included in the Administrator role). - Endpoints enrolled in TridentStack Control that correspond to the devices in your Entra groups. ## Connecting your tenant 1. Go to **Settings > Integrations**. 2. On the **Microsoft Entra** card, click **Connect**. 3. You are redirected to Microsoft to sign in and grant consent. Review the requested read-only permissions and approve. 4. After consent, you return to TridentStack Control and the card shows **Connected**, along with your tenant and the last sync time. If consent is declined or interrupted, the card shows **Consent pending** or **Error**. Click **Reconnect** to try again. ## Mapping a group to a tag With the tenant connected, open **Settings > Integrations** and use the **Group to tag mappings** section. 1. Click **Add mapping**. 2. **Include nested group members** (on by default) controls whether members of nested groups count toward the mapping. 3. Choose the **Entra group**. The group picker is searchable and shows, for each group, how many of its devices are managed by TridentStack Control alongside its total device count, so you can judge the impact before mapping. Turn on **Hide groups with no devices** to filter out groups that have no managed endpoints. 4. Choose the **Tag** to apply. 5. The dialog previews the immediate impact, for example "This will tag 12 agents now." 6. Click **Create mapping**. The tag is applied to matching endpoints on the next sync. You can trigger that immediately with **Sync now**. ## Managing mappings The **Group to tag mappings** table lists every mapping and its current state: | Column | Meaning | |--------|---------| | **Entra group** | The source group in your directory | | **Tag** | The TridentStack Control tag applied to that group's members | | **Nested** | Whether nested group members are included (toggle) | | **Enabled** | Whether the mapping is active (toggle) | | **Matched** | How many enrolled endpoints matched at the last reconcile | | **Last sync** | When this mapping last reconciled | Each mapping has three actions: - **Preview** shows how many enrolled endpoints currently match, without making any change. - **Sync now** reconciles this mapping immediately. The reconcile runs in the background, so the updated match count and last sync time appear a few seconds after you start it. - **Delete** removes the mapping and the tags it applied. You are asked to confirm, because removing the mapping removes the tag from the endpoints it tagged. Turning **Enabled** off pauses a mapping without deleting it: it stops applying and maintaining the tag until you turn it back on. ## Sync behavior and timing - The scheduled reconcile runs about once an hour across all mappings. - **Sync now** runs on demand for a single mapping. - Reconcile is membership-driven. At each run, endpoints currently in the group receive the tag, and endpoints no longer in the group have that mapping's tag removed. Because a tag applied by a mapping is maintained by the sync, manage who has the tag by managing the Entra group, rather than adding or removing that tag by hand on individual endpoints. ## Disconnecting To disconnect, click **Disconnect** on the **Microsoft Entra** card. This removes all group mappings and the tags they applied. The connection and the consent it relied on are removed from TridentStack Control. You can also revoke consent at any time from the Microsoft Entra admin center under **Enterprise applications**. Revoking consent in Entra stops all syncing; the integration shows a **Revoked** state until you reconnect or disconnect. ## Security and privacy - **Read-only, inbound only.** TridentStack Control requests only the permissions needed to read your groups, their members, and device records. It never modifies your Entra directory. - **Tenant-level consent.** Consent is granted once by an administrator and applies to your tenant. You remain in control and can revoke it at any time. :::tip Map the groups you already use to organize devices, such as by department, location, hardware class, or risk tier. Your TridentStack Control policies then inherit that structure automatically, and new devices pick up the right tags as soon as they join the group and enroll. ::: --- # Verified Sign-in Domains URL: https://docs.tridentstack.com/administration/verified-signin-domains Description: Use every email domain your organization owns with a single TridentStack Control workspace: verify domains automatically through Microsoft or manually with a DNS record. # Verified Sign-in Domains If your organization owns more than one email domain, for example `acme.com` and `acme.io`, you can use all of them with a single TridentStack Control workspace. Once a domain is verified, someone signing in with an email address on that domain is recognized as part of your organization instead of starting a separate one. This is useful for organizations that grew through a rebrand, a regional TLD, an acquisition, or simply register mail on more than one domain. ## What verifying a domain does Verifying a domain changes one thing: where sign-ins from that domain are routed. A verified domain is recognized as part of your organization, so someone signing in with an email on it joins your workspace instead of starting a new, separate one. Verifying a domain does not open your workspace to everyone on that domain. Access is controlled exactly as it is for any other new person: - Anyone signing in from a verified domain lands in the pending-approval queue, and an admin approves them before they can use TridentStack Control. - You can invite people on any of your verified domains from your user management settings. You cannot invite someone on a domain you have not verified. ## Automatic verification through Microsoft If your team signs in with Microsoft work accounts, adding another domain usually requires no action from you. When someone signs in with a Microsoft work account whose sign-in name is on another domain your Microsoft organization owns, for example `sam@acme.io`, TridentStack Control recognizes that the domain belongs to the same Microsoft organization as a domain you have already verified, and adds and verifies it automatically. There is no DNS record to add and no button to click. This works because your workspace is tied to your Microsoft organization the first time anyone from your primary domain signs in with a Microsoft work account. As always, that sign-in verifies the domain, not the person: whoever signs in still waits for admin approval before they can use TridentStack Control. ## Adding a domain manually If your team does not use Microsoft accounts to sign in, or you want to verify a domain before anyone signs in with it, you can add and verify it manually with a DNS record. 1. Go to **Settings -> Authentication -> Sign-in domains**. 2. Click **Add domain** and enter the domain, for example `acme.io`. 3. TridentStack Control shows you a DNS TXT record to create: - **Host**: `_tridentstack.acme.io` - **Value**: a unique verification token, for example `tridentstack-verify=abc123...` 4. Add that TXT record in your DNS provider's control panel. 5. DNS changes can take up to an hour to propagate, depending on your provider and existing DNS settings. 6. Back in TridentStack Control, click **Verify**. Once the TXT record is found, the domain is marked verified and ready to use. If verification fails, double-check the host and value were entered exactly as shown, then wait a little longer for DNS to propagate before trying again. ## Controlling sign-in methods per domain Every sign-in domain in your organization, including your primary domain, has its own card in **Settings -> Authentication -> Sign-in domains** with independent controls for which sign-in methods it allows. Each domain is configured the same way, in one place, so you can allow different domains to sign in different ways. For example, your primary domain might allow Microsoft, Google, and an email code, while a secondary domain is restricted to Microsoft only. Open a domain's card and use the toggle next to each sign-in method to choose which ones are allowed for that domain. Only methods you have configured for your organization, such as specific OAuth providers, are available to turn on. At least one sign-in method must stay enabled for every domain, so the last remaining method cannot be turned off. Single sign-on stays a separate, organization-wide setting under **Settings -> Authentication -> SAML Single Sign-On** and is not configured per domain. ## Disabling a domain You can disable a verified domain at any time from the same **Sign-in domains** list. Disabling a domain stops future sign-ins from that domain from resolving to your organization. Existing users who already have accounts keep them and are not affected, but new sign-in attempts from that domain are no longer recognized as belonging to your workspace. You can re-enable a disabled domain later, which restores it to normal behavior. ## Troubleshooting **"This domain is already in use by another organization"** Each domain can be verified by only one TridentStack Control organization at a time. If you see this message while trying to add a domain, it means the domain is already claimed elsewhere, most commonly because it was verified by a different workspace. If you believe this is an error, for example the domain should belong to your organization and you do not recognize the other workspace, contact TridentStack support. **A coworker on an added domain is asked to be invited** Automatic sign-in for a coworker works when the domain on their email address matches the domain on their Microsoft sign-in name. Some organizations set these to different domains: the email address is on one domain, for example a brand domain, while the Microsoft sign-in name is on the primary domain. When they differ, TridentStack Control asks that coworker to be invited before they can join, so that no one outside your organization can slip in. Invite them from your user management settings, and they can sign in normally. --- # Secure Boot Certificate Rotation URL: https://docs.tridentstack.com/security/secure-boot-2026-rotation Description: How TridentStack Control reports the 2026 Secure Boot certificate update. # Secure Boot Certificate Rotation TridentStack Control reports each Windows endpoint's status against Microsoft's 2026 Secure Boot certificate rotation. This page explains what the rotation is, why it matters, and how to read the four states you will see. ## What is changing Microsoft's existing Secure Boot certificate authorities, the **Microsoft Corporation UEFI CA 2011** and **Windows Production PCA 2011**, expire in mid-2026. Devices that do not receive the new **Windows UEFI CA 2023** certificate will stop receiving boot-level security updates after the deadline. ## Where to see status in TridentStack Control - **Dashboard.** A "Secure Boot Certificate Status" tile shows how many endpoints still need the update. It auto-hides once everything is up to date. - **Agent details, System State tab.** A "Firmware & Security" panel shows each endpoint's current state, with a callout when action is required. - **Agents list.** Add the "Secure Boot" column from the column manager to see fleet-wide status at a glance. ## What the four states mean | State | Meaning | |---|---| | **Updated** | The endpoint has the new certificate. No action required. | | **In Progress** | Microsoft's update is currently being applied. The process takes multiple reboots and typically completes within 48 hours. | | **Not Started** | The endpoint has not received the new certificate yet. Microsoft applies the rotation gradually; if you would like to speed up your fleet, see [Speed up rollout](./speed-up-secure-boot-rotation.md). | | **Not Applicable** | The endpoint does not use Secure Boot (BIOS firmware, or Secure Boot disabled). No action. | ## What you should do For most customers, the answer is "wait". Microsoft is rolling this out automatically and tightly controls the rollout for safety. If you want to accelerate the rotation across your fleet, see [Speed up rollout](./speed-up-secure-boot-rotation.md). ## What TridentStack Control does not do TridentStack Control does not write firmware or modify Secure Boot variables. The actual certificate update is performed by Windows itself, gated by Microsoft's own rollout safety checks. TridentStack Control reports status only. --- # Speed Up Secure Boot Rollout URL: https://docs.tridentstack.com/security/speed-up-secure-boot-rotation Description: Use Custom Registry Settings to opt endpoints into Microsoft's 2026 Secure Boot rotation. # Speed Up Secure Boot Rollout Microsoft rolls out the 2026 Secure Boot certificate gradually based on telemetry signals from each device's hardware and Windows version. Endpoints that are not yet eligible can be opted in by setting two registry values. The actual certificate update still happens through Microsoft's own scheduled task, with all of Microsoft's per-device safety checks intact, this just tells Windows "this device is ready, do not wait for the gradual rollout signal". You can apply these registry values fleet-wide using a TridentStack Control **Policy Object**. ## When to use this - You want to accelerate the 2026 Secure Boot rotation across some or all of your fleet. - You have reviewed your endpoints' hardware and are not aware of any with known firmware issues that would make Secure Boot updates risky. ## When not to use this - You operate any dual-boot Linux machines whose distros depend on shim binaries signed under the older 2011 certificate. Verify Linux readiness first. - You have endpoints with custom or third-party Secure Boot policies. The opt-in only affects Microsoft's own update path. ## Step-by-step 1. In TridentStack Control, go to **Policy Objects**, then **New Policy Object**. 2. Name it something memorable, for example "Secure Boot 2026 Opt-In". 3. Add two **Custom Registry Settings**: | Field | Value | |---|---| | Hive | `HKEY_LOCAL_MACHINE` | | Key path | `SYSTEM\CurrentControlSet\Control\SecureBoot` | | Value name | `AvailableUpdates` | | Type | `REG_DWORD` | | Data | `0x5944` (decimal `22852`) | | Field | Value | |---|---| | Hive | `HKEY_LOCAL_MACHINE` | | Key path | `SYSTEM\CurrentControlSet\Control\SecureBoot` | | Value name | `MicrosoftUpdateManagedOptIn` | | Type | `REG_DWORD` | | Data | `1` | 4. Assign the Policy Object to a tag matching your target endpoints. 5. Save. Within the next agent check-in, the registry values will be applied. Microsoft's `\Microsoft\Windows\PI\Secure-Boot-Update` scheduled task picks up the opt-in on its next 12-hour run, and the certificate update typically completes over the following two reboots (about 48 hours). You will see status transition from **Not Started**, then **In Progress**, then **Updated** in TridentStack Control. ## Reverting If you need to opt out, edit the Policy Object and either remove the registry values or set both to `0`. Once opted out, Microsoft's gradual rollout resumes for those endpoints. ## Reference - Microsoft Tech Community: [Updating Microsoft Secure Boot keys](https://techcommunity.microsoft.com/blog/windows-itpro-blog/updating-microsoft-secure-boot-keys/4055324) - Microsoft Support: [Registry key updates for Secure Boot](https://support.microsoft.com/en-us/topic/registry-key-updates-for-secure-boot-windows-devices-with-it-managed-updates-a7be69c9-4634-42e1-9ca1-df06f43f360d) --- # EDR and SIEM Onboarding URL: https://docs.tridentstack.com/security/edr-and-siem-onboarding Description: What the TridentStack Control agent does on Windows, macOS, and Linux endpoints, how to identify it, and how to tune endpoint security tools that monitor it. # EDR and SIEM Onboarding Patch management agents legitimately do things that endpoint security products watch closely: they download executables, install software with elevated privileges, modify policy, create scheduled tasks, and restart machines. If your organization runs an EDR, SIEM, or a security operations center, this page gives your security team what they need to positively identify the TridentStack Control agent on each platform, understand which behaviors are expected, and write precise, minimal trust rules instead of broad exclusions. If you see agent behavior that is not listed here, treat it as unexpected and investigate it like any other alert. ## Network profile (all platforms) Agents hold a single persistent outbound TLS connection to `gateway.tridentstack.com` on port 443 and make HTTPS requests to your TridentStack Control server addresses. Update payloads download directly from the platform vendor (for example `*.download.windowsupdate.com` and `*.delivery.mp.microsoft.com` on Windows, Apple's software update CDN on macOS, your configured package mirrors on Linux) and from the relevant package sources for third-party applications. The agent never listens on inbound network ports on any platform. ## The agent on Windows ### Binaries and signing Every executable TridentStack Control ships for Windows is Authenticode-signed and timestamped. Verify the signature chain rather than trusting file names or paths alone. | Property | Value | |---|---| | Signer subject | `CN=TridentStack LLC, O=TridentStack LLC, L=Saratoga Springs, S=Utah, C=US` | | Issuer | Microsoft ID Verified CS EOC CA 04 (Azure Trusted Signing) | | Executable | Location | Role | |---|---|---| | `TridentStack-ControlService.exe` | `C:\Program Files\TridentStack Control\` | Windows service. Supervises the agent and maintains the server connection. | | `tridentstack-core.exe` | `C:\Program Files\TridentStack Control\bin\` | Agent engine. Runs the persistent daemon and per-operation work (update checks, installs, inventory, telemetry). | | `tridentstack-updater.exe` | `C:\Program Files\TridentStack Control\bin\` | Agent self-update helper. | | `TridentStack-Control.exe` | `C:\Program Files\TridentStack Control\` | Desktop status app. Runs only in logged-in user sessions. | | `result-writer.exe` | `C:\Program Files\TridentStack Control\` | Helper for per-user application installs. | Signer-scoped rules survive agent updates; file-hash rules do not, because every release is a new build. If your EDR supports trusting a signer, prefer that over per-hash allowlisting. ### Process tree - `services.exe` starts `TridentStack-ControlService.exe` (the service, running as SYSTEM) - The service starts `tridentstack-core.exe agent run-daemon` (the persistent agent) - The engine starts short-lived children per operation: Microsoft installers (`wusa.exe`, `msiexec.exe`, update packages), package manager operations, and OS query tools ### Expected behaviors | Behavior | What it looks like | When it happens | |---|---|---| | Update downloads | `tridentstack-core.exe` writes installers under `C:\ProgramData\TridentStack Control\downloads\` | Update installs and pre-staging ahead of maintenance windows | | Windows update installation | The engine runs `wusa.exe`, DISM servicing, or the Microsoft-signed update package as SYSTEM | Approved system update installs | | Malicious Software Removal Tool updates | The engine runs the Microsoft-signed KB890830 package with its quiet switch; that Microsoft process writes `C:\Windows\System32\mrt.exe`, runs a quiet scan, and logs to `C:\Windows\Debug\mrt.log` | Monthly MSRT releases, when approved | | Application installs and updates | Package manager operations and vendor installers run as SYSTEM; installs that must run in a user context use a one-time scheduled task under `\TridentStack\PerUserInstall\` plus `result-writer.exe`, launched in the target user's session | Approved application updates | | Third-party installer resume hooks | Some application installers stage a self-contained copy of themselves under `C:\ProgramData\Package Cache\{GUID}\` and register a transient `RunOnce` value (for example `HKLM\...\CurrentVersion\RunOnce`, calling the cached installer with a resume switch) so the install can continue across a restart, clearing it on completion. This is the vendor installer's own behavior, performed identically under any deployment tool (or a manual double-click); TridentStack Control only launches the installer | Approved application installs that use self-contained bootstrapper installers, such as the .NET SDK/runtime | | Policy enforcement | Writes to `C:\Windows\System32\GroupPolicy\` (`Registry.pol`) and policy registry keys under HKLM | Configuration policy deployment | | Security posture collection | Read-only runs of OS query tools such as `secedit` (security policy export), `w32tm` (time service), `reagentc` (recovery environment), plus scheduled task, certificate store, and file permission enumeration | Compliance and telemetry collection cycles | | Agent self-update | `tridentstack-updater.exe` runs `msiexec /i` on a signed MSI from `C:\ProgramData\TridentStack Control\downloads\agent-updates\`, replacing the agent binaries and restarting the service | Agent version rollouts | | System restarts | Restart initiated by the agent as SYSTEM | Only per your update policy and restart windows | Two things the Windows agent deliberately does not do, which your security team can treat as tripwires: it never writes executables into OS system directories from its own process (Microsoft installers perform their own file placement), and it never injects code into other processes. ## The agent on macOS ### Binaries and signing All macOS binaries and the installer package are signed with an Apple Developer ID for **TridentStack LLC (Team ID `2T8VBB5XQB`)** and notarized by Apple. The agent refuses to self-update from a package that fails Apple's Developer ID and notarization checks. | Component | Location | Role | |---|---|---| | `tridentstack-agent` | `/usr/local/sbin/` | The agent daemon (universal binary), runs as root | | `TridentStack Control.app` | `/Applications/` | Desktop status app, runs only in logged-in GUI sessions | ### Process model - launchd runs the daemon as the LaunchDaemon `com.tridentstack.agent` (`/usr/local/sbin/tridentstack-agent daemon`, root, kept alive) - launchd runs the status app as the LaunchAgent `com.tridentstack.ui` in each logged-in user's GUI session - The daemon and the app communicate over a local Unix socket at `/var/run/tridentstack/ui.sock`; there is no network channel between them - Data and logs live under `/Library/Application Support/TridentStack/`, `/var/lib/tridentstack/`, and `/var/log/tridentstack/` ### Expected behaviors | Behavior | What it looks like | When it happens | |---|---|---| | OS update installation | The daemon runs Apple's `softwareupdate`; major version upgrades are downloaded and staged first, then committed in a second step, with staged content under `/var/lib/tridentstack/staged-os-installs/` | Approved system update installs | | Application installs and updates | `installer -pkg` for package installers; disk images and archives are handled with `hdiutil` and `ditto`; Homebrew operations run as the logged-in console user via `sudo -u` because Homebrew refuses to run as root | Approved application updates | | Pre-install verification | The daemon runs `codesign --verify` and `spctl --assess` against every downloaded application before installing it, and rejects software that fails Gatekeeper assessment | Every third-party application install | | Credential storage | Keychain reads and writes through the `security` command | Agent enrollment and startup | | Posture and inventory collection | Read-only runs of `system_profiler`, `softwareupdate --history`, `lsof`, `ps`, `scutil`, `ioreg`, `sysctl`, and code-signature inspection of installed apps; the daemon also reads Apple's `/var/log/install.log` | Compliance and telemetry collection cycles | | Agent self-update | The daemon downloads a signed `.pkg` over a certificate-pinned TLS connection, verifies its SHA-256 hash, then runs `/usr/sbin/installer -pkg ... -target /`, which enforces the Developer ID signature and notarization; launchd restarts the new daemon | Agent version rollouts | | User notifications and restarts | Restart prompts through the status app or `osascript`; restarts via `/sbin/shutdown` as root | Only per your update policy and restart windows | ## The agent on Linux ### Binary and integrity Linux has no platform-wide binary signing equivalent to Authenticode or Developer ID, so identify the agent by its installation path, service unit, and delivery chain. Agent builds are GPG-signed at build time and TridentStack Control verifies that signature before a build can be distributed to agents; endpoint-side installs and self-updates additionally verify a SHA-256 checksum of the binary delivered over TLS (self-updates over a certificate-pinned connection). | Component | Location | Role | |---|---|---| | `tridentstack-agent` | `/opt/tridentstack/bin/` | The only agent binary. No UI, no helper processes. | | `tridentstack-agent.service` | systemd unit | Runs `/opt/tridentstack/bin/tridentstack-agent daemon` as root, auto-restarts | Configuration lives in `/etc/tridentstack/`, working data in `/var/lib/tridentstack/`, logs in `/var/log/tridentstack/` and the systemd journal. ### Expected behaviors | Behavior | What it looks like | When it happens | |---|---|---| | Package installs and updates | `apt-get` and `dpkg-query` on Debian and Ubuntu; `dnf` and `rpm` on RHEL-family systems, all as root | Approved package updates | | Restart-requirement detection | `needrestart` (Debian/Ubuntu) or `needs-restarting` (RHEL family), plus kernel version comparison | After installs and during telemetry cycles | | Posture and inventory collection | Read-only runs of `dpkg-query`/`rpm`, `lspci`, `lsblk`, `dmidecode`, `sysctl -a`, `ss`, `uname`, and `systemctl` listings; firewall state reads through `ufw`, `firewall-cmd`, `nft list`, or `iptables -L` (list operations only, the agent does not change firewall rules); an outbound `curl` for public IP discovery | Compliance and telemetry collection cycles | | Agent self-update | Downloads the new binary to `/var/lib/tridentstack/downloads/`, verifies its SHA-256 checksum and file format, replaces `/opt/tridentstack/bin/tridentstack-agent` (keeping a `.backup` copy for rollback), and restarts its own systemd unit | Agent version rollouts | | System restarts | `/sbin/shutdown -r` as root | Only per your update policy and restart windows | ## Tuning guidance - **Scope rules to the strongest identity each platform offers, plus the install paths.** On Windows: the TridentStack LLC Authenticode signer with `C:\Program Files\TridentStack Control\` and `C:\ProgramData\TridentStack Control\`. On macOS: Developer ID Team ID `2T8VBB5XQB` with `/usr/local/sbin/tridentstack-agent` and `/Applications/TridentStack Control.app`. On Linux: the executable path `/opt/tridentstack/bin/tridentstack-agent` running under the `tridentstack-agent.service` systemd unit. Avoid directory-only exclusions, which anything on the machine could plant files into. - **Do not disable detection for system folder writes.** The agent does not require it on any platform. Where OS files change (for example `mrt.exe` during Windows MSRT updates), the write is performed by the platform vendor's own signed installer process, the same write your EDR sees from native OS updates. - **Keep scanning the download directories.** `C:\ProgramData\TridentStack Control\downloads\` and `/var/lib/tridentstack/downloads/` hold real installers; letting your EDR scan them costs little and preserves defense in depth. Hash verification happens independently inside the agent before anything executes. - **Baseline the process trees.** Alerting on deviations from the ancestries above (for example, `tridentstack-core.exe` spawned by anything other than the service, or `tridentstack-agent` running from a path other than its install location) is a better use of detection engineering than suppressing the agent wholesale. - **Expect one new binary set per release.** Agent updates are staged rollouts of newly built, newly signed binaries. Reputation-based analytics may score the first sighting of a new version as rare. The signature chain (Windows, macOS) and install path plus delivery chain (Linux) are the stable identities across releases. If your security operations team needs additional detail about a specific observed behavior, contact TridentStack support with the process names, command lines, and timestamps from the alert. --- # Agent Reference URL: https://docs.tridentstack.com/reference/agent-reference Description: Reference for the TridentStack Control agent: installation paths, configuration files, service details, log locations, and supported platforms per OS. # Agent Reference This page documents the TridentStack Control agent's installation paths, configuration files, service details, and supported platforms for each operating system. ## Windows Agent ### Supported Versions - Windows 8.1 and later - Windows Server 2012 R2 and later :::note On Windows Server 2012 R2 and older, the agent runs as a headless service without the desktop system tray UI. All management features work normally. See [Desktop UI](#desktop-ui-system-tray) below for details. ::: ### Installation The Windows agent is distributed as an MSI installer. Install interactively or via command line: ```powershell msiexec /i TridentStack-Control.msi ENROLLMENT_TOKEN="" /qn /norestart ``` The `/qn` flag runs a silent install. The `/norestart` flag prevents an automatic reboot after installation. ### File Locations | Path | Contents | |------|----------| | `C:\Program Files\TridentStack Control\` | Agent binaries (read-only after install) | | `C:\ProgramData\TridentStack Control\` | Runtime data root | | `C:\ProgramData\TridentStack Control\config\` | Configuration files | | `C:\ProgramData\TridentStack Control\logs\` | Agent log files | | `C:\ProgramData\TridentStack Control\downloads\` | Downloaded update files and pre-staged content | | `C:\ProgramData\TridentStack Control\servicedata\` | Service runtime state | | `C:\ProgramData\TridentStack Control\cache\` | Cached data | ### Configuration Files All configuration files are located in `C:\ProgramData\TridentStack Control\config\`: | File | Purpose | |------|---------| | `server.json` | Server connection URL, gateway address | | `agent.json` | Agent identity and configuration | | `agent_credentials.dat` | Encrypted credentials (DPAPI, SYSTEM-only access) | | `debug-settings.json` | Debug logging levels and options | :::warning Never manually edit `agent_credentials.dat`. It is encrypted using Windows DPAPI under the SYSTEM account and cannot be read or modified by user accounts. ::: ### Windows Service | Property | Value | |----------|-------| | Service Name | `TridentStack-ControlService` | | Display Name | TridentStack Control Service | | Account | Local System (SYSTEM) | | Start Type | Automatic | | Recovery | Restart on failure | **Common commands:** ```powershell # Check service status Get-Service TridentStack-ControlService # Restart the service Restart-Service TridentStack-ControlService # View recent service logs Get-EventLog -LogName Application -Source "TridentStack*" -Newest 20 ``` ### Binaries | Binary | Purpose | |--------|---------| | `tridentstack-core.exe` | Core agent daemon (runs as SYSTEM) | | `TridentStack Control.exe` | Desktop UI application (runs as current user) | | `tridentstack-updater.exe` | Self-update handler (runs as SYSTEM) | ### Desktop UI (System Tray) The TridentStack Control agent includes a desktop UI application that runs in the system tray when a user is logged in. The system tray icon provides quick access to agent status, version information, and update notifications. The desktop UI requires the Microsoft Edge WebView2 Runtime, which is pre-installed on Windows 10 and Windows 11. On Windows Server editions, the agent installer downloads and installs WebView2 automatically during setup. **Legacy OS limitation:** On Windows Server 2012 R2 and older, the desktop UI is not available. Microsoft ended WebView2 support for these operating systems in October 2023, and installing the last compatible version (v109) would introduce known security vulnerabilities. The agent installer skips WebView2 installation on these systems to avoid this risk. The desktop UI is optional. The agent service operates with full functionality without it. All patch management, vulnerability scanning, policy enforcement, and update deployment features work identically whether or not the desktop UI is running. Server endpoints, which typically run without interactive user sessions, are unaffected by this limitation. ### Windows Update Management When the TridentStack Control agent is installed, it automatically configures the endpoint so that the platform is the primary update provider. Native Windows Update scanning and automatic installation are suppressed to prevent conflicts with managed patching. This is the behavior of **Exclusive** mode, the default for the **Windows Update Management** client setting. If you switch that setting to **Hybrid**, the agent removes the configuration described below and native Windows Update resumes its normal behavior (Windows may then install updates and restart on its own schedule, outside deployment-ring controls). The change is applied live: the agent removes or re-establishes these policies within seconds of the setting being saved. See [What Hybrid mode removes](#what-hybrid-mode-removes) below for exactly what the removal does and does not undo, and the [Client settings](/administration/settings-overview#client) reference for the full comparison and trade-offs. **What the agent configures:** The agent applies these Windows Update policies on startup and re-verifies them every 15 minutes. If the configuration is changed or removed (for example, by a Group Policy refresh, Windows servicing, or a manual edit), the agent reapplies it automatically. | Windows Version | Mode | Behavior | |----------------|------|----------| | Windows 10 2004+, Windows 11, Server 2022+ | Driver-only | Quality, feature, and other updates are blocked from Windows Update. Driver updates are still delivered through Windows Update. All non-driver patching is managed exclusively by TridentStack Control. | | Server 2019, Server 2016, older Windows 10 | Fully managed | All updates (including drivers) are blocked from Windows Update. TridentStack Control manages every update category. | **Registry policies applied:** All values are written under two machine-policy keys: - `HKLM\SOFTWARE\Policies\Microsoft\Windows\WindowsUpdate` - `HKLM\SOFTWARE\Policies\Microsoft\Windows\WindowsUpdate\AU` Because these are machine policies, they appear in **Settings > Windows Update** (under "View configured update policies" / "Policies set on your device") with a source of "Administrator" and type "Group Policy". This is expected: the agent writes them so that TridentStack Control, not native Windows Update, controls patching. | Value (key) | Data | Purpose | Applies to | |---|---|---|---| | `WUServer` (WindowsUpdate) | `http://localhost:8530` | Points update scanning at an unreachable WSUS endpoint | All Windows versions | | `WUStatusServer` (WindowsUpdate) | `http://localhost:8530` | Matching status server | All Windows versions | | `UseWUServer` (AU) | `1` | Enforces the configured (unreachable) WSUS source | All Windows versions | | `AUOptions` (AU) | `1` | Disables Automatic Updates | All Windows versions | | `NoAutoRebootWithLoggedOnUsers` (AU) | `1` | Prevents automatic restarts; TridentStack Control manages reboot timing | All Windows versions | | `SetDisableUXWUAccess` (WindowsUpdate) | `1` | Hides the "Check for updates" button so end users cannot trigger native scans that conflict with managed patching | All Windows versions | | `NoAutoUpdate` (AU) | `1` | Fully disables automatic update checks | Fully managed mode only (Server 2016/2019, older Windows 10) | | `SetPolicyDrivenUpdateSourceForDriverUpdates` (WindowsUpdate) | `0` | Routes driver updates to Windows Update (allowed through) | Driver-only mode (build 19041+) | | `SetPolicyDrivenUpdateSourceForQualityUpdates` (WindowsUpdate) | `1` | Routes quality updates to the unreachable WSUS (blocked) | Driver-only mode (build 19041+) | | `SetPolicyDrivenUpdateSourceForFeatureUpdates` (WindowsUpdate) | `1` | Routes feature updates to the unreachable WSUS (blocked) | Driver-only mode (build 19041+) | | `SetPolicyDrivenUpdateSourceForOtherUpdates` (WindowsUpdate) | `1` | Routes other updates to the unreachable WSUS (blocked) | Driver-only mode (build 19041+) | | `UseUpdateClassPolicySource` (AU) | `1` | Enables the per-category source policies above | Driver-only mode (build 19041+) | The agent also removes any stale `ScheduledInstall*` values under the AU key that would conflict with the managed configuration. ### What Hybrid mode removes Before the agent writes any of the policy values above, it records the value that was already on the device (or records that the value did not exist). Switching to **Hybrid** undoes the Exclusive configuration by restoring that recorded state, not by blanket-deleting policies: - Every value the agent set is returned to the exact value it had before the agent applied it. Values that did not exist before TridentStack Control are deleted. - The agent then restarts the Windows Update service so the change takes effect. Because Hybrid restores the device's prior state, two things follow: 1. **Windows Update restrictions that existed before the agent was installed come back exactly as they were.** For example, if the device previously had a "notify before download" Automatic Updates policy from an older management tool, that policy is what Hybrid restores. 2. **Restrictions applied by other systems are never removed.** Active Directory or local Group Policy, Microsoft Intune or another MDM, another management tool, or manual registry edits are outside TridentStack Control's ownership, and the agent does not touch them. If **Settings > Windows Update** still shows "Some settings are managed by your organization" after switching to Hybrid, the remaining policy comes from one of those other sources, not from TridentStack Control. Common places to check: the local Group Policy editor (**Computer Configuration > Administrative Templates > Windows Components > Windows Update**, in particular "Configure Automatic Updates"), your MDM console, and any other management or RMM agents installed on the device. Windows Update itself starts using the restored settings right away: the agent restarts the Windows Update service, and update scans immediately run against Microsoft's servers again. The **Windows Update page in Settings** is slower to catch up, because it reads a separately cached copy of policy that Windows only rebuilds when it next reprocesses policy (typically within a couple of hours). Until then the page may still show "Some settings are managed by your organization" even though the restriction is gone. Close and reopen the Settings app to see the current state once the cache refreshes. **Microsoft Update service registration:** so the platform can deliver updates for other Microsoft products (not just Windows), the agent registers the endpoint with the Microsoft Update service (service ID `7971f918-a847-4430-9279-4a52d1efe18d`). This is why **"Get updates for other Microsoft products"** appears as a managed policy. **Optional content (preview updates):** if an update policy enables preview cumulative updates, the agent additionally sets `SetAllowOptionalContent = 2` under the WindowsUpdate key. **Clean uninstall:** When the agent is uninstalled, all Windows Update registry changes are restored to their pre-installation values. The agent maintains a registry backup of every value it modifies, so uninstalling returns the endpoint to its original Windows Update configuration. :::info Administrators do not need to configure Windows Update suppression manually. The agent handles this automatically on every supported Windows version. If your organization uses Active Directory Group Policy to manage Windows Update settings, be aware that GPO may override the agent's configuration on domain-joined endpoints. In that case, configure your GPO to align with the agent's settings or exclude managed endpoints from the WU GPO. ::: ### Self-Update Process When an update is available, the agent: 1. Downloads the new MSI to `C:\ProgramData\TridentStack Control\downloads\agent-updates\` 2. Validates the file integrity 3. Executes the MSI upgrade silently 4. The service restarts automatically with the new version ### Application Updates Note Application updates (third-party software management) are supported on all Windows versions. On modern systems (Windows 10+, Server 2019+), the agent uses the native package manager when available. On legacy systems (Server 2016, Windows 8.1), the agent downloads and executes installers directly from the synced catalog. --- ## Linux Agent ### Supported Distributions **Primary support (DEB packages):** - Ubuntu 20.04 LTS and later - Debian 12 and later **Detected and supported (package manager integration):** - RHEL 8 and later - CentOS Stream 8 and later - Rocky Linux 8 and later - AlmaLinux 8 and later - Fedora (latest stable) - Amazon Linux 2 and later The installer script automatically detects the distribution and package manager. ### Installation Install using the one-line installer: ```bash curl -fsSL https://get.tridentstack.com/linux | sudo bash -s -- --key ``` The installer downloads the latest DEB package, installs it, configures the agent, and starts the service. **Installer options:** | Flag | Purpose | |------|---------| | `--key ` | Install with enrollment token (new installation) | | `--upgrade` | Upgrade an existing installation to the latest version | | `--uninstall` | Remove the agent and all configuration | | (no flags) | Repair/heal an existing installation (preserves credentials) | ### File Locations | Path | Contents | |------|----------| | `/opt/tridentstack/bin/` | Agent binary | | `/etc/tridentstack/` | Configuration files (root-only, mode 700) | | `/var/log/tridentstack/` | Agent log files | | `/var/lib/tridentstack/` | Runtime state and cache (root-only, mode 700) | ### Configuration Files All configuration files are located in `/etc/tridentstack/`: | File | Purpose | |------|---------| | `agent.json` | Agent identity and configuration | | `credentials.enc` | Encrypted agent credentials | ### Systemd Service | Property | Value | |----------|-------| | Service Name | `tridentstack-agent` | | Binary | `/opt/tridentstack/bin/tridentstack-agent daemon` | | Account | root | | Start Type | Enabled (starts on boot) | | Recovery | Always restart (10-second delay) | **Security hardening** applied via systemd: - `ProtectHome=yes` (cannot access /home) - `PrivateTmp=yes` (isolated /tmp) - `ProtectKernelTunables=yes` - `ProtectControlGroups=yes` **Common commands:** ```bash # Check service status sudo systemctl status tridentstack-agent # Restart the service sudo systemctl restart tridentstack-agent # View recent logs sudo journalctl -u tridentstack-agent -n 50 # Follow logs in real time sudo journalctl -u tridentstack-agent -f ``` ### Self-Update Process When an update is available, the agent: 1. Downloads the new binary 2. Replaces the binary at `/opt/tridentstack/bin/tridentstack-agent` 3. The systemd service restarts automatically with the new version ### Linux-Specific Features - **Package update detection**: The agent queries apt/dnf for available package updates and reports them as pending updates, including whether each update is a security patch. - **Docker enrichment**: Ports held by `docker-proxy` are enriched with the associated container name and image. - **Reboot detection**: The agent checks for `/var/run/reboot-required` to determine if the system needs a restart after updates. --- ## macOS Agent ### Supported Versions - macOS 14.0 (Sonoma) and later - Apple Silicon (M-series) and Intel, delivered as a single universal binary ### Installation Install with the one-line installer (run with `sudo`): ```bash curl -fsSL https://control.tridentstack.com/api/agent-packages/installer/macos/install | sudo bash -s -- --key ``` The script downloads the latest macOS package, verifies its SHA256 hash, installs it with the standard macOS installer (`.pkg`), configures the agent with your enrollment token, and registers it automatically. The package is signed and notarized, so Gatekeeper accepts it without manual steps. See [Agent Enrollment](../getting-started/agent-enrollment#macos-installation) for the full install steps. **Installer options:** | Flag | Purpose | |------|---------| | `--key ` | Install with enrollment token (new installation) | | `--uninstall` | Remove the agent and all configuration | ### File Locations | Path | Contents | |------|----------| | `/usr/local/sbin/tridentstack-agent` | Agent binary | | `/Library/Application Support/TridentStack/` | Configuration and credentials | | `/var/lib/tridentstack/` | Runtime state and staged installs | | `/var/log/tridentstack/` | Agent log files (`agent.log`) | ### Configuration Files Located in `/Library/Application Support/TridentStack/` (owned by `root:wheel`, mode 0600): | File | Purpose | |------|---------| | `agent.json` | Agent identity and configuration | | `credentials.json` | Encrypted agent credentials | ### launchd Services The macOS agent runs as two launchd jobs: | Job | Type | Account | Purpose | |-----|------|---------|---------| | `com.tridentstack.agent` | LaunchDaemon | root | The agent daemon: telemetry, inventory, updates, and policy enforcement. Runs whether or not a user is logged in. | | `com.tridentstack.ui` | LaunchAgent | logged-in user | The menu bar status app. Loads in a user session and is optional; the daemon has full functionality without it. | **Common commands:** ```bash # Confirm the daemon is running (look for a PID, not a dash, in the first column) sudo launchctl list | grep tridentstack # Follow the agent log tail -f /var/log/tridentstack/agent.log ``` ### Self-Update Process When an update is available, the agent downloads the latest macOS package, verifies it, installs it with the system installer, and the daemon relaunches on the new version. No manual action is required. ### macOS-Specific Features - **System telemetry and software inventory**: hardware, OS version, installed applications, and update status. - **Vulnerability detection**: installed software and OS version matched against CVE data, with System and Software source tabs. - **Compliance**: evaluated against the CIS Apple macOS Sonoma Benchmark. - **Application updates**: third-party applications are installed and kept current through the macOS package manager integration, using the same catalog and configurations as other platforms. See [Application Updates](../platform-guide/update-management/application-updates). - **Microsoft Office updates**: managed through Microsoft AutoUpdate (MAU). See [System Updates](../platform-guide/update-management/system-updates#microsoft-office-updates). - **FileVault status**: disk-encryption state is reported in system telemetry. :::note Operating-system update management for macOS (installing Apple system updates and major OS upgrades through a policy) is in active development. The current release manages Microsoft Office updates, compliance, vulnerability detection, and inventory on macOS. ::: --- ## Network Requirements Windows, macOS, and Linux agents require: | Requirement | Details | |-------------|---------| | **Outbound port 443** | gRPC connection to `gateway.tridentstack.com` (TLS encrypted) | | **No inbound ports** | The agent initiates all connections. No firewall rules needed for inbound traffic. | | **Proxy support** | The agent respects system proxy settings for outbound connections | The agent maintains a persistent gRPC connection to the gateway for real-time command delivery and telemetry reporting. ## Agent Version Check the installed agent version: ```powershell # Windows reg query "HKLM\SOFTWARE\TridentStack\Control" /v Version ``` ```bash # Linux /opt/tridentstack/bin/tridentstack-agent --version ``` ```bash # macOS /usr/local/sbin/tridentstack-agent --version ``` The agent version is also visible in the TridentStack Control console on the agent detail page under the **System** tab. --- # Telemetry Reference URL: https://docs.tridentstack.com/reference/telemetry Description: Reference for every category of telemetry the TridentStack Control agent collects: OS state, software, patches, network exposure, compliance, and security posture. # Telemetry Reference The TridentStack Control agent collects system state data at regular intervals and sends it to the platform for analysis, scoring, and compliance evaluation. This page documents every category of data the agent collects. ## Telemetry Categories ### System Information Core operating system and hardware details collected on agent startup and periodically refreshed. | Data Point | Description | Platforms | |------------|-------------|-----------| | OS name and version | e.g., "Windows 11 Pro 24H2", "macOS 14 Sonoma", "Ubuntu 22.04" | Windows, macOS, Linux | | OS build number | Full build including UBR (e.g., "26100.2605") | Windows | | OS architecture | x64, x86, ARM64 | Windows, macOS, Linux | | OS edition | Professional, Enterprise, ServerStandard | Windows | | System locale | e.g., "en-US" | Windows | | CPU details | Processor model and core count | Windows, macOS, Linux | | RAM | Total and available memory | Windows, macOS, Linux | | Disk partitions | Mount points, total/free space, system drive flag | Windows, macOS, Linux | ### Windows Defender Status Antivirus and endpoint protection state (Windows only). | Data Point | Description | |------------|-------------| | Signature version | Current definition version (e.g., "1.425.67.0") | | Signature age | Hours since last definition update | | Engine version | Antimalware engine version | | Product version | Defender product version | | Out-of-date flag | Whether Defender considers signatures stale | | Real-time protection | Whether real-time scanning is active | ### EDR and Third-Party Antivirus Detection of installed security products beyond Windows Defender. | Data Point | Description | Platforms | |------------|-------------|-----------| | Product name | Name of detected EDR/AV product | Windows | | Vendor | Product vendor | Windows | | Version | Installed version | Windows | | Enabled status | Whether the product is active | Windows | | Primary flag | Whether this is the primary antivirus | Windows | ### macOS Security Posture Built-in macOS security state (macOS only). | Data Point | Description | |------------|-------------| | System Integrity Protection | Whether SIP is enabled | | Gatekeeper | Whether Gatekeeper assessment is enabled | | XProtect version | Version of Apple's built-in malware signature set | | Malware Removal Tool | MRT version present on the endpoint | | FileVault | Whether full-disk encryption is enabled | ### Software Inventory Complete enumeration of installed applications. **Windows:** | Data Point | Description | |------------|-------------| | Application name | Display name from the registry | | Version | Installed version string | | Publisher | Vendor or company | | Install path | Installation directory | | Install date | When the application was installed | | Size | Installation size | | Install source | Package manager used (Winget, MSI, etc.) | | Package ID | Winget package identifier, if applicable | **Linux:** | Data Point | Description | |------------|-------------| | Package name | e.g., "openssl", "nginx" | | Version | Installed version | | Architecture | amd64, arm64, i386 | | Size | Installed size | | Source repository | main, universe, security, etc. | | Description | Short package description | **macOS:** | Data Point | Description | |------------|-------------| | Application name | Application display name | | Version | Installed version | | Install path | Application location (e.g., /Applications/Safari.app) | | Source | Where the app came from (App Store, Identified Developer, Apple, or unknown) | ### Network Configuration Network interfaces and connectivity details. | Data Point | Description | Platforms | |------------|-------------|-----------| | Interface name | e.g., "Ethernet", "eth0", "en0" | Windows, macOS, Linux | | MAC address | Hardware address | Windows, macOS, Linux | | IP addresses | IPv4 and IPv6 addresses | Windows, macOS, Linux | | Subnet / CIDR | Network mask | Windows, macOS, Linux | | Gateway | Default gateway address | Windows, macOS, Linux | | DNS servers | Configured DNS resolvers | Windows, macOS, Linux | | Connection status | Connected, disconnected | Windows, macOS, Linux | | Interface type | Ethernet, Wireless, VPN, Loopback | Windows, macOS, Linux | | Speed | Link speed in Mbps | Windows, macOS, Linux | ### Network Ports and Exposure Listening ports with process attribution and firewall context. See [Network Exposure](/platform-guide/agents/network-exposure) for full details. | Data Point | Description | Platforms | |------------|-------------|-----------| | Port and protocol | Port number with TCP/UDP | Windows, macOS, Linux | | Binding address | What address the service listens on | Windows, macOS, Linux | | Process name and path | Which process holds the port | Windows, macOS, Linux | | Process signing | Whether the executable is signed | Windows, macOS | | Firewall state | Whether the firewall allows inbound | Windows, macOS | | Service identity | Windows service name and display name | Windows | | Docker container | Container name and image for docker-proxy ports | Linux | ### Policy State Configuration policy data from multiple sources (Windows only). | Data Point | Description | |------------|-------------| | Platform policy settings | Settings pushed by TridentStack Control | | Domain GPO settings | Active Directory Group Policy (via gpresult) | | Intune MDM settings | Mobile Device Management policies (via CSP registry) | | Local registry settings | Values not claimed by other sources | | Security policies | Account lockout, password policy, UAC settings | | Audit policies | Windows audit policy configuration | ### Windows Services State of all Windows services. | Data Point | Description | |------------|-------------| | Service name | Internal service name | | Display name | Human-readable name | | Status | Running, Stopped, Disabled | | Start type | Automatic, Manual, Disabled | | Binary path | Executable location | | Service account | Account the service runs under | ### Certificates Installed certificates across all certificate stores (Windows only). | Data Point | Description | |------------|-------------| | Subject | Certificate subject (CN) | | Issuer | Certificate authority | | Thumbprint | SHA-1 fingerprint | | Expiration date | When the certificate expires | | Store | Certificate store location (Trusted Root, Personal, etc.) | | Key length | Cryptographic key size | | Self-signed flag | Whether the certificate is self-signed | ### Windows Features Installed Windows features and roles (Windows only). | Data Point | Description | |------------|-------------| | Feature name | e.g., "Hyper-V", "IIS", "Windows Subsystem for Linux" | | Status | Enabled or Disabled | ### Scheduled Tasks Scheduled tasks and their configuration (Windows only). | Data Point | Description | |------------|-------------| | Task name | Name and folder path | | Status | Ready, Running, Disabled | | Trigger | Schedule type (on boot, at logon, cron-like) | | Last/Next run | Previous and upcoming execution times | | Last result | Exit code from most recent run | | Run-as user | Account the task executes under | | Action | Command or script executed | ### Local Groups and Membership Local group membership (Windows only). | Data Point | Description | |------------|-------------| | Group name | e.g., "Administrators", "Remote Desktop Users" | | Members | Users and groups in each local group | | Member type | Local User, Domain User, Group | | Domain membership | Domain name and controller, if domain-joined | ### Defender ASR Rules Attack Surface Reduction rule state (Windows only). | Data Point | Description | |------------|-------------| | Rule ID | GUID of each ASR rule | | Rule name | e.g., "Block Office apps from creating child processes" | | Mode | Block, Warn, Audit, or Off | ### Extended Security Updates (ESU) ESU license state for older Windows versions (Windows only). | Data Point | Description | |------------|-------------| | ESU status | Active, None, or Not Applicable | | ESU year | Year 1, 2, or 3 of extended support | ### .NET Versions Installed .NET Framework and .NET runtime versions (Windows only). | Data Point | Description | |------------|-------------| | Framework versions | All installed .NET Framework versions (3.5, 4.8, etc.) | | Modern runtimes | .NET 5+ runtimes (NETCore, AspNetCore, WindowsDesktop) | ### Office Installation Microsoft Office details. Reported on Windows and macOS endpoints that have Office installed. | Data Point | Description | |------------|-------------| | Products | Installed Office products | | Architecture | 32-bit or 64-bit | | Version | Installed version | | Update channel | Current, Monthly Enterprise, Semi-Annual, etc. | ### Reboot State Whether the system is pending a restart. | Data Point | Description | Platforms | |------------|-------------|-----------| | Reboot pending | Whether updates or configuration changes require a restart | Windows, Linux | | WUA install events | Windows Update Agent events since last boot (KB, status, error code) | Windows | ### Pre-Staged Files Downloaded update files waiting to be installed. | Data Point | Description | Platforms | |------------|-------------|-----------| | KB number | Update identifier | Windows | | Filename | Downloaded file name | Windows | | File size | Size of the downloaded file | Windows | | Download time | When the file was downloaded | Windows | ## Collection Schedule | Telemetry Type | Default Interval | Trigger | |----------------|-----------------|---------| | System information | On startup, then periodic | Also on-demand via Refresh | | Software inventory | On startup, then periodic | Also after app install/uninstall | | Network ports | Every 1 hour | Also on-demand via Refresh | | Policy state | On check-in | When policy changes detected | | Certificates | Periodic | On-demand via Refresh | | Services | Periodic | On-demand via Refresh | | Defender status | Periodic | On-demand via Refresh | All telemetry can be refreshed on-demand from the agent detail page using the **Refresh** button on each tab. ## How Telemetry Is Used Telemetry data flows through several analysis services after collection: ```mermaid flowchart TD A[Agent collects telemetry] --> B[Agent Gateway receives data] B --> C[Software Inventory stored] B --> D[System State stored] B --> E[Network State stored] C --> F[Vulnerability Scanner] C --> G[Update Applicability] C --> H[App Applicability] D --> I[Compliance Evaluator] F --> J[Health Score] G --> J H --> J I --> J E --> J ``` | Service | What It Does | |---------|-------------| | **Vulnerability Scanner** | Matches installed software against CVE databases to detect known vulnerabilities | | **Update Applicability** | Determines which system updates apply to the endpoint based on OS version and installed KBs | | **App Applicability** | Determines which application updates are available based on installed software versions | | **Compliance Evaluator** | Evaluates agent state against assigned compliance frameworks (CIS, DISA STIG, etc.) | | **Health Score** | Combines vulnerability, compliance, update, and network data into the overall health score | ## Data Quality The agent includes quality safeguards in its telemetry: - **State hashing**: Each telemetry payload includes a SHA-256 hash so the server can detect duplicate data and skip redundant processing. - **Error reporting**: If any individual data collection fails, the agent reports the error alongside the data it could collect, rather than failing the entire telemetry cycle. - **Version tracking**: Each telemetry message includes a schema version for forward compatibility. ## Product Usage & Diagnostics When Usage Analytics is enabled (Settings > Privacy), TridentStack Control collects anonymized signals about how the web console itself is used, to find and fix friction and bugs. This covers: - **Page views** - which screens are visited, as route patterns (never the specific record you opened). - **Feature milestones** - that an action happened (for example, a policy was created), as a simple event. - **Interaction diagnostics** - counts only, such as how many times an editor was saved or showed a validation message, and rapid repeated clicks that suggest something felt stuck. - **Error diagnostics** - that a client-side error occurred, with the error type and screen and a scrubbed message. This data is **counts and patterns only**. It never includes field values, agent data, patch details, policy configuration values, hostnames, or personal identifiers; error messages are scrubbed of identifiers before they leave the browser. Turning Usage Analytics off stops all of it immediately.