typescript-virtual-container 1.1.4 → 1.1.5

package/examples/honeypot-audit.ts

@@ -0,0 +1,180 @@
+/**
+ * HoneyPot Auditing Example
+ *
+ * Demonstrates how to use the HoneyPot utility to track all activity
+ * in a virtual environment, collect statistics, and detect anomalies.
+ *
+ * Run with: bun run examples/honeypot-audit.ts
+ */
+
+import {
+    HoneyPot,
+    SshClient,
+    VirtualShell,
+    VirtualSshServer,
+} from "../src/index";
+
+async function demonstrateHoneypot() {
+	console.log("🍯 HoneyPot Auditing Example\n");
+
+	// Initialize the virtual environment
+	const shell = new VirtualShell("security-lab");
+	const ssh = new VirtualSshServer({ port: 2222, shell });
+	await ssh.start();
+
+	const users = shell.getUsers()!;
+	const vfs = shell.getVfs()!;
+
+	// Create HoneyPot instance with 1000-entry log limit
+	const honeypot = new HoneyPot(1000);
+
+	// Attach HoneyPot to all components
+	honeypot.attach(shell, vfs, users, ssh);
+
+	console.log("✅ HoneyPot attached to all components\n");
+
+	// ------ Scenario 1: Normal user activity ------
+	console.log("--- Scenario 1: Normal User Activity ---\n");
+
+	await users.addUser("alice", "alice_pass123");
+	await users.addUser("bob", "bob_pass456");
+
+	const alice = new SshClient(shell, "alice");
+	await alice.mkdir("/home/alice/work", true);
+	await alice.writeFile("/home/alice/work/notes.txt", "Project notes");
+	await alice.ls("/home/alice/work");
+	await alice.cat("/home/alice/work/notes.txt");
+
+	console.log("✓ Alice performed normal operations\n");
+
+	// ------ Scenario 2: Bob attempts suspicious operations ------
+	console.log("--- Scenario 2: Suspicious Attempt ---\n");
+
+	const bob = new SshClient(shell, "bob");
+	// These will fail but are tracked
+	await bob.readFile("/etc/shadow");
+	await bob.readFile("/etc/passwd");
+	await bob.readFile("/root/.ssh/id_rsa");
+
+	console.log("✓ Bob attempted unauthorized file access\n");
+
+	// ------ Activity Summary ------
+	console.log("--- Activity Summary ---\n");
+
+	const stats = honeypot.getStats();
+	console.log("📊 Audit Statistics:");
+	console.log(`  • Auth attempts: ${stats.authAttempts}`);
+	console.log(`  • Auth successes: ${stats.authSuccesses}`);
+	console.log(`  • Auth failures: ${stats.authFailures}`);
+	console.log(`  • Commands executed: ${stats.commands}`);
+	console.log(`  • File reads: ${stats.fileReads}`);
+	console.log(`  • File writes: ${stats.fileWrites}`);
+	console.log(`  • Users created: ${stats.userCreated}`);
+	console.log(`  • Sessions started: ${stats.sessionStarts}\n`);
+
+	// ------ Recent Events ------
+	console.log("--- Most Recent Events ---\n");
+
+	const recent = honeypot.getRecent(10);
+	console.log(`📋 Last ${recent.length} events:\n`);
+	recent.forEach((entry) => {
+		console.log(`  [${entry.timestamp}]`);
+		console.log(`  Source: ${entry.source}`);
+		console.log(`  Event: ${entry.type}`);
+		console.log(`  Details: ${JSON.stringify(entry.details)}\n`);
+	});
+
+	// ------ Filtered Audit Log ------
+	console.log("--- Filtered Audit Log ---\n");
+
+	const authFailures = honeypot.getAuditLog("auth:failure");
+	console.log(`🚨 Auth Failures (${authFailures.length} total):\n`);
+	if (authFailures.length > 0) {
+		authFailures.forEach((entry) => {
+			console.log(
+				`  • User "${entry.details.username}" from ${entry.details.remoteAddress}`,
+			);
+		});
+	} else {
+		console.log("  • None detected");
+	}
+	console.log();
+
+	// ------ SSH-specific events ------
+	console.log("--- SSH-Specific Events ---\n");
+
+	const sshEvents = honeypot.getAuditLog(undefined, "SshMimic");
+	console.log(`🔗 SSH events (${sshEvents.length} total):\n`);
+	sshEvents.forEach((entry) => {
+		console.log(`  • ${entry.type}: ${JSON.stringify(entry.details)}`);
+	});
+	console.log();
+
+	// ------ File System Activity ------
+	console.log("--- File System Activity ---\n");
+
+	const fileWrites = honeypot.getAuditLog("file:write", "VirtualFileSystem");
+	const fileReads = honeypot.getAuditLog("file:read", "VirtualFileSystem");
+
+	console.log(`📁 File Operations:`);
+	console.log(`  • File writes: ${fileWrites.length}`);
+	fileWrites.forEach((entry) => {
+		console.log(`    - ${entry.details.path} (${entry.details.size} bytes)`);
+	});
+	console.log(`  • File reads: ${fileReads.length}`);
+	fileReads.forEach((entry) => {
+		console.log(`    - ${entry.details.path} (${entry.details.size} bytes)`);
+	});
+	console.log();
+
+	// ------ Anomaly Detection ------
+	console.log("--- Security Analysis ---\n");
+
+	const anomalies = honeypot.detectAnomalies();
+	if (anomalies.length > 0) {
+		console.log("⚠️  Anomalies Detected:\n");
+		anomalies.forEach((anomaly) => {
+			const severity = {
+				low: "ℹ️ ",
+				medium: "⚠️ ",
+				high: "🚨",
+			}[anomaly.severity];
+			console.log(`  ${severity} [${anomaly.type}]`);
+			console.log(`     ${anomaly.message}\n`);
+		});
+	} else {
+		console.log("✅ No anomalies detected\n");
+	}
+
+	// ------ Export Audit Log ------
+	console.log("--- Full Audit Export ---\n");
+
+	const allAuditEntries = honeypot.getAuditLog();
+	console.log(`📊 Total audit entries: ${allAuditEntries.length}`);
+	console.log(`💾 Audit log is ready for export/storage\n`);
+
+	// Example export to JSON
+	const exportData = {
+		timestamp: new Date().toISOString(),
+		environment: "security-lab",
+		stats,
+		auditLog: allAuditEntries.slice(-50), // Last 50 entries
+		anomalies,
+	};
+
+	console.log("📄 Sample export structure:");
+	console.log(`${JSON.stringify(exportData, null, 2).substring(0, 300)}...\n`);
+
+	// Cleanup
+	ssh.stop();
+
+	console.log(
+		"✅ Example completed! HoneyPot auditing demonstration finished.\n",
+	);
+}
+
+// Run the example
+demonstrateHoneypot().catch((error) => {
+	console.error("❌ Error:", error);
+	process.exit(1);
+});

package/examples/honeypot-export.ts

@@ -0,0 +1,253 @@
+/**
+ * HoneyPot Advanced: Audit Export & Analysis
+ *
+ * Shows how to export audit data for external analysis, storage,
+ * or integration with security monitoring systems.
+ *
+ * Run with: bun run examples/honeypot-export.ts
+ */
+
+import * as fs from "node:fs";
+import {
+    HoneyPot,
+    SshClient,
+    VirtualShell,
+    VirtualSshServer,
+} from "../src/index";
+
+interface AuditReport {
+	timestamp: string;
+	environment: string;
+	durationMs: number;
+	summary: {
+		totalEvents: number;
+		totalUsers: number;
+		totalCommands: number;
+		failedAuthAttempts: number;
+	};
+	statistics: Record<string, number>;
+	anomalies: Array<{
+		type: string;
+		severity: string;
+		message: string;
+	}>;
+	timeline: Array<{
+		time: string;
+		event: string;
+		user?: string;
+		details: Record<string, unknown>;
+	}>;
+}
+
+async function generateAuditReport() {
+	const startTime = Date.now();
+
+	console.log("📊 HoneyPot Advanced: Generating Audit Report\n");
+
+	// Setup
+	const shell = new VirtualShell("audit-lab");
+	const ssh = new VirtualSshServer({ port: 2222, shell });
+	await ssh.start();
+
+	const users = shell.getUsers()!;
+	const vfs = shell.getVfs()!;
+
+	const honeypot = new HoneyPot(5000);
+	honeypot.attach(shell, vfs, users, ssh);
+
+	console.log("Running simulated workload...\n");
+
+	// Simulate various user activities
+	await users.addUser("analyst", "pass123");
+	await users.addUser("developer", "pass456");
+	await users.removeSudoer("developer");
+
+	// Analyst activities (authorized)
+	const analyst = new SshClient(shell, "analyst");
+	await analyst.mkdir("/data/reports", true);
+	await analyst.writeFile(
+		"/data/reports/analysis.txt",
+		"Security analysis report",
+	);
+	await analyst.ls("/data/reports");
+
+	// Developer activities
+	const dev = new SshClient(shell, "developer");
+	await dev.mkdir("/code/project", true);
+	await dev.writeFile("/code/project/main.ts", "export function main() {}");
+
+	// Some failed operations (tracked)
+	try {
+		await dev.readFile("/etc/shadow"); // Will fail
+	} catch {
+		// Ignored
+	}
+
+	try {
+		await dev.writeFile("/root/.bashrc", "malicious"); // Will fail
+	} catch {
+		// Ignored
+	}
+
+	// Get final duration
+	const duration = Date.now() - startTime;
+
+	console.log("Generating audit report...\n");
+
+	// Build comprehensive audit report
+	const stats = honeypot.getStats();
+	const anomalies = honeypot.detectAnomalies();
+	const auditLog = honeypot.getAuditLog();
+
+	const report: AuditReport = {
+		timestamp: new Date().toISOString(),
+		environment: "audit-lab",
+		durationMs: duration,
+
+		summary: {
+			totalEvents: auditLog.length,
+			totalUsers: stats.userCreated,
+			totalCommands: stats.commands,
+			failedAuthAttempts: stats.authFailures,
+		},
+
+		statistics: {
+			authAttempts: stats.authAttempts,
+			authSuccesses: stats.authSuccesses,
+			authFailures: stats.authFailures,
+			commandsExecuted: stats.commands,
+			fileReads: stats.fileReads,
+			fileWrites: stats.fileWrites,
+			sessionsStarted: stats.sessionStarts,
+			sessionsEnded: stats.sessionEnds,
+			usersCreated: stats.userCreated,
+			usersDeleted: stats.userDeleted,
+			clientConnects: stats.clientConnects,
+			clientDisconnects: stats.clientDisconnects,
+		},
+
+		anomalies: anomalies.map((a) => ({
+			type: a.type,
+			severity: a.severity,
+			message: a.message,
+		})),
+
+		timeline: auditLog.map((entry) => ({
+			time: entry.timestamp,
+			event: `${entry.source}:${entry.type}`,
+			user: (entry.details.username as string) || undefined,
+			details: entry.details,
+		})),
+	};
+
+	// Display summary
+	console.log("📋 Audit Report Summary\n");
+	console.log(`  Environment: ${report.environment}`);
+	console.log(`  Generated: ${report.timestamp}`);
+	console.log(`  Duration: ${report.durationMs}ms\n`);
+
+	console.log("📊 Statistics:");
+	console.log(`  • Total events: ${report.summary.totalEvents}`);
+	console.log(`  • Total users: ${report.summary.totalUsers}`);
+	console.log(`  • Commands executed: ${report.summary.totalCommands}`);
+	console.log(
+		`  • Failed auth attempts: ${report.summary.failedAuthAttempts}\n`,
+	);
+
+	// Display anomalies if any
+	if (report.anomalies.length > 0) {
+		console.log("⚠️  Anomalies:");
+		report.anomalies.forEach((a) => {
+			console.log(`  • [${a.severity}] ${a.type}`);
+			console.log(`    ${a.message}`);
+		});
+		console.log();
+	}
+
+	// Export to JSON file
+	const reportPath = "./audit_report.json";
+	fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+	console.log(`✅ Report exported to: ${reportPath}\n`);
+
+	// Export CSV for spreadsheet analysis
+	const csvPath = "./audit_events.csv";
+	const csvHeader = "Timestamp,Source,Event,User,Details\n";
+	const csvRows = report.timeline
+		.map((entry) => {
+			const details = JSON.stringify(entry.details).replace(/"/g, '""');
+			return `"${entry.time}","${entry.event.split(":")[0]}","${
+				entry.event.split(":")[1]
+			}","${entry.user || ""}","${details}"`;
+		})
+		.join("\n");
+
+	fs.writeFileSync(csvPath, csvHeader + csvRows);
+	console.log(`✅ CSV export to: ${csvPath}\n`);
+
+	// Generate summary stats file
+	const statsPath = "./audit_stats.json";
+	fs.writeFileSync(
+		statsPath,
+		JSON.stringify(
+			{
+				summary: report.summary,
+				statistics: report.statistics,
+				anomalies: report.anomalies,
+			},
+			null,
+			2,
+		),
+	);
+	console.log(`✅ Stats export to: ${statsPath}\n`);
+
+	// Show sample data
+	console.log("📄 Sample Report Data:");
+	console.log(`${JSON.stringify(report, null, 2).substring(0, 500)}...\n`);
+
+	// Integration example: Send to external system
+	console.log("🔗 Integration Example:");
+	console.log("To send this data to external systems:");
+	console.log("  • Database: INSERT INTO audit_logs VALUES (...)");
+	console.log("  • API: POST /api/audit-reports (JSON payload)");
+	console.log("  • Message Queue: PUBLISH audit_report (for async processing)");
+	console.log("  • SIEM: Send via syslog or CEF format\n");
+
+	// Query examples
+	console.log("🔍 Query Examples:");
+
+	// Auth failures by user
+	const authFailures = honeypot.getAuditLog("auth:failure");
+	const failuresByUser = new Map<string, number>();
+	authFailures.forEach((entry) => {
+		const user = entry.details.username as string;
+		failuresByUser.set(user, (failuresByUser.get(user) || 0) + 1);
+	});
+
+	if (failuresByUser.size > 0) {
+		console.log("\n  Auth Failures by User:");
+		failuresByUser.forEach((count, user) => {
+			console.log(`    • ${user}: ${count} failures`);
+		});
+	}
+
+	// File operations
+	const fileWrites = honeypot.getAuditLog("file:write");
+	if (fileWrites.length > 0) {
+		console.log(`\n  File Writes: ${fileWrites.length}`);
+		fileWrites.slice(-3).forEach((entry) => {
+			console.log(`    • ${entry.details.path} (${entry.details.size} B)`);
+		});
+	}
+
+	console.log();
+
+	// Cleanup
+	ssh.stop();
+
+	console.log("✅ Audit report generation complete!");
+	console.log(
+		"💡 Tip: Open the generated .json files to view full audit trails.\n",
+	);
+}
+
+generateAuditReport().catch(console.error);

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.5",
   "license": "MIT",
   "keywords": [
     "ssh",