A deliberately vulnerable Python code interpreter library for TypeScript, designed for educational and security testing purposes.

[!CAUTION] ⚠️ SECURITY WARNING 🚨 THIS PACKAGE CONTAINS INTENTIONAL VULNERABILITIES FOR EDUCATIONAL PURPOSES ONLY! DO NOT USE IN PRODUCTION ENVIRONMENTS! This package is designed to demonstrate common security vulnerabilities in code interpretation systems.

• 🚀 Installation
  • Prerequisites
• 📖 Quick Start
  • Basic Usage
  • Streaming Output
  • Educational Vulnerability Demonstration
• 🛠️ API Reference
  • Classes
    • PythonInterpreter
    • PythonLinter
  • Utility Functions
    • createInterpreter(config?)
    • createUnsafeInterpreter(config?)
    • createQuickInterpreter(preset, config?)
    • checkPythonAvailability(pythonPath?)
  • Configuration Options
  • Execution Options
• 🎯 Examples
• 🔒 Security Vulnerabilities (Educational)
  • 1. Command Injection
  • 2. Arbitrary Code Execution
  • 3. File System Access
  • 4. Input Sanitization Bypass
  • 5. Information Disclosure
  • 6. Resource Exhaustion
• 🧪 Testing
• 📜 Scripts
• 📄 License
• ⚖️ Legal Disclaimer
• 🔗 Inspired from

🚀 Installation

npm install @damnvulnerablewebsite/interpreter-py

Prerequisites

• Node.js 18 or higher
• Python 3.x installed and accessible in PATH
• TypeScript (if using TypeScript)

📖 Quick Start

Basic Usage

import { createInterpreter } from '@damnvulnerablewebsite/interpreter-py';

async function example() {
  const interpreter = createInterpreter();
  
  const result = await interpreter.executeCode(`
    print("Hello from Python!")
    import math
    print(f"Pi is approximately {math.pi}")
  `);
  
  console.log('Output:', result.stdout);
  console.log('Success:', result.success);
}

Streaming Output

import { createQuickInterpreter } from '@damnvulnerablewebsite/interpreter-py';

const interpreter = createQuickInterpreter('testing');

interpreter.on('data', (output) => {
  console.log(`[${output.type}]`, output.data);
});

interpreter.on('complete', (result) => {
  console.log('Execution completed:', result.success);
});

await interpreter.executeCode(`
import time
for i in range(3):
    print(f"Step {i + 1}")
    time.sleep(1)
`, { stream: true });

Educational Vulnerability Demonstration

import { createUnsafeInterpreter, createUnsafeContext } from '@damnvulnerablewebsite/interpreter-py';

// WARNING: This creates an interpreter with NO security measures!
const unsafeInterpreter = createUnsafeInterpreter();

// This demonstrates how vulnerabilities can be exploited
const dangerousCode = `
import os
import subprocess

# This would normally be blocked by security measures
print("Current directory:", os.getcwd())
print("Environment vars:", list(os.environ.keys())[:5])

# Command execution
result = subprocess.run(['echo', 'System access!'], capture_output=True, text=True)
print("Command output:", result.stdout)
`;

const result = await unsafeInterpreter.executeUnsafe(dangerousCode, createUnsafeContext());

🛠️ API Reference

Classes

PythonInterpreter

Main interpreter class for executing Python code.

const interpreter = new PythonInterpreter({
  pythonPath: 'python3',
  timeout: 30000,
  maxOutputLines: 1000,
  enableLinting: true,
  allowUnsafeOperations: false
});

PythonLinter

Lints Python code for syntax errors and security issues.

const linter = new PythonLinter();
const result = await linter.lintCode('print("hello")');

Utility Functions

createInterpreter(config?)

Creates a safe interpreter with security measures enabled.

createUnsafeInterpreter(config?)

Creates an unsafe interpreter with all security measures disabled.

createQuickInterpreter(preset, config?)

Creates an interpreter with preset configurations:

• 'safe' - Maximum security, limited execution time
• 'testing' - Balanced security for testing
• 'educational' - Some unsafe operations for learning
• 'dangerous' - All security measures disabled

checkPythonAvailability(pythonPath?)

Checks if Python is available on the system.

Configuration Options

interface InterpreterConfig {
  pythonPath?: string;          // Path to Python executable
  timeout?: number;             // Execution timeout in ms
  maxOutputLines?: number;      // Maximum output lines
  enableLinting?: boolean;      // Enable code linting
  allowUnsafeOperations?: boolean; // Allow dangerous operations
  workingDirectory?: string;    // Working directory for execution
  environment?: Record<string, string>; // Environment variables
}

Execution Options

interface ExecutionOptions {
  timeout?: number;     // Override timeout
  cwd?: string;         // Working directory
  env?: Record<string, string>; // Environment variables
  stream?: boolean;     // Enable streaming output
  sanitize?: boolean;   // Enable input sanitization
}

🎯 Examples

See the examples/ directory for comprehensive examples:

• basic-usage.ts - Complete demonstration of all features
• More examples coming soon...

Run the examples:

npm run dev  # Runs examples/basic-usage.ts

🔒 Security Vulnerabilities (Educational)

This package intentionally contains the following vulnerabilities for educational purposes:

1. Command Injection

• Environment variables can be manipulated to execute arbitrary commands
• Python path can be controlled by attackers

2. Arbitrary Code Execution

• Unsafe mode allows execution of any Python code
• Linting can be completely bypassed

3. File System Access

• No sandboxing when unsafe operations are enabled
• Temporary files may not be properly cleaned up

4. Input Sanitization Bypass

• Very basic sanitization that can be easily circumvented
• Regular expressions can be bypassed with alternative syntax

5. Information Disclosure

• Configuration details exposed in environment variables
• Error messages may leak sensitive information
• Temporary file paths may be predictable

6. Resource Exhaustion

• No limits on execution time when disabled
• No limits on output size when disabled
• Memory usage not controlled

🧪 Testing

npm test        # Run tests (when implemented)
npm run build   # Build TypeScript
npm run dev     # Run example in development mode

📜 Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Run example with hot reload
• npm start - Run compiled JavaScript
• npm run clean - Remove compiled files

📄 License

ISC License - see LICENSE file for details.

⚖️ Legal Disclaimer

This software is provided for educational and security research purposes only. The authors are not responsible for any misuse of this software. Users must comply with all applicable laws and regulations.

DO NOT USE THIS SOFTWARE IN PRODUCTION ENVIRONMENTS OR FOR MALICIOUS PURPOSES.

🔗 Inspired from

• DVWA - Damn Vulnerable Web Application
• WebGoat - Deliberately insecure application
• Juice Shop - Vulnerable web application