Query & Policy Editors

Relevant source files

The following files were used as context for generating this wiki page:

• frontend/pages/policies/edit/EditPolicyPage.tsx
• ee/cis/CIS-BENCHMARKS.md
• tools/fleet-slackbot/system-prompt.js
• website/scripts/build-static-content.js
• ee/cis/prompt.md
• tools/fleet-slackbot/yaml-handler.js

The Query and Policy Editors are central components of the Fleet interface, designed to facilitate the creation, modification, and management of osquery-based instructions. Queries are used for on-demand data retrieval and scheduled reporting, while Policies represent specific compliance checks that return a binary pass/fail state based on whether a query returns any rows.

These editors integrate live schema inspection, team-based access control, and YAML-based configuration to provide a unified workflow for IT and security teams. They support both global and team-specific scopes, ensuring that configuration changes are targeted and authorized according to the user's role.

Architecture and Data Flow

The editor architecture relies on React-based frontend pages that interact with specialized API services. The EditPolicyPage and EditQueryPage components manage complex state through contexts like PolicyContext, which tracks query bodies, descriptions, and platform-specific metadata.

Data Synchronization Flow

When a user opens the editor, the system fetches the existing resource via the policiesAPI or queriesAPI. The retrieved data is then populated into the component state for local editing.

Component Lifecycle

1. Authorization: The page validates the user's permissions (e.g., isGlobalAdmin, isTeamMaintainer) using the AppContext and useTeamIdParam hook. Sources: frontend/pages/policies/edit/EditPolicyPage.tsx:55-63
2. Schema Integration: A QuerySidePanel provides a searchable interface for osquery tables, allowing users to select tables and view their columns without leaving the editor. Sources: frontend/pages/policies/edit/EditPolicyPage.tsx:289-293
3. Live Validation: The editor checks if live queries are runnable via statusAPI.live_query() to ensure the backend is responsive before a user attempts to run a test query. Sources: frontend/pages/policies/edit/EditPolicyPage.tsx:189-193

Policy and Query Specifications

Fleet uses a structured YAML format for defining queries and policies, particularly within GitOps workflows. While the frontend editor provides a GUI, the underlying data structures must conform to specific schemas for validation.

Policy YAML Schema

Policies are fundamentally defined by a name, a query, and platform targets.

Field	Type	Description
name	String	Format: <Platform> - <Description> (e.g., "macOS - Firefox installed").
query	SQL String	Osquery SQL. Must return 1+ rows when compliant for CIS benchmarks.
critical	Boolean	Determines if the policy is flagged as a critical security check.
platform	String	Comma-separated list: darwin, windows, linux, chrome.
resolution	String	Human-readable steps to fix the issue if the policy fails.

Sources: tools/fleet-slackbot/system-prompt.js:145-162, tools/fleet-slackbot/yaml-handler.js:101-125

Query SQL Patterns

Queries in the editor follow standard SQL syntax but are optimized for osquery tables. For CIS compliance policies, Fleet requires a specific logic where a return of one or more rows indicates "Compliance" and zero rows indicate "Non-compliance."

-- Direct table check example
SELECT 1 FROM alf WHERE global_state >= 1;

-- Managed policy check (MDM)
SELECT 1 WHERE EXISTS (
  SELECT 1 FROM managed_policies WHERE
    domain='com.apple.SoftwareUpdate' AND
    name='CriticalUpdateInstall' AND
    (value = 1 OR value = 'true') AND
    username = ''
);

Sources: ee/cis/CIS-BENCHMARKS.md:58-75

Integration with Automation

The Policy Editor supports extended metadata that links compliance checks to automated remediation actions.

Automated Actions

Users can associate a policy with a script or software package. Only one automation action is permitted per policy.

• Run Script: A path to a shell script (e.g., .sh for macOS/Linux, .ps1 for Windows).
• Install Software: A path to a software package YAML definition.

Validation Logic

The yaml-handler.js utility performs strict validation on these configurations before they are committed to the repository:

1. Placeholder Rejection: Rejects any content containing TODO or UNABLE_TO_GENERATE.
2. Schema Integrity: Ensures required fields like query and resolution are present.
3. Platform Verification: Validates that the targeted platforms match the supported set (darwin, windows, etc.).

Sources: tools/fleet-slackbot/yaml-handler.js:132-155, tools/fleet-slackbot/system-prompt.js:159-162

Schema and Documentation Building

Fleet includes an automated build process for static content, which extracts query and policy definitions from the codebase to generate documentation and sitemaps.

Build Process Flow

The build-static-content.js script parses YAML libraries to prepare them for the Fleet website.

Static Content Generation

• Slug Generation: Unique slugs are generated from query names to provide stable URLs (e.g., /reports/macos-collect-logs).
• Tag Formatting: Tags are trimmed, lowercased, and deduplicated.
• Line Number Tracking: The script tracks the exact line number in the source YAML file, allowing users to jump from the documentation directly to the code in the GitHub repository.

Sources: website/scripts/build-static-content.js:52-65

Summary

The Query & Policy Editors bridge the gap between low-level osquery SQL and high-level endpoint management. By enforcing strict YAML schemas, integrating live schema documentation, and supporting automated remediation scripts, the system provides a robust environment for security engineering. The synchronization between frontend editor states and GitOps-ready YAML files ensures that configuration changes are both auditable and scalable across large fleets of devices.