OASM

https://docs.oasm.dev
Admin
OASM is an open-source platform for cybersecurity Attack Surface Management, built to help security...
Tokens:8,171
Snippets:154
Trust Score:4.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Copy Environment File

Source: https://docs.oasm.dev/quickstart

Copy the example environment file to create your own configuration. Update this file to match your specific environment settings.

```bash
cp .env.example .env
```

--------------------------------

### Install act for Windows (Git Bash)

Source: https://docs.oasm.dev/developer-guide

Installs the 'act' tool using a curl script for Windows environments when using Git Bash. Ensure Docker Desktop is running.

```bash
# Windows (Git Bash)
curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash
```

--------------------------------

### Install act for Linux/macOS

Source: https://docs.oasm.dev/developer-guide

Installs the 'act' tool using a curl script for Linux and macOS environments. Ensure Docker Desktop is running.

```bash
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | bash
```

--------------------------------

### Build and Start OASM Services

Source: https://docs.oasm.dev/quickstart

Build and start all necessary OASM services using the Make command. This command handles the Docker image building and service initialization.

```bash
make
```

--------------------------------

### Start PostgreSQL Database

Source: https://docs.oasm.dev/setup

Start the PostgreSQL database service in detached mode using Docker Compose. This is a necessary step before starting the development servers.

```bash
docker compose up postgres -d
```

--------------------------------

### Initialize OASM Environment

Source: https://docs.oasm.dev/setup

Run the 'task init' command at the project root to copy environment files, install npm and Go dependencies, and set up worker security tools.

```bash
task init
```

--------------------------------

### Start OASM Development Servers

Source: https://docs.oasm.dev/setup

Launch the development servers for the Core API and the Console. The Core API will be available at http://localhost:6276 and the Console at http://localhost:5173.

```bash
task dev
```

--------------------------------

### Run Console Development Server

Source: https://docs.oasm.dev/developer-guide

Starts the Console web interface development server using Vite. The Console runs on port 5173.

```bash
task console:dev
```

```bash
cd console && npm run dev
```

--------------------------------

### Run Core API Development Server

Source: https://docs.oasm.dev/developer-guide

Starts the Core API development server. The API runs on port 6276 with a gRPC server on port 16276.

```bash
task api:dev
```

```bash
cd core-api && npm run start:dev
```

--------------------------------

### Run Entire Stack with Docker Compose

Source: https://docs.oasm.dev/developer-guide

Start the entire application stack using Docker Compose with the 'task docker-compose' command. This command initiates all services including the console, core API, workers, database, and more.

```bash
task docker-compose
```

--------------------------------

### Run Database Migrations with Docker Compose

Source: https://docs.oasm.dev/developer-guide

Executes pending migrations using Docker Compose. This starts the PostgreSQL container, runs the migration service, and automatically removes the migration container.

```bash
docker compose up migration
```

--------------------------------

### Run Workers in App Mode

Source: https://docs.oasm.dev/developer-guide

Starts workers locally in app mode, driven by environment variables.

```bash
task worker:dev-app
```

--------------------------------

### Clone OASM Docker Repository

Source: https://docs.oasm.dev/quickstart

Clone the OASM Docker repository to your local machine. Navigate into the cloned directory to proceed with the setup.

```bash
git clone https://github.com/oasm-platform/oasm-docker.git
cd oasm-docker
```

--------------------------------

### Run Migration Container Manually with Docker Compose

Source: https://docs.oasm.dev/developer-guide

Starts the migration container manually using Docker Compose and keeps it for debugging. The --rm flag ensures the container is removed after it stops.

```bash
docker compose run --rm migration
```

--------------------------------

### Run Workers in CLI Mode

Source: https://docs.oasm.dev/developer-guide

Starts workers locally in CLI mode. You can specify parameters like replicas, maxJobs, apiKey, and network.

```bash
task worker:dev
```

```bash
task worker:dev replicas=3 maxJobs=10 apiKey=<your-api-key> network=<target-network>
```

--------------------------------

### Run All Pending Database Migrations

Source: https://docs.oasm.dev/developer-guide

Executes all pending database migrations. Connects to PostgreSQL and applies new migrations.

```bash
task migration:run
```

--------------------------------

### Configure Claude Desktop for MCP

Source: https://docs.oasm.dev/settings/mcp

Add this configuration to your `claude_desktop_config.json` to connect Claude Desktop to your OASM workspace.

```json
{
  "mcpServers": {
    "oasm-platform": {
      "url": "https://your-instance-oasm/api/mcp",
      "headers": {
        "x-oasm-api-key": "your-api-key-here"
      }
    }
  }
}
```

--------------------------------

### Lint Workers with go vet

Source: https://docs.oasm.dev/developer-guide

Run static analysis on Go code for the Workers using 'go vet'.

```bash
task worker:lint
```

--------------------------------

### List available GitHub Actions workflows

Source: https://docs.oasm.dev/developer-guide

Executes a local script to list all available GitHub Actions workflows in the repository. This is a dry-run command.

```bash
# List available workflows
bash .github/scripts/test-local.sh
```

--------------------------------

### Run Console Unit Tests with Vitest

Source: https://docs.oasm.dev/developer-guide

Execute unit tests for the Console application using Vitest. This command runs the standard unit test suite.

```bash
task console:test       # Unit tests
```

--------------------------------

### Local command for frontend-tests.yml workflow

Source: https://docs.oasm.dev/developer-guide

This command is the local equivalent for the 'frontend-tests.yml' CI workflow. It requires navigating to the console directory and running 'npm run test:run'.

```bash
cd console && npm run test:run
```

--------------------------------

### Run a workflow with a custom act binary path

Source: https://docs.oasm.dev/developer-guide

Executes a local script to run a specific workflow, specifying a custom path to the 'act' binary using the ACT_BIN environment variable.

```bash
# Custom act binary path
ACT_BIN=act bash .github/scripts/test-local.sh check-lint
```

--------------------------------

### Lint Core API with ESLint and Prettier

Source: https://docs.oasm.dev/developer-guide

Run the lint task for the Core API. This task uses ESLint and Prettier for code style enforcement.

```bash
task api:lint
```

--------------------------------

### Format Workers with go fmt

Source: https://docs.oasm.dev/developer-guide

Format Go code for the Workers using 'go fmt'.

```bash
task worker:format
```

--------------------------------

### Run Worker Tests with Go Testing

Source: https://docs.oasm.dev/developer-guide

Execute tests for the Workers using Go's built-in testing framework. This command runs the standard test suite.

```bash
task worker:test
```

--------------------------------

### Test CI Workflows Locally

Source: https://docs.oasm.dev/developer-guide

Execute CI workflows on your local machine before pushing changes. Replace <workflow> with the specific workflow name you want to test.

```bash
bash .github/scripts/test-local.sh <workflow>
```

--------------------------------

### Run Core API Unit Tests with Jest

Source: https://docs.oasm.dev/developer-guide

Execute unit tests for the Core API using Jest. This command runs the standard test suite.

```bash
task api:test           # Unit tests
```

--------------------------------

### Configure VS Code (GitHub Copilot) for MCP

Source: https://docs.oasm.dev/settings/mcp

Add this configuration to your VS Code `settings.json` to enable MCP integration with GitHub Copilot.

```json
{
  "github.copilot.mcpServers": {
    "oasm-platform": {
      "url": "https://your-instance-oasm/api/mcp",
      "headers": {
        "x-oasm-api-key": "your-api-key-here"
      }
    }
  }
}
```

--------------------------------

### Clone OASM Repository

Source: https://docs.oasm.dev/setup

Clone the Open-ASM repository to your local machine and navigate into the project directory.

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

--------------------------------

### Generate a New Database Migration

Source: https://docs.oasm.dev/developer-guide

Creates a new migration file with a custom name in the specified directory. Useful for adding new database schemas or changes.

```bash
task migration:generate MIGRATION_NAME=YourMigrationName
```

```bash
task migration:generate MIGRATION_NAME=AddUserTable
```

--------------------------------

### Lint Console with ESLint and Prettier

Source: https://docs.oasm.dev/developer-guide

Run the lint task for the Console application. This task uses ESLint and Prettier for code style enforcement.

```bash
task console:lint
```

--------------------------------

### Local command for check-build.yml workflow

Source: https://docs.oasm.dev/developer-guide

This command is the local equivalent for the 'check-build.yml' CI workflow. It uses the 'task build' command and requires Docker to be running.

```bash
task build (requires Docker)
```

--------------------------------

### Run a specific GitHub Actions workflow locally

Source: https://docs.oasm.dev/developer-guide

Executes a local script to run a specified GitHub Actions workflow. Provide the workflow name as an argument.

```bash
# Run a specific workflow
bash .github/scripts/test-local.sh check-lint
bash .github/scripts/test-local.sh worker-ci
```

--------------------------------

### Run Core API End-to-End Tests

Source: https://docs.oasm.dev/developer-guide

Execute end-to-end tests for the Core API. This command runs the full suite of integration tests.

```bash
cd core-api && npm run test:e2e      # End-to-end tests
```

--------------------------------

### Generate gRPC Stubs

Source: https://docs.oasm.dev/developer-guide

Regenerate gRPC stubs after modifying proto files using the 'task proto' command. This generates Go and TypeScript stubs into the 'grpc-client/' directory.

```bash
task proto
```

--------------------------------

### Local command for check-lint.yml workflow

Source: https://docs.oasm.dev/developer-guide

This command is the local equivalent for the 'check-lint.yml' CI workflow. It uses the 'task lint' command.

```bash
task lint
```

--------------------------------

### Local command for check-test.yml workflow

Source: https://docs.oasm.dev/developer-guide

This command is the local equivalent for the 'check-test.yml' CI workflow. It uses the 'task api:test' command.

```bash
task api:test
```

--------------------------------

### Local commands for worker-ci.yml workflow

Source: https://docs.oasm.dev/developer-guide

These commands are the local equivalents for the 'worker-ci.yml' CI workflow. They involve running 'task worker:lint' and 'task worker:check'.

```bash
task worker:lint && task worker:check
```

--------------------------------

### Run Core API Tests in Watch Mode

Source: https://docs.oasm.dev/developer-guide

Run unit tests for the Core API in watch mode using npm. This command re-runs tests automatically on file changes.

```bash
cd core-api && npm run test:watch    # Watch mode
```

--------------------------------

### OASM Project Structure

Source: https://docs.oasm.dev/developer-guide

Overview of the OASM project's directory layout, detailing the purpose of each major component like core-api, console, and worker.

```text
open-asm/
├── core-api/           # NestJS API server
│   ├── src/            # Source code
│   ├── example.env     # Environment template
│   └── package.json
├── console/            # React web interface
│   ├── src/            # React components
│   ├── public/         # Static assets
│   └── package.json
├── worker/             # Go-based scanning workers
│   ├── cmd/            # CLI and App entry points
│   ├── internal/       # Business logic
│   ├── scripts/        # Install scripts (install.ps1, install.sh)
│   ├── go.mod          # Go module definition
│   └── .example.env    # Environment template
├── grpc-client/        # Generated gRPC stubs (Go + TypeScript)
├── .open-api/          # Auto-generated API docs
├── docker-compose.yml  # Container orchestration
├── taskfile.yml        # Task automation
└── README.md           # Documentation
```

--------------------------------

### Validate all GitHub Actions workflows locally (dry-run)

Source: https://docs.oasm.dev/developer-guide

Executes a local script with the --all flag to perform a dry-run validation of all GitHub Actions workflows.

```bash
# Validate all workflows (dry-run)
bash .github/scripts/test-local.sh --all
```

--------------------------------

### Run Console End-to-End Tests with Playwright

Source: https://docs.oasm.dev/developer-guide

Execute end-to-end tests for the Console application using Playwright. This command runs the full suite of integration tests.

```bash
cd console && npm run e2e           # E2E tests
```

--------------------------------

### Commit Code with Conventional Commits

Source: https://docs.oasm.dev/developer-guide

Use this format for commit messages to ensure consistency and clarity in project history. Adhere to the Conventional Commits specification.

```bash
git commit -m 'feat(scope): add amazing feature'
```

--------------------------------

### OASM Distributed Architecture Diagram

Source: https://docs.oasm.dev/architecture

Mermaid diagram illustrating the OASM platform's distributed architecture, components, and data flow.

```mermaid
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[(PostgreSQL)]
        Redis[(Redis)]
        MCP[MCP Server]

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

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

    API <-->|Persist Data| DB
    API <-->|Queue / Cache| Redis

    %% Job Flow (2-way)
    API <-->|Job / Result| W1
    API <-->|Job / Result| W2
    API <-->|Job / Result| WN

    %% Scan
    W1 -->|Scan| Internet
    W2 -->|Scan| Internet
    WN -->|Scan| Internet

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

--------------------------------

### Generate Console API Client with orval

Source: https://docs.oasm.dev/developer-guide

Regenerate the console API client using the 'task gen-api' command. This task uses orval to generate TanStack Query hooks from the OpenAPI spec.

```bash
task gen-api
```

--------------------------------

### Revert the Last Database Migration

Source: https://docs.oasm.dev/developer-guide

Rolls back the most recently executed migration. This action reverts one migration at a time.

```bash
task migration:revert
```
Tokens:
Raw