Initial RPCScope release

docs/NETEXEC_REVIEW.md

@@ -0,0 +1,73 @@
+# NetExec execution review
+
+Reviewed upstream revision: `89a698d93dfc101e7104d42523aac4765372cd7d`.
+This is an interface/architecture review, not copied NetExec implementation code.
+RPCScope continues to invoke the operator's installed executable.
+
+## Findings and implementation
+
+| Finding | RPCScope change |
+| --- | --- |
+| NetExec starts a protocol object per target in a thread pool, default 256 workers. | 256 lightweight discovery workers; bounded live-host batches for heavier checks. |
+| Our old runner launched one NetExec process for every host/check pair. | One process per module/live-host batch, amortizing imports and initialization. |
+| Full enum4linux `-A` preceded the dedicated probes. | Dedicated probes first; normal CLI leaves full enumeration to `--deep`. RPC dump remains enabled. |
+| NetExec supports multiple modules per SMB session, but its module loop does not isolate arbitrary callback exceptions. | Keep unrelated modules in separate processes; no automatic retry of failed probes. |
+| All five selected `coerce_plus` bind methods can use `METHOD=All` without a listener. | Combine only the complete, unchanged five-method selection. Subsets stay separate. Each method still has its own result record. |
+| Current NetExec uses ACL-based share checks and opts into file writes with `--file-write-check`. Older versions offered `--no-write-check`. | Inspect installed help, select a known read-only mode, otherwise skip with an explicit error. Never enable file-write testing. |
+| Admin checking adds an SCM RPC exchange; our adapters use `on_login`, not `on_admin_login`. | Use `--no-admin-check` only when the installed CLI advertises support. |
+| NetExec may catch individual host exceptions and still exit zero. | Attribute known host exceptions and mark that host's check failed/unknown without invalidating other hosts. |
+| Console output can contain credential echoes, truncated module labels and unrecognized messages. | Index by canonical IP/module/port once per batch; allow known label truncation; require documented full negative markers. |
+| Reviewed MS17-010 and SMBGhost modules create IPv4 sockets. | Skip these adapters explicitly on IPv6 rather than pretending a checker executed successfully. |
+| Local socket limits and noisy subprocesses could produce misleading outcomes or excessive temporary output. | Report local resource exhaustion as an execution failure, and actively stop over-limit output. |
+
+## Execution and budgets
+
+```text
+scope -> TCP discovery -> NetExec inventory (open SMB listeners only)
+      -> same-module NetExec check batches (live, eligible hosts only)
+      -> bounded host pipelines: native / optional MSF / RPC / optional deep enum
+      -> evidence-backed reports
+```
+
+`--jobs` bounds each check batch and the later host pool; these phases do not
+multiply their concurrency. Batches contain no more than 128 targets, even with
+a larger jobs limit, and no more hosts than can execute in one NetExec thread
+wave. A single-check process receives one check timeout. The combined five-bind
+process receives five check timeouts in total; individual methods are not
+independently timed inside that external process. Global batch failures remain
+unknown/partial. Positive evidence is not inferred from process exit alone.
+
+The core library keeps legacy isolated execution and full enum defaults for
+compatibility. CLI defaults select batching and leave full enum to `--deep`.
+`--isolated-checks` is a diagnostic fallback, not an automatic retry policy.
+
+## Verification and limits
+
+The mocked 32-live-host recommended scan executes 28 NetExec check invocations
+instead of the old 352 (seven module groups, four eight-host batches). All twelve
+selected results per host remain represented; inventory and capability-help
+invocations are separate from this count. This is not a wall-clock benchmark.
+
+Tests cover batching, selection boundaries, per-host result isolation, zero-exit
+errors, cancellation, read-only share compatibility, output caps, and resource
+failures. External tools are absent on the development host. Real version
+interoperability, network throughput, and detection sensitivity/specificity are
+not established by mocks and need an authorized, patched/unpatched lab matrix.
+No live target scan was performed for this review.
+
+A bare `nxc smb` connection/banner scan does less work than twelve selected
+checks plus RPC/deep enumeration. The optimization removes avoidable overhead;
+it does not remove the protocol work or turn heuristic findings into patch
+proof. No scanner can promise flawless results across every network/tool build.
+
+## Primary sources
+
+- [Threaded target runner](https://github.com/Pennyw0rth/NetExec/blob/89a698d93dfc101e7104d42523aac4765372cd7d/nxc/netexec.py)
+- [CLI worker default](https://github.com/Pennyw0rth/NetExec/blob/89a698d93dfc101e7104d42523aac4765372cd7d/nxc/cli.py)
+- [Connection/module callback flow](https://github.com/Pennyw0rth/NetExec/blob/89a698d93dfc101e7104d42523aac4765372cd7d/nxc/connection.py)
+- [SMB CLI and share options](https://github.com/Pennyw0rth/NetExec/blob/89a698d93dfc101e7104d42523aac4765372cd7d/nxc/protocols/smb/proto_args.py)
+- [Share and admin checks](https://github.com/Pennyw0rth/NetExec/blob/89a698d93dfc101e7104d42523aac4765372cd7d/nxc/protocols/smb.py)
+- [Combined bind-method interface](https://github.com/Pennyw0rth/NetExec/blob/89a698d93dfc101e7104d42523aac4765372cd7d/nxc/modules/coerce_plus.py)
+- [Logger format](https://github.com/Pennyw0rth/NetExec/blob/89a698d93dfc101e7104d42523aac4765372cd7d/nxc/logger.py)
+- [MS17-010 IPv4 implementation](https://github.com/Pennyw0rth/NetExec/blob/89a698d93dfc101e7104d42523aac4765372cd7d/nxc/modules/ms17-010.py)
+- [SMBGhost IPv4 implementation](https://github.com/Pennyw0rth/NetExec/blob/89a698d93dfc101e7104d42523aac4765372cd7d/nxc/modules/smbghost.py)