Docs/Advanced/Python / RPC

Python / RPC

Out-of-process campaign control over a Unix-domain socket — live steering without recompilation.

The scripting surface exposes a control plane so an operator or Python client can inject seeds, swap protocol models, attach a live is_interesting oracle, change integrity/encryptor strategies, and push mutator dictionary extras — all while the campaign is running.

Module

src/scripting/ — RpcServer, bridges (protocol / integrity / encryptor / mutator / oracle), pure-stdlib JSON. Activated via -Y / NEXSIZ_RPC_SOCK.

Activation

nexsiz -h 127.0.0.1 -p 21 -m ftp -Y /tmp/nexsiz.sock -v
# or
export NEXSIZ_RPC_SOCK=/tmp/nexsiz.sock
nexsiz -h 127.0.0.1 -p 21 -m ftp -v

Unix only. On non-Unix platforms RpcServer::start returns an explicit error; the rest of the fuzzer remains fully usable.

Capabilities

BridgeWhat you can push
ProtocolLive ProtocolModel store (JSON model or name)
IntegrityStrategy name → repairer factory
EncryptorName + key → encryptor factory
MutatorExtra dictionary tokens + generation counter
OracleRegister as live Python oracle (reverse-RPC is_interesting)
SeedsStructured JSON seed → TestCase

Transport & concurrency

  • Line-delimited JSON over a Unix-domain socket.
  • One accept thread (nexsiz-rpc) + one short-lived client thread per connection.
  • Non-blocking accept, 50 ms poll, read/write timeouts prevent a stalled client from blocking the surface.
  • Hot path (mutate → repair → encrypt → send) never performs reverse-RPC except the optional oracle query (bounded timeout).
  • All plugin injection is push-style; workers re-resolve on the next cycle via generation or name comparison.

Oracle mode (reverse-RPC)

After a successful register_oracle the connection leaves the normal request/response path:

  1. Engine pushes is_interesting requests to the Python client.
  2. Python answers with a boolean (or structured result).
  3. On disconnect / timeout / stop flag the bridge unregisters and the default oracle is restored.

Design invariants

  • Zero behaviour change when the RPC socket is not configured.
  • The server never owns campaign logic — pure transport + mode switcher that delegates to RpcContext and the bridges.
  • Socket path is removed on Drop; cooperative shutdown shares the same AtomicBool used by workers and the Engine.
Client

Reference client: python/nexsiz_client.py (shipped with the source tree). Use it as the starting point for custom steering scripts.