typescript-virtual-container 1.1.4 → 1.1.6

package/dist/index.js

@@ -1,7 +1,8 @@
+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 { 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";

package/examples/README.md

@@ -0,0 +1,210 @@
+# HoneyPot Examples
+
+This directory contains practical examples demonstrating how to use the `HoneyPot` auditing and event tracking utility.
+
+## Quick Start with HoneyPot
+
+### 1. Basic Introduction (Recommended First)
+
+**File:** `honeypot-quickstart.ts`
+
+A beginner-friendly, step-by-step introduction to HoneyPot:
+
+```bash
+bun run examples/honeypot-quickstart.ts
+```
+
+**What it covers:**
+- Creating a virtual environment
+- Initializing HoneyPot
+- Attaching HoneyPot to components
+- Collecting statistics
+- Viewing recent events
+- Querying filtered logs
+- Detecting anomalies
+
+**Output:** Console display with colored examples and activity statistics
+
+---
+
+### 2. Comprehensive Auditing
+
+**File:** `honeypot-audit.ts`
+
+A complete auditing scenario with multiple users and suspicious activities:
+
+```bash
+bun run examples/honeypot-audit.ts
+```
+
+**What it covers:**
+- Normal user activity tracking
+- Suspicious operation attempts
+- Detailed activity summaries
+- Event filtering by type and source
+- File system activity tracking
+- Anomaly detection with severity levels
+- Audit log export preparation
+
+**Output:** Detailed audit report with sections for each component
+
+---
+
+### 3. Advanced: Export & Analysis
+
+**File:** `honeypot-export.ts`
+
+Professional audit report generation with file exports:
+
+```bash
+bun run examples/honeypot-export.ts
+```
+
+**What it covers:**
+- Generating structured audit reports
+- Exporting to JSON format
+- Exporting to CSV format (for spreadsheet analysis)
+- Exporting statistics
+- Integration patterns with external systems
+- Query examples for custom analysis
+
+**Output:** 
+- `audit_report.json` - Complete audit report
+- `audit_events.csv` - Timeline in spreadsheet format
+- `audit_stats.json` - Summary statistics
+
+---
+
+## HoneyPot API Quick Reference
+
+```typescript
+// Create instance
+const honeypot = new HoneyPot(maxLogSize);
+
+// Attach to components
+honeypot.attach(shell, vfs, users, ssh, sftp);
+
+// Get statistics
+const stats = honeypot.getStats();
+
+// Get audit log
+const allLogs = honeypot.getAuditLog();
+const typeFiltered = honeypot.getAuditLog("auth:failure");
+const sourceFiltered = honeypot.getAuditLog(undefined, "SshMimic");
+
+// Get recent entries
+const recent = honeypot.getRecent(50);
+
+// Detect anomalies
+const anomalies = honeypot.detectAnomalies();
+
+// Reset tracking
+honeypot.reset();
+```
+
+## Common Use Cases
+
+### Use Case 1: Real-Time Monitoring
+
+```typescript
+honeypot.on("auth:failure", (count) => {
+	if (count > 3) {
+		console.log("⚠️  Potential brute-force attack detected!");
+	}
+});
+```
+
+### Use Case 2: Post-Execution Audit Report
+
+```typescript
+// After operations complete
+const report = {
+	timestamp: new Date(),
+	stats: honeypot.getStats(),
+	anomalies: honeypot.detectAnomalies(),
+	auditLog: honeypot.getAuditLog(),
+};
+```
+
+### Use Case 3: Security Analysis
+
+```typescript
+// Find all failed auth attempts by user
+const failures = honeypot
+	.getAuditLog("auth:failure")
+	.reduce((map, entry) => {
+		const user = entry.details.username;
+		map[user] = (map[user] || 0) + 1;
+		return map;
+	}, {});
+```
+
+### Use Case 4: Compliance & Audit Trail
+
+```typescript
+// Export complete trail for compliance
+const auditData = {
+	exportDate: new Date().toISOString(),
+	entries: honeypot.getAuditLog(),
+	stats: honeypot.getStats(),
+};
+
+// Store in database, send to SIEM, or archive
+```
+
+## Integration Examples
+
+### With Database
+
+```typescript
+const entries = honeypot.getAuditLog();
+await database.insertMany("audit_logs", entries);
+```
+
+### With Monitoring System
+
+```typescript
+const anomalies = honeypot.detectAnomalies();
+if (anomalies.length > 0) {
+	await monitoring.alert({
+		type: "security",
+		level: "high",
+		anomalies,
+	});
+}
+```
+
+### With Message Queue
+
+```typescript
+const report = honeypot.getRecent(1000);
+await queue.publish("audit-topic", report);
+```
+
+## Performance Notes
+
+- HoneyPot maintains an in-memory log with configurable size limit
+- Older entries are automatically trimmed when max size is exceeded
+- Statistics are computed efficiently and cached
+- Anomaly detection runs in O(1) time
+
+## Troubleshooting
+
+**No events logged?**
+- Ensure `honeypot.attach()` is called after all components are created
+- Check that operations are actually performed (file writes, auth attempts, etc.)
+
+**Memory growth?**
+- Adjust `maxLogSize` in the constructor to limit retention
+- Call `honeypot.reset()` to clear logs between test phases
+
+**Missing events?**
+- Use `honeypot.getAuditLog(type, source)` to filter and verify
+- Check the exact event names in the [API Reference](../README.md#honeypot-auditing--event-tracking)
+
+## More Information
+
+See the main [README.md](../README.md) for:
+- [HoneyPot API Reference](../README.md#honeypot-auditing--event-tracking)
+- [Example 8: Security Auditing with HoneyPot](../README.md#example-8-security-auditing-with-honeypot)
+- Complete [Event Types Documentation](../README.md#events)

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