typescript-virtual-container 1.1.4 → 1.1.6

package/dist/VirtualFileSystem/index.js

@@ -1,3 +1,4 @@
+import { EventEmitter } from "node:events";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { gunzipSync, gzipSync } from "node:zlib";
@@ -9,7 +10,7 @@ import { normalizePath } from "./path";
  * {@link VirtualFileSystem.restoreMirror} on startup and
  * {@link VirtualFileSystem.flushMirror} to persist pending changes.
  */
-class VirtualFileSystem {
+class VirtualFileSystem extends EventEmitter {
     mirrorRoot;
     ensureMirrorRoot() {
         fs.mkdirSync(this.mirrorRoot, { recursive: true, mode: 0o755 });
@@ -75,6 +76,7 @@ class VirtualFileSystem {
      * @param baseDir Base directory used to resolve mirror archive location.
      */
     constructor(baseDir = process.cwd()) {
+        super();
         this.mirrorRoot = path.resolve(baseDir, ".vfs", "mirror");
     }
     /**
@@ -92,6 +94,7 @@ class VirtualFileSystem {
      */
     async flushMirror() {
         this.ensureMirrorRoot();
+        this.emit("mirror:flush");
     }
     /**
      * Creates directory and any missing parent directories.
@@ -106,6 +109,7 @@ class VirtualFileSystem {
             throw new Error(`Cannot create directory '${normalizePath(targetPath)}': path is a file.`);
         }
         fs.mkdirSync(fsPath, { recursive: true, mode });
+        this.emit("dir:create", { path: normalizePath(targetPath), mode });
     }
     /**
      * Writes UTF-8 text or binary content into file.
@@ -132,6 +136,7 @@ class VirtualFileSystem {
         }
         fs.writeFileSync(fsPath, storedContent);
         fs.chmodSync(fsPath, options.mode ?? 0o644);
+        this.emit("file:write", { path: normalized, size: storedContent.length });
     }
     /**
      * Reads file content as UTF-8 text.
@@ -149,6 +154,8 @@ class VirtualFileSystem {
         }
         const stored = fs.readFileSync(fsPath);
         const raw = this.detectGzipFile(fsPath) ? gunzipSync(stored) : stored;
+        const normalized = normalizePath(targetPath);
+        this.emit("file:read", { path: normalized, size: raw.length });
         return raw.toString("utf8");
     }
     /**

package/dist/VirtualShell/index.d.ts

@@ -1,3 +1,4 @@
+import { EventEmitter } from "node:events";
 import type { CommandContext, CommandResult } from "../types/commands";
 import type { ShellStream } from "../types/streams";
 import VirtualFileSystem from "../VirtualFileSystem";
@@ -13,7 +14,7 @@ export interface ShellProperties {
  * Instances are used both by the SSH server facade and by the programmatic
  * client API.
  */
-declare class VirtualShell {
+declare class VirtualShell extends EventEmitter {
     basePath: string;
     vfs: VirtualFileSystem;
     users: VirtualUserManager;

package/dist/VirtualShell/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualShell/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,iBAAiB,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG3D,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACb;AA8BD;;;;;GAKG;AACH,cAAM,YAAY;IACjB,QAAQ,EAAE,MAAM,CAAO;IACvB,GAAG,EAAE,iBAAiB,CAAC;IACvB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,CAAC,WAAW,CAAgB;IAEnC;;;;;;OAMG;gBAEF,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,eAAe,EAC5B,QAAQ,CAAC,EAAE,MAAM;IAuBlB;;;OAGG;IACU,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/C;;;;;;OAMG;IACH,UAAU,CACT,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GACvE,IAAI;IASP;;;;;;OAMG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAIrE;;;;;;;OAOG;IAEH,uBAAuB,CACtB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC1C,IAAI;IAcP;;;;OAIG;IACI,MAAM,IAAI,iBAAiB,GAAG,IAAI;IAIzC;;;;OAIG;IACI,QAAQ,IAAI,kBAAkB,GAAG,IAAI;IAI5C;;;;OAIG;IACI,WAAW,IAAI,MAAM;IAI5B;;;;;;OAMG;IACI,eAAe,CACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,MAAM,GACtB,IAAI;CAIP;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualShell/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,iBAAiB,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAG3D,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACb;AA8BD;;;;;GAKG;AACH,cAAM,YAAa,SAAQ,YAAY;IACtC,QAAQ,EAAE,MAAM,CAAO;IACvB,GAAG,EAAE,iBAAiB,CAAC;IACvB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,CAAC,WAAW,CAAgB;IAEnC;;;;;;OAMG;gBAEF,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,eAAe,EAC5B,QAAQ,CAAC,EAAE,MAAM;IAyBlB;;;OAGG;IACU,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/C;;;;;;OAMG;IACH,UAAU,CACT,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EAAE,EAChB,QAAQ,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GACvE,IAAI;IASP;;;;;;OAMG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKrE;;;;;;;OAOG;IAEH,uBAAuB,CACtB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAC1C,IAAI;IAeP;;;;OAIG;IACI,MAAM,IAAI,iBAAiB,GAAG,IAAI;IAIzC;;;;OAIG;IACI,QAAQ,IAAI,kBAAkB,GAAG,IAAI;IAI5C;;;;OAIG;IACI,WAAW,IAAI,MAAM;IAI5B;;;;;;OAMG;IACI,eAAe,CACrB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,MAAM,GACtB,IAAI;CAIP;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/VirtualShell/index.js

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { EventEmitter } from "node:events";
 import { createCustomCommand, registerCommand, runCommand } from "../commands";
 import VirtualFileSystem from "../VirtualFileSystem";
 import { VirtualUserManager } from "../VirtualUserManager";
@@ -30,7 +31,7 @@ function resolveAutoSudoForNewUsers() {
  * Instances are used both by the SSH server facade and by the programmatic
  * client API.
  */
-class VirtualShell {
+class VirtualShell extends EventEmitter {
     basePath = ".";
     vfs;
     users;
@@ -45,6 +46,7 @@ class VirtualShell {
      * @param basePath Optional base path for the virtual filesystem (defaults to process.cwd()).
      */
     constructor(hostname, properties, basePath) {
+        super();
         this.hostname = hostname;
         this.properties = properties || defaultShellProperties;
         this.basePath = basePath || ".";
@@ -57,6 +59,7 @@ class VirtualShell {
         this.initialized = (async () => {
             await vfs.restoreMirror();
             await users.initialize();
+            this.emit("initialized");
         })();
     }
     /**
@@ -89,6 +92,7 @@ class VirtualShell {
      */
     executeCommand(rawInput, authUser, cwd) {
         runCommand(rawInput, authUser, this.hostname, "shell", cwd, this);
+        this.emit("command", { command: rawInput, user: authUser, cwd });
     }
     /**
      * Starts an interactive session with the shell.
@@ -100,6 +104,7 @@ class VirtualShell {
      */
     startInteractiveSession(stream, authUser, sessionId, remoteAddress, terminalSize) {
         // Interactive shell logic
+        this.emit("session:start", { user: authUser, sessionId, remoteAddress });
         startShell(this.properties, stream, authUser, this.hostname, sessionId, remoteAddress, terminalSize, this);
     }
     /**

package/dist/VirtualUserManager/index.d.ts

@@ -1,3 +1,4 @@
+import { EventEmitter } from "node:events";
 import type VirtualFileSystem from "../VirtualFileSystem";
 /** Persisted virtual user credential record. */
 export interface VirtualUserRecord {
@@ -26,7 +27,7 @@ export interface VirtualActiveSession {
  *
  * Passwords are hashed with scrypt and stored in the backing virtual filesystem.
  */
-export declare class VirtualUserManager {
+export declare class VirtualUserManager extends EventEmitter {
     private readonly vfs;
     private readonly defaultRootPassword;
     private readonly autoSudoForNewUsers;

package/dist/VirtualUserManager/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualUserManager/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/VirtualUserManager/index.ts"],"names":[],"mappings":"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"}

package/dist/VirtualUserManager/index.js

@@ -1,11 +1,12 @@
 import { randomBytes, randomUUID, scryptSync } from "node:crypto";
+import { EventEmitter } from "node:events";
 import * as path from "node:path";
 /**
  * Persistent user, sudoers, and active-session manager for the shell runtime.
  *
  * Passwords are hashed with scrypt and stored in the backing virtual filesystem.
  */
-export class VirtualUserManager {
+export class VirtualUserManager extends EventEmitter {
     vfs;
     defaultRootPassword;
     autoSudoForNewUsers;
@@ -26,6 +27,7 @@ export class VirtualUserManager {
      * @param autoSudoForNewUsers Whether newly created users are added to sudoers.
      */
     constructor(vfs, defaultRootPassword = "root", autoSudoForNewUsers = true) {
+        super();
         this.vfs = vfs;
         this.defaultRootPassword = defaultRootPassword;
         this.autoSudoForNewUsers = autoSudoForNewUsers;
@@ -55,6 +57,7 @@ export class VirtualUserManager {
             }
         }
         await this.persist();
+        this.emit("initialized");
     }
     /**
      * Sets max allowed bytes under /home/<username>.
@@ -177,6 +180,7 @@ export class VirtualUserManager {
             this.vfs.writeFile(`${homePath}/README.txt`, `Welcome to the virtual environment, ${username}`);
         }
         await this.persist();
+        this.emit("user:add", { username });
     }
     /**
      * Updates password for an existing user account.
@@ -207,6 +211,7 @@ export class VirtualUserManager {
             throw new Error(`deluser: user '${username}' does not exist`);
         }
         this.sudoers.delete(username);
+        this.emit("user:delete", { username });
         await this.persist();
     }
     /**
@@ -260,6 +265,11 @@ export class VirtualUserManager {
             startedAt: new Date().toISOString(),
         };
         this.activeSessions.set(session.id, session);
+        this.emit("session:register", {
+            sessionId: session.id,
+            username,
+            remoteAddress,
+        });
         return session;
     }
     /**
@@ -271,6 +281,14 @@ export class VirtualUserManager {
         if (!sessionId) {
             return;
         }
+        const session = this.activeSessions.get(sessionId);
+        this.activeSessions.delete(sessionId);
+        if (session) {
+            this.emit("session:unregister", {
+                sessionId,
+                username: session.username,
+            });
+        }
         this.activeSessions.delete(sessionId);
     }
     /**

package/dist/honeypot.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Honeypot tracking and auditing module for virtual shell events.
+ *
+ * Attaches listeners to VirtualShell, VirtualFileSystem, VirtualUserManager,
+ * SshMimic, and SftpMimic instances to log all activity for security auditing,
+ * anomaly detection, and forensic analysis.
+ *
+ * @module honeypot
+ */
+import type { VirtualShell } from "./VirtualShell";
+import type VirtualFileSystem from "./VirtualFileSystem";
+import type { VirtualUserManager } from "./VirtualUserManager";
+import type { SshMimic } from "./SSHMimic";
+import type { SftpMimic } from "./SSHMimic/sftp";
+/**
+ * Audit log entry recorded for each event.
+ */
+export interface AuditLogEntry {
+    timestamp: string;
+    type: string;
+    source: string;
+    details: Record<string, unknown>;
+}
+/**
+ * Statistics tracker for honeypot activity.
+ */
+export interface HoneyPotStats {
+    authAttempts: number;
+    authSuccesses: number;
+    authFailures: number;
+    commands: number;
+    fileWrites: number;
+    fileReads: number;
+    sessionStarts: number;
+    sessionEnds: number;
+    userCreated: number;
+    userDeleted: number;
+    clientConnects: number;
+    clientDisconnects: number;
+}
+/**
+ * HoneyPot audit and event tracking utility.
+ *
+ * Singleton-like helper that attaches listeners to virtual shell components
+ * and maintains an audit log of all activity.
+ */
+export declare class HoneyPot {
+    private auditLog;
+    private stats;
+    private maxLogSize;
+    /**
+     * Creates a new HoneyPot instance.
+     *
+     * @param maxLogSize Maximum audit log entries to retain (default: 10000).
+     */
+    constructor(maxLogSize?: number);
+    /**
+     * Attaches honeypot listeners to all provided event emitters.
+     *
+     * @param shell VirtualShell instance.
+     * @param vfs VirtualFileSystem instance.
+     * @param users VirtualUserManager instance.
+     * @param ssh SshMimic instance (optional).
+     * @param sftp SftpMimic instance (optional).
+     */
+    attach(shell: VirtualShell, vfs: VirtualFileSystem, users: VirtualUserManager, ssh?: SshMimic, sftp?: SftpMimic): void;
+    /**
+     * Attaches to VirtualShell events.
+     */
+    private attachVirtualShell;
+    /**
+     * Attaches to VirtualFileSystem events.
+     */
+    private attachVirtualFileSystem;
+    /**
+     * Attaches to VirtualUserManager events.
+     */
+    private attachVirtualUserManager;
+    /**
+     * Attaches to SshMimic events.
+     */
+    private attachSshMimic;
+    /**
+     * Attaches to SftpMimic events.
+     */
+    private attachSftpMimic;
+    /**
+     * Records an audit log entry.
+     *
+     * @param source Event source (e.g., "SshMimic", "VirtualFileSystem").
+     * @param type Event type.
+     * @param details Event-specific data.
+     */
+    private log;
+    /**
+     * Returns audit log entries matching optional filters.
+     *
+     * @param type Optional event type filter.
+     * @param source Optional source filter.
+     * @returns Filtered audit log entries.
+     */
+    getAuditLog(type?: string, source?: string): AuditLogEntry[];
+    /**
+     * Returns current activity statistics.
+     *
+     * @returns Snapshot of honeypot stats.
+     */
+    getStats(): Readonly<HoneyPotStats>;
+    /**
+     * Clears audit log and resets statistics.
+     */
+    reset(): void;
+    /**
+     * Returns recent log entries in reverse chronological order.
+     *
+     * @param limit Number of recent entries to return (default: 100).
+     * @returns Recent audit log entries.
+     */
+    getRecent(limit?: number): AuditLogEntry[];
+    /**
+     * Detects potential security issues based on activity patterns.
+     *
+     * @returns Array of anomalies detected.
+     */
+    detectAnomalies(): Array<{
+        type: string;
+        severity: "low" | "medium" | "high";
+        message: string;
+    }>;
+}
+export default HoneyPot;
+//# sourceMappingURL=honeypot.d.ts.map

package/dist/honeypot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"honeypot.d.ts","sourceRoot":"","sources":["../src/honeypot.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,iBAAiB,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,QAAQ;IACpB,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,KAAK,CAaX;IAEF,OAAO,CAAC,UAAU,CAAS;IAE3B;;;;OAIG;gBACS,UAAU,GAAE,MAAc;IAItC;;;;;;;;OAQG;IACI,MAAM,CACZ,KAAK,EAAE,YAAY,EACnB,GAAG,EAAE,iBAAiB,EACtB,KAAK,EAAE,kBAAkB,EACzB,GAAG,CAAC,EAAE,QAAQ,EACd,IAAI,CAAC,EAAE,SAAS,GACd,IAAI;IAYP;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAmB1B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAoB/B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAkChC;;OAEG;IACH,OAAO,CAAC,cAAc;IAyCtB;;OAEG;IACH,OAAO,CAAC,eAAe;IAyCvB;;;;;;OAMG;IACH,OAAO,CAAC,GAAG;IAuBX;;;;;;OAMG;IACI,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE;IAOnE;;;;OAIG;IACI,QAAQ,IAAI,QAAQ,CAAC,aAAa,CAAC;IAI1C;;OAEG;IACI,KAAK,IAAI,IAAI;IAkBpB;;;;;OAKG;IACI,SAAS,CAAC,KAAK,GAAE,MAAY,GAAG,aAAa,EAAE;IAItD;;;;OAIG;IACI,eAAe,IAAI,KAAK,CAAC;QAC/B,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;QACpC,OAAO,EAAE,MAAM,CAAC;KAChB,CAAC;CAkDF;AAED,eAAe,QAAQ,CAAC"}

package/dist/honeypot.js

@@ -0,0 +1,289 @@
+/**
+ * Honeypot tracking and auditing module for virtual shell events.
+ *
+ * Attaches listeners to VirtualShell, VirtualFileSystem, VirtualUserManager,
+ * SshMimic, and SftpMimic instances to log all activity for security auditing,
+ * anomaly detection, and forensic analysis.
+ *
+ * @module honeypot
+ */
+/**
+ * HoneyPot audit and event tracking utility.
+ *
+ * Singleton-like helper that attaches listeners to virtual shell components
+ * and maintains an audit log of all activity.
+ */
+export class HoneyPot {
+    auditLog = [];
+    stats = {
+        authAttempts: 0,
+        authSuccesses: 0,
+        authFailures: 0,
+        commands: 0,
+        fileWrites: 0,
+        fileReads: 0,
+        sessionStarts: 0,
+        sessionEnds: 0,
+        userCreated: 0,
+        userDeleted: 0,
+        clientConnects: 0,
+        clientDisconnects: 0,
+    };
+    maxLogSize;
+    /**
+     * Creates a new HoneyPot instance.
+     *
+     * @param maxLogSize Maximum audit log entries to retain (default: 10000).
+     */
+    constructor(maxLogSize = 10000) {
+        this.maxLogSize = maxLogSize;
+    }
+    /**
+     * Attaches honeypot listeners to all provided event emitters.
+     *
+     * @param shell VirtualShell instance.
+     * @param vfs VirtualFileSystem instance.
+     * @param users VirtualUserManager instance.
+     * @param ssh SshMimic instance (optional).
+     * @param sftp SftpMimic instance (optional).
+     */
+    attach(shell, vfs, users, ssh, sftp) {
+        this.attachVirtualShell(shell);
+        this.attachVirtualFileSystem(vfs);
+        this.attachVirtualUserManager(users);
+        if (ssh) {
+            this.attachSshMimic(ssh);
+        }
+        if (sftp) {
+            this.attachSftpMimic(sftp);
+        }
+    }
+    /**
+     * Attaches to VirtualShell events.
+     */
+    attachVirtualShell(shell) {
+        shell.on("initialized", () => {
+            this.log("VirtualShell", "initialized", {});
+        });
+        shell.on("command", (data) => {
+            this.stats.commands++;
+            this.log("VirtualShell", "command", data);
+        });
+        shell.on("session:start", (data) => {
+            this.stats.sessionStarts++;
+            this.log("VirtualShell", "session:start", data);
+        });
+    }
+    /**
+     * Attaches to VirtualFileSystem events.
+     */
+    attachVirtualFileSystem(vfs) {
+        vfs.on("file:read", (data) => {
+            this.stats.fileReads++;
+            this.log("VirtualFileSystem", "file:read", data);
+        });
+        vfs.on("file:write", (data) => {
+            this.stats.fileWrites++;
+            this.log("VirtualFileSystem", "file:write", data);
+        });
+        vfs.on("dir:create", (data) => {
+            this.log("VirtualFileSystem", "dir:create", data);
+        });
+        vfs.on("mirror:flush", () => {
+            this.log("VirtualFileSystem", "mirror:flush", {});
+        });
+    }
+    /**
+     * Attaches to VirtualUserManager events.
+     */
+    attachVirtualUserManager(users) {
+        users.on("initialized", () => {
+            this.log("VirtualUserManager", "initialized", {});
+        });
+        users.on("user:add", (data) => {
+            this.stats.userCreated++;
+            this.log("VirtualUserManager", "user:add", data);
+        });
+        users.on("user:delete", (data) => {
+            this.stats.userDeleted++;
+            this.log("VirtualUserManager", "user:delete", data);
+        });
+        users.on("session:register", (data) => {
+            this.log("VirtualUserManager", "session:register", data);
+        });
+        users.on("session:unregister", (data) => {
+            this.stats.sessionEnds++;
+            this.log("VirtualUserManager", "session:unregister", data);
+        });
+    }
+    /**
+     * Attaches to SshMimic events.
+     */
+    attachSshMimic(ssh) {
+        ssh.on("start", (data) => {
+            this.log("SshMimic", "start", data);
+        });
+        ssh.on("stop", () => {
+            this.log("SshMimic", "stop", {});
+        });
+        ssh.on("auth:success", (data) => {
+            this.stats.authAttempts++;
+            this.stats.authSuccesses++;
+            this.log("SshMimic", "auth:success", data);
+        });
+        ssh.on("auth:failure", (data) => {
+            this.stats.authAttempts++;
+            this.stats.authFailures++;
+            this.log("SshMimic", "auth:failure", data);
+        });
+        ssh.on("client:connect", () => {
+            this.stats.clientConnects++;
+            this.log("SshMimic", "client:connect", {});
+        });
+        ssh.on("client:disconnect", (data) => {
+            this.stats.clientDisconnects++;
+            this.log("SshMimic", "client:disconnect", data);
+        });
+    }
+    /**
+     * Attaches to SftpMimic events.
+     */
+    attachSftpMimic(sftp) {
+        sftp.on("start", (data) => {
+            this.log("SftpMimic", "start", data);
+        });
+        sftp.on("stop", () => {
+            this.log("SftpMimic", "stop", {});
+        });
+        sftp.on("auth:success", (data) => {
+            this.stats.authAttempts++;
+            this.stats.authSuccesses++;
+            this.log("SftpMimic", "auth:success", data);
+        });
+        sftp.on("auth:failure", (data) => {
+            this.stats.authAttempts++;
+            this.stats.authFailures++;
+            this.log("SftpMimic", "auth:failure", data);
+        });
+        sftp.on("client:connect", () => {
+            this.stats.clientConnects++;
+            this.log("SftpMimic", "client:connect", {});
+        });
+        sftp.on("client:disconnect", (data) => {
+            this.stats.clientDisconnects++;
+            this.log("SftpMimic", "client:disconnect", data);
+        });
+    }
+    /**
+     * Records an audit log entry.
+     *
+     * @param source Event source (e.g., "SshMimic", "VirtualFileSystem").
+     * @param type Event type.
+     * @param details Event-specific data.
+     */
+    log(source, type, details) {
+        const entry = {
+            timestamp: new Date().toISOString(),
+            type,
+            source,
+            details,
+        };
+        this.auditLog.push(entry);
+        // Trim log if exceeds max size
+        if (this.auditLog.length > this.maxLogSize) {
+            this.auditLog = this.auditLog.slice(-this.maxLogSize);
+        }
+        // Console output for real-time monitoring
+        console.log(`[AUDIT] ${entry.timestamp} | ${source} | ${type}`, details);
+    }
+    /**
+     * Returns audit log entries matching optional filters.
+     *
+     * @param type Optional event type filter.
+     * @param source Optional source filter.
+     * @returns Filtered audit log entries.
+     */
+    getAuditLog(type, source) {
+        return this.auditLog.filter((entry) => (!type || entry.type === type) && (!source || entry.source === source));
+    }
+    /**
+     * Returns current activity statistics.
+     *
+     * @returns Snapshot of honeypot stats.
+     */
+    getStats() {
+        return Object.freeze({ ...this.stats });
+    }
+    /**
+     * Clears audit log and resets statistics.
+     */
+    reset() {
+        this.auditLog = [];
+        this.stats = {
+            authAttempts: 0,
+            authSuccesses: 0,
+            authFailures: 0,
+            commands: 0,
+            fileWrites: 0,
+            fileReads: 0,
+            sessionStarts: 0,
+            sessionEnds: 0,
+            userCreated: 0,
+            userDeleted: 0,
+            clientConnects: 0,
+            clientDisconnects: 0,
+        };
+    }
+    /**
+     * Returns recent log entries in reverse chronological order.
+     *
+     * @param limit Number of recent entries to return (default: 100).
+     * @returns Recent audit log entries.
+     */
+    getRecent(limit = 100) {
+        return this.auditLog.slice(Math.max(0, this.auditLog.length - limit));
+    }
+    /**
+     * Detects potential security issues based on activity patterns.
+     *
+     * @returns Array of anomalies detected.
+     */
+    detectAnomalies() {
+        const anomalies = [];
+        // High auth failure rate
+        if (this.stats.authAttempts > 0 &&
+            this.stats.authFailures / this.stats.authAttempts > 0.5) {
+            anomalies.push({
+                type: "high_auth_failure_rate",
+                severity: "medium",
+                message: `Auth failure rate: ${((this.stats.authFailures / this.stats.authAttempts) * 100).toFixed(1)}%`,
+            });
+        }
+        // Excessive auth failures in short time
+        if (this.stats.authFailures > 10) {
+            anomalies.push({
+                type: "excessive_auth_failures",
+                severity: "high",
+                message: `${this.stats.authFailures} authentication failures detected`,
+            });
+        }
+        // Unusual command execution volume
+        if (this.stats.commands > 1000) {
+            anomalies.push({
+                type: "high_command_volume",
+                severity: "low",
+                message: `${this.stats.commands} commands executed`,
+            });
+        }
+        // Unusual file write volume
+        if (this.stats.fileWrites > 500) {
+            anomalies.push({
+                type: "high_write_volume",
+                severity: "medium",
+                message: `${this.stats.fileWrites} file write operations`,
+            });
+        }
+        return anomalies;
+    }
+}
+export default HoneyPot;

package/dist/index.d.ts

@@ -1,11 +1,13 @@
+import { HoneyPot } from "./Honeypot";
 import { SshClient } from "./SSHClient";
 import { SftpMimic, SshMimic } from "./SSHMimic/index";
 import VirtualFileSystem from "./VirtualFileSystem";
 import { VirtualShell } from "./VirtualShell";
 import { VirtualUserManager } from "./VirtualUserManager";
+export type { AuditLogEntry, HoneyPotStats, } from "./Honeypot";
 export type { CommandContext, CommandMode, CommandOutcome, CommandResult, NanoEditorSession, ShellModule, SudoChallenge, } from "./types/commands";
 export type { ExecStream, ShellStream } from "./types/streams";
 export type { RemoveOptions, VfsBaseNode, VfsDirectoryNode, VfsFileNode, VfsNodeStats, VfsNodeType, VfsSnapshot, VfsSnapshotBaseNode, VfsSnapshotDirectoryNode, VfsSnapshotFileNode, VfsSnapshotNode, WriteFileOptions, } from "./types/vfs";
-export { SshClient, VirtualFileSystem, SftpMimic as VirtualSftpServer, VirtualShell, SshMimic as VirtualSshServer, VirtualUserManager, };
+export { HoneyPot, SshClient, VirtualFileSystem, SftpMimic as VirtualSftpServer, VirtualShell, SshMimic as VirtualSshServer, VirtualUserManager, };
 export { getArg, getFlag, ifFlag, } from "./commands/command-helpers";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,iBAAiB,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,YAAY,EACX,cAAc,EACd,WAAW,EACX,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,aAAa,GACb,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/D,YAAY,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,SAAS,EACT,iBAAiB,EACjB,SAAS,IAAI,iBAAiB,EAC9B,YAAY,EACZ,QAAQ,IAAI,gBAAgB,EAC5B,kBAAkB,GAClB,CAAC;AAEF,OAAO,EACN,MAAM,EACN,OAAO,EACP,MAAM,GACN,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,iBAAiB,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,YAAY,EACX,aAAa,EACb,aAAa,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EACX,cAAc,EACd,WAAW,EACX,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,aAAa,GACb,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/D,YAAY,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,SAAS,IAAI,iBAAiB,EAC9B,YAAY,EACZ,QAAQ,IAAI,gBAAgB,EAC5B,kBAAkB,GAClB,CAAC;AAEF,OAAO,EACN,MAAM,EACN,OAAO,EACP,MAAM,GACN,MAAM,4BAA4B,CAAC"}