@deepbounty/sdk 1.1.9 → 1.2.1

package/dist/events.d.ts

@@ -1,4 +1,20 @@
 import { TrafficContext, HttpTraffic } from "./types/burpsuite";
+import { Target } from "./types/targets";
+/**
+ * Event origin metadata
+ */
+export type EventOrigin = "server" | "module";
+/**
+ * Event wrapper with origin metadata
+ */
+export interface EventMetadata<T> {
+    /** Origin of the event */
+    origin: EventOrigin;
+    /** Module ID if origin is "module", undefined if origin is "server" */
+    moduleId?: string;
+    /** Actual event data */
+    data: T;
+}
 /**
  * Predefined core events emitted by the server
  * Modules can also emit custom events for inter-module communication
@@ -13,11 +29,15 @@ export interface CoreEvents {
         context: TrafficContext;
         html: string;
     };
+    "target:created": Target;
+    "target:updated": Target;
+    "target:deleted": Target;
 }
 /**
  * Event handler function signature
+ * Receives event data wrapped with metadata about its origin
  */
-export type EventHandler<T = any> = (data: T) => void | Promise<void>;
+export type EventHandler<T = any> = (event: EventMetadata<T>) => void | Promise<void>;
 /**
  * Subscription object returned when subscribing to events
  */
@@ -37,7 +57,7 @@ export interface IEventBus {
      * Emit an event with data
      * Non-blocking, async execution with rate limiting and error isolation
      * @param event - Event name
-     * @param data - Event data
+     * @param data - Event data (will be wrapped with origin metadata internally)
      */
     emit<K extends keyof CoreEvents>(event: K, data: CoreEvents[K]): void;
     emit<T = any>(event: string, data: T): void;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Alert, ModuleSetting, TaskContent, TaskResult, Tool } from "./types";
+import { Alert, ModuleSetting, TaskContent, TaskResult, Tool, ModuleCallback, CallbackHandler, CreateCallbackOptions } from "./types";
 import { IEventBus } from "./events";
 export interface Logger {
     info: (...args: any[]) => void;
@@ -77,22 +77,143 @@ export interface StorageAPI {
      */
     dropTable(tableName: string): void;
 }
+/**
+ * ScopedDirectory provides isolated file system access within a specific directory.
+ * All file operations are restricted to the base directory and its subdirectories.
+ */
+export interface ScopedDirectory {
+    /**
+     * Write binary data to a file (creates parent directories if needed)
+     * @param relativePath Path relative to this directory (supports nested paths like "subfolder/file.bin")
+     * @param data Binary data to write
+     */
+    writeFile(relativePath: string, data: Buffer | Uint8Array): void;
+    /**
+     * Write text to a file (creates parent directories if needed)
+     * @param relativePath Path relative to this directory (supports nested paths like "logs/output.txt")
+     * @param text Text content to write
+     * @param encoding Text encoding (default: "utf8")
+     */
+    writeFileText(relativePath: string, text: string, encoding?: BufferEncoding): void;
+    /**
+     * Read binary data from a file
+     * @param relativePath Path relative to this directory
+     * @returns Binary data as Buffer
+     */
+    readFile(relativePath: string): Buffer;
+    /**
+     * Read text from a file
+     * @param relativePath Path relative to this directory
+     * @param encoding Text encoding (default: "utf8")
+     * @returns Text content
+     */
+    readFileText(relativePath: string, encoding?: BufferEncoding): string;
+    /**
+     * Delete a file
+     * @param relativePath Path relative to this directory
+     */
+    deleteFile(relativePath: string): void;
+    /**
+     * Get a scoped subdirectory (creates it if it doesn't exist)
+     * Returns a new ScopedDirectory object for the subdirectory
+     * @param relativePath Path relative to this directory
+     * @returns New ScopedDirectory for the subdirectory
+     */
+    getSubdirectory(relativePath: string): ScopedDirectory;
+    /**
+     * List all files in a directory (optionally in a subdirectory)
+     * @param subdirPath Optional subdirectory path to list files from
+     * @returns Array of relative file paths
+     */
+    listFiles(subdirPath?: string): string[];
+    /**
+     * Check if a file exists
+     * @param relativePath Path relative to this directory
+     * @returns true if the file exists, false otherwise
+     */
+    fileExists(relativePath: string): boolean;
+}
+/**
+ * FilesAPI provides file system access for modules.
+ * Each module can create isolated directories within their module folder.
+ */
+export interface FilesAPI {
+    /**
+     * Get or create a directory by path (supports nested paths like "cache/images")
+     * Returns a ScopedDirectory object for isolated file operations.
+     * The directory is automatically created if it doesn't exist.
+     *
+     * @param directoryPath Directory path relative to module's files folder (e.g., "cache", "exports/json")
+     * @returns ScopedDirectory object for file operations within this directory
+     */
+    getDirectory(directoryPath: string): ScopedDirectory;
+}
+/**
+ * CallbackAPI provides external callback functionality for modules.
+ * Used for out-of-band exfiltration detection.
+ */
+export interface CallbackAPI {
+    /**
+     * Create a new callback with auto-generated UUID
+     * @param name Human-readable name for the callback
+     * @param metadata Arbitrary data to associate with this callback (e.g., target info)
+     * @param options Optional configuration (expiration, multiple triggers)
+     * @returns Object containing the UUID and full callback URL
+     */
+    create(name: string, metadata?: Record<string, any>, options?: CreateCallbackOptions): Promise<{
+        uuid: string;
+        url: string;
+    }>;
+    /**
+     * Register a handler for when callbacks are triggered
+     * Only one handler per module - calling again replaces the previous handler
+     * @param handler Function called when any callback for this module is triggered
+     */
+    onTrigger(handler: CallbackHandler): void;
+    /**
+     * Get a callback by UUID
+     * @param uuid The callback UUID
+     * @returns The callback data or null if not found
+     */
+    get(uuid: string): Promise<ModuleCallback | null>;
+    /**
+     * List all callbacks registered by this module
+     * @param includeExpired Include expired callbacks (default: false)
+     * @returns Array of callbacks
+     */
+    list(includeExpired?: boolean): Promise<ModuleCallback[]>;
+    /**
+     * Delete a callback by UUID
+     * @param uuid The callback UUID
+     * @returns true if deleted, false if not found
+     */
+    delete(uuid: string): Promise<boolean>;
+    /**
+     * Delete all callbacks for this module
+     * @returns Number of callbacks deleted
+     */
+    deleteAll(): Promise<number>;
+}
 export interface ServerAPI {
     version: string;
     logger: Logger;
     config: ConfigAPI;
     storage: StorageAPI;
+    files: FilesAPI;
     events: IEventBus;
+    callbacks: CallbackAPI;
+    /** Check if a hostname is in scope based on targets_subdomains */
+    isHostnameInScope(hostname: string): Promise<boolean>;
     /**
      * Register a task template that can be scheduled for all targets
      * @param uniqueKey Unique identifier for this task within the module (e.g., "subdomain-scan")
      * @param name Friendly name for the task
      * @param description Task description
      * @param taskContent The task content including commands and tools
-     * @param interval Interval in seconds between task executions
+     * @param interval Interval in seconds between task executions. For CUSTOM mode: if <= 0, no automatic scheduling (manual mode only)
      * @param schedulingType How to schedule tasks: "TARGET_BASED" (one per target), "GLOBAL" (single instance), or "CUSTOM" (callback-based)
      * @param onComplete Optional callback executed when a task instance completes
-     * @param onSchedule Optional callback for CUSTOM mode, invoked at interval to create instances
+     * @param onSchedule Optional callback for CUSTOM mode, invoked at interval to create instances (not called if interval <= 0)
      * @returns The ID of the registered task template
      */
     registerTaskTemplate(uniqueKey: string, name: string, description: string, taskContent: TaskContent, interval: number, schedulingType?: "TARGET_BASED" | "GLOBAL" | "CUSTOM", onComplete?: (result: TaskResult) => void, onSchedule?: (templateId: number) => void | Promise<void>): Promise<number>;
@@ -117,22 +238,33 @@ export interface ServerAPI {
     registerTool(tool: Tool): void;
     /**
      * Create a new alert for a target
-     * @param targetId The ID of the target
+     * The target is automatically detected from the subdomain parameter
+     * @param name The title of the alert
+     * @param subdomain The subdomain where the vulnerability was found (can be main domain or subdomain)
+     * @param score The severity score (0=Informational, 1=Low, 2=Medium, 3=High, 4=Critical)
+     * @param description Detailed description of the alert
+     * @param endpoint Specific endpoint/path where the vulnerability was found
+     * @param confirmed Whether the vulnerability has been confirmed (default: false)
+     * @returns The created alert
+     */
+    createAlert(name: string, subdomain: string, score: number, description: string, endpoint: string, confirmed?: boolean): Promise<Alert>;
+    /**
+     * Create a new alert for a target using its ID
      * @param name The title of the alert
-     * @param subdomain The subdomain where the vulnerability was found
+     * @param targetId The ID of the target
      * @param score The severity score (0=Informational, 1=Low, 2=Medium, 3=High, 4=Critical)
      * @param description Detailed description of the alert
      * @param endpoint Specific endpoint/path where the vulnerability was found
      * @param confirmed Whether the vulnerability has been confirmed (default: false)
-     * @returns The created alert ID
+     * @returns The created alert
      */
-    createAlert(targetId: number, name: string, subdomain: string, score: number, description: string, endpoint: string, confirmed?: boolean): Promise<Alert>;
+    createAlert(name: string, targetId: number, score: number, description: string, endpoint: string, confirmed?: boolean): Promise<Alert>;
 }
 export interface ModuleLifecycle {
     run?(api: ServerAPI): Promise<void> | void;
     stop?(): Promise<void> | void;
 }
 export type ModuleFactory = (api: ServerAPI) => ModuleLifecycle | Promise<ModuleLifecycle>;
-export { IEventBus, EventSubscription, CoreEvents, EventHandler, } from "./events";
+export * from "./events";
 declare const _default: any;
 export default _default;

package/dist/index.js

@@ -1 +1,3 @@
+// Re-export EventBus and related types
+export * from "./events";
 export default {}; // Type-only module for modules to import types during compile

package/dist/types/callbacks.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Callback types for external exfiltration detection
+ * Used by modules to register callbacks that can be triggered by external HTTP requests
+ */
+/**
+ * Options for creating a callback
+ */
+export interface CreateCallbackOptions {
+    /** Time-to-live in seconds. If not set, the callback never expires */
+    expiresIn?: number;
+    /** Whether the callback can be triggered multiple times (default: true) */
+    allowMultipleTriggers?: boolean;
+}
+/**
+ * Data stored with a callback
+ */
+export interface ModuleCallback {
+    /** Unique identifier (UUID) for the callback */
+    uuid: string;
+    /** Module that registered this callback */
+    moduleId: string;
+    /** Human-readable name for the callback */
+    name: string;
+    /** Arbitrary metadata associated with this callback (e.g., target info) */
+    metadata: Record<string, any>;
+    /** When the callback was created */
+    createdAt: string;
+    /** When the callback expires (null = never) */
+    expiresAt: string | null;
+    /** Whether multiple triggers are allowed */
+    allowMultipleTriggers: boolean;
+    /** Number of times this callback has been triggered */
+    triggerCount: number;
+    /** When the callback was last triggered (null = never) */
+    lastTriggeredAt: string | null;
+}
+/**
+ * Data received when a callback is triggered
+ */
+export interface CallbackTriggerData {
+    /** The request body sent by the external caller */
+    body: Record<string, any>;
+    /** HTTP headers from the request */
+    headers: Record<string, string>;
+    /** IP address of the caller */
+    remoteIp: string;
+    /** User agent of the caller */
+    userAgent: string;
+    /** When this trigger occurred */
+    triggeredAt: string;
+}
+/**
+ * Handler function called when a callback is triggered
+ */
+export type CallbackHandler = (callback: ModuleCallback, triggerData: CallbackTriggerData) => void | Promise<void>;

package/dist/types/callbacks.js

@@ -0,0 +1,5 @@
+/**
+ * Callback types for external exfiltration detection
+ * Used by modules to register callbacks that can be triggered by external HTTP requests
+ */
+export {};

package/dist/types/index.d.ts

@@ -6,3 +6,4 @@ export * from "./websockets.js";
 export * from "./tasks.js";
 export * from "./tools.js";
 export * from "./notifications.js";
+export * from "./callbacks.js";

package/dist/types/index.js

@@ -6,3 +6,4 @@ export * from "./websockets.js";
 export * from "./tasks.js";
 export * from "./tools.js";
 export * from "./notifications.js";
+export * from "./callbacks.js";

package/dist/types/tasks.d.ts

@@ -44,7 +44,7 @@ export interface TaskResult {
     executionId: number;
     scheduledTaskId: number;
     success: boolean;
-    output?: any;
+    output?: string;
     error?: string;
     targetId?: number;
     customData?: Record<string, any>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@deepbounty/sdk",
-	"version": "1.1.9",
+	"version": "1.2.1",
 	"description": "DeepBounty SDK for module development",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",