@j3r3mcdev/oast-server 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build project
+        run: npm run build

package/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Publish package
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public

package/README.md

@@ -0,0 +1,192 @@
+# OAST Server — Multi‑Protocol Out‑of‑Band Interaction Framework
+
+Un serveur OAST modulaire, extensible et agnostique, conçu pour capturer, normaliser et diffuser des interactions _out‑of‑band_ provenant de multiples canaux : HTTP, DNS, SMTP, SSRF, Webhook, WebSocket, TCP, API REST et SSE.
+
+Ce framework fournit une architecture listener‑based robuste, unifiée et testée, idéale pour les outils de diagnostic, scanners de vulnérabilités, plateformes d’audit ou systèmes de détection avancés.
+
+---
+
+## ✨ Caractéristiques principales
+
+- **Architecture modulaire par listeners**  
+  Chaque protocole est isolé dans son propre module (`http`, `dns`, `smtp`, `ssrf`, `webhook`, `websocket`, `tcp`, `api`).
+
+- **Extractors dédiés**  
+  Chaque listener dispose d’un extractor responsable de la normalisation des données brutes.
+
+- **API REST intégrée**  
+  Permet de récupérer les events, les tasks, les métadonnées et l’état du serveur.
+
+- **SSE (Server‑Sent Events)**  
+  Diffusion en temps réel des interactions capturées.
+
+- **Storage agnostique**  
+  Implémentation par défaut en mémoire, extensible vers Redis, SQLite, PostgreSQL, etc.
+
+- **Suite de tests complète**  
+  118 tests unitaires couvrant extractors, listeners, API, SSE et services.
+
+- **Aucune dépendance lourde**  
+  Pas d’Express, pas de framework web : un cœur minimaliste, rapide et portable.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @j3r3mcdev/oast-server
+```
+
+## 🚀 Démarrage rapide
+
+```ts
+import { ApiListener, HttpListener, DnsListener } from "@j3r3mcdev/oast-server";
+
+const api = new ApiListener({ port: 8080 });
+const http = new HttpListener({ port: 8000 });
+const dns = new DnsListener({ port: 5353 });
+
+api.start();
+http.start();
+dns.start();
+
+console.log("OAST server running");
+```
+
+## 📡 Protocoles supportés
+
+| Protocole     | Listener            | Description                             |
+| ------------- | ------------------- | --------------------------------------- |
+| **HTTP**      | `HttpListener`      | Capture des requêtes HTTP entrantes     |
+| **DNS**       | `DnsListener`       | Résolution DNS OAST (A, AAAA, TXT…)     |
+| **SMTP**      | `SmtpListener`      | Réception d’emails OAST                 |
+| **SSRF**      | `SsrfListener`      | Détection d’interactions SSRF           |
+| **Webhook**   | `WebhookListener`   | Réception d’appels webhook              |
+| **WebSocket** | `WebSocketListener` | Connexions WebSocket entrantes          |
+| **TCP**       | `TcpListener`       | Connexions TCP brutes                   |
+| **API + SSE** | `ApiListener`       | API REST + diffusion temps réel via SSE |
+
+## 🧩 Architecture
+
+![alt text](image.png)
+
+Chaque listener contient :
+
+- `*.listener.ts` → serveur du protocole
+- `*.extractor.ts` → normalisation des données
+- `__tests__/` → tests unitaires
+
+## 🧨 Exemple : Listener HTTP
+
+```ts
+import { HttpListener } from "@j3r3mcdev/oast-server";
+
+const http = new HttpListener({
+  port: 8000,
+  onEvent: (event) => {
+    console.log("HTTP event:", event);
+  },
+});
+
+http.start();
+```
+
+---
+
+# 🧨 **Exemple : Listener DNS**
+
+## 🧨 Exemple : Listener DNS
+
+```ts
+import { DnsListener } from "@j3r3mcdev/oast-server";
+
+const dns = new DnsListener({
+  port: 5353,
+  onEvent: (event) => {
+    console.log("DNS event:", event);
+  },
+});
+
+dns.start();
+```
+
+---
+
+# 🧨 **Exemple : SSE (temps réel)**
+
+```md
+## 🧨 Exemple : SSE (temps réel)
+```
+
+```ts
+const stream = new EventSource(
+  "http://localhost:8080/stream?channels=http,dns",
+);
+
+stream.onmessage = (msg) => {
+  const event = JSON.parse(msg.data);
+  console.log("Event reçu :", event);
+};
+```
+
+---
+
+# 🧨 **Exemple : API REST**
+
+## 🧨 Exemple : API REST
+
+### Récupérer les events
+
+```bash
+curl http://localhost:8080/events
+```
+
+### Créer une tâche
+
+```bash
+curl -X POST http://localhost:8080/tasks \
+  -H "Content-Type: application/json" \
+  -d '{"type":"scan","payload":{"url":"http://example.com"}}'
+```
+
+---
+
+# 🧱 **Storage** (Markdown PRO)
+
+## 🧱 Storage
+
+Par défaut : **in‑memory**
+
+Vous pouvez implémenter votre propre storage :
+
+```ts
+export interface StorageAdapter {
+  save(event: OastEvent): Promise<void>;
+  list(filters: any): Promise<OastEvent[]>;
+}
+
+class MyStorage implements StorageAdapter {
+  private events = [];
+  async save(e) {
+    this.events.push(e);
+  }
+  async list() {
+    return this.events;
+  }
+}
+```
+
+---
+
+# 🧪 **Tests** (Markdown PRO)
+
+## 🧪 Tests
+
+- **37 suites**
+- **118 tests**
+- **100% verts**
+- Tests d’intégration réservés à l’outil d’audit (non inclus dans la lib)
+
+## 📘 Licence
+
+MIT

package/dist/api/controllers/__tests__/tasks.controller.test.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const tasks_controller_1 = require("../tasks.controller");
+(0, globals_1.describe)("TasksController", () => {
+    let service;
+    let controller;
+    (0, globals_1.beforeEach)(() => {
+        service = {
+            create: globals_1.jest.fn(),
+            get: globals_1.jest.fn(),
+            list: globals_1.jest.fn(),
+            cancel: globals_1.jest.fn(),
+        };
+        controller = new tasks_controller_1.TasksController(service);
+    });
+    (0, globals_1.it)("crée une tâche", async () => {
+        const fakeTask = {
+            id: "123",
+            type: "x",
+            payload: {},
+            priority: "normal",
+            metadata: {},
+            status: "pending",
+            createdAt: Date.now(),
+            updatedAt: Date.now(),
+        };
+        service.create.mockReturnValue(fakeTask);
+        const req = { body: { type: "x", payload: {} } };
+        const result = await controller.create({ req, res: {}, params: {} });
+        (0, globals_1.expect)(service.create).toHaveBeenCalled();
+        (0, globals_1.expect)(result).toEqual({
+            status: 201,
+            body: fakeTask,
+        });
+    });
+    (0, globals_1.it)("retourne 404 si tâche absente", async () => {
+        service.get.mockReturnValue(undefined);
+        const result = await controller.getOne({
+            req: {},
+            res: {},
+            params: { id: "123" },
+        });
+        (0, globals_1.expect)(result).toEqual({
+            status: 404,
+            body: { error: "Task not found" },
+        });
+    });
+    (0, globals_1.it)("annule une tâche", async () => {
+        service.cancel.mockReturnValue(true);
+        const result = await controller.cancel({
+            req: {},
+            res: {},
+            params: { id: "123" },
+        });
+        (0, globals_1.expect)(result).toEqual({
+            status: 200,
+            body: { cancelled: true },
+        });
+    });
+});

package/dist/api/controllers/events.controller.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventsController = void 0;
+class EventsController {
+    constructor(events) {
+        this.events = events;
+        this.stream = async ({ res, query }) => {
+            const channels = query.channels?.split(",") ?? [];
+            return this.events.connect(res, channels);
+        };
+    }
+}
+exports.EventsController = EventsController;

package/dist/api/controllers/health.controller.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthController = void 0;
+class HealthController {
+    constructor() {
+        this.check = (req, res) => {
+            res.json({ status: "ok", timestamp: Date.now() });
+        };
+    }
+}
+exports.HealthController = HealthController;

package/dist/api/controllers/index.js

@@ -0,0 +1 @@
+"use strict";

package/dist/api/controllers/tasks.controller.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TasksController = void 0;
+const create_task_dto_1 = require("../dto/create-task.dto");
+const filter_tasks_dto_1 = require("../dto/filter-tasks.dto");
+class TasksController {
+    constructor(tasks) {
+        this.tasks = tasks;
+        this.list = async ({ req }) => {
+            const dto = filter_tasks_dto_1.FilterTasksDtoValidator.validate(req.query);
+            const result = await this.tasks.list(dto);
+            return { status: 200, body: result };
+        };
+        this.create = async ({ req }) => {
+            const dto = create_task_dto_1.CreateTaskDtoValidator.validate(req.body);
+            const task = await this.tasks.create(dto);
+            return { status: 201, body: task };
+        };
+        this.getOne = async ({ params }) => {
+            const task = await this.tasks.get(params.id);
+            if (!task) {
+                return { status: 404, body: { error: "Task not found" } };
+            }
+            return { status: 200, body: task };
+        };
+        this.cancel = async ({ params }) => {
+            const ok = await this.tasks.cancel(params.id);
+            if (!ok) {
+                return { status: 404, body: { error: "Task not found" } };
+            }
+            return { status: 200, body: { cancelled: true } };
+        };
+    }
+}
+exports.TasksController = TasksController;

package/dist/api/dto/__tests__/create-task.dto.test.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const create_task_dto_1 = require("../create-task.dto");
+(0, globals_1.describe)("CreateTaskDtoValidator", () => {
+    (0, globals_1.it)("valide un DTO correct", () => {
+        const dto = create_task_dto_1.CreateTaskDtoValidator.validate({
+            type: "crawl:api",
+            payload: { url: "https://example.com" },
+            priority: "high",
+        });
+        (0, globals_1.expect)(dto).toEqual({
+            type: "crawl:api",
+            payload: { url: "https://example.com" },
+            priority: "high",
+            metadata: {},
+        });
+    });
+    (0, globals_1.it)("applique les valeurs par défaut", () => {
+        const dto = create_task_dto_1.CreateTaskDtoValidator.validate({
+            type: "ping",
+            payload: {},
+        });
+        (0, globals_1.expect)(dto.priority).toBe("normal");
+        (0, globals_1.expect)(dto.metadata).toEqual({});
+    });
+    (0, globals_1.it)("rejette un type invalide", () => {
+        (0, globals_1.expect)(() => create_task_dto_1.CreateTaskDtoValidator.validate({ payload: {} })).toThrow("Invalid type");
+    });
+    (0, globals_1.it)("rejette un payload invalide", () => {
+        (0, globals_1.expect)(() => create_task_dto_1.CreateTaskDtoValidator.validate({ type: "x", payload: null })).toThrow("Invalid payload");
+    });
+});

package/dist/api/dto/__tests__/filter-tasks.dto.test.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const filter_tasks_dto_1 = require("../filter-tasks.dto");
+(0, globals_1.describe)("FilterTasksDtoValidator", () => {
+    (0, globals_1.it)("valide un query correct", () => {
+        const dto = filter_tasks_dto_1.FilterTasksDtoValidator.validate({
+            status: "running",
+            limit: "10",
+            type: "crawl:api",
+        });
+        (0, globals_1.expect)(dto).toEqual({
+            status: "running",
+            limit: 10,
+            type: "crawl:api",
+        });
+    });
+    (0, globals_1.it)("rejette un status invalide", () => {
+        (0, globals_1.expect)(() => filter_tasks_dto_1.FilterTasksDtoValidator.validate({ status: "unknown" })).toThrow("Invalid status");
+    });
+    (0, globals_1.it)("rejette un limit invalide", () => {
+        (0, globals_1.expect)(() => filter_tasks_dto_1.FilterTasksDtoValidator.validate({ limit: "-5" })).toThrow("Invalid limit");
+    });
+    (0, globals_1.it)("accepte un query vide", () => {
+        const dto = filter_tasks_dto_1.FilterTasksDtoValidator.validate({});
+        (0, globals_1.expect)(dto).toEqual({});
+    });
+});

package/dist/api/dto/create-task.dto.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateTaskDtoValidator = void 0;
+class CreateTaskDtoValidator {
+    static validate(input) {
+        if (!input || typeof input !== "object") {
+            throw new Error("Invalid body: expected object");
+        }
+        if (!input.type || typeof input.type !== "string") {
+            throw new Error("Invalid type: expected non-empty string");
+        }
+        if (!input.payload || typeof input.payload !== "object") {
+            throw new Error("Invalid payload: expected object");
+        }
+        if (input.priority && !["low", "normal", "high"].includes(input.priority)) {
+            throw new Error("Invalid priority: must be low, normal or high");
+        }
+        return {
+            type: input.type,
+            payload: input.payload,
+            priority: input.priority ?? "normal",
+            metadata: input.metadata ?? {},
+        };
+    }
+}
+exports.CreateTaskDtoValidator = CreateTaskDtoValidator;

package/dist/api/dto/filter-tasks.dto.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilterTasksDtoValidator = void 0;
+class FilterTasksDtoValidator {
+    static validate(query) {
+        const dto = {};
+        if (query.status) {
+            const allowed = ["pending", "running", "completed", "failed"];
+            if (!allowed.includes(query.status)) {
+                throw new Error("Invalid status");
+            }
+            dto.status = query.status;
+        }
+        if (query.limit) {
+            const n = Number(query.limit);
+            if (isNaN(n) || n <= 0) {
+                throw new Error("Invalid limit");
+            }
+            dto.limit = n;
+        }
+        if (query.type) {
+            dto.type = String(query.type);
+        }
+        return dto;
+    }
+}
+exports.FilterTasksDtoValidator = FilterTasksDtoValidator;

package/dist/api/services/__tests__/events.service.test.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const tasks_service_1 = require("../tasks.service");
+const events_service_1 = require("../events.service");
+const events_stream_1 = require("../../sse/events.stream");
+(0, globals_1.describe)("TasksService", () => {
+    (0, globals_1.it)("émet un événement lors de la création d'une tâche", () => {
+        const stream = new events_stream_1.EventStreamManager({ heartbeatInterval: 999999 });
+        const events = new events_service_1.EventsService(stream);
+        const spy = globals_1.jest.spyOn(stream, "broadcast");
+        const service = new tasks_service_1.TasksService(events);
+        const task = service.create({ type: "x", payload: {} });
+        (0, globals_1.expect)(spy).toHaveBeenCalledWith("tasks", "task.created", globals_1.expect.objectContaining({ id: task.id }));
+    });
+    (0, globals_1.it)("émet un événement lors de l'annulation d'une tâche", () => {
+        const stream = new events_stream_1.EventStreamManager({ heartbeatInterval: 999999 });
+        const events = new events_service_1.EventsService(stream);
+        const spy = globals_1.jest.spyOn(stream, "broadcast");
+        const service = new tasks_service_1.TasksService(events);
+        const task = service.create({ type: "x", payload: {} });
+        service.cancel(task.id);
+        (0, globals_1.expect)(spy).toHaveBeenCalledWith("tasks", "task.cancelled", globals_1.expect.objectContaining({ id: task.id }));
+    });
+});

package/dist/api/services/__tests__/tasks.service.test.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const tasks_service_1 = require("../tasks.service");
+const events_service_1 = require("../events.service");
+const events_stream_1 = require("../../sse/events.stream");
+(0, globals_1.describe)("TasksService", () => {
+    (0, globals_1.it)("émet un événement lors de la création d'une tâche", () => {
+        const stream = new events_stream_1.EventStreamManager({ heartbeatInterval: 999999 });
+        const events = new events_service_1.EventsService(stream);
+        const spy = globals_1.jest.spyOn(stream, "broadcast");
+        const service = new tasks_service_1.TasksService(events);
+        const task = service.create({ type: "x", payload: {} });
+        (0, globals_1.expect)(spy).toHaveBeenCalledWith("tasks", "task.created", globals_1.expect.objectContaining({ id: task.id }));
+    });
+    (0, globals_1.it)("émet un événement lors de l'annulation d'une tâche", () => {
+        const stream = new events_stream_1.EventStreamManager({ heartbeatInterval: 999999 });
+        const events = new events_service_1.EventsService(stream);
+        const spy = globals_1.jest.spyOn(stream, "broadcast");
+        const service = new tasks_service_1.TasksService(events);
+        const task = service.create({ type: "x", payload: {} });
+        service.cancel(task.id);
+        (0, globals_1.expect)(spy).toHaveBeenCalledWith("tasks", "task.cancelled", globals_1.expect.objectContaining({ id: task.id }));
+    });
+});

package/dist/api/services/events.service.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventsService = void 0;
+class EventsService {
+    constructor(stream) {
+        this.stream = stream;
+    }
+    connect(res, channels = []) {
+        return this.stream.addClient(res, channels);
+    }
+    emit(channel, event, data) {
+        this.stream.broadcast(channel, event, data);
+    }
+    emitAll(event, data) {
+        this.stream.broadcastAll(event, data);
+    }
+}
+exports.EventsService = EventsService;

package/dist/api/services/tasks.service.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TasksService = void 0;
+class TasksService {
+    constructor(events) {
+        this.tasks = new Map();
+        this.events = events;
+    }
+    create(dto) {
+        const id = crypto.randomUUID();
+        const now = Date.now();
+        const task = {
+            id,
+            type: dto.type,
+            payload: dto.payload,
+            priority: dto.priority ?? "normal",
+            metadata: dto.metadata ?? {},
+            status: "pending",
+            createdAt: now,
+            updatedAt: now,
+        };
+        this.tasks.set(id, task);
+        this.events.emit("tasks", "task.created", task);
+        return task;
+    }
+    get(id) {
+        return this.tasks.get(id);
+    }
+    list(filters) {
+        let results = Array.from(this.tasks.values());
+        if (filters.status) {
+            results = results.filter((t) => t.status === filters.status);
+        }
+        if (filters.type) {
+            results = results.filter((t) => t.type === filters.type);
+        }
+        if (filters.limit) {
+            results = results.slice(0, filters.limit);
+        }
+        return results;
+    }
+    cancel(id) {
+        const task = this.tasks.get(id);
+        if (!task)
+            return false;
+        task.status = "failed";
+        task.updatedAt = Date.now();
+        this.events.emit("tasks", "task.cancelled", task);
+        return true;
+    }
+}
+exports.TasksService = TasksService;