Other Commands
The star of the FSQL show is the QUERY
command. But FSQL has a supporting cast of other commands. The EXPLAIN
commands allow users to interrogate the schema, list their connections, or review FSQL documentation, and the VALIDATE QUERY
command checks the validity of an FSQL query.
Note: if you're using FSQL through Query's search UI, you only have access to the QUERY
command today. API and console users have access to the full set of commands shown here.
EXPLAIN VERSION
FSQL is new technology and advancing quickly. The EXPLAIN VERSION
command can retrieve the FSQL and Query Data Model versions of the FSQL server you're working with.
EXPLAIN VERSION
Response:
{
"fsql": "fsql-0.5.0",
"qdm": "qdm-1.4.1+ocsf-1.4.0"
}
EXPLAIN ATTRIBUTES
FSQL owes a lot of its power to its attribute selectors. If you'd like to test an attribute selector, you can see what one evaluates to with the EXPLAIN ATTRIBUTES
command.
For example, if you want to see all fields of network_activity
that are IP observables, try the following:
EXPLAIN ATTRIBUTES network_activity.%ip
Response:
[
"network_activity.device.ip",
"network_activity.device.network_interfaces.ip",
"network_activity.dst_endpoint.intermediate_ips",
"network_activity.dst_endpoint.ip",
"network_activity.dst_endpoint.ip_intelligence.ip",
"network_activity.dst_endpoint.proxy_endpoint.intermediate_ips",
"network_activity.dst_endpoint.proxy_endpoint.ip",
"network_activity.load_balancer.dst_endpoint.intermediate_ips",
"network_activity.load_balancer.dst_endpoint.ip",
"network_activity.load_balancer.ip",
"network_activity.osint.email.x_originating_ip",
"network_activity.proxy.intermediate_ips",
"network_activity.proxy.ip",
"network_activity.proxy.ip_intelligence.ip",
"network_activity.proxy_endpoint.intermediate_ips",
"network_activity.proxy_endpoint.ip",
"network_activity.proxy_endpoint.ip_intelligence.ip",
"network_activity.proxy_http_request.x_forwarded_for",
"network_activity.src_endpoint.intermediate_ips",
"network_activity.src_endpoint.ip",
"network_activity.src_endpoint.ip_intelligence.ip",
"network_activity.src_endpoint.proxy_endpoint.intermediate_ips",
"network_activity.src_endpoint.proxy_endpoint.ip"
]
EXPLAIN SCHEMA
The EXPLAIN SCHEMA
command describes the schema for a given attribute selection. It expands the attribute selector expression and responds with the schema definition for each path that's been selected. If you're familiar with OCSF schema definitions, you should feel right at home with the output.
EXPLAIN SCHEMA network_activity.proxy.%ip
Response:
{
"network_activity.proxy.intermediate_ips": {
"caption": "Intermediate IP Addresses",
"type": "ip_t",
"requirement": "optional",
"description": "The intermediate IP Addresses. For example, the IP addresses in the HTTP X-Forwarded-For header.",
"is_array": true,
"observable": 2
},
"network_activity.proxy.ip": {
"caption": "IP Address",
"type": "ip_t",
"requirement": "recommended",
"description": "The IP address of the endpoint, in either IPv4 or IPv6 format.",
"is_array": false,
"observable": 2
},
"network_activity.proxy.ip_intelligence.ip": {
"caption": "IP Address",
"type": "ip_t",
"requirement": "optional",
"description": "The IP address, in either IPv4 or IPv6 format.",
"is_array": false,
"observable": 2
}
}
By default, FSQL removes keys from the response with null
values. You can enable them by adding WITH NULLS
after the attribute selector (WITHOUT NULLS
has the opposite effect). For example:
EXPLAIN SCHEMA network_activity.proxy.ip WITH NULLS
Response:
{
"network_activity.proxy.ip": {
"caption": "IP Address",
"type": "ip_t",
"requirement": "recommended",
"description": "The IP address of the endpoint, in either IPv4 or IPv6 format.",
"is_array": false,
"@deprecated": null,
"enum": null,
"group": null,
"observable": 2,
"profile": null,
"sibling": null,
"object_type": null,
"object_name": null,
"type_name": null
}
}
EXPLAIN CONNECTORS
The EXPLAIN CONNECTORS
command lists all connectors available to your FSQL session.
The output includes the connector ID, connector name, whether or not the connector is enabled, and the name of the source platform.
EXPLAIN CONNECTORS
Response:
[
{
"id": 1389,
"name": "SL-CTM-AcctChg",
"is_enabled": true,
"platform_name": "AwsSecurityLake"
},
{
"id": 1192,
"name": "WHOIS",
"is_enabled": true,
"platform_name": "Whois"
},
{
"id": 1193,
"name": "AV",
"is_enabled": true,
"platform_name": "AlienVault"
},
{
"id": 1199,
"name": "Virus Total",
"is_enabled": true,
"platform_name": "VirusTotal"
},
{
"id": 1142,
"name": "ATB - Intune",
"is_enabled": true,
"platform_name": "MicrosoftIntune"
},
{
"id": 1370,
"name": "SecOps AWS ALB",
"is_enabled": true,
"platform_name": "GoogleSecOps"
},
{
"id": 1233,
"name": "Lancet3 DLP Findings",
"is_enabled": true,
"platform_name": "AzureLogAnalytics"
}
]
EXPLAIN MANUAL
The EXPLAIN MANUAL
command responds with this documentation in Markdown format.
EXPLAIN QUERY
The EXPLAIN QUERY
command shows how your FSQL query is converted into Query's internal search syntax. Invoke it with any search QUERY
input to see how it will be interpreted by Query's engine.
The response has two key elements.
expanded_query
shows your FSQL query with all attribute selectors in the SHOW
and WITH
clauses expanded and any additional attributes or filters that were added by Query.
ast_query
shows how your query will be translated into Query's internal hierarchical search syntax. The SHOW
and WITH
clauses are separate for each event type and list operations are explicitly assigned.
The values of these fields are meant to be human readable, and their formatting may change slightly.
EXPLAIN QUERY http_activity.* WITH %ip='136.103.57.67'
Response:
{
"command": "explain ast query http_activity.* with %ip='136.103.57.67'",
"expanded_query": "QUERY\nSHOW\n http_activity.action_id,\n http_activity.activity_id,\n http_activity.app_name,\n http_activity.category_uid,\n http_activity.class_uid,\n http_activity.confidence_id,\n http_activity.confidence_score,\n http_activity.count,\n http_activity.disposition_id,\n http_activity.duration,\n http_activity.end_time,\n http_activity.http_status,\n http_activity.is_alert,\n http_activity.message,\n http_activity.record_id,\n http_activity.risk_details,\n http_activity.risk_level_id,\n http_activity.risk_score,\n http_activity.severity_id,\n http_activity.start_time,\n http_activity.status_code,\n http_activity.status_detail,\n http_activity.status_id,\n http_activity.time,\n http_activity.timezone_offset,\n http_activity.type_uid\nWITH ANY http_activity.observables.type_id EQ 'IP_ADDRESS'\n AND ANY http_activity.observables.value EQ '136.103.57.67'\n AND ANY http_activity.time GT '2025-06-27T04:07:44'\n AND ANY http_activity.time LE '2025-06-28T04:07:44'\nSINCE 2025-06-27T04:07:44\nUNTIL 2025-06-28T04:07:44\n",
"ast_query": "EVENT: http_activity\n WITH\n ANY observables { (type_id EQ 'IP_ADDRESS' AND value EQ '136.103.57.67') }\n AND time GT '2025-06-27T04:07:44'\n AND time LE '2025-06-28T04:07:44'\n SHOW\n action_id\n activity_id\n app_name\n category_uid\n class_uid\n confidence_id\n confidence_score\n count\n disposition_id\n duration\n end_time\n http_status\n is_alert\n message\n record_id\n risk_details\n risk_level_id\n risk_score\n severity_id\n start_time\n status_code\n status_detail\n status_id\n time\n timezone_offset\n type_uid\n"
}
Below is an example from a terminal† with newlines rendered:
>>> EXPLAIN AST QUERY authentication.#primary WITH %ip='1.2.3.4'
EVENT: authentication
SHOW
auth_protocol_id
is_mfa
is_remote
logon_type_id
message
record_id
status_code
status_detail
status_id
WITH
ANY observables { (type_id EQ 'IP_ADDRESS' AND value EQ '1.2.3.4') }
AND time GT '2025-06-27T09:55:23'
AND time LE '2025-06-28T09:55:23'
† Terminal users may wish to useEXPLAIN AST QUERY
or EXPLAIN EXPANDED QUERY
to specify which format they prefer in the output.
EXPLAIN GRAPHQL QUERY
If you're familiar with Query's GraphQL search API, you can use the EXPLAIN GRAPHQL QUERY
command to translate an FSQL query into a GraphQL request. The example below shows a translated search query, but the EXPLAIN GRAPHQL
command also provides a subscription query that can be used to retrieve results for a submitted search query.
EXPLAIN GRAPHQL QUERY network_activity.* WITH network_activity.count < 50 BEFORE 1h AFTER 720h
Response:
query {
search {
id
status
data {
network_activity(
filter: {
op: AND
conditions: [
{
fields: {
time: {
greater_than_equals: "2025-03-29T14:49:02.884049"
less_than_equals: "2025-04-28T13:49:02.883945"
}
}
}
{ op: OR, conditions: [{ fields: { count: { less_than: 50 } } }] }
]
}
) {
connection_id
action_id
activity_id
app_name
category_uid
class_uid
confidence_id
confidence_score
count
disposition_id
duration
end_time
is_alert
message
record_id
risk_details
risk_level_id
risk_score
severity_id
start_time
status_code
status_detail
status_id
time
timezone_offset
type_uid
}
}
}
}
VALIDATE QUERY
The VALIDATE QUERY
command validates a FSQL query for debugging.
VALIDATE QUERY #network.* WITH @ip = '10.0.0.1'
Response:
{
"is_valid": true,
"input": "validate query #network.* with @ip = '10.0.0.1'"
}
Updated 1 day ago