typescript-virtual-container 1.1.4 → 1.1.5

package/src/Honeypot/index.ts

@@ -0,0 +1,422 @@
+/**
+ * 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 { EventEmitter } from "node:events";
+import type { SshMimic } from "../SSHMimic";
+import type { SftpMimic } from "../SSHMimic/sftp";
+import type VirtualFileSystem from "../VirtualFileSystem";
+import type { VirtualShell } from "../VirtualShell";
+import type { VirtualUserManager } from "../VirtualUserManager";
+
+/**
+ * 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 class HoneyPot {
+	private auditLog: AuditLogEntry[] = [];
+	private stats: HoneyPotStats = {
+		authAttempts: 0,
+		authSuccesses: 0,
+		authFailures: 0,
+		commands: 0,
+		fileWrites: 0,
+		fileReads: 0,
+		sessionStarts: 0,
+		sessionEnds: 0,
+		userCreated: 0,
+		userDeleted: 0,
+		clientConnects: 0,
+		clientDisconnects: 0,
+	};
+
+	private maxLogSize: number;
+
+	/**
+	 * Creates a new HoneyPot instance.
+	 *
+	 * @param maxLogSize Maximum audit log entries to retain (default: 10000).
+	 */
+	constructor(maxLogSize: number = 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).
+	 */
+	public attach(
+		shell: VirtualShell,
+		vfs: VirtualFileSystem,
+		users: VirtualUserManager,
+		ssh?: SshMimic,
+		sftp?: SftpMimic,
+	): void {
+		this.attachVirtualShell(shell);
+		this.attachVirtualFileSystem(vfs);
+		this.attachVirtualUserManager(users);
+		if (ssh) {
+			this.attachSshMimic(ssh);
+		}
+		if (sftp) {
+			this.attachSftpMimic(sftp);
+		}
+	}
+
+	/**
+	 * Attaches to VirtualShell events.
+	 */
+	private attachVirtualShell(shell: VirtualShell): void {
+		(shell as EventEmitter).on("initialized", () => {
+			this.log("VirtualShell", "initialized", {});
+		});
+
+		(shell as EventEmitter).on("command", (data: Record<string, unknown>) => {
+			this.stats.commands++;
+			this.log("VirtualShell", "command", data);
+		});
+
+		(shell as EventEmitter).on(
+			"session:start",
+			(data: Record<string, unknown>) => {
+				this.stats.sessionStarts++;
+				this.log("VirtualShell", "session:start", data);
+			},
+		);
+	}
+
+	/**
+	 * Attaches to VirtualFileSystem events.
+	 */
+	private attachVirtualFileSystem(vfs: VirtualFileSystem): void {
+		(vfs as EventEmitter).on("file:read", (data: Record<string, unknown>) => {
+			this.stats.fileReads++;
+			this.log("VirtualFileSystem", "file:read", data);
+		});
+
+		(vfs as EventEmitter).on("file:write", (data: Record<string, unknown>) => {
+			this.stats.fileWrites++;
+			this.log("VirtualFileSystem", "file:write", data);
+		});
+
+		(vfs as EventEmitter).on("dir:create", (data: Record<string, unknown>) => {
+			this.log("VirtualFileSystem", "dir:create", data);
+		});
+
+		(vfs as EventEmitter).on("mirror:flush", () => {
+			this.log("VirtualFileSystem", "mirror:flush", {});
+		});
+	}
+
+	/**
+	 * Attaches to VirtualUserManager events.
+	 */
+	private attachVirtualUserManager(users: VirtualUserManager): void {
+		(users as EventEmitter).on("initialized", () => {
+			this.log("VirtualUserManager", "initialized", {});
+		});
+
+		(users as EventEmitter).on("user:add", (data: Record<string, unknown>) => {
+			this.stats.userCreated++;
+			this.log("VirtualUserManager", "user:add", data);
+		});
+
+		(users as EventEmitter).on(
+			"user:delete",
+			(data: Record<string, unknown>) => {
+				this.stats.userDeleted++;
+				this.log("VirtualUserManager", "user:delete", data);
+			},
+		);
+
+		(users as EventEmitter).on(
+			"session:register",
+			(data: Record<string, unknown>) => {
+				this.log("VirtualUserManager", "session:register", data);
+			},
+		);
+
+		(users as EventEmitter).on(
+			"session:unregister",
+			(data: Record<string, unknown>) => {
+				this.stats.sessionEnds++;
+				this.log("VirtualUserManager", "session:unregister", data);
+			},
+		);
+	}
+
+	/**
+	 * Attaches to SshMimic events.
+	 */
+	private attachSshMimic(ssh: SshMimic): void {
+		(ssh as EventEmitter).on("start", (data: Record<string, unknown>) => {
+			this.log("SshMimic", "start", data);
+		});
+
+		(ssh as EventEmitter).on("stop", () => {
+			this.log("SshMimic", "stop", {});
+		});
+
+		(ssh as EventEmitter).on(
+			"auth:success",
+			(data: Record<string, unknown>) => {
+				this.stats.authAttempts++;
+				this.stats.authSuccesses++;
+				this.log("SshMimic", "auth:success", data);
+			},
+		);
+
+		(ssh as EventEmitter).on(
+			"auth:failure",
+			(data: Record<string, unknown>) => {
+				this.stats.authAttempts++;
+				this.stats.authFailures++;
+				this.log("SshMimic", "auth:failure", data);
+			},
+		);
+
+		(ssh as EventEmitter).on("client:connect", () => {
+			this.stats.clientConnects++;
+			this.log("SshMimic", "client:connect", {});
+		});
+
+		(ssh as EventEmitter).on(
+			"client:disconnect",
+			(data: Record<string, unknown>) => {
+				this.stats.clientDisconnects++;
+				this.log("SshMimic", "client:disconnect", data);
+			},
+		);
+	}
+
+	/**
+	 * Attaches to SftpMimic events.
+	 */
+	private attachSftpMimic(sftp: SftpMimic): void {
+		(sftp as EventEmitter).on("start", (data: Record<string, unknown>) => {
+			this.log("SftpMimic", "start", data);
+		});
+
+		(sftp as EventEmitter).on("stop", () => {
+			this.log("SftpMimic", "stop", {});
+		});
+
+		(sftp as EventEmitter).on(
+			"auth:success",
+			(data: Record<string, unknown>) => {
+				this.stats.authAttempts++;
+				this.stats.authSuccesses++;
+				this.log("SftpMimic", "auth:success", data);
+			},
+		);
+
+		(sftp as EventEmitter).on(
+			"auth:failure",
+			(data: Record<string, unknown>) => {
+				this.stats.authAttempts++;
+				this.stats.authFailures++;
+				this.log("SftpMimic", "auth:failure", data);
+			},
+		);
+
+		(sftp as EventEmitter).on("client:connect", () => {
+			this.stats.clientConnects++;
+			this.log("SftpMimic", "client:connect", {});
+		});
+
+		(sftp as EventEmitter).on(
+			"client:disconnect",
+			(data: Record<string, unknown>) => {
+				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.
+	 */
+	private log(
+		source: string,
+		type: string,
+		details: Record<string, unknown>,
+	): void {
+		const entry: AuditLogEntry = {
+			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.
+	 */
+	public getAuditLog(type?: string, source?: string): AuditLogEntry[] {
+		return this.auditLog.filter(
+			(entry) =>
+				(!type || entry.type === type) && (!source || entry.source === source),
+		);
+	}
+
+	/**
+	 * Returns current activity statistics.
+	 *
+	 * @returns Snapshot of honeypot stats.
+	 */
+	public getStats(): Readonly<HoneyPotStats> {
+		return Object.freeze({ ...this.stats });
+	}
+
+	/**
+	 * Clears audit log and resets statistics.
+	 */
+	public reset(): void {
+		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.
+	 */
+	public getRecent(limit: number = 100): AuditLogEntry[] {
+		return this.auditLog.slice(Math.max(0, this.auditLog.length - limit));
+	}
+
+	/**
+	 * Detects potential security issues based on activity patterns.
+	 *
+	 * @returns Array of anomalies detected.
+	 */
+	public detectAnomalies(): Array<{
+		type: string;
+		severity: "low" | "medium" | "high";
+		message: string;
+	}> {
+		const anomalies: Array<{
+			type: string;
+			severity: "low" | "medium" | "high";
+			message: string;
+		}> = [];
+
+		// 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/src/SSHMimic/index.ts

@@ -1,3 +1,4 @@
+import { EventEmitter } from "node:events";
 import { Server as SshServer } from "ssh2";
 import { VirtualShell } from "../VirtualShell";
 import { runExec } from "./exec";
@@ -10,7 +11,7 @@ import { loadOrCreateHostKey } from "./hostKey";
  * Create an instance, call {@link SshMimic.start}, and stop it with
  * {@link SshMimic.stop} when your process exits.
  */
-class SshMimic {
+class SshMimic extends EventEmitter {
 	port: number;
 	server: SshServer | null;
 	private shell: VirtualShell;
@@ -32,6 +33,7 @@ class SshMimic {
 		hostname?: string;
 		shell?: VirtualShell;
 	}) {
+		super();
 		this.port = port;
 		this.shellHostname = hostname;
 		this.server = null;
@@ -60,6 +62,8 @@ class SshMimic {
 				let remoteAddress = "unknown";
 				let sessionId: string | null = null;
 
+				this.emit("client:connect");
+
 				client.on("authentication", (ctx) => {
 					shell;
 					if (ctx.method === "password") {
@@ -69,12 +73,17 @@ class SshMimic {
 						if (
 							!shell.users.verifyPassword(candidateUser, ctx.password ?? "")
 						) {
+							this.emit("auth:failure", {
+								username: candidateUser,
+								remoteAddress,
+							});
 							ctx.reject();
 							return;
 						}
 
 						authUser = candidateUser;
 						sessionId = shell.users.registerSession(authUser, remoteAddress).id;
+						this.emit("auth:success", { username: authUser, remoteAddress });
 
 						const homePath = `/home/${authUser}`;
 						if (!shell.vfs.exists(homePath)) {
@@ -95,6 +104,7 @@ class SshMimic {
 
 				client.on("close", () => {
 					shell.users.unregisterSession(sessionId);
+					this.emit("client:disconnect", { user: authUser });
 					sessionId = null;
 				});
 
@@ -149,6 +159,7 @@ class SshMimic {
 			this.server?.once("error", (err: unknown) => reject(err));
 			this.server?.listen(this.port, "0.0.0.0", () => {
 				console.log(`SSH Mimic listening on port ${this.port}`);
+				this.emit("start", { port: this.port });
 				resolve(this.port);
 			});
 		});
@@ -161,6 +172,7 @@ class SshMimic {
 		if (this.server) {
 			this.server.close(() => {
 				console.log("SSH Mimic stopped");
+				this.emit("stop");
 			});
 		}
 	}

package/src/SSHMimic/sftp.ts

@@ -1,4 +1,5 @@
 /** biome-ignore-all lint/style/useNamingConvention: const as enum */
+import { EventEmitter } from "node:events";
 import * as path from "node:path";
 import type { AuthenticationType, KeyboardAuthContext } from "ssh2";
 import { Server as SshServer } from "ssh2";
@@ -135,7 +136,7 @@ export interface SftpMimicOptions {
 	users?: VirtualUserManager;
 }
 
-export class SftpMimic {
+export class SftpMimic extends EventEmitter {
 	port: number;
 	server: SshServer | null;
 	private readonly hostname: string;
@@ -152,6 +153,7 @@ export class SftpMimic {
 		vfs,
 		users,
 	}: SftpMimicOptions) {
+		super();
 		this.port = port;
 		this.server = null;
 		this.hostname = hostname;
@@ -206,6 +208,8 @@ export class SftpMimic {
 				let sessionId: string | null = null;
 				let remoteAddress = "unknown";
 
+				this.emit("client:connect");
+
 				// Add error handling for the client
 				client.on("error", (error: unknown) => {
 					console.error(`[SFTP] Client error:`, error);
@@ -246,11 +250,16 @@ export class SftpMimic {
 						if (
 							!this.getUsers().verifyPassword(candidateUser, ctx.password ?? "")
 						) {
+							this.emit("auth:failure", {
+								username: candidateUser,
+								remoteAddress,
+							});
 							ctx.reject(allowedAuthMethods);
 							return;
 						}
 
 						acceptSession(candidateUser);
+						this.emit("auth:success", { username: authUser, remoteAddress });
 						ctx.accept();
 						return;
 					}
@@ -262,11 +271,19 @@ export class SftpMimic {
 							(answers) => {
 								const password = answers[0] ?? "";
 								if (!this.getUsers().verifyPassword(candidateUser, password)) {
+									this.emit("auth:failure", {
+										username: candidateUser,
+										remoteAddress,
+									});
 									keyboardCtx.reject(allowedAuthMethods);
 									return;
 								}
 
 								acceptSession(candidateUser);
+								this.emit("auth:success", {
+									username: authUser,
+									remoteAddress,
+								});
 								keyboardCtx.accept();
 							},
 						);
@@ -278,6 +295,7 @@ export class SftpMimic {
 
 				client.on("close", () => {
 					this.getUsers().unregisterSession(sessionId);
+					this.emit("client:disconnect", { user: authUser });
 					sessionId = null;
 				});
 
@@ -311,6 +329,7 @@ export class SftpMimic {
 						? address.port
 						: this.port;
 				console.log(`SFTP Mimic listening on port ${actualPort}`);
+				this.emit("start", { port: actualPort });
 				resolve(actualPort as number);
 			});
 		});
@@ -320,6 +339,7 @@ export class SftpMimic {
 		if (this.server) {
 			this.server.close(() => {
 				console.log("SFTP Mimic stopped");
+				this.emit("stop");
 			});
 		}
 	}

package/src/VirtualFileSystem/index.ts

@@ -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";
@@ -15,7 +16,7 @@ import { normalizePath } from "./path";
  * {@link VirtualFileSystem.restoreMirror} on startup and
  * {@link VirtualFileSystem.flushMirror} to persist pending changes.
  */
-class VirtualFileSystem {
+class VirtualFileSystem extends EventEmitter {
 	private readonly mirrorRoot: string;
 
 	private ensureMirrorRoot(): void {
@@ -93,6 +94,7 @@ class VirtualFileSystem {
 	 * @param baseDir Base directory used to resolve mirror archive location.
 	 */
 	constructor(baseDir: string = process.cwd()) {
+		super();
 		this.mirrorRoot = path.resolve(baseDir, ".vfs", "mirror");
 	}
 
@@ -112,6 +114,7 @@ class VirtualFileSystem {
 	 */
 	public async flushMirror(): Promise<void> {
 		this.ensureMirrorRoot();
+		this.emit("mirror:flush");
 	}
 
 	/**
@@ -129,6 +132,7 @@ class VirtualFileSystem {
 			);
 		}
 		fs.mkdirSync(fsPath, { recursive: true, mode });
+		this.emit("dir:create", { path: normalizePath(targetPath), mode });
 	}
 
 	/**
@@ -165,6 +169,7 @@ class VirtualFileSystem {
 
 		fs.writeFileSync(fsPath, storedContent);
 		fs.chmodSync(fsPath, options.mode ?? 0o644);
+		this.emit("file:write", { path: normalized, size: storedContent.length });
 	}
 
 	/**
@@ -184,6 +189,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/src/VirtualShell/index.ts

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { EventEmitter } from "node:events";
 import { createCustomCommand, registerCommand, runCommand } from "../commands";
 import type { CommandContext, CommandResult } from "../types/commands";
 import type { ShellStream } from "../types/streams";
@@ -46,7 +47,7 @@ function resolveAutoSudoForNewUsers(): boolean {
  * Instances are used both by the SSH server facade and by the programmatic
  * client API.
  */
-class VirtualShell {
+class VirtualShell extends EventEmitter {
 	basePath: string = ".";
 	vfs: VirtualFileSystem;
 	users: VirtualUserManager;
@@ -66,6 +67,7 @@ class VirtualShell {
 		properties?: ShellProperties,
 		basePath?: string,
 	) {
+		super();
 		this.hostname = hostname;
 		this.properties = properties || defaultShellProperties;
 		this.basePath = basePath || ".";
@@ -84,6 +86,7 @@ class VirtualShell {
 		this.initialized = (async () => {
 			await vfs.restoreMirror();
 			await users.initialize();
+			this.emit("initialized");
 		})();
 	}
 
@@ -124,6 +127,7 @@ class VirtualShell {
 	 */
 	executeCommand(rawInput: string, authUser: string, cwd: string): void {
 		runCommand(rawInput, authUser, this.hostname, "shell", cwd, this);
+		this.emit("command", { command: rawInput, user: authUser, cwd });
 	}
 
 	/**
@@ -143,6 +147,7 @@ class VirtualShell {
 		terminalSize: { cols: number; rows: number },
 	): void {
 		// Interactive shell logic
+		this.emit("session:start", { user: authUser, sessionId, remoteAddress });
 		startShell(
 			this.properties,
 			stream,