typescript-virtual-container 1.5.2 → 1.5.4

package/src/Honeypot/index.ts

@@ -1,457 +0,0 @@
-/**
- * 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 { PerfLogger } from "../utils/perfLogger";
-import { createPerfLogger } from "../utils/perfLogger";
-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;
-	shellFreezes: number;
-	shellThaws: number;
-}
-
-const perf: PerfLogger = createPerfLogger("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 {
-	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,
-		shellFreezes: 0,
-		shellThaws: 0,
-	};
-
-	private maxLogSize: number;
-	/** Reference kept so VFS events can ping the shell's idle manager. */
-	private _shell: VirtualShell | null = null;
-
-	/**
-	 * Creates a new HoneyPot instance.
-	 *
-	 * @param maxLogSize Maximum audit log entries to retain (default: 10000).
-	 */
-	constructor(maxLogSize: number = 10000) {
-		perf.mark("constructor");
-		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 {
-		perf.mark("attach");
-		this._shell = shell;
-		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);
-			},
-		);
-
-		(shell as EventEmitter).on("shell:freeze", () => {
-			this.stats.shellFreezes++;
-			this.log("VirtualShell", "shell:freeze", {});
-		});
-
-		(shell as EventEmitter).on("shell:thaw", () => {
-			this.stats.shellThaws++;
-			this.log("VirtualShell", "shell:thaw", {});
-		});
-	}
-
-	/**
-	 * Attaches to VirtualFileSystem events.
-	 * Also pings the shell's idle manager so SFTP/direct VFS activity
-	 * counts as activity and prevents spurious freezes.
-	 */
-	private attachVirtualFileSystem(vfs: VirtualFileSystem): void {
-		(vfs as EventEmitter).on("file:read", (data: Record<string, unknown>) => {
-			this.stats.fileReads++;
-			this._shell?.pingIdle();
-			this.log("VirtualFileSystem", "file:read", data);
-		});
-
-		(vfs as EventEmitter).on("file:write", (data: Record<string, unknown>) => {
-			this.stats.fileWrites++;
-			this._shell?.pingIdle();
-			this.log("VirtualFileSystem", "file:write", data);
-		});
-
-		(vfs as EventEmitter).on("dir:create", (data: Record<string, unknown>) => {
-			this._shell?.pingIdle();
-			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[] {
-		perf.mark("getAuditLog");
-		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> {
-		perf.mark("getStats");
-		return Object.freeze({ ...this.stats });
-	}
-
-	/**
-	 * Clears audit log and resets statistics.
-	 */
-	public reset(): void {
-		perf.mark("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,
-			shellFreezes: 0,
-			shellThaws: 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[] {
-		perf.mark("getRecent");
-		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;
-	}> {
-		perf.mark("detectAnomalies");
-		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/SSHClient/index.ts

@@ -1,270 +0,0 @@
-import { runCommand } from "../commands";
-import type { CommandResult } from "../types/commands";
-import type { PerfLogger } from "../utils/perfLogger";
-import { createPerfLogger } from "../utils/perfLogger";
-import type { VirtualShell } from "../VirtualShell";
-
-/**
- * Programmatic client for executing shell commands against a virtual shell.
- *
- * Maintains working-directory state across invocations and runs commands as a
- * single authenticated user without SSH transport overhead.
- *
- * @example
- * ```ts
- * const shell = new VirtualShell("typescript-vm");
- * const client = new SshClient(shell, "alice");
- * const result = await client.cd("/tmp");
- * const list = await client.ls();
- * ```
- */
-const perf: PerfLogger = createPerfLogger("SshClient");
-
-export class SshClient {
-	private currentCwd = "/";
-
-	/**
-	 * Creates a programmatic client bound to a virtual shell and user.
-	 *
-	 * @param shell Parent virtual shell instance.
-	 * @param username Login user for all commands.
-	 */
-	constructor(
-		private shell: VirtualShell,
-		private username: string,
-	) {
-		perf.mark("constructor");
-	}
-
-	/**
-	 * Executes raw shell command.
-	 *
-	 * @param command Unparsed command line.
-	 * @returns Command result with stdout/stderr/exitCode.
-	 */
-	async exec(command: string): Promise<CommandResult> {
-		perf.mark("exec");
-		const vfs = this.shell.getVfs();
-		const users = this.shell.getUsers();
-		const hostname = this.shell.getHostname();
-
-		if (!vfs || !users) {
-			throw new Error("SSH client not started");
-		}
-
-		const result = runCommand(
-			command,
-			this.username,
-			hostname,
-			"exec",
-			this.currentCwd,
-			this.shell,
-		);
-
-		// Handle async results
-		const resolved = result instanceof Promise ? await result : result;
-
-		// Propagate cwd changes (cd, su, etc.)
-		if (resolved.nextCwd && (resolved.exitCode ?? 0) === 0) {
-			this.currentCwd = resolved.nextCwd;
-		}
-
-		return resolved;
-	}
-
-	/**
-	 * Lists directory contents.
-	 *
-	 * @param path Target directory, defaults to cwd.
-	 * @returns Result with directory listing in stdout.
-	 */
-	async ls(path?: string): Promise<CommandResult> {
-		perf.mark("ls");
-		const target = path ?? ".";
-		return this.exec(`ls ${target}`);
-	}
-
-	/**
-	 * Prints current working directory.
-	 *
-	 * @returns Result with cwd path in stdout.
-	 */
-	async pwd(): Promise<CommandResult> {
-		perf.mark("pwd");
-		return this.exec("pwd");
-	}
-
-	/**
-	 * Changes working directory.
-	 *
-	 * @param path Target directory path.
-	 * @returns Result; updates internal cwd on success.
-	 */
-	async cd(path: string): Promise<CommandResult> {
-		perf.mark("cd");
-		const result = await this.exec(`cd ${path}`);
-		if (result.nextCwd && result.exitCode !== 1) {
-			this.currentCwd = result.nextCwd;
-		}
-		return result;
-	}
-
-	/**
-	 * Reads file content.
-	 *
-	 * @param path File path.
-	 * @returns Result with file content in stdout.
-	 */
-	async cat(path: string): Promise<CommandResult> {
-		perf.mark("cat");
-		return this.exec(`cat ${path}`);
-	}
-
-	/**
-	 * Creates directory.
-	 *
-	 * @param path Directory path.
-	 * @param recursive When true, create parents.
-	 * @returns Result from mkdir command.
-	 */
-	async mkdir(path: string, recursive = false): Promise<CommandResult> {
-		perf.mark("mkdir");
-		const flag = recursive ? "-p " : "";
-		return this.exec(`mkdir ${flag}${path}`);
-	}
-
-	/**
-	 * Creates file (empty).
-	 *
-	 * @param path File path.
-	 * @returns Result from touch command.
-	 */
-	async touch(path: string): Promise<CommandResult> {
-		perf.mark("touch");
-		return this.exec(`touch ${path}`);
-	}
-
-	/**
-	 * Removes file or directory.
-	 *
-	 * @param path Target path.
-	 * @param recursive When true, delete directory tree.
-	 * @returns Result from rm command.
-	 */
-	async rm(path: string, recursive = false): Promise<CommandResult> {
-		perf.mark("rm");
-		const flag = recursive ? "-r " : "";
-		return this.exec(`rm ${flag}${path}`);
-	}
-
-	/**
-	 * Writes file content.
-	 *
-	 * @param path Target file path.
-	 * @param content Text to write.
-	 * @returns Result from touch/write simulation.
-	 */
-	async writeFile(path: string, content: string): Promise<CommandResult> {
-		perf.mark("writeFile");
-		const vfs = this.shell.getVfs();
-		if (!vfs) {
-			throw new Error("SSH client not started");
-		}
-
-		try {
-			this.shell.writeFileAsUser(this.username, path, content);
-			return { stdout: `File '${path}' written`, exitCode: 0 };
-		} catch (error) {
-			return {
-				stderr: `Failed to write '${path}': ${error instanceof Error ? error.message : String(error)}`,
-				exitCode: 1,
-			};
-		}
-	}
-
-	/**
-	 * Reads file content programmatically.
-	 *
-	 * @param path Target file path.
-	 * @returns File content as string or error in result.
-	 */
-	async readFile(path: string): Promise<CommandResult> {
-		perf.mark("readFile");
-		const vfs = this.shell.getVfs();
-		if (!vfs) {
-			throw new Error("SSH client not started");
-		}
-
-		try {
-			const content = vfs.readFile(path);
-			return { stdout: content, exitCode: 0 };
-		} catch (error) {
-			return {
-				stderr: `Failed to read '${path}': ${error instanceof Error ? error.message : String(error)}`,
-				exitCode: 1,
-			};
-		}
-	}
-
-	/**
-	 * Gets current working directory.
-	 *
-	 * @returns Normalized cwd path.
-	 */
-	getCwd(): string {
-		perf.mark("getCwd");
-		return this.currentCwd;
-	}
-
-	/**
-	 * Gets logged-in username.
-	 *
-	 * @returns Associated username.
-	 */
-	getUsername(): string {
-		perf.mark("getUsername");
-		return this.username;
-	}
-
-	/**
-	 * Renders tree view of directory.
-	 *
-	 * @param path Target directory, defaults to cwd.
-	 * @returns Result with ASCII tree in stdout.
-	 */
-	async tree(path?: string): Promise<CommandResult> {
-		perf.mark("tree");
-		const target = path ?? ".";
-		return this.exec(`tree ${target}`);
-	}
-
-	/**
-	 * Shows current user.
-	 *
-	 * @returns Result from whoami command.
-	 */
-	async whoami(): Promise<CommandResult> {
-		perf.mark("whoami");
-		return this.exec("whoami");
-	}
-
-	/**
-	 * Shows hostname.
-	 *
-	 * @returns Result from hostname command.
-	 */
-	async hostname(): Promise<CommandResult> {
-		perf.mark("hostname");
-		return this.exec("hostname");
-	}
-
-	/**
-	 * Lists active users/sessions.
-	 *
-	 * @returns Result from who command.
-	 */
-	async who(): Promise<CommandResult> {
-		perf.mark("who");
-		return this.exec("who");
-	}
-}