Skip to content

iyulab/code-beaker

BranchesTags

Repository files navigation

CodeBeaker

Multi-runtime code execution platform for .NET

License: MIT .NET Docker Deno Bun Node.js Python

개요

CodeBeaker는 다중 런타임을 지원하는 코드 실행 플랫폼입니다. WebSocket + JSON-RPC 2.0 프로토콜을 사용하여 실시간 양방향 통신을 제공하며, 세션 기반 실행 환경 재사용을 통해 성능을 향상시킵니다.

주요 기능

  • 다중 런타임 지원: Docker, Deno, Bun, Node.js, Python 5개 런타임
  • 세션 관리: 환경 재사용을 통한 성능 향상
  • 패키지 관리: npm, pip 자동 설치 지원
  • 보안 기능: 입력 검증, 속도 제한, 감사 로깅
  • 실시간 통신: WebSocket + JSON-RPC 2.0
  • 모니터링: Prometheus 메트릭, 헬스체크

지원 언어 및 런타임

언어 런타임 시작 시간 메모리 격리 수준 패키지 관리
Python Docker ~560ms 250MB 9/10 pip
Python Native ~100ms 50MB 6/10 pip+venv
JavaScript Bun ~50ms 25MB 7/10 npm
TypeScript Bun ~50ms 25MB 7/10 npm
JavaScript Deno ~80ms 30MB 7/10 -
TypeScript Deno ~80ms 30MB 7/10 -
JavaScript Node.js ~200ms 60MB 6/10 npm
JavaScript Docker ~560ms 250MB 9/10 npm

설치 및 실행

요구사항

  • .NET 8.0 SDK
  • Docker Desktop (선택사항, Docker 런타임 사용 시)
  • Node.js 18+ (선택사항, Node.js 런타임 사용 시)
  • Python 3.9+ (선택사항, Python 런타임 사용 시)
  • Deno 1.40+ (선택사항, Deno 런타임 사용 시)
  • Bun 1.0+ (선택사항, Bun 런타임 사용 시)

시작하기

Windows:

# Clone repository
git clone https://github.com/iyulab/codebeaker.git
cd codebeaker

# Build and run
dotnet build
dotnet run --project src/CodeBeaker.API

Linux/Mac:

# Clone repository
git clone https://github.com/iyulab/codebeaker.git
cd codebeaker

# Build and run
dotnet build
dotnet run --project src/CodeBeaker.API

WebSocket 연결

ws://localhost:5039/ws/jsonrpc

사용 예제

const ws = new WebSocket('ws://localhost:5039/ws/jsonrpc');

// 1. Create session with security
ws.send(JSON.stringify({
  jsonrpc: '2.0',
  id: 1,
  method: 'session.create',
  params: {
    language: 'javascript',
    runtimePreference: 'Speed',  // Speed, Security, Memory, Balanced
    security: {
      enableInputValidation: true,
      enableRateLimiting: true,
      executionsPerMinute: 60
    }
  }
}));

// 2. Install packages (npm/pip)
ws.send(JSON.stringify({
  jsonrpc: '2.0',
  id: 2,
  method: 'session.execute',
  params: {
    sessionId: 'abc123',
    command: {
      type: 'install_packages',
      packages: ['express', 'lodash']
    }
  }
}));

// 3. Execute code
ws.send(JSON.stringify({
  jsonrpc: '2.0',
  id: 3,
  method: 'session.execute',
  params: {
    sessionId: 'abc123',
    command: {
      type: 'execute',
      code: 'console.log("Hello from CodeBeaker!");'
    }
  }
}));

아키텍처

시스템 구조

┌──────────────────────────────────────────────┐
│         WebSocket Client (JSON-RPC 2.0)      │
└───────────────────┬──────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────────┐
│            CodeBeaker API Server             │
│         (ASP.NET Core 8 + WebSocket)         │
│                                              │
│  ┌────────────────────────────────────────┐ │
│  │       SecurityEnhancedEnvironment      │ │
│  │  1. Rate Limiting                      │ │
│  │  2. Input Validation                   │ │
│  │  3. Command Execution                  │ │
│  │  4. Output Sanitization                │ │
│  │  5. Audit Logging                      │ │
│  └────────────────────────────────────────┘ │
│                                              │
│  ┌────────────────────────────────────────┐ │
│  │         Session Manager                │ │
│  │  - Runtime selection                   │ │
│  │  - Package management                  │ │
│  │  - Filesystem persistence              │ │
│  │  - Auto cleanup                        │ │
│  └────────────────────────────────────────┘ │
└───────────────────┬──────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────────────────┐
│           Multi-Runtime Layer                │
│  ┌────────────────────────────────────────┐ │
│  │ Docker (Isolation: 9/10)               │ │
│  │ Startup: ~560ms | Memory: 250MB        │ │
│  └────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────┐ │
│  │ Bun (Isolation: 7/10)                  │ │
│  │ Startup: ~50ms | Memory: 25MB          │ │
│  └────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────┐ │
│  │ Deno (Isolation: 7/10)                 │ │
│  │ Startup: ~80ms | Memory: 30MB          │ │
│  └────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────┐ │
│  │ Node.js (Isolation: 5/10)              │ │
│  │ Startup: ~100ms | Memory: 40MB         │ │
│  │ Package: npm (local/global)            │ │
│  └────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────┐ │
│  │ Python (Isolation: 5/10)               │ │
│  │ Startup: ~200ms | Memory: 50MB         │ │
│  │ Package: pip (venv auto-created)       │ │
│  └────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘

주요 기능

1. 다중 런타임 아키텍처

런타임 선택 전략에 따라 최적의 실행 환경을 자동으로 선택합니다.

var selector = new RuntimeSelector(runtimes);

// 속도 우선
var runtime = await selector.SelectBestRuntimeAsync(
    "javascript", RuntimePreference.Speed);

// 보안 우선
var runtime = await selector.SelectBestRuntimeAsync(
    "python", RuntimePreference.Security);

2. 패키지 관리

npm 패키지 설치

{
  "jsonrpc": "2.0",
  "method": "session.execute",
  "params": {
    "sessionId": "abc123",
    "command": {
      "type": "install_packages",
      "packages": ["express", "lodash", "@types/node"],
      "global": false
    }
  }
}

pip 패키지 설치 (venv 자동 생성)

{
  "jsonrpc": "2.0",
  "method": "session.execute",
  "params": {
    "sessionId": "python-session",
    "command": {
      "type": "install_packages",
      "packages": ["requests", "numpy", "pandas"],
      "requirementsFile": "requirements.txt"
    }
  }
}

기능:

  • npm: 로컬/전역 설치, package.json 지원
  • pip: 자동 venv 생성, requirements.txt 지원, 세션 격리

3. 보안 기능

5단계 보안 아키텍처

// Production security configuration
var security = new SecurityConfig
{
    // Layer 1: Input Validation
    EnableInputValidation = true,
    MaxCodeLength = 100_000,
    MaxOutputLength = 1_000_000,

    // Layer 2: Rate Limiting
    EnableRateLimiting = true,
    ExecutionsPerMinute = 60,
    MaxExecutionsPerSession = 1000,

    // Layer 3: Sandbox
    EnableSandbox = true,
    SandboxRestrictFilesystem = true,
    AllowedFileExtensions = new[] { ".js", ".py", ".txt", ".json" },

    // Layer 4: Audit Logging
    EnableAuditLogging = true,
    AuditLogRetentionDays = 90,

    // Layer 5: Pattern Blocking
    BlockedCommandPatterns = new[] { "rm -rf /", "sudo", "dd if=" }
};

보안 기능:

  • 입력 검증: 코드/파일/명령어 검증 및 패턴 차단
  • 속도 제한: 세션당 실행 제한 (기본 60회/분)
  • 감사 로깅: 모든 작업 로그 기록 (12개 이벤트 타입)
  • 샌드박스: 작업 공간 제한, 파일 확장자 필터링
  • 공격 방어: 98.1% 탐지율 (147개 테스트 중 144개 통과)

방어 대상:

  • 디렉토리 탐색 (100% 차단)
  • 명령어 주입 (100% 차단)
  • 패키지 주입 (100% 차단)
  • 권한 상승 (100% 차단)
  • DoS 공격 (속도 제한 + 리소스 제한)

4. 모니터링

Prometheus 메트릭

GET /metrics

# Application metrics
codebeaker_executions_total
codebeaker_execution_duration_seconds
codebeaker_active_sessions
codebeaker_security_violations_total
codebeaker_rate_limit_exceeded_total

Health Checks

GET /health          # Overall health
GET /health/ready    # Readiness
GET /health/live     # Liveness

Documentation Site

  • Docusaurus-powered documentation
  • API reference
  • Architecture guides
  • Production deployment guide

🧪 Testing

Test Strategy

CodeBeaker separates tests into two categories:

Unit Tests (CI + Local)

  • ✅ Run automatically on every push/PR
  • Fast execution (~1-2 minutes)
  • No external dependencies required
  • 93 tests covering core functionality

Integration Tests (Local Only)

  • ⚠️ Require Docker and full runtime environment
  • Longer execution time (~5-10 minutes)
  • Run manually or on-demand
  • 54 tests for end-to-end scenarios

Test Results (v1.0)

Total Tests: 147
Passed: 144 (98.1%)
Failed: 3 (fork bomb variants - non-critical)

Categories:
✅ Unit Tests: 93 tests (100%) - CI Enabled
✅ Integration Tests: 54 tests (96.3%) - Local Only
✅ Security Simulation: 43 tests (95.3%)

Run Tests

# CI Tests (Unit Tests - Fast)
dotnet test tests/CodeBeaker.Core.Tests
dotnet test tests/CodeBeaker.Runtimes.Tests

# Local Tests (Integration Tests - Requires Docker)
dotnet test tests/CodeBeaker.Integration.Tests

# All tests (Local Development)
dotnet test

# Security tests only
dotnet test --filter "FullyQualifiedName~Security"

GitHub Actions Integration Tests

Integration tests can be run manually on GitHub Actions:

  1. Go to Actions tab → "Integration Tests (Manual)"
  2. Click "Run workflow"
  3. Select runtime to test (or "all")

Note: Integration tests may have limited functionality in CI due to Docker constraints. For best results, run locally.

성능

런타임 비교 (벤치마크 결과)

지표 Docker Bun Deno Node.js Python
시작 시간 560ms 50ms 80ms 100ms 200ms
메모리 250MB 25MB 30MB 40MB 50MB
코드 실행 1.2ms <1ms <1ms <1ms <2ms
파일 작업 146ms <5ms <5ms <5ms <5ms
격리 수준 9/10 7/10 7/10 5/10 5/10

성능 특징:

  • Bun: Docker 대비 시작 시간 11배, 파일 작업 30배 빠름
  • Deno: Docker 대비 시작 시간 7배, 파일 작업 30배 빠름
  • Node.js: Docker 대비 시작 시간 5.6배, npm 생태계 지원
  • Python: venv 격리, 최소 오버헤드
  • 보안 오버헤드: <1% (실행당 3-10ms)

문서

핵심 문서

배포 및 운영

Phase 문서

API 문서

사용 사례

  • AI 에이전트: LLM 생성 코드 안전 실행
  • 코딩 플랫폼: 온라인 저지, 코드 채점
  • CI/CD: 빌드 및 테스트 자동화
  • 교육: 학생 코드 실행 및 피드백
  • 대화형 노트북: Jupyter 스타일 실행

🤖 AI Agent Sample (Phase 12)

CodeBeaker를 AI 에이전트가 활용하는 실전 샘플을 제공합니다.

기능

  • AI 코드 생성: OpenAI API로 요구사항에 맞는 코드 자동 생성
  • 자동 실행: 생성된 코드를 CodeBeaker에서 안전하게 실행
  • 결과 검증: 실행 결과 확인 및 성공/실패 판단
  • 점진적 개선: 에러 발생 시 AI가 분석하고 수정 (향후 구현)

빠른 시작

# 1. .env 파일 설정 (프로젝트 루트)
echo "OPENAI_API_KEY=your-key-here" > .env
echo "OPENAI_MODEL=gpt-4" >> .env

# 2. CodeBeaker API 실행 (터미널 1)
dotnet run --project src/CodeBeaker.API

# 3. AI Agent 샘플 실행 (터미널 2)
cd samples/CodeBeaker.AI.Agent
dotnet run

실행 예시

[Scenario] Simple Coding: Write a Python function to calculate factorial...

[Step 1] Creating CodeBeaker session...
✅ Session created: session-abc123

[Step 2] Requesting code from OpenAI...
✅ Code generated

[Step 3] Writing code to CodeBeaker workspace...
✅ File written: solution.py

[Step 4] Executing code...
✅ Execution successful!

--- Output ---
120
3628800
--- End Output ---

✅ Scenario completed successfully!

문서

개발

Project Structure

CodeBeaker/
├── src/
│   ├── CodeBeaker.Commands/      # Command type system
│   ├── CodeBeaker.Core/          # Core library
│   │   ├── Runtime/              # RuntimeSelector
│   │   ├── Sessions/             # SessionManager
│   │   └── Security/             # Security services (NEW)
│   ├── CodeBeaker.Runtimes/      # Runtime implementations
│   │   ├── Docker/
│   │   ├── Deno/
│   │   ├── Bun/
│   │   ├── Node/                 # Node.js runtime (NEW)
│   │   └── Python/               # Python runtime (NEW)
│   ├── CodeBeaker.JsonRpc/       # JSON-RPC router
│   ├── CodeBeaker.API/           # WebSocket API
│   └── CodeBeaker.Worker/        # Background worker
├── tests/
│   ├── CodeBeaker.Core.Tests/   # Unit tests
│   └── CodeBeaker.Integration.Tests/ # Integration tests
├── docs/                          # Core documentation
├── docs-site/                     # Docusaurus documentation
├── claudedocs/                    # Development documentation
└── RELEASE_NOTES_v1.0.md          # Release notes

Build & Run

# Build solution
dotnet build

# Run API server
dotnet run --project src/CodeBeaker.API

# Run tests
dotnet test

# Run specific test category
dotnet test --filter "FullyQualifiedName~Security"

# Build documentation site
cd docs-site && npm start

로드맵

v1.0 (완료)

  • 다중 런타임 아키텍처 (5개 런타임)
  • 패키지 관리 (npm, pip)
  • 보안 하드닝 (5단계 방어)
  • 모니터링 (Prometheus, 헬스체크, 문서)
  • 프로덕션 준비 (98.1% 테스트 통과율)

v1.1+ (예정)

  • 향상된 fork bomb 탐지
  • 감사 로그 데이터베이스 영속성
  • 고급 속도 제한 (사용자 기반, 계층형)
  • 보안 대시보드 UI
  • 다중 노드 분산 실행
  • 추가 런타임 (Ruby, Rust, Go)

자세한 내용은 RELEASE_NOTES_v1.0.md 참조.

기여

기여를 환영합니다:

  1. Fork the repository
  2. Create a feature branch
  3. Commit your changes
  4. Push to the branch
  5. Open a Pull Request

라이선스

MIT License - LICENSE 파일 참조

참고

다음 프로젝트에서 영감을 받았습니다:

About

Multi-runtime sandboxed code execution platform supporting Docker, Deno, Bun, Node.js, and Python via WebSocket and JSON-RPC 2.0 with layered security controls.

Topics

security websocket sandbox json-rpc code-execution multi-runtime

Resources

Readme

License

MIT license

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages