System Internals & Contributors Guide

Deep-dive into VScanX's underlying runtime orchestration, plugin discovery engine, thread pooling pipelines, and framework standards.

Mental Model

This internals guide is prepared exclusively for framework maintainers, core contributors, and advanced users. To keep onboarding simple and frictionless, **new users do not need to understand these internal mechanics to operate VScanX successfully.**

VScanX organizes its core engine into decoupled Python blocks under core/:

  • PluginManager (`core/plugins/manager.py`): Dynamically mounts and instantiates scanning subclasses at runtime.
  • Orchestrator (`core/orchestrator.py`): Manages thread-pool execution queues, task maps, and validation retries.
  • EventBus (`core/events/bus.py`): Coordinates event propagation across decoupled publishers.

Plugin Discovery & Loading

VScanX mounts modules dynamically without hardcoded config imports. When vscanx.py starts, the PluginManager scans the module folders, inspects Python modules for subclasses inheriting BaseModule (from modules.base_module), and registers their signatures:

# core/plugins/manager.py import importlib import pkgutil import inspect from modules.base_module import BaseModule  class PluginManager: def discover_modules(self, directory: str): # Walk directory, import modules, and register BaseModule subclasses for finder, name, ispkg in pkgutil.walk_packages([directory]): mod = importlib.import_module(f'modules.{name}') for _, obj in inspect.getmembers(mod, inspect.isclass): if issubclass(obj, BaseModule) and obj is not BaseModule: self.register_plugin(obj())

Orchestration Concurrency

The core orchestrator (core/orchestrator.py) utilizes a high-performance thread-pool architecture (concurrent.futures.ThreadPoolExecutor) to handle concurrent module probing.

To protect host network bandwidth and prevent target socket exhaustion, VScanX enforces strict resource boundaries:

  • Thread Limits: Concurrent tasks are capped at a maximum parameter size (defaulting to 10 threads per scan profile).
  • Verification Queues: Sandbox validators run sequentially or in isolated pools, ensuring dynamic exploit payload traces are executed with high precision.

Framework Contributor Standards

To maintain architectural alignment, clean schemas, and clean code styles as VScanX scales, all contributors must adhere strictly to the following standards:

1. Module Design Standards

Every scanning module must inherit BaseModule and override inspect_target(). Passive probes should strictly write zero active payloads to targets, delegating validations fully to sandbox verification engines.

2. Event Schema Standards

Custom anomaly events must be defined inside core/events/schemas.py. The schema payload contract must strictly store serialize-friendly parameters (strings, ints, floats) to allow clean disk snapshots.

3. Telemetry & Log Standards

Never inject raw print() statements inside framework cores. Always use the structured logger core.logging_config, passing trace IDs and log level parameters (such as logger.debug() or logger.error()) to ensure clean diagnostics outputs.