Guides
Start typing to search…

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 22 days ago