> ## 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.

# Attack Surface Query

> A JSON query language for everything OASM knows about your attack surface: targets, hosts, ports, HTTP, technologies, TLS, URLs, IPs, DNS and findings

> [!NOTE]
>
> **Beta.** Attack Surface Query (ASQ) is in beta. The query language is stable enough to build on, but resources and fields may still be added, and limits may change between releases.

**Attack Surface Query (ASQ)** is a small JSON query language over the data OASM collects about a workspace. One request can ask several questions at once — *which domains appeared this week, which of them expose an admin panel, and how many hosts have each port open* — and get back exactly the fields it asked for.

```json theme={null}
{
  "window": { "since": "now-7d" },
  "queries": {
    "newDomains": {
      "from": "hosts",
      "select": ["value", "firstSeen", "target.value"],
      "where": { "logic": "and", "items": [{ "field": "kind", "op": "eq", "value": "domain" }] }
    },
    "adminPanels": {
      "from": "services",
      "select": ["host.value", "port", "http.title"],
      "where": { "logic": "and", "items": [{ "field": "http.title", "op": "contains", "value": "admin" }] }
    },
    "hostsPerPort": {
      "from": "services",
      "groupBy": ["port"],
      "aggregate": { "hosts": { "fn": "countDistinct", "field": "host.id" } }
    }
  }
}
```

## What you can ask

If OASM has recorded it, you can ask about it — and the shape of the question maps onto the language:

| You want to know… | ASQ uses | Read more |
| - | - | - |
| *Which domains appeared this week?* | a time `window` | [Filtering](https://docs.oasm.io/attack-surface-query/filtering.md#time-windows) |
| *Which admin pages are not on a dev host?* | nested groups and `not` | [Groups, nesting and not](https://docs.oasm.io/attack-surface-query/filtering.md#groups-nesting-and-not) |
| *Which hosts serve HTTP but not HTTPS?* | a relation test with `none` | [Relation tests](https://docs.oasm.io/attack-surface-query/filtering.md#relation-tests) |
| *Which hosts have ten ports or more?* | a relation test with `count` | [Relation tests](https://docs.oasm.io/attack-surface-query/filtering.md#relation-tests) |
| *How many open findings per host, by severity?* | conditional aggregates | [Conditional aggregates](https://docs.oasm.io/attack-surface-query/aggregations.md#conditional-aggregates) |
| *Only the hosts with something critical?* | `having` | [having](https://docs.oasm.io/attack-surface-query/aggregations.md#having-filter-the-groups) |
| *New ports per day for a chart, in my time zone?* | `fill` and `options.timezone` | [Time series](https://docs.oasm.io/attack-surface-query/aggregations.md#time-series) |
| *The same review, for another target each week?* | a saved query with params | [Params](https://docs.oasm.io/attack-surface-query/saved-queries-and-reports.md#params) |

## Why ASQ

> [card] One request, many questions
>
> A batch holds up to ten named queries. Each comes back under its own name, and one failing query does not stop the others.

> [card] Only the fields you ask for
>
> Pick fields of a row and of its related rows (`host.value`, `http.title`), and attach lists of related rows (`include`).

> [card] Filters as precise as the question
>
> Any and/or/not combination, operators per field type (ranges, prefixes, subnets, empty values), and tests on whole lists of related rows: *none*, *every*, *at least n*.

> [card] Numbers ready for a table or a chart
>
> `count`, `countDistinct`, `sum`, `min`, `max`, `avg`, a filter per aggregate, `having`, and time series with no gaps in your own time zone.

> [card] Reusable
>
> Save a batch, give it params, run it again with other values, or render it as a PDF report.

> [card] Safe by construction
>
> Every query is compiled to read-only SQL scoped to your workspace, with values passed as parameters. A query can never read another workspace.

## Where you can use it

| Surface | How it uses ASQ |
| - | - |
| **REST API** | `POST /api/attack-surface/query`, `explain`, `schema`, report jobs and saved queries — see [Your first query](https://docs.oasm.io/attack-surface-query/quickstart.md) |
| **AI Studio agent** | The agent answers every question about your attack surface with the `query_attack_surface` tool — see [AI agent and MCP](https://docs.oasm.io/attack-surface-query/ai-agent-and-mcp.md) |
| **MCP server** | External AI assistants (Claude, Cursor, VS Code…) call the same tool with the workspace API key |
| **Reports** | A saved query can be rendered as a PDF report, one table per query — see [Saved queries and reports](https://docs.oasm.io/attack-surface-query/saved-queries-and-reports.md) |

## Key concepts

> [accordion] Batch and named queries
>
> A request is a **batch**: an object with a `queries` map. Each key is a name you choose (`newDomains`), each value is a query. An optional batch-level `window` applies to every query that does not set its own.

> [accordion] Resources
>
> A query reads one **resource** (`from`): `targets`, `hosts`, `services`, `technologies`, `tls`, `urls`, `ips`, `dnsRecords`, `vulnerabilities` or `rollups`. See [Resources and fields](https://docs.oasm.io/attack-surface-query/resources.md).

> [accordion] Related rows and lists
>
> A resource links to **single related rows** (a service has one `host`, one `target`, one latest `http` response) that you read with dot paths, and to **lists** (a host has many `services`) that you fetch with `include` or test in `where`.

> [accordion] List mode and aggregate mode
>
> A query either returns rows (`select`, `include`, paging) or counts them (`groupBy` + `aggregate`). See [Counting and grouping](https://docs.oasm.io/attack-surface-query/aggregations.md).

> [accordion] Current state, not history
>
> `technologies`, `tls` and the `http` relation describe each service's **latest** HTTP probe, so a technology that disappeared in the last scan no longer matches.

## Permissions

ASQ follows the same permission matrix as the rest of the workspace. Any member can send a query; each resource the query touches then requires its read permission:

| Resources | Permission |
| - | - |
| `hosts`, `services`, `technologies`, `tls`, `urls`, `ips`, `dnsRecords`, `rollups` | `asset.read` |
| `vulnerabilities` | `vulnerability.read` |
| `targets` | `target.read` |

A query that reaches a resource you cannot read — in `select`, `include` or `where` — is refused with `PERMISSION_DENIED`. Saved queries additionally need `report.read` / `report.write` (see [Permissions](https://docs.oasm.io/permissions.md)).

## Next steps

> [card] [Your first query](https://docs.oasm.io/attack-surface-query/quickstart.md)
>
> Send a query to the API and read the response.

> [card] [Query structure](https://docs.oasm.io/attack-surface-query/query-structure.md)
>
> `from`, `select`, related rows and `include`.

> [card] [Composing queries](https://docs.oasm.io/attack-surface-query/composing-queries.md)
>
> Combine queries, filters and lists to answer real questions.

> [card] [Resources and fields](https://docs.oasm.io/attack-surface-query/resources.md)
>
> Every resource, field, type and relation.


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