> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasm.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering

> Narrow Attack Surface Query results with where: conditions, nested and/or groups, not, operators per field type, relation tests and time windows

`where` decides which rows a query returns. It reads like the sentence you would say out loud: *services on port 80 or 443 whose page title mentions admin* becomes

```json theme={null}
{
  "logic": "and",
  "items": [
    { "field": "port", "op": "in", "value": ["80", "443"] },
    { "field": "http.title", "op": "contains", "value": "admin" }
  ]
}
```

A filter is a tree built from four kinds of items. You can mix them freely:

> [card] Condition
>
> `{ "field", "op", "value" }` tests one field: `port in [80, 443]`.

> [card] Group
>
> `{ "logic": "and" | "or", "items": [...] }` combines items, like parentheses.

> [card] Not
>
> `{ "not": <item> }` keeps the rows the item does *not* match.

> [card] Relation test
>
> `{ "relation": "services", … }` asks about a list of related rows as a whole: *has none*, *all of them*, *at least five*.

The filter always runs inside your workspace: no combination of `or` and `not` can reach beyond it.

## Conditions

**field** `string` *required*

A field of the resource (`port`), of a related row (`http.title`, `target.value`), or of a list (`technologies.name`, see [Conditions on a list](#conditions-on-a-list)).

**op** `string` *required*

The operator. Which ones a field accepts depends on its type: see [Operators](#operators).

**value** `string | string[]`

**Always strings**, even for numbers and booleans (`"443"`, `"true"`). An array for the list operators (`in`, `notIn`, `inSubnet`, `notInSubnet`, `containsAll`, `containsAny`), a pair `[from, to]` for `between`, and nothing at all for `isNull` / `isNotNull`.

A value that does not fit the field — `"abc"` for a port, `"urgent"` for a severity, `"fe80::1%eth0"` for an IP — is refused before anything runs, with the path of the faulty value.

## Groups, nesting and not

The top of a `where` is always a group. Inside it, a group can hold conditions and other groups, up to **four levels** deep, so any boolean expression can be written down.

*Admin or login pages that are not on a development host:*

```json theme={null}
{
  "logic": "and",
  "items": [
    { "logic": "or", "items": [
      { "field": "http.title", "op": "contains", "value": "admin" },
      { "field": "http.title", "op": "contains", "value": "login" }
    ] },
    { "not": { "logic": "or", "items": [
      { "field": "host.value", "op": "startsWith", "value": "dev-" },
      { "field": "host.value", "op": "endsWith", "value": ".internal" }
    ] } }
  ]
}
```

* `not` wraps any item: a condition, a group or a relation test.
* A filter holds at most **50 conditions** (20 for the AI agent and MCP). Relation tests count as one condition each.

> [!TIP]
>
> Filters written before nesting existed use `"conditions"` instead of `"items"` in inner groups (`{ "logic": "or", "conditions": [...] }`). That form still works.

## Operators

| Field type | Operators | Value | Examples |
| - | - | - | - |
| text | `eq`, `neq`, `contains`, `notContains`, `startsWith`, `endsWith`, `in`, `notIn` | any string; `contains`, `startsWith` and `endsWith` ignore case | `value`, `url`, `http.title`, `name` |
| int | `eq`, `neq`, `in`, `notIn`, `gt`, `gte`, `lt`, `lte`, `between` | `"443"`; `between` takes `["1", "1024"]` | `port`, `http.statusCode`, `daysToExpiry` |
| number | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `between` | `"7.5"` | `cvssScore`, `epssScore` |
| bool | `eq`, `neq` | `"true"` or `"false"` | `isOpen`, `isNew`, `isPrimary`, `wildcard` |
| enum | `eq`, `neq`, `in`, `notIn` | one of the listed values | `kind`, `severity`, `detectionStatus`, `type` |
| id | `eq`, `neq`, `in`, `notIn` | an `id` from an earlier result | `id`, `host.id` |
| ip | `eq`, `neq`, `in`, `notIn`, `inSubnet`, `notInSubnet` | `"10.0.0.1"`; the subnet operators take CIDRs | `ip` |
| time | `gt`, `gte`, `lt`, `lte`, `between` | a [time expression](#time-expressions); `between` takes `["now-7d", "now"]` | `firstSeen`, `lastSeen`, `notAfter` |
| list of strings | `eq`, `neq`, `contains`, `in`, `notIn`, `containsAll`, `containsAny` | see below | `cve`, `cwe`, `tags`, `ports` |

* **`between`** includes both ends: `port between ["1", "1024"]` matches 1 and 1024.
* **Lists of strings** (`cve`, `tags`…): `eq` / `in` match when the list contains that element, `containsAny` when it shares at least one element with your array, `containsAll` when it holds every element of it.

> [!TIP]
>
> `contains`, `startsWith` and `endsWith` on large text fields (`value`, `url`, `http.title`, finding `name`) cost more than `eq` or `in`. Prefer exact values when you have them.

### Empty values

Some fields can be empty: a service with no HTTP response has no `http.title`, a finding may have no `cvssScore`, a host never seen by a scan has no `lastSeen`. Every such field accepts two extra operators, which take no `value`:

```json theme={null}
{ "field": "http.title", "op": "isNull" }
{ "field": "cvssScore", "op": "isNotNull" }
```

An empty value never matches a positive operator and **always matches** a negative one (`neq`, `notIn`, `notContains`, `notInSubnet`): a service without a title is not in `contains "admin"`, and is in `notContains "admin"`. To leave those rows out, add `isNotNull` on the same field.

## Conditions on a list

A condition on a field of a **list** (`technologies.name` on `services`, `vulnerabilities.severity` on `hosts`) looks at the related rows:

* A positive operator means **"has at least one related row that matches"**.
* A negative operator (`neq`, `notIn`, `notContains`) means **"has no related row that matches"**.

```json Hosts with a critical finding theme={null}
{ "from": "hosts", "select": ["value"],
  "where": { "logic": "and", "items": [
    { "field": "vulnerabilities.severity", "op": "eq", "value": "critical" } ] } }
```

```json Services running nginx theme={null}
{ "from": "services", "select": ["host.value", "port"],
  "where": { "logic": "and", "items": [
    { "field": "technologies.name", "op": "eq", "value": "nginx" } ] } }
```

```json Hosts without port 443 theme={null}
{ "from": "hosts", "select": ["value"],
  "where": { "logic": "and", "items": [
    { "field": "services.port", "op": "neq", "value": "443" } ] } }
```

This is the quick form. When you need several conditions on **the same** related row, or anything other than "at least one", use a relation test.

## Relation tests

A relation test asks a question about a whole list of related rows.

```json theme={null}
{ "relation": "services", "quantifier": "none", "where": { "logic": "and", "items": [
  { "field": "port", "op": "eq", "value": "443" } ] } }
```

**relation** `string` *required*

A list of the resource (`services` on `hosts`), or one reached through related rows (`host.vulnerabilities` on `services`).

**quantifier** `"some" | "none" | "every"` (default: some)

* `some`: at least one related row matches `where`. Without `where`: the row has any related row at all.
* `none`: no related row matches `where`. Without `where`: the row has no related rows.
* `every`: every related row matches `where` (required here). A row with no related rows passes.

**count** `object`

`{ "op": "eq" | "neq" | "gt" | "gte" | "lt" | "lte", "value": "<n>" }`: compares the **number** of related rows (those matching `where`, if given) with a number. Use either `quantifier` or `count`, not both.

**where** `object`

A filter on the related rows. Its fields are the related resource's own: `port`, not `services.port`. It cannot contain another list.

Unlike a condition on a list, every condition inside one relation test applies to **the same related row**:

```json HTTP but no HTTPS theme={null}
{ "from": "hosts", "select": ["value"],
  "where": { "logic": "and", "items": [
    { "relation": "services", "where": { "logic": "and", "items": [
      { "field": "port", "op": "in", "value": ["80", "8080"] } ] } },
    { "relation": "services", "quantifier": "none", "where": { "logic": "and", "items": [
      { "field": "port", "op": "eq", "value": "443" } ] } } ] } }
```

```json Only web ports open theme={null}
{ "from": "hosts", "select": ["value"],
  "where": { "logic": "and", "items": [
    { "relation": "services", "quantifier": "every", "where": { "logic": "and", "items": [
      { "field": "port", "op": "in", "value": ["80", "443"] } ] } } ] } }
```

```json Ten ports or more theme={null}
{ "from": "hosts", "select": ["value"],
  "where": { "logic": "and", "items": [
    { "relation": "services", "count": { "op": "gte", "value": "10" } } ] } }
```

```json A finding both critical and open theme={null}
{ "from": "hosts", "select": ["value"],
  "where": { "logic": "and", "items": [
    { "relation": "vulnerabilities", "where": { "logic": "and", "items": [
      { "field": "severity", "op": "eq", "value": "critical" },
      { "field": "isOpen", "op": "eq", "value": "true" } ] } } ] } }
```

> [!NOTE]
>
> A relation test reads the related resource, so it needs that resource's permission: a test on `vulnerabilities` requires `vulnerability.read`, even when the query only returns hosts.

A filter selects parent rows; it does not change which children an `include` returns. To get only matching children, put the same condition in the include's own `where` (see [Composing queries](https://docs.oasm.io/attack-surface-query/composing-queries.md#pattern-6-filter-the-included-children)).

## Time expressions

A time value is one of:

| Form | Meaning |
| - | - |
| `now` | The batch's evaluation time (`meta.now`); every query of a batch uses the same one |
| `now-30m`, `now-24h`, `now-7d`, `now-2w` | Minutes, hours, days or weeks before `now` (1 to 3650 units) |
| `now+30d` | After `now`, **in filters only**: certificates expiring within 30 days |
| `2026-11-01T00:00:00Z`, `2026-11-01T07:00:00+07:00` | ISO 8601 with an offset; a time without an offset is refused |

```json theme={null}
{ "from": "tls", "select": ["host", "notAfter"],
  "where": { "logic": "and", "items": [ { "field": "notAfter", "op": "between", "value": ["now", "now+30d"] } ] } }
```

## Time windows

A **window** keeps the rows whose time field falls in `[since, until)`. It is the short way to say *recent*:

```json theme={null}
{ "window": { "since": "now-7d" }, "queries": { "newHosts": { "from": "hosts" } } }
```

* On the batch, a window applies to every query that does not set its own. On a query, it overrides the batch's.
* `"window": null` on a query reads all time, even when the batch has a window.
* No window at all means all time.
* The window applies to the resource's `firstSeen` by default; `"windowField": "lastSeen"` uses another time field (*hosts seen by a scan this week*).
* `until` defaults to `now` and cannot be more than a day in the future.
* `rollups` has no time field: give it `"window": null` when the batch has a window.

> [!NOTE]
>
> `firstSeen` is when OASM first recorded the row, `lastSeen` when a scan last reported it. *New this week* is a window on `firstSeen`; *still alive this week* is a window on `lastSeen`. The `isNew` field is different again: the row was found by the latest finished run of its workflow on that target (the "new" badge of the console).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.