Architecture

OASM separates the way you interact with the platform from the heavy scanning work it does for you, across five tiers:

1. Web console — the operations interface you use every day: asset inventory, dashboards, targets, groups, 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, groups, issues, reports, workflows, notifications, and management pages such as workers and API keys. The Console runs in your browser, communicates with the core API over secure connections, and holds no business logic of its own — it simply presents what the platform knows and lets you act on it. It 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 — what you monitor and what has been discovered.
• 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 — how you review and find what the platform has collected.

The core API also runs background processing: it enqueues jobs, merges scan results into your inventory, sends notifications, and updates dashboard statistics. It also hosts the Security Agent — a chat-driven runtime that plans work and calls tools against workspace data and worker nodes.

​

3. Infrastructure

The platform’s memory. PostgreSQL stores your inventory of assets, services, and vulnerabilities, plus system state. Supporting services include a fast in-memory layer (Redis/BullMQ) used for queues and caching, geo-location enrichment for your 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 — small programs that connect securely 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 your 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 the Security Agent works

The core API also hosts the Security Agent, a chat-driven runtime that answers questions about your attack surface and, in Agent mode, acts on them. It is not drawn in the platform diagram above because it lives inside Tier 2 rather than forming its own tier.

​

The loop

A run is a streaming loop: the model receives the conversation, the system prompt for the current mode, the conversation history, and the tool definitions, then emits text or tool calls. Each tool call executes and its result is fed back, so the model can chain calls until it has what it needs — up to a configured step limit. The system prompt is assembled from a small set of files: a base prompt shared by all modes, a mode-specific prompt (Ask or Agent), and a plan prompt added only when plan mode is active. Skills are appended as a list of available specialist instructions, which the agent loads on demand rather than carrying in full context up front.

​

Tools

The agent’s tools fall into three groups:

• Workspace data tools — read and query your inventory: assets, vulnerabilities, targets, ports, technologies, TLS certificates, issues, jobs, workers, and dashboard statistics. Every call is scoped to the current workspace, so the agent cannot see another tenant’s data.
• Web fetch — retrieves public pages for CVE records, vendor advisories, and exploit references when workspace data alone is not enough.
• External MCP tools — tools you connect from outside OASM, discovered from configured MCP servers and passed through the same approvals gate as built-in tools.

One tool is special: remote command execution. Instead of reading data, it runs a shell command on a connected worker node — never on the core API host — which is how the agent uses real security tooling like nmap, dig, and curl against your scope.

​

Plans and approvals

Plans and approvals are two separate gates that answer different questions. A plan is the agent’s proposed sequence of steps for the investigation, shown to you before execution. Approving a plan also decides how the rest of the run behaves: either it proceeds automatically, or it asks before each command. Once approved, the plan is fixed — the agent cannot restructure it mid-run, so the step list you approved is the step list that executes. The approvals gate then governs individual calls as they happen:

• Read-only tools run without asking.
• Side-effecting calls — remote commands and non-read-only MCP tools — block until you approve. You can approve once, approve for the rest of the conversation, or reject with feedback telling the agent what to do instead.
• A rejected command is not retried. The agent follows your feedback or asks how to proceed.

​

Memory

Findings are remembered at two scopes. Short-term memory lives in Redis for the duration of a conversation, so the agent can recall what it already discovered without re-querying. Long-term memory is persisted per workspace, carrying knowledge across conversations — target profiles, known exposures, and analysis worth keeping. Messages and every tool call are persisted too, so the full history of a run — what was called, with what arguments, and what came back — remains inspectable after the fact.

​

How a scan becomes part of your 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:

1. Trigger. A job is created by a manual discovery, a workflow run, 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 your 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 to your assets.
• HTTP probing — live web services are attached to your assets.
• Port scanning — open ports are attached to your assets.
• Vulnerability scanning — findings are linked to your assets.
• Screenshots — screenshots are attached to your 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 chaining — workflows can react to lifecycle events, so a discovery workflow can automatically kick off a scan workflow when it finishes. See Workflows.
• Notifications — events stream to the Console and forward through integrations such as Slack, Telegram, and webhooks.

​

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.

​

Deploying the architecture

The full stack — web console, core API, infrastructure, workers, and connector containers — is defined in the platform’s Docker Compose deployment. See Deployment for production configuration, scaling, and the environment reference.

​

Related