typescript-virtual-container 1.5.3 → 1.5.4

package/.github/workflows/test-battery.yml

@@ -1,102 +0,0 @@
-name: Test battery
-
-on:
-  pull_request:
-    branches:
-
-permissions:
-  contents: read
-
-jobs:
-  setup:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Cache dependencies
-        uses: actions/cache@v3
-        with:
-          path: node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
-
-  typecheck:
-    needs: setup
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-        with:
-          bun-version: latest
-
-      - name: Restore dependencies
-        uses: actions/cache@v3
-        with:
-          path: node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
-
-      - name: Run typecheck
-        run: bun check
-
-  lint:
-    needs: setup
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-        with:
-          bun-version: latest
-
-      - name: Restore dependencies
-        uses: actions/cache@v3
-        with:
-          path: node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
-
-      - name: Run lint
-        run: bun lint
-
-  tests:
-    needs: setup
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v1
-        with:
-          bun-version: latest
-
-      - name: Restore dependencies
-        uses: actions/cache@v3
-        with:
-          path: node_modules
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lockb') }}
-
-      - name: Run tests
-        run: bun test
-
-  test-battery:
-    needs:
-      - typecheck
-      - lint
-      - tests
-    runs-on: ubuntu-latest
-    steps:
-      - name: Test battery passed
-        run: echo "Typecheck, lint and tests succeeded."

package/.vscode/settings.json

@@ -1,20 +0,0 @@
-{
-    "files.exclude": {
-        "**/.git": true,
-        "**/.hg": true,
-        "**/.svn": true,
-        "**/.DS_Store": true,
-        "**/Thumbs.db": true,
-        "**/node_modules": true,
-
-        ".ssh-mimic": true,
-        // ".vfs": true,
-        // "builds": true,
-        "docs": true,
-        // "examples": true,
-        
-        "LICENSE": true,
-        "tsconfig.tsbuildinfo": true
-    },
-    "js/ts.tsdk.path": "node_modules/typescript/lib"
-}

package/CODE_OF_CONDUCT.md

@@ -1,39 +0,0 @@
-# Code of Conduct
-
-## Our Pledge
-
-We are committed to making participation in this project a harassment-free experience for everyone.
-
-## Our Standards
-
-Examples of behavior that contributes to a positive environment include:
-
-- Being respectful and inclusive
-- Giving and receiving constructive feedback
-- Focusing on what is best for the community
-- Showing empathy toward other contributors
-
-Examples of unacceptable behavior include:
-
-- Harassment, insults, or discriminatory language
-- Trolling or personal attacks
-- Publishing private information without consent
-- Any conduct that is inappropriate in a professional setting
-
-## Enforcement Responsibilities
-
-Project maintainers are responsible for clarifying and enforcing standards and may remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned with this Code of Conduct.
-
-## Scope
-
-This Code of Conduct applies within project spaces and in public spaces when an individual is officially representing the project.
-
-## Enforcement
-
-If you experience or witness unacceptable behavior, report it through the repository maintainers.
-
-Maintainers will review and investigate reports and respond in a way they deem appropriate to the circumstances.
-
-## Attribution
-
-This document is inspired by the Contributor Covenant, version 2.1.

package/CONTRIBUTING.md

@@ -1,59 +0,0 @@
-# Contributing
-
-Thanks for contributing to typescript-virtual-container.
-
-## Development Setup
-
-1. Fork and clone the repository.
-2. Install dependencies:
-
-```bash
-bun install
-```
-
-3. Run checks before opening a pull request:
-
-```bash
-bun format
-bun check
-```
-
-## Branch and Commit Style
-
-- Create focused branches (example: feat/programmatic-client-timeout).
-- Keep commits small and descriptive.
-- Prefer conventional commit prefixes when possible:
-  - feat:
-  - fix:
-  - docs:
-  - refactor:
-  - test:
-  - chore:
-
-## Coding Guidelines
-
-- Use TypeScript with explicit, readable types.
-- Avoid introducing any without a strong reason.
-- Preserve existing API behavior unless the change is intentional and documented.
-- Keep command behavior deterministic for tests and CI use cases.
-
-## Pull Request Checklist
-
-- I ran format and checks locally.
-- I added or updated documentation for public behavior changes.
-- I added tests for bug fixes or new behavior when applicable.
-- I kept changes scoped to one objective.
-
-## Reporting Issues
-
-When opening an issue, include:
-
-- Package version
-- Runtime (Node or Bun) and version
-- Minimal reproduction steps
-- Expected behavior and actual behavior
-
-## Security
-
-Please do not open public issues for vulnerabilities.
-See SECURITY.md for responsible disclosure details.

package/HONEYPOT.md

@@ -1,358 +0,0 @@
-# HoneyPot Implementation Guide
-
-## Overview
-
-The `HoneyPot` class is a comprehensive auditing and event tracking utility that monitors all activity across your virtual environment. It provides real-time event logging, statistics collection, and anomaly detection.
-
-## Installation
-
-`HoneyPot` is included in the main `typescript-virtual-container` package:
-
-```bash
-npm install typescript-virtual-container
-```
-
-Then import it:
-
-```typescript
-import { HoneyPot } from "typescript-virtual-container";
-```
-
-## Basic Setup
-
-### Step 1: Create Your Environment
-
-```typescript
-import {
-	VirtualSshServer,
-	VirtualShell,
-	HoneyPot,
-} from "typescript-virtual-container";
-
-// Create shell and SSH server
-const shell = new VirtualShell("my-environment");
-const ssh = new VirtualSshServer({ port: 2222, shell });
-await ssh.start();
-
-// Get references to key components
-const users = ssh.getUsers()!;
-const vfs = ssh.getVfs()!;
-```
-
-### Step 2: Initialize HoneyPot
-
-```typescript
-// Create HoneyPot with optional log size limit
-const honeypot = new HoneyPot(5000); // Keep last 5000 entries
-```
-
-### Step 3: Attach to Components
-
-```typescript
-// Attach HoneyPot to all components
-// Now all events are automatically tracked
-honeypot.attach(shell, vfs, users, ssh);
-```
-
-## Core Operations
-
-### Collecting Statistics
-
-```typescript
-const stats = honeypot.getStats();
-
-console.log(`Successful logins: ${stats.authSuccesses}`);
-console.log(`Failed logins: ${stats.authFailures}`);
-console.log(`Commands executed: ${stats.commands}`);
-console.log(`File operations: ${stats.fileWrites + stats.fileReads}`);
-```
-
-### Retrieving Audit Logs
-
-```typescript
-// Get all entries
-const allEntries = honeypot.getAuditLog();
-
-// Filter by event type
-const authFailures = honeypot.getAuditLog("auth:failure");
-
-// Filter by source component
-const sshEvents = honeypot.getAuditLog(undefined, "SshMimic");
-
-// Combined filter
-const sshAuthEvents = honeypot.getAuditLog("auth:success", "SshMimic");
-```
-
-### Getting Recent Events
-
-```typescript
-// Last 10 events (default)
-const recent10 = honeypot.getRecent();
-
-// Last 100 events
-const recent100 = honeypot.getRecent(100);
-
-// Process events
-recent100.forEach((entry) => {
-	console.log(`[${entry.timestamp}] ${entry.source}: ${entry.type}`);
-	console.log(`  Details: ${JSON.stringify(entry.details)}`);
-});
-```
-
-### Detecting Anomalies
-
-```typescript
-const anomalies = honeypot.detectAnomalies();
-
-anomalies.forEach((anomaly) => {
-	console.log(`Severity: ${anomaly.severity}`);
-	console.log(`Type: ${anomaly.type}`);
-	console.log(`Message: ${anomaly.message}`);
-});
-
-// Severity levels: "low", "medium", "high"
-```
-
-## Common Patterns
-
-### Pattern 1: Real-Time Monitoring
-
-```typescript
-async function monitorAuthAttempts() {
-	const honeypot = new HoneyPot();
-	honeypot.attach(shell, vfs, users, ssh);
-
-	// Monitor continuously
-	setInterval(() => {
-		const stats = honeypot.getStats();
-
-		if (stats.authFailures > 10) {
-			console.log("🚨 High number of failed auth attempts!");
-			const failures = honeypot.getAuditLog("auth:failure");
-			console.log(failures.map((f) => f.details.username));
-		}
-	}, 5000); // Check every 5 seconds
-}
-```
-
-### Pattern 2: Post-Execution Analysis
-
-```typescript
-async function runTestAndAnalyze() {
-	const shell = new VirtualShell("test-env");
-	const ssh = new VirtualSshServer({ port: 2222, shell });
-	await ssh.start();
-
-	const honeypot = new HoneyPot();
-	honeypot.attach(shell, vfs, users, ssh);
-
-	// ... run your tests/operations ...
-
-	// Generate report
-	const report = {
-		executedAt: new Date().toISOString(),
-		statistics: honeypot.getStats(),
-		anomalies: honeypot.detectAnomalies(),
-		allEvents: honeypot.getAuditLog(),
-	};
-
-	return report;
-}
-```
-
-### Pattern 3: Security Analysis by User
-
-```typescript
-function analyzeUserActivity(honeypot, username) {
-	// Get all events related to this user
-	const userEvents = honeypot
-		.getAuditLog()
-		.filter((entry) => entry.details.username === username);
-
-	const analysis = {
-		totalActions: userEvents.length,
-		fileWrites: userEvents.filter(
-			(e) => e.type === "file:write",
-		).length,
-		failedAuthAttempts: userEvents.filter(
-			(e) => e.type === "auth:failure",
-		).length,
-		commands: userEvents.filter((e) => e.type === "command").length,
-		timeline: userEvents.map((e) => ({
-			time: e.timestamp,
-			action: e.type,
-			details: e.details,
-		})),
-	};
-
-	return analysis;
-}
-```
-
-### Pattern 4: Compliance Export
-
-```typescript
-function generateComplianceReport(honeypot) {
-	const timestamp = new Date().toISOString();
-	const stats = honeypot.getStats();
-
-	return {
-		reportDate: timestamp,
-		auditTrail: {
-			totalEvents: stats.authAttempts + stats.commands,
-			authenticationEvents: {
-				attempts: stats.authAttempts,
-				successes: stats.authSuccesses,
-				failures: stats.authFailures,
-			},
-			commandExecution: {
-				total: stats.commands,
-				fileOperations: stats.fileWrites + stats.fileReads,
-			},
-		},
-		anomalyDetection: honeypot.detectAnomalies(),
-		detailedLog: honeypot.getAuditLog(),
-	};
-}
-```
-
-## Event Types
-
-### Authentication Events
-
-- `auth:success` - User authenticated successfully
-- `auth:failure` - Authentication failed
-
-### File System Events
-
-- `file:read` - File read operation
-- `file:write` - File write operation
-- `dir:create` - Directory created
-
-### User Management Events
-
-- `user:add` - User account created
-- `user:delete` - User account deleted
-
-### Session Events
-
-- `session:register` - Session started
-- `session:unregister` - Session ended
-
-### Command Execution
-
-- `command` - Command executed
-
-## Integration Examples
-
-### With a Database
-
-```typescript
-const honeypot = new HoneyPot();
-honeypot.attach(shell, vfs, users, ssh);
-
-// Later, export to database
-async function exportToDatabase() {
-	const entries = honeypot.getAuditLog();
-
-	for (const entry of entries) {
-		await db.collection("audit_logs").insertOne({
-			timestamp: entry.timestamp,
-			type: entry.type,
-			source: entry.source,
-			details: entry.details,
-		});
-	}
-}
-```
-
-### With a Logging Service
-
-```typescript
-const honeypot = new HoneyPot();
-honeypot.attach(shell, vfs, users, ssh);
-
-// Export to external logging
-const report = honeypot.getRecent(1000);
-await loggingService.send({
-	environment: "production",
-	auditTrail: report,
-	timestamp: new Date().toISOString(),
-});
-```
-
-### With Monitoring/Alerting
-
-```typescript
-const honeypot = new HoneyPot();
-honeypot.attach(shell, vfs, users, ssh);
-
-// Check for anomalies periodically
-setInterval(() => {
-	const anomalies = honeypot.detectAnomalies();
-
-	anomalies.forEach((a) => {
-		if (a.severity === "high") {
-			alerting.triggerAlert({
-				type: a.type,
-				message: a.message,
-				timestamp: new Date().toISOString(),
-			});
-		}
-	});
-}, 10000);
-```
-
-## Performance Considerations
-
-- HoneyPot maintains an in-memory buffer with configurable max size
-- Older entries are automatically trimmed when limit is reached
-- All operations are O(1) or O(n) where n is reasonable
-- Statistics computation is cached and efficient
-- For long-running processes, consider periodic exports and resets
-
-## Cleanup and Reset
-
-```typescript
-// Clear all logs and reset statistics
-honeypot.reset();
-
-// Continues to listen for new events after reset
-// Useful for clearing after each test phase
-```
-
-## Best Practices
-
-1. **Initialize Early**: Attach HoneyPot right after creating components
-2. **Export Regularly**: Don't rely solely on in-memory storage
-3. **Monitor Continuously**: Use periodic checks for real-time monitoring
-4. **Archive Audit Trails**: Save audit logs for compliance/forensics
-5. **Set Appropriate Log Size**: Balance memory usage with data retention
-6. **Use Filters**: Filter large logs by type or source for analysis
-7. **Automate Anomaly Response**: Set up automated responses to detected anomalies
-
-## Troubleshooting
-
-### No events recorded?
-
-- Ensure `honeypot.attach()` is called after all components are initialized
-- Verify that actual operations are being performed (commands, file ops, etc.)
-- Check that components extend EventEmitter (they should by default)
-
-### Memory growing?
-
-- Reduce `maxLogSize` in the constructor
-- Call `honeypot.reset()` between test phases
-- Export logs periodically to external storage
-
-### Missing specific events?
-
-- Check the exact event name in the events list
-- Use `honeypot.getAuditLog()` to verify events exist
-- Filter by source and type to narrow down search
-
-## See Also
-
-- [API Reference](../README.md#honeypot-auditing--event-tracking)
-- [Example 8: Security Auditing](../README.md#example-8-security-auditing-with-honeypot)
-- [Examples Directory](./README.md)

package/SECURITY.md

@@ -1,33 +0,0 @@
-# Security Policy
-
-## Supported Versions
-
-Security fixes are prioritized for the latest published release.
-
-## Reporting a Vulnerability
-
-Please report vulnerabilities privately.
-
-Preferred channel:
-
-- Open a private GitHub security advisory for this repository.
-
-If advisory tooling is unavailable, open an issue with minimal details and request private contact.
-Do not include exploit details or sensitive information in a public issue.
-
-## What to Include
-
-Please include:
-
-- A clear description of the issue
-- Impact assessment
-- Reproduction steps or proof of concept
-- Affected versions
-- Suggested remediation if available
-
-## Disclosure Process
-
-- We will acknowledge receipt as soon as possible.
-- We will validate, triage, and work on a fix.
-- We may request additional technical details.
-- We will publish a patch and release notes after remediation.

package/benchmark-results.txt

@@ -1,40 +0,0 @@
-Benchmarking VirtualShell concurrency:
-
-Running 1 shells...
-  Initialized 1 shells in 58ms, RSS 98 MB
-  Executed shell commands in 5ms, RSS now 98 MB (+1 MB)
-
-Running 2 shells...
-  Initialized 2 shells in 10ms, RSS 102 MB
-  Executed shell commands in 1ms, RSS now 102 MB (+0 MB)
-
-Running 5 shells...
-  Initialized 5 shells in 21ms, RSS 113 MB
-  Executed shell commands in 1ms, RSS now 113 MB (+0 MB)
-
-Running 10 shells...
-  Initialized 10 shells in 43ms, RSS 132 MB
-  Executed shell commands in 6ms, RSS now 132 MB (+1 MB)
-
-Running 20 shells...
-  Initialized 20 shells in 107ms, RSS 150 MB
-  Executed shell commands in 4ms, RSS now 150 MB (+0 MB)
-
-Running 50 shells...
-  Initialized 50 shells in 177ms, RSS 178 MB
-  Executed shell commands in 5ms, RSS now 179 MB (+0 MB)
-
-Running 100 shells...
-  Initialized 100 shells in 302ms, RSS 190 MB
-  Executed shell commands in 9ms, RSS now 190 MB (+0 MB)
-
-Summary:
-
-count   init_ms cmd_ms  init_rss        final_rss       delta_rss
-1       58      5       98 MB           98 MB           1 MB
-2       10      1       102 MB          102 MB          0 MB
-5       21      1       113 MB          113 MB          0 MB
-10      43      6       132 MB          132 MB          1 MB
-20      107     4       150 MB          150 MB          0 MB
-50      177     5       178 MB          179 MB          0 MB
-100     302     9       190 MB          190 MB          0 MB