@deepbounty/sdk 1.1.8 → 1.2.0

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
@@ -9,11 +25,19 @@ export interface CoreEvents {
         context: TrafficContext;
         js: string;
     };
+    "http:html": {
+        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
  */
@@ -33,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

@@ -77,22 +77,96 @@ 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;
+}
 export interface ServerAPI {
     version: string;
     logger: Logger;
     config: ConfigAPI;
     storage: StorageAPI;
+    files: FilesAPI;
     events: IEventBus;
+    /** 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>;
@@ -104,35 +178,46 @@ export interface ServerAPI {
     unregisterTaskTemplate(templateId: number): Promise<boolean>;
     /**
      * Create a task instance manually (for CUSTOM scheduling type)
+     * Task instances are always one-time and automatically deleted after execution.
      * @param templateId The ID of the task template
      * @param targetId Optional target ID for this instance
      * @param customData Optional custom data to attach to this instance (accessible via {{KEY}} placeholders)
-     * @param oneTime If true, delete the scheduled task after execution (default: false)
      * @returns The scheduled task ID
      */
-    createTaskInstance(templateId: number, targetId?: number, customData?: Record<string, any>, oneTime?: boolean): Promise<number>;
+    createTaskInstance(templateId: number, targetId?: number, customData?: Record<string, any>): Promise<number>;
     /** Register a tool
      * @param tool The tool to register
      */
     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/tasks.d.ts

@@ -32,6 +32,7 @@ export interface ScheduledTask {
 export interface TaskExecution {
     executionId: number;
     scheduledTaskId: number;
+    templateId?: number;
     workerId?: number;
     status: "pending" | "running" | "completed" | "failed";
     createdAt: Date;
@@ -43,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.8",
+	"version": "1.2.0",
 	"description": "DeepBounty SDK for module development",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",