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

# Overview

> How OASM works at a high level — the web console, the core API, infrastructure, distributed workers, connector containers, and how a scan becomes part of the inventory

OASM separates interaction from execution across five tiers:

1. **Web console** — the operations interface: asset inventory, dashboards, targets, projects, issues, reports, workflows, and management pages.
2. **Core API** — the brain of the system. It holds the business logic, coordinates scanning, stores results, and sends notifications.
3. **Infrastructure** — the platform's memory: database, queues and cache, object storage, and geo-location enrichment.
4. **Distributed workers** — the execution layer that pulls jobs and reports results back. Stateless, so it scales horizontally.
5. **Connector containers** — each security tool runs in its own isolated container, spawned on demand by a worker.

```mermaid theme={null}
graph TD
    User[User / Security Team]
    Internet[Internet / Attack Surface]

    subgraph "Tier 1 — Web console"
        Console[Web Console]
    end

    subgraph "Tier 2 — Core API"
        API[Core API]
    end

    subgraph "Tier 3 — Infrastructure"
        DB[(PostgreSQL)]
        Redis[(Redis / BullMQ)]
        Rustfs[(RustFS Object Storage)]
        GeoIP[Geo-IP Proxy]
    end

    subgraph "Tier 4 — Distributed workers"
        W1[Worker 1]
        W2[Worker N]
    end

    subgraph "Tier 5 — Connector containers"
        C1[Port scanners]
        C2[Vulnerability scanners]
        C3[Discovery and crawl]
    end

    User -->|Manage and monitor| Console
    Console <-->|REST API| API

    API <-->|Persist data| DB
    API <-->|Queue and cache| Redis
    API <-->|Store artifacts| Rustfs
    API <-->|IP enrichment| GeoIP

    API <-->|gRPC jobs| W1
    API <-->|gRPC jobs| W2

    W1 -->|Spawn| C1
    W1 -->|Spawn| C2
    W2 -->|Spawn| C3

    C1 -->|Scan| Internet
    C2 -->|Scan| Internet
    C3 -->|Scan| Internet
```

## The tiers

### 1. Web console

The Console is the single pane of glass for the platform: asset inventory, dashboards, targets, [projects](https://docs.oasm.io/project.md), [issues](https://docs.oasm.io/issue.md), [reports](https://docs.oasm.io/reports.md), [workflows](https://docs.oasm.io/workflows.md), [notifications](https://docs.oasm.io/notifications.md), and management pages such as [workers](https://docs.oasm.io/worker.md) and [API keys](https://docs.oasm.io/api-keys.md).

The Console is a stateless presentation layer: it holds no business logic of its own, communicates with the core API over secure connections, reflects job state from the registry, and streams in activity in real time.

### 2. Core API

The core API is the brain of OASM. It owns the business logic, persistence, and orchestration:

* **Authentication and workspaces** — who can access what.
* **Targets and assets** — the defined scope and the discovered surface.
* **Jobs registry** — every scan, discovery, and workflow run is tracked here.
* **Workflows and tools** — the automation and the scanning tools workers execute.
* **Integrations and notifications** — forwarding events to Slack, Telegram, webhooks, and ticketing services.
* **Reports, audit, and search** — review, trail, and retrieval over collected data.

The core API also runs background processing: it enqueues jobs, merges scan results into the inventory, and updates dashboard statistics. Two subsystems inside it get their own page:

* the **[Security Agent](https://docs.oasm.io/architecture/ai-agent.md)** — a chat-driven runtime that plans work and calls tools against workspace data and worker nodes.
* the **[event bridge](https://docs.oasm.io/architecture/event-bridge.md)** — the internal publish/subscribe bus that carries every domain event to the audit trail, notifications, integrations, and project triggers.

### 3. Infrastructure

The platform's memory. PostgreSQL stores the inventory of assets, services, and vulnerabilities, plus system state. Supporting services include a fast in-memory layer (Redis/BullMQ) used for queues, caching, and the event stream, geo-location enrichment for assets, and S3-compatible object storage for screenshots, scan artifacts, and the tool registry that serves connector binaries to workers.

> [!NOTE]
>
> Screenshots and scan artifacts are stored separately from the structured results. If artifact storage is lost, the inventory survives and artifacts can be regenerated by rescanning.

### 4. Distributed workers

Workers are the execution layer — stateless processes that authenticate to the core API with a workspace API key and pull jobs as capacity frees up. They do not run the security tools themselves: for each job they resolve the connector image from the catalog, spawn it as an isolated container, and stream results back. Because they are stateless, they scale horizontally without coordination — see [Worker](https://docs.oasm.io/worker.md).

### 5. Connector containers

Each security tool runs as its own short-lived Docker container, so a misbehaving scanner is contained and never touches the worker's own filesystem or the core API host. See [Connector containers](#connector-containers) below for the lifecycle.

## Connector containers

Scanning tools are maintained in the companion [oasm-connectors](https://github.com/oasm-platform/oasm-connectors) repository, each packaged as an isolated Docker image wrapping the tool in a small SDK adapter. OASM consumes that catalog as **data** rather than as compiled-in code, so adding or upgrading a scanner never requires an OASM release.

### The catalog

The core API reads a manifest describing every connector: its name, slug, version, image reference, the JSON Schema for its inputs (e.g. `target`), the JSON Schema for its configuration options, and default CPU/memory/timeout budgets. The console renders configuration forms directly from these schemas, which is why adding a new tool needs no UI work.

Because the catalog is data, publishing a connector upstream and re-syncing the manifest is all it takes for the tool to appear across the platform.

### The execution lifecycle

1. **Resolve.** A worker receives a job over gRPC, looks up the connector in the manifest, and knows the image to run plus the resource budget to enforce.
2. **Spawn.** The worker creates the container through the Docker Engine API, passing the job's inputs and a shared secret that authenticates the callback.
3. **Register.** The container's SDK adapter dials back to the worker over a gRPC connection and registers itself for that execution. The worker keeps the job pending until registration arrives, so a slow container boot never loses work.
4. **Execute.** The worker streams the job to the registered container. The adapter runs the underlying tool and emits findings as they are produced rather than waiting for the whole scan to finish.
5. **Stream back.** Results flow over the same gRPC connection as they are discovered — raw output plus normalized findings — and the worker forwards them to the core API, which merges them into the inventory.
6. **Finish.** The connector signals completion. The worker stops and removes the container.

Because the adapter owns the tool, tool updates are upstream changes: publish a new image, bump its version in the manifest, re-sync. The platform picks it up with no OASM release and no API contract change.

> [!NOTE]
>
> The worker reaches the Docker daemon to spawn containers, so anyone who can talk to that daemon can effectively run code on the host. Trusted connector images only: the worker is a privileged component in any deployment.

## How a scan becomes part of the inventory

A scan's journey: **trigger** (manual, workflow, or schedule) → **waiting** in queue → **running** on a worker → **results merged** into inventory (subdomains, services, ports, vulnerabilities, screenshots) → **downstream** (findings, notifications, dashboard stats) → **finished** in the job registry.

The job lifecycle is the core pipeline of OASM. Every scan, discovery, and workflow run is a **job** recorded in the jobs registry — see [Job registry](https://docs.oasm.io/architecture/job-registry.md) for the claim, result, and recovery mechanics:

1. **Trigger.** A job is created by a manual discovery, a [workflow](https://docs.oasm.io/workflows.md) run — started by a target event, a [project](https://docs.oasm.io/project.md) schedule, or new assets joining a project — or a scheduled run against a [target](https://docs.oasm.io/target.md).
2. **Waiting.** The job is queued and waits for a connected worker. Jobs at this stage consume no compute.
3. **Running.** A [worker](https://docs.oasm.io/worker.md) picks up the job and executes its tool steps in order, depending on the job category.
4. **Results merge.** The worker streams results back to the platform, which merges them into the workspace inventory.
5. **Downstream.** Merged results drive vulnerability findings, notifications, dashboard statistics, and asset state (such as TLS status).
6. **Finished.** The job ends as completed, failed, or cancelled and remains inspectable in the [Job Registry](https://docs.oasm.io/jobs.md).

> [!NOTE]
>
> Waiting is passive: nothing times a job out of the queue. A growing backlog is therefore always an execution-layer signal — no connected capacity — never a scheduling one.

## The data pipeline

The **data adapter** inside the core API turns raw connector output into structured inventory. Each job category has a merge path:

* **Subdomain discovery** — newly found hosts and domains are added as assets.
* **HTTP probing** — live web services are attached to the corresponding assets.
* **Port scanning** — open ports are attached to the corresponding assets.
* **Vulnerability scanning** — findings are linked to the corresponding assets.
* **Screenshots** — screenshots are attached to the corresponding web services.

Merged results flow to [assets](https://docs.oasm.io/asset.md) and [services](https://docs.oasm.io/asset.md), where they are enriched with [technologies](https://docs.oasm.io/asset.md), locations, and TLS state. New detections fire notifications such as "new asset detected" and "new vulnerability found" — see [Notifications](https://docs.oasm.io/notifications.md).

## Automation and events

The platform coordinates work asynchronously:

* **Job distribution** — jobs are queued and consumed by workers as capacity frees up.
* **Workflow triggers** — default workflows run when a target is added, re-scanned or synced; project workflows run on their schedules and when newly discovered assets join a project, so new exposure is scanned within minutes. See [Workflows](https://docs.oasm.io/workflows.md) and [Projects](https://docs.oasm.io/project.md).
* **Notifications** — events stream to the Console and forward through [integrations](https://docs.oasm.io/integrations/overview.md) such as Slack, Telegram, and webhooks.

Every one of those events travels over the same internal bus. See [Event bridge](https://docs.oasm.io/architecture/event-bridge.md) for the stream, the catalog, and the delivery guarantees.

## Security

* **Workspace isolation** — every workspace is a hard data boundary; assets, jobs, workflows, and settings are scoped to it.
* **Permission groups** — each member can only see and change what their role allows. See [Permissions](https://docs.oasm.io/permissions.md).
* **API key authentication** — programmatic clients and workers authenticate with the workspace API key. See [API keys](https://docs.oasm.io/api-keys.md).
* **Audit log** — an append-only audit trail records member and configuration actions. See [Audit log](https://docs.oasm.io/audit-log.md).

## Architecture vs deployment

The tiers map one-to-one onto deployable services — web console, core API, infrastructure, workers, and connector containers — but which tiers share a host and how workers scale is a deployment concern, not an architectural one. See [Deployment](https://docs.oasm.io/deployment.md).

## Related

> [card] [AI agent](https://docs.oasm.io/architecture/ai-agent.md)
>
> The Security Agent runtime — the loop, tools, plans, approvals, and memory

> [card] [Event bridge](https://docs.oasm.io/architecture/event-bridge.md)
>
> The Redis Stream bus behind audit, notifications, integrations, and project triggers

> [card] [Chat Agent](https://docs.oasm.io/chat-agent.md)
>
> The conversational surface over the agent runtime

> [card] [Worker](https://docs.oasm.io/worker.md)
>
> The distributed execution layer that consumes jobs

> [card] [Jobs](https://docs.oasm.io/jobs.md)
>
> The registry where every job lifecycle is recorded

> [card] [Tools](https://docs.oasm.io/tools.md)
>
> The scanning tools workers execute per category

> [card] [Assets](https://docs.oasm.io/asset.md)
>
> The inventory the data adapter populates

> [card] [Integrations](https://docs.oasm.io/integrations/overview.md)
>
> The outbound delivery surface for platform events

> [card] [Deployment](https://docs.oasm.io/deployment.md)
>
> How the tiers map onto deployable services


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