Open Attack Surface Management (OASM)

AI-powered, open-source Attack Surface Management platform. Discover, monitor, and secure your digital infrastructure — from assets to exposures — backed by distributed scanning, real-time monitoring, and AI-driven analytics.

Features • System Architecture • Connectors • Installation • Developer Guide • Screenshots

Features

• Asset Discovery & Management — Automatically discover and manage internet-facing assets (IPs, ports, services, technologies) as a continuously updated inventory.
• Vulnerability Assessment — Detect vulnerabilities and misconfigurations with issue tracking, risk analysis, and remediation guidance.
• Technology Detection — Identify frameworks, platforms, and services running on discovered assets.
• Groups & Targeted Scanning — Organize assets into groups with custom tool configurations and execution schedules for focused scans.
• Distributed Scanning Engine — Horizontally scalable workers with a high-performance scanning engine and fault-tolerant job distribution.
• Tool Integration — Pluggable security-tool connectors (nuclei, subfinder, httpx, naabu, dnsx, and more) sourced from the separate oasm-connectors repository, plus an extensible SDK for custom tools.
• Workflow Automation — Automated scan scheduling, alerts, and remediation workflows.
• Real-time Monitoring — Live notifications and a statistics dashboard fed by a streaming event channel.
• Search & Analytics — Full-text search, asset filtering, risk trend analysis, and reporting.
• Integrations — Alert to Slack, Telegram, or any webhook, and pull assets in automatically from AWS, Cloudflare, and Vercel on a schedule.
• AI Assistant Integration — MCP endpoint enabling AI assistants (OpenAI, Anthropic, Google) to query and analyze asset data via natural language.
• Geo-IP Enrichment — Automatic IP geolocation enrichment for discovered assets.
• File Storage — S3-compatible object storage for scan artifacts and reports.
• Multi-workspace — Isolated environments for different organizations, projects, or environments.

System Architecture

The system runs on a distributed architecture consisting of:

• A web console for user interaction, asset management, and real-time monitoring.
• A core API service responsible for business logic, data persistence, and job orchestration.
• A queue and caching layer enabling asynchronous job distribution, rate limiting, and system decoupling.
• Distributed worker nodes that pull connector images and run scans in isolated containers, designed for horizontal auto-scaling and fault tolerance.
• A relational database for persistent storage of assets, scan results, and system state.
• S3-compatible object storage for scan artifacts and reports.
• A Geo-IP proxy service for automatic IP geolocation enrichment.
• An MCP (Model Context Protocol) endpoint that provides structured context to AI systems.
• Integration with AI/LLM components for intelligent querying, analysis, and automation over collected asset data.

graph TD
    %% Actors & External
    User[User / Security Team]
    AI[AI Assistant / LLM]
    Internet[Internet / Attack Surface]

    %% Core Components
    subgraph "OASM Platform"
        Console[Web Console]
        API[Core API Service]
        DB[(Database)]
        Queue[(Queue & Cache)]
        MCP[MCP Endpoint]
        Storage[(Object Storage)]
        GeoIP[Geo-IP Proxy]

        subgraph "Execution Plane"
            W1[Worker 1]
            W2[Worker 2]
            WN[Worker N]
        end

        subgraph "Connector Containers"
            C1[Connector Image]
            CN[Connector Image N]
        end
    end

    %% Relationships
    User -->|Manage & Monitor| Console
    Console <-->|REST API| API

    API <-->|Persist Data| DB
    API <-->|Queue / Cache| Queue
    API <-->|Store Artifacts| Storage
    API <-->|IP Enrichment| GeoIP

    %% Job Flow
    API <-->|Jobs| W1
    API <-->|Jobs| W2
    API <-->|Jobs| WN

    %% Scan — workers dispatch jobs to connector containers they spawn
    W1 -->|Dispatch| C1
    W2 -->|Dispatch| CN
    WN -->|Dispatch| C1
    C1 -->|Scan| Internet
    CN -->|Scan| Internet
    C1 -.->|Stream Findings| W1
    CN -.->|Stream Findings| WN

    %% AI Flow
    AI <-->|Query Context| MCP
    MCP <-->|Fetch Asset Data| API

Loading

Connectors

Scanning tools are not hard-wired into this repository. They live in a companion repository, oasm-connectors, which ships each tool as an isolated Docker image wrapping a small Go SDK adapter. Open ASM consumes that catalog as data: it reads the connector manifest, resolves the image for a requested tool, and lets the worker run it on demand.

flowchart LR
    MAN["oasm-connectors<br/>manifest.json"] -->|"task sync-connectors"| CORE[Core API]
    CORE -->|"ExecutionCommand: image + inputs"| WK[Worker]
    WK -->|"pull connector image"| DR[Docker Runtime]
    DR --> CT[Connector container]
    CT -.->|"stream findings"| WK
    WK -.->|"persist findings"| CORE

Loading

How the two repositories fit together:

1. Catalog — oasm-connectors aggregates every <category>/<connector>/manifest.yaml into a single manifest.json (built by its combine-manifest command). Each entry declares the connector's image, capabilities, inputs schema, and resource defaults.
2. Sync — task sync-connectors pulls that manifest into core-api/resources/connectors/manifest.json, so the platform always knows which connectors exist and what each one accepts.
3. Dispatch — for a scan, Core resolves the connector image from the manifest, validates the inputs against the connector's schema, and hands the worker an execution command carrying the image reference and the resolved inputs.
4. Execution — the worker pulls the image and starts the container, passing the inputs through.
5. Findings — inside the container the SDK adapter runs the wrapped tool and streams findings back to the worker, which persists them through Core into the asset inventory.

Because connectors are versioned images referenced by the manifest, adding or upgrading a tool never requires an Open ASM release — you publish the connector in oasm-connectors and re-sync the manifest (see that repository's README for the connector contract, SDK adapter interface, and Dockerfile pattern).

Screenshots

Installation

Docker (Recommended)

To quickly get started with OASM using Docker:

1. Clone the repository:

   git clone https://github.com/oasm-platform/open-asm.git
   cd open-asm

2. Copy the example environment files (note the dot in the worker template name):

   cp core-api/example.env core-api/.env
   cp console/example.env console/.env
   cp worker/.example.env worker/.env

3. Pull the connector catalog:

   task sync-connectors

4. Start the services:

   task docker-compose

This will launch the entire system — console, core API, 3 workers, database, queue, Geo-IP proxy, and S3-compatible object storage — with migrations applied before the API starts. Access the console at http://localhost:3000.

Not using the task runner? task docker-compose derives the host docker.sock group gid the worker needs. If you start with raw Compose instead, pass that gid explicitly — otherwise vulnerability-scan jobs fail with permission denied on Linux:

WORKER_DOCKER_GID=$(stat -c '%g' /var/run/docker.sock 2>/dev/null || echo 0) docker compose up -d --build

Pre-built Images

You can also use pre-built images from Docker Hub:

WORKER_DOCKER_GID=$(stat -c '%g' /var/run/docker.sock 2>/dev/null || echo 0) docker compose -f docker-compose.yml up -d

Images: oasm/oasm-console, oasm/oasm-api, oasm/oasm-worker

task docker-compose is the recommended entry point: it passes --env-file ./core-api/.env, rebuilds, force-recreates, and scales the worker service to 3 instances (the compose service key is oasm-worker).

Developer Guide

For detailed instructions on setting up your development environment, running services, and contributing, please refer to our dedicated Developer Guide.

Quick Start

# Install dependencies, copy .env templates, start postgres + redis
task init

# Start API + Console dev servers
task dev

# Run a worker locally (tools download automatically on first run)
task worker:dev

task init does not create worker/.env — copy worker/.example.env yourself and set WORKER_API_KEY.

Key Commands

All commands run from the repository root through task; raw npm run / go test invocations bypass the resource limits and configuration baked into the taskfiles.

task test            # Run API tests (console tests are excluded — use task console:test:run)
task api:test        # API unit tests only
task console:test:run # Console unit tests, single pass (CI equivalent)
task worker:test     # Go worker tests
task lint            # Lint API + Console (sequential)
task build           # Build all services
task docker-compose  # Start full stack with Docker (3 workers)
task sync-connectors # Refresh the connector catalog from oasm-connectors
task gen-api         # Regenerate the OpenAPI spec + console API client
task proto           # Regenerate Go gRPC stubs into worker/internal/gen
task migration:generate name=AddFooColumn  # Generate a DB migration (never hand-write one)
task migration:run   # Run database migrations