dart_vm_injector 🔬 #

⚠️ Security Warning
This package opens a direct, unrestricted channel to the live Dart VM heap — including all in-memory secrets (passwords, API tokens, private keys, PII).
Use only with explicit authorisation on systems you own or are permitted to inspect.

Inject and evaluate arbitrary Dart expressions inside live, running Dart VM Isolates without stopping, restarting, or modifying the target application.

Powered by the official Dart VM Service Protocol (WebSocket + JSON-RPC 2.0).

✨ Features #

⚠️ Requirements #

This package works only with JIT-compiled Dart programs running with the --enable-vm-service flag.

🚀 Quick Start #

1. Add to pubspec.yaml #

dependencies:
  dart_vm_injector: ^1.0.0

2. Start your target app with VM Service enabled #

dart run --enable-vm-service your_app.dart

You will see:

The Dart VM service is listening on http://127.0.0.1:8181/FmMJoBzneFU=/

3. Inject an expression #

import 'package:dart_vm_injector/dart_vm_injector.dart';

void main() async {
  // One-shot injection — connects, evaluates, disconnects
  final result = await VmInjector.inject(
    3495637284,                  // isolate number from startup output
    'userService.currentUser?.email ?? "none"',
    token: 'FmMJoBzneFU',        // from the VM service URL
  );

  print(result.valueAsString);   // admin@example.com
  print(result.latency);         // Duration(milliseconds: 12)
}

📖 API Reference #

One-shot static methods #

// Inject into a specific Isolate and disconnect immediately
final r = await VmInjector.inject(isolateNumber, expression, token: '...');

// Inject into the main Isolate (auto-detected)
final r = await VmInjector.injectMain(expression, token: '...');

Persistent session #

// Open a reusable session
final injector = await VmInjector.connect(
  host: '127.0.0.1',
  port: 8181,
  token: 'YourToken',
);

try {
  // List Isolates
  final isolates = await injector.listIsolates();

  // Evaluate expressions
  final r = await injector.evaluateInIsolate(12345, '2 + 2');
  final r = await injector.evaluateInMainIsolate('"hello"');
  final r = await injector.evaluateInNamedIsolate('worker', 'queue.length');

  // Evaluate in a paused stack frame
  final r = await injector.evaluateInFrame(12345, 0, 'localVar');

  // Watch a variable (continuous polling stream)
  await for (final e in injector.watch(12345, 'requestCount', interval: 1.seconds)) {
    print('requestCount = ${e.value}');
  }

  // Live VM streams
  injector.stdout.listen(print);
  injector.stderr.listen(print);
  injector.vmEvents.listen((e) => print(e.kind));

  // Deep object inspection
  final obj = await injector.getObject(12345, result.instanceId!);
  final instances = await injector.getInstances(12345, 'objects/class/42');

  // Lifecycle control
  await injector.pauseIsolate(12345);
  await injector.resumeIsolate(12345);

  // Statistics
  print(injector.stats);
} finally {
  await injector.dispose();
}

🔬 How It Works #

Your code            dart_vm_injector        Dart VM (JIT)
─────────────────────────────────────────────────────────────
VmInjector.inject()
  │
  ├─► WebSocket handshake ─────────────────► VM Service (port 8181)
  │                                              │
  ├─► getVM() JSON-RPC ────────────────────────► │ list isolates
  │   ◄─────────────────── IsolateRef[] ─────────┤
  │                                              │
  ├─► getIsolate(id) ──────────────────────────► │ get root library
  │   ◄─────────────────── Isolate{rootLib} ─────┤
  │                                              │
  ├─► evaluate(isolateId, libId, expr) ────────► │
  │                                         JIT compiler
  │                                         ┌────────────────┐
  │                                         │ parse expr      │
  │                                         │ → AST           │
  │                                         │ → kernel IR     │
  │                                         │ → bytecode      │
  │                                         │ execute in heap │
  │                                         └────────────────┘
  │   ◄──────────── InstanceRef{valueAsString} ──┤
  │
  └─► InjectionResult{valueAsString, valueKind, instanceId}

The evaluate RPC is implemented by the incremental Dart compiler embedded in every JIT runtime. It compiles the expression in the scope of a specific Library, executes the resulting bytecode on the target Isolate's thread, and returns an InstanceRef — a reference to the live heap object.

🧭 Finding the Isolate Number #

The Isolate number is the numeric portion of the Isolate ID (isolates/XXXXXXXXXX).

Method 1 — listIsolates() (recommended) #

final injector = await VmInjector.connect(host: 'localhost', port: 8181, token: '...');
final isolates = await injector.listIsolates();
for (final iso in isolates) {
  print('${iso.number}  ${iso.name}');  // 3495637284  main
}

Method 2 — Observatory UI #

Open http://127.0.0.1:8181/FmMJoBzneFU=/ in a browser → Isolates tab.

Method 3 — dart:developer #

import 'dart:developer' as dev;

void main() {
  print(dev.Service.getIsolateID(Isolate.current));
  // prints: isolates/3495637284
}

🔒 Security Model #

What the VM Service exposes #

Defence in depth #

1. Never run --enable-vm-service on public-facing production servers.
2. Restrict the VM Service port with firewall rules (iptables, ufw, security groups).
3. Never use --disable-service-auth-codes — the random token is your only layer of protection.
4. Audit all injections — log every expression evaluated in a tamper-proof audit trail.
5. Prefer --observe (profile mode) over debug when you need live inspection — it is slightly faster.
6. Use TLS tunnelling (e.g. SSH port-forward) when connecting to remote VMs.

🗂️ Package Structure #

dart_vm_injector/
├── lib/
│   ├── dart_vm_injector.dart          ← Barrel export
│   └── src/
│       ├── vm_injector.dart           ← VmInjector — main class
│       ├── vm_connection.dart         ← WebSocket connection management
│       ├── isolate_resolver.dart      ← Isolate discovery & resolution
│       ├── expression_evaluator.dart  ← evaluate / evaluateInFrame / invoke
│       ├── result_parser.dart         ← InstanceRef → InjectionResult
│       ├── stream_listener.dart       ← Live VM event streams
│       ├── models/
│       │   ├── injection_result.dart
│       │   ├── isolate_info.dart
│       │   ├── vm_connection_config.dart
│       │   ├── vm_connection_stats.dart
│       │   └── watch_event.dart
│       ├── exceptions/
│       │   ├── vm_connection_exception.dart
│       │   ├── isolate_not_found_exception.dart
│       │   ├── injection_failed_exception.dart
│       │   ├── aot_mode_exception.dart
│       │   └── vm_timeout_exception.dart
│       └── utils/
│           ├── logger.dart
│           └── websocket_helper.dart
├── example/
│   ├── basic_inject.dart
│   ├── list_isolates.dart
│   ├── watch_variable.dart
│   ├── listen_stdout.dart
│   ├── advanced_inspect.dart
│   └── server_example/
│       ├── target_server.dart         ← Shelf server to inject into
│       └── injector_client.dart       ← Client that injects into it
└── test/
    ├── models_test.dart
    ├── exceptions_test.dart
    ├── result_parser_test.dart
    └── websocket_helper_test.dart

🔧 VM Service RPC Reference #

🧑‍💻 Legitimate Use Cases #

• ✅ IDE plugin development — power live variable inspection panels.
• ✅ Custom debuggers — build domain-specific debuggers for Dart servers.
• ✅ Staging environment inspection — debug issues without deploying new code.
• ✅ Developer tooling — CLI tools for Dart server introspection.
• ✅ Authorised penetration testing — assess VM Service exposure on client systems.
• ✅ Hot-patch tooling — apply emergency in-memory patches in JIT environments.
• ✅ Forensics — post-incident memory inspection on isolated, authorised systems.

❌ Out of Scope #

• ❌ Unauthorized access to any system.
• ❌ Production systems without explicit operator consent.
• ❌ AOT-compiled Flutter release or standalone binaries.
• ❌ Exfiltrating user data.

📜 License #

MIT © 2026 — See LICENSE.