Permission Commands

FSQL includes a family of statements for managing access-control grants on Query resources: GRANT, REVOKE, EXPLAIN GRANTS, and EXPLAIN GROUPS. They let an administrator control which groups (or users) can use or edit connectors and detections, who can create resources or read the audit log, and who can manage column-masking rules.

These statements don't run a search — they're dispatched to the authorization service rather than the query engine. All grants are scoped to the current tenant (the authenticated caller's tenant); there's no syntax to target another tenant.

Note: keywords and verb names are case-insensitive (GRANT, grant, and Grant are equivalent), multiple statements can be separated with ;, and -- starts a comment that runs to the end of the line.

Verbs

There are two kinds of verb. The kind determines whether an ON <resource> clause is required.

Using a resource verb without ON is a syntax error, and using a tenant verb with ON is a syntax error.

Resource references

The ON target of a resource-scoped grant is CONNECTOR <ref>, DETECTION <ref>, or a #tag shortcut. A <ref> can be written four ways:

These forms apply equally to connectors and detections:

GRANT can_edit ON DETECTION brute-force      TO GROUP soc-analysts
GRANT can_edit ON DETECTION 'Brute force AD' TO GROUP detection-engineers

Tag shortcut — #<tag> expands to every connector currently carrying that tag, at the moment the statement runs:

GRANT can_use ON #siem TO GROUP soc-analysts

This writes one grant per matching connector. It's a point-in-time expansion, not a live rule: connectors tagged siem later aren't retroactively granted, and connectors that lose the tag keep the grants they already have. If no connector carries the tag, the statement errors rather than silently doing nothing. Tag names use lowercase letters, digits, and /, and are 2–64 chars. The #tag shortcut applies to connectors only.

Identity references

The TO / FROM target of GRANT and REVOKE:

Every tenant can have groups from two sources: entra: (groups synced from the customer's Entra/AD directory) and query: (Query-native groups, including the built-in admin/member groups). If a bare group name matches in both sources, the statement fails with an ambiguity error and you must add the entra: or query: prefix. If the name matches no group, the statement fails with a "no group named … found" error.

GRANT

Grants a permission to a group or user.

GRANT <resource-verb> ON <resource> TO USER|GROUP <identity>
GRANT <tenant-verb>             TO USER|GROUP <identity>

-- Resource-scoped
GRANT can_use  ON CONNECTOR splunk-prod         TO GROUP 'SOC Analysts'
GRANT can_edit ON CONNECTOR 550e8400-...-440000 TO GROUP soc-analysts
GRANT can_use  ON #siem                         TO GROUP soc-analysts
GRANT can_edit ON DETECTION 'Brute force AD'    TO GROUP entra:detection-engineers

-- Tenant-scoped (no ON clause)
GRANT can_create_connector TO GROUP soc-leads
GRANT can_create_detection TO GROUP detection-engineers
GRANT can_read_audit       TO GROUP query:compliance-readers
GRANT can_mask             TO GROUP compliance-team

Re-granting a permission a group or user already has is idempotent — it succeeds without error rather than complaining the grant already exists. When a tag expands to several connectors, each grant is written independently; the result reports how many were affected and lists any per-connector failures.

REVOKE

Mirrors GRANT, with FROM in place of TO.

REVOKE <resource-verb> ON <resource> FROM USER|GROUP <identity>
REVOKE <tenant-verb>             FROM USER|GROUP <identity>

REVOKE can_use  ON CONNECTOR splunk-prod FROM GROUP soc-analysts
REVOKE can_use  ON #siem                 FROM GROUP soc-analysts
REVOKE can_edit ON DETECTION brute-force FROM GROUP detection-engineers
REVOKE can_create_detection              FROM GROUP soc-leads
REVOKE can_mask                          FROM GROUP compliance-team

Revoking a permission that isn't currently in effect is a no-op success, not an error. For the #tag form, REVOKE removes grants on the connectors that carry the tag now — a connector granted under #siem that was since untagged needs an explicit per-connector REVOKE.

EXPLAIN GRANTS

Lists the grants configured in the current tenant. Both filters are optional and can be combined.

EXPLAIN GRANTS [ON <resource>] [TO USER|GROUP <identity>]

EXPLAIN GRANTS                                              -- all grants in this tenant
EXPLAIN GRANTS ON CONNECTOR splunk-prod                     -- grants on one connector
EXPLAIN GRANTS ON DETECTION 'Brute force AD'                -- grants on one detection
EXPLAIN GRANTS TO GROUP soc-analysts                        -- grants held by one group
EXPLAIN GRANTS ON CONNECTOR splunk-prod TO GROUP soc-analysts

Each row shows the subject (rendered as a group display name where known), the object (connector or detection display name, or tenant for tenant-scoped grants), the relation, who granted it, and when. The relation column can show grants beyond the FSQL verbs (e.g. admin) when they exist in the authorization model.

EXPLAIN GROUPS

Lists the groups available to grant to in the current tenant — the discovery surface for finding the names to use in GRANT … TO GROUP.

EXPLAIN GROUPS [LIKE '<pattern>']

The optional LIKE pattern is a glob (shell-style wildcards: * matches any run of characters, ? matches one), matched case-insensitively against the display name. The quotes are required.

EXPLAIN GROUPS                 -- every group in this tenant
EXPLAIN GROUPS LIKE 'soc*'     -- groups whose name starts with "soc"

Each row shows the group's source (entra / query), its id, its display name, and — for the built-in Query groups — its system kind (admin / member).

Current limitation

GRANT/REVOKE TO/FROM USER parses successfully but is rejected at execution time in the current release: granting or revoking a resource or tenant verb directly to a user by email returns "Granting to a specific user is not yet supported." (EXPLAIN GRANTS TO USER … as a filter hits the same gate.) Group grants are the supported path today for GRANT/REVOKE.

This limitation is specific to the grant verbs (can_use, can_edit, can_create_connector, can_create_detection, can_read_audit, can_mask) — it does not apply to column masking, where MASK/UNMASK/EXPLAIN MASKS FOR fully support USER identities today.