@deepbounty/sdk 1.2.0 → 1.2.2

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;
@@ -148,6 +148,52 @@ export interface FilesAPI {
      */
     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;
@@ -155,6 +201,7 @@ export interface ServerAPI {
     storage: StorageAPI;
     files: FilesAPI;
     events: IEventBus;
+    callbacks: CallbackAPI;
     /** Check if a hostname is in scope based on targets_subdomains */
     isHostnameInScope(hostname: string): Promise<boolean>;
     /**

package/dist/types/callbacks.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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;
+    /** Delay before the callback becomes active, in seconds (default: 0 = active immediately) */
+    effectiveIn?: 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 becomes active (callbacks before this time are ignored) */
+    effectiveAt: 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/package.json

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