Filtering behavior
JupiterOne aligns its query language with De Morgan's Law. This standard mathematical theory is two sets of rules or laws developed from Boolean expressions for AND, OR, and NOT gates, using two input variables, A and B. These two rules or theorems allow the input variables to be negated and converted from one form of a Boolean function into an opposite form. J1QL uses this law in filtering the results of queries.
When you use a != followed by a set of arguments offset by parentheses, such as != (A or B or C), it is equivalent to the expression != A and != B and != C. For example:
FIND jira_user WITH accountType != ("atlassian" OR "app" OR "customer")
This query above is equivalent to the following:
FIND jira_user WITH accountType != "atlassian" AND accountType != "app" AND accountType != "customer"
#S# Interpretation
In the above example, J1QL interprets the query to return all jira_user assets, excluding those that have an accountType value of atlassian or app or customer. The following tables show the resulting truth values of a complex statement that are all possible for a simple statement in both positive and negative states:
Truth table
| Entity | "fruit" | "nut-filled" | =("fruit" AND "nut-filled") | =("fruit" OR "nut-filled") |
|---|---|---|---|---|
| "fruit" | true | false | false | true |
| "nut-filled" | false | true | false | true |
| "fruit", "nut-filled" | true | true | true | true |
| "non-fruit" | false | false | false | false |
| "non-fruit", "plain" | false | false | false | false |
| undefined | false | false | false | false |
Truth table with negated queries:
| Entity | "fruit" | "nut-filled" | !=("fruit" AND "nut-filled") | !=("fruit" OR "nut-filled") |
|---|---|---|---|---|
| "fruit" | true | false | true | false |
| "nut-filled" | false | true | true | false |
| "fruit", "nut-filled" | true | true | false | false |
| "non-fruit" | false | false | true | true |
| "non-fruit", "plain" | false | false | true | true |
| undefined | false | false | true | true |
Property filtering
In J1QL, property filtering allows you to filter entities based on multiple property values. This is achieved using parentheses to group values and the OR operator to include any of the specified values. Here are a few examples of filtering by property:
FIND user_endpoint WITH platform = ("darwin" OR "linux")
FIND Host WITH tag.Environment = ("A" or "B" or "C")
FIND DataStore WITH classification != ("critical" and "restricted")
When applying property filters, J1QL follows a specific order of operations: parentheses are evaluated first, followed by comparisons such as equals (=), greater than or equal to (>=), less than or equal to (<=), and not equals (!=). Finally, AND and OR operators are evaluated in that order. This ensures proper evaluation of complex property filters in your queries.
Metadata filtering
Filtering on metadata can often be useful in performing security analysis. The example below is used to find network or host entities that did not get ingested by an integration instance. In other words, these are entities that are likely "external" or "foreign" to the environment.
FIND (Network|Host) WITH _IntegrationInstanceId = undefined
The following would find all brand new code repos created within the last 48 hours:
FIND CodeRepo WITH _beginOn > DATE.now - 24 hours AND _version = 1
By leveraging metadata properties, such as integration instance IDs or creation timestamps, it becomes possible to filter and focus on specific subsets of assets based on their metadata characteristics.
For more details on metadata properties, see the JupiterOne data model documentation.