typescript-virtual-container 1.1.4 → 1.1.5

package/dist/honeypot.js

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

@@ -3,9 +3,11 @@ import { SftpMimic, SshMimic } from "./SSHMimic/index";
 import VirtualFileSystem from "./VirtualFileSystem";
 import { VirtualShell } from "./VirtualShell";
 import { VirtualUserManager } from "./VirtualUserManager";
+import { HoneyPot } from "./honeypot";
 export type { CommandContext, CommandMode, CommandOutcome, CommandResult, NanoEditorSession, ShellModule, SudoChallenge, } from "./types/commands";
 export type { ExecStream, ShellStream } from "./types/streams";
 export type { RemoveOptions, VfsBaseNode, VfsDirectoryNode, VfsFileNode, VfsNodeStats, VfsNodeType, VfsSnapshot, VfsSnapshotBaseNode, VfsSnapshotDirectoryNode, VfsSnapshotFileNode, VfsSnapshotNode, WriteFileOptions, } from "./types/vfs";
-export { SshClient, VirtualFileSystem, SftpMimic as VirtualSftpServer, VirtualShell, SshMimic as VirtualSshServer, VirtualUserManager, };
+export type { AuditLogEntry, HoneyPotStats, } from "./honeypot";
+export { SshClient, VirtualFileSystem, SftpMimic as VirtualSftpServer, VirtualShell, SshMimic as VirtualSshServer, VirtualUserManager, HoneyPot, };
 export { getArg, getFlag, ifFlag, } from "./commands/command-helpers";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,iBAAiB,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,YAAY,EACX,cAAc,EACd,WAAW,EACX,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,aAAa,GACb,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/D,YAAY,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,SAAS,EACT,iBAAiB,EACjB,SAAS,IAAI,iBAAiB,EAC9B,YAAY,EACZ,QAAQ,IAAI,gBAAgB,EAC5B,kBAAkB,GAClB,CAAC;AAEF,OAAO,EACN,MAAM,EACN,OAAO,EACP,MAAM,GACN,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,iBAAiB,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,YAAY,EACX,cAAc,EACd,WAAW,EACX,cAAc,EACd,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,aAAa,GACb,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/D,YAAY,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,GAChB,MAAM,aAAa,CAAC;AACrB,YAAY,EACX,aAAa,EACb,aAAa,GACb,MAAM,YAAY,CAAC;AAEpB,OAAO,EACN,SAAS,EACT,iBAAiB,EACjB,SAAS,IAAI,iBAAiB,EAC9B,YAAY,EACZ,QAAQ,IAAI,gBAAgB,EAC5B,kBAAkB,EAClB,QAAQ,GACR,CAAC;AAEF,OAAO,EACN,MAAM,EACN,OAAO,EACP,MAAM,GACN,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -3,5 +3,6 @@ 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, };
+import { HoneyPot } from "./honeypot";
+export { SshClient, VirtualFileSystem, SftpMimic as VirtualSftpServer, VirtualShell, SshMimic as VirtualSshServer, VirtualUserManager, HoneyPot, };
 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)