typescript-virtual-container 1.1.4 → 1.1.6

package/examples/honeypot-quickstart.ts

@@ -0,0 +1,110 @@
+/**
+ * HoneyPot Quick Start Example
+ *
+ * A minimal, step-by-step introduction to HoneyPot auditing.
+ * Perfect for beginners.
+ *
+ * Run with: bun run examples/honeypot-quickstart.ts
+ */
+
+import {
+    HoneyPot,
+    SshClient,
+    VirtualShell,
+    VirtualSshServer,
+} from "../src/index";
+
+async function quickStart() {
+	console.log("🍯 HoneyPot Quick Start\n");
+
+	// Step 1: Create virtual environment
+	console.log("Step 1️⃣  Creating virtual environment...");
+	const shell = new VirtualShell("my-lab");
+	const ssh = new VirtualSshServer({ port: 2222, shell });
+	await ssh.start();
+
+	const users = shell.getUsers()!;
+	const vfs = shell.getVfs()!;
+
+	console.log("✅ Environment ready\n");
+
+	// Step 2: Create HoneyPot instance
+	console.log("Step 2️⃣  Initializing HoneyPot...");
+	const honeypot = new HoneyPot();
+
+	// Step 3: Attach HoneyPot to all components
+	console.log("Step 3️⃣  Attaching HoneyPot to components...");
+	honeypot.attach(shell, vfs, users, ssh);
+
+	console.log("✅ HoneyPot is now tracking all activity\n");
+
+	// Step 4: Do some work (which will be audited)
+	console.log("Step 4️⃣  Performing some operations...\n");
+
+	// Create a user
+	await users.addUser("dev_user", "secure_pass");
+	console.log("  ✓ Created user 'dev_user'");
+
+	// Create a client
+	const client = new SshClient(shell, "dev_user");
+
+	// Create files
+	await client.mkdir("/app", true);
+	await client.writeFile("/app/config.json", '{"debug":true}');
+	await client.readFile("/app/config.json");
+
+	console.log("  ✓ Created /app directory and config.json");
+	console.log("  ✓ Read config.json\n");
+
+	// Step 5: Get statistics
+	console.log("Step 5️⃣  Viewing activity statistics...\n");
+	const stats = honeypot.getStats();
+	console.log(`  📊 Commands: ${stats.commands}`);
+	console.log(`  📝 File writes: ${stats.fileWrites}`);
+	console.log(`  📖 File reads: ${stats.fileReads}`);
+	console.log(`  👤 Users created: ${stats.userCreated}\n`);
+
+	// Step 6: Get recent events
+	console.log("Step 6️⃣  Last 5 events:\n");
+	honeypot.getRecent(5).forEach((entry, idx) => {
+		console.log(`  ${idx + 1}. [${entry.source}] ${entry.type}`);
+		if (Object.keys(entry.details).length > 0) {
+			console.log(`     └─ ${JSON.stringify(entry.details)}`);
+		}
+	});
+	console.log();
+
+	// Step 7: Query filtered logs
+	console.log("Step 7️⃣  Querying specific event types...\n");
+
+	const userEvents = honeypot.getAuditLog("user:add");
+	console.log(`  👤 User creation events: ${userEvents.length}`);
+
+	const fileEvents = honeypot.getAuditLog(undefined, "VirtualFileSystem");
+	console.log(`  📁 VirtualFileSystem events: ${fileEvents.length}\n`);
+
+	// Step 8: Detect anomalies
+	console.log("Step 8️⃣  Checking for anomalies...\n");
+	const anomalies = honeypot.detectAnomalies();
+	if (anomalies.length === 0) {
+		console.log("  ✅ No anomalies detected\n");
+	} else {
+		console.log("  ⚠️  Anomalies found:");
+		anomalies.forEach((a) => {
+			console.log(`     • ${a.message}`);
+		});
+		console.log();
+	}
+
+	// Step 9: Export audit data (for storage/analysis)
+	console.log("Step 9️⃣  Exporting audit log...\n");
+	const fullLog = honeypot.getAuditLog();
+	console.log(`  ✓ Exported ${fullLog.length} audit entries`);
+	console.log(`  ✓ Ready to store in database, file, or monitoring system\n`);
+
+	// Cleanup
+	ssh.stop();
+	console.log("✅ Example complete!");
+}
+
+quickStart().catch(console.error);

package/package.json

@@ -4,7 +4,7 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "license": "MIT",
   "keywords": [
     "ssh",

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");
 			});
 		}
 	}