Overview

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.

The tiers

1. Web console

The Console is the single pane of glass for the platform: asset inventory, dashboards, targets, projects, issues, reports, workflows, notifications, and management pages such as workers and API keys. 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 — a chat-driven runtime that plans work and calls tools against workspace data and worker nodes.
• the event bridge — 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.

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.

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 below for the lifecycle.

Connector containers

Scanning tools are maintained in the companion 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.

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 for the claim, result, and recovery mechanics:

1. Trigger. A job is created by a manual discovery, a workflow run — started by a target event, a project schedule, or new assets joining a project — or a scheduled run against a target.
2. Waiting. The job is queued and waits for a connected worker. Jobs at this stage consume no compute.
3. Running. A worker 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.

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 and services, where they are enriched with technologies, locations, and TLS state. New detections fire notifications such as “new asset detected” and “new vulnerability found” — see Notifications.

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 and Projects.
• Notifications — events stream to the Console and forward through integrations such as Slack, Telegram, and webhooks.

Every one of those events travels over the same internal bus. See Event bridge 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.
• API key authentication — programmatic clients and workers authenticate with the workspace API key. See API keys.
• Audit log — an append-only audit trail records member and configuration actions. See Audit log.

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.

Related