Release RelayX v0.1.14 engineering quality

Author: RedteamNotes

README.md

@@ -58,7 +58,8 @@ telemetry.
   awareness, noise filtering, blockers, fixes, and OPSEC notes.
 - Route/Pivot Awareness for source sessions, segments, subnets, structured
   `route_hops`, Ligolo, Sliver P2P, SOCKS, tun2socks, port forwarding, hop
-  count, reachability state, and route risk scoring.
+  count, reachability state, route risk scoring, and optional authorized direct
+  TCP reachability checks that do not open pivot sessions.
 - Relay decision calculus with rule IDs, target families, preconditions,
   hardening gates, defensive controls, and remediation priorities.
 - Lab calibration profiles for HTTP/IIS EPA, AD CS Web Enrollment EPA, LDAP
@@ -86,10 +87,15 @@ telemetry.
 - OPSEC policy evaluation for validation, execution, and source planning,
   including noise ceilings, scope requirements, confirmed-mode context,
   network-action boundaries, expected telemetry, and rollback checks.
+- Operation controls for assessment and validation, including rate limits,
+  delay, jitter, scheduled operation windows, listener/callback scope contracts,
+  and machine-clean output preservation.
 - Execution module inventory, compatibility planning, and Adapter SDK
   dispatch, including built-in offline audit recording, JSON manifest-backed
   module definitions, credential policy guardrails, listener policy guardrails,
-  and audited adapter lifecycle records.
+  lab-only adapter fixtures that hard-fail in confirmed mode,
+  one-shot/timeout/evidence-capture contracts, and audited adapter lifecycle
+  records.
 - Versioned schema and evidence contract validation for result files, lab
   profiles, corpuses, lab stability and differential reports, execution
   records, evidence reports, module manifests, OpenGraph, JSONL, CSV, OPSEC
@@ -152,6 +158,7 @@ Review relay paths, decisions, controls, and remediation:
 ```bash
 relayx paths result.json
 relayx routes --result result.json
+relayx routes --result result.json --target-protocol ldap --connect-check --rate-limit 60 --format json --out relayx-routes.json
 relayx calculus result.json
 relayx evidence-report --result result.json
 relayx controls result.json
@@ -163,8 +170,8 @@ Run guarded validation or offline execution recording:
 
 ```bash
 relayx validate --result result.json --path-id PX-0001 --mode dry-run
-relayx validate --result result.json --path-id PX-0001 --mode confirmed --confirm --operator redpen --reason "authorized target reprobe" --audit-log audit.jsonl --reprobe
-relayx run --result result.json --path-id PX-0001 --module relayx_audit_record --mode confirmed --confirm --operator redpen --reason "authorized offline audit record" --audit-log audit.jsonl
+relayx validate --result result.json --path-id PX-0001 --mode confirmed --confirm --operator redpen --reason "authorized target reprobe" --audit-log audit.jsonl --scope filesrv01 --reprobe --stop-before 2030-01-01T18:00:00+08:00
+relayx run --result result.json --path-id PX-0001 --module relayx_audit_record --mode confirmed --confirm --operator redpen --reason "authorized offline audit record" --audit-log audit.jsonl --scope filesrv01
 ```
 
 Export enterprise artifacts:
@@ -201,6 +208,8 @@ relayx -q bundle -r examples/tutorial/sample-result.json -d /tmp/relayx-tutorial
 
 Read the full runbook in [docs/TUTORIAL.md](docs/TUTORIAL.md). The tutorial
 fixtures live in [examples/tutorial](examples/tutorial).
+Authorized AD/IIS/AD CS/MSSQL lab expectations are documented in
+[docs/INTEGRATION_TESTS.md](docs/INTEGRATION_TESTS.md).
 
 ## Command Reference
 
@@ -287,11 +296,15 @@ guardrails.
 
 - `json`: full RelayX result or command output for automation.
 - `markdown` / `html`: assessment reports for operators and stakeholders.
+  HTML reports include offline filters for status, severity, protocol, source
+  capability, target family, defensive control, and free-text review.
 - `mermaid`: lightweight path diagrams.
-- `csv`: spreadsheet-oriented finding and path review.
-- `jsonl`: one event per line for SIEM and blue-team pipelines.
+- `csv`: spreadsheet-oriented finding and path review with a stable field
+  contract.
+- `jsonl`: one event per line for SIEM and blue-team pipelines, including
+  stable event IDs and field contract versions.
 - `opengraph`: custom BloodHound/OpenGraph-style graph with RelayX node and
-  edge kinds.
+  edge kinds, in-artifact mapping, deterministic edge IDs, and control nodes.
 - `bundle-manifest`: validated enterprise bundle manifest with hashes and
   schema status.
 - `quality-gate`: CI and release gate report for package, fixture, docs, and
@@ -314,6 +327,12 @@ Supported kinds include `result`, `evidence`, `lab-profile`, `lab-corpus`,
 Validation reports explain invalid fields by path and return exit code `2` when
 an artifact does not satisfy the selected contract.
 
+`relayx diff` reports added, removed, and changed paths plus exposure trend,
+score delta, control trends, remediation regressions, and remediation
+improvements. `relayx simulate-fixes` reports affected paths, control
+dependencies, remaining controls, remaining target families, and estimated
+residual exposure.
+
 `relayx evidence-report -r result.json` audits an existing result without
 network activity. It highlights candidate or relayable records without
 evidence, protocol judgement records missing policy inference or remaining
@@ -360,8 +379,9 @@ coercion. `--auth-validation` sends synthetic NTLM authenticate messages with
 placeholder credentials and can create failed authentication telemetry.
 
 Confirmed validation and execution require operator identity, reason,
-confirmation, and audit logging. The built-in supported execution adapter is
-offline audit recording only. Execution is dispatched through the RelayX
+confirmation, and audit logging; confirmed execution also requires explicit
+scope. The built-in supported execution adapter is offline audit recording only.
+Execution is dispatched through the RelayX
 Adapter SDK, which blocks unregistered adapters, unsafe credential policies,
 unsafe listener policies, and inconsistent manifest support declarations. Live
 relay adapters are not enabled by default.

docs/CLI.md

@@ -6,6 +6,8 @@ for workflows, examples, exports, and safety boundaries.
 For a complete end-to-end offline walkthrough, use
 [`docs/TUTORIAL.md`](TUTORIAL.md) with the fixtures in
 [`examples/tutorial`](../examples/tutorial).
+Authorized AD/IIS/AD CS/MSSQL integration-test expectations are documented in
+[`docs/INTEGRATION_TESTS.md`](INTEGRATION_TESTS.md).
 
 ## Quick Help
 
@@ -63,6 +65,11 @@ Common aliases:
 -S, --scope         Scope input
 -q, --no-banner     Suppress human-readable banner output
 -V, --version       Print RelayX version
+-Q, --rate-limit    Maximum active starts per minute where supported
+-D, --delay         Minimum delay between active starts
+-J, --jitter        Random delay added to active start spacing
+-U, --start-after   ISO-8601 operation window start
+-Z, --stop-before   ISO-8601 operation window end
 ```
 
 Safety and execution aliases:
@@ -75,6 +82,8 @@ Safety and execution aliases:
 -R, --reason        Authorization or operational reason
 -A, --audit-log     JSONL audit log path
 -P, --opsec-policy  Built-in policy name or external policy JSON
+-L, --listener-host Planned listener host for scope checks
+-K, --callback-host Planned callback host for scope checks
 ```
 
 Use `relayx help short-options` for the complete alias map. Short aliases do not
@@ -86,14 +95,32 @@ confirmation, operator, reason, scope where required, and audit logging.
 ```bash
 relayx routes --sources examples/sources.json --targets examples/targets.txt
 relayx routes -r result.json -f json -o relayx-routes.json
+relayx routes -s examples/sources.json -t examples/targets.txt -P ldap --connect-check --rate-limit 60 -f json -o relayx-routes.json
 ```
 
-Route awareness is model-driven. RelayX does not open pivot sessions or test
-live reachability from the operator host. Source profiles can provide
+Route awareness is model-driven by default. With `--connect-check`, RelayX runs
+authorized direct TCP checks from the operator runtime only; it does not open,
+prove, or operate pivot sessions. Source profiles can provide
 `session`, `segment`, `subnets`, free-form `routes`, and structured
 `route_hops`. Structured routes produce stronger reachability evidence than
 unconstrained labels.
 
+## Operation Controls
+
+`scan`, `assess`, `routes --connect-check`, and `validate` accept operation
+controls for controlled assessment windows:
+
+```bash
+relayx scan -t examples/targets.txt -o result.json --rate-limit 120 --stop-before 2030-01-01T18:00:00+08:00
+relayx validate -r result.json -p PX-0001 -m confirmed -y -O redpen -R "authorized target reprobe" -A audit.jsonl -e --start-after 2030-01-01T14:00:00+08:00 --stop-before 2030-01-01T18:00:00+08:00
+```
+
+`--rate-limit` controls operation starts per minute. `--delay` sets a minimum
+spacing between starts, and `--jitter` adds randomized delay. `--start-after`
+and `--stop-before` use ISO-8601 timestamps; naive timestamps are interpreted
+in the local timezone. Confirmed validation reprobes fail closed outside the
+window, while dry-run validation records the same window as a warning.
+
 ## Evidence Report
 
 ```bash
@@ -151,6 +178,17 @@ In `relayx bundle`, `-f/--format` controls the manifest summary printed by the
 command, while `-F/--formats` controls which artifacts are written into the
 bundle.
 
+`relayx export -f opengraph` includes node/edge mappings, deterministic edge
+IDs, and RelayX control nodes. `relayx export -f jsonl` and `relayx export -f
+csv` use stable field contracts for SIEM and spreadsheet ingestion. HTML
+reports include offline filters for status, severity, protocol, source
+capability, target family, defensive control, and free text.
+
+`relayx diff` reports exposure trend, score delta, control trends, remediation
+regressions, and remediation improvements. `relayx simulate-fixes` reports
+control dependencies and estimated residual exposure in addition to affected
+paths and score reduction.
+
 ## Validation And Execution Modes
 
 `dry-run` explains guardrails and expected telemetry without performing an
@@ -163,6 +201,10 @@ context.
 can create failed-logon telemetry. Use it only in explicitly authorized lab or
 assessment windows.
 
+`source-plan` and `run` accept `--listener-host` and `--callback-host` as
+planning inputs for stricter scope contracts. Supplying these values does not
+start listeners or callbacks; it records and checks the intended boundaries.
+
 ## Lab Matrix And Corpus Verification
 
 ```bash
@@ -210,7 +252,9 @@ not silently produce an empty pass report.
 `relayx modules` and `relayx module-plan` expose both module manifests and the
 registered Adapter SDK contract. Confirmed execution is blocked unless the
 adapter is registered, credential policy is allowed, listener policy is allowed,
-and the module support declaration is consistent with the adapter boundary.
+the module support declaration is consistent with the adapter boundary, and
+explicit scope is supplied. Lab-only module fixtures may describe future live
+adapter contracts, but they are not registered live execution modules.
 
 ## Help Content
 

docs/ENTERPRISE_OUTPUTS.md

@@ -34,6 +34,25 @@ with `graph.nodes` and `graph.edges`. RelayX uses custom kinds such as
 `RelayXScan`, `RelayXSource`, `RelayXTargetService`, and `RelayXPath` so that
 relay readiness context does not collide with AD or Azure entity kinds.
 
+The export includes `metadata.field_contract_version` and a `mapping` object.
+`mapping.node_kinds` and `mapping.edge_kinds` document the RelayX node and edge
+contract inside the artifact itself. Edges carry deterministic IDs so graph
+imports, repeat exports, and scan diffs can reason about stable relationships.
+
+Current custom node kinds include:
+
+- `RelayXScan`
+- `RelayXSource`
+- `RelayXTarget`
+- `RelayXTargetService`
+- `RelayXFinding`
+- `RelayXPath`
+- `RelayXControl`
+
+Current custom edge kinds include path ownership, source/target relationships,
+candidate relay relationships, and `RelayXPathMitigatedBy` edges from paths to
+defensive controls.
+
 ## JSONL
 
 `--format jsonl` emits one event per line:
@@ -46,6 +65,36 @@ relay readiness context does not collide with AD or Azure entity kinds.
 
 This is the preferred format for SIEM and blue-team pipelines.
 
+Every event includes `event_type`, `event_id`, `schema_version`, and
+`field_contract_version`. Path events keep stable judgement and routing fields
+such as `rule_id`, `decision`, `target_family`, `source_capability`,
+`control_keys`, `route_state`, `route_risk_level`, and
+`remaining_uncertainty`.
+
+## CSV
+
+`--format csv` emits one table with `finding` and `path` rows. The header is the
+field contract. It includes stable SIEM/spreadsheet fields for host, protocol,
+status, score, impact, source, target service, calculus decision, target
+family, source capability, defensive controls, route risk, blockers, fixes,
+remaining uncertainty, and `field_contract_version`.
+
+## HTML Reports
+
+HTML reports are designed to work as offline bundle artifacts. The path table
+includes filters for:
+
+- free text
+- status
+- severity
+- protocol
+- source capability
+- target family
+- defensive control
+
+The filters operate on row `data-*` attributes, so the visible table and the
+underlying path metadata remain aligned when the report is archived.
+
 ## Enterprise Bundle
 
 `relayx bundle` writes a complete handoff directory from one result file. The
@@ -65,8 +114,10 @@ relayx schema validate -k bundle-manifest relayx-bundle/manifest.json
 
 `relayx routes` emits a route and pivot awareness report. It records modeled
 source-to-target reachability, route state, pivot types, hop count, route risk,
-and remaining uncertainty. Route reports are offline model artifacts; they do
-not open pivot sessions or perform live reachability checks.
+and remaining uncertainty. Route reports are offline model artifacts by
+default. With `--connect-check`, they can include authorized direct TCP
+reachability observations from the operator runtime; this still does not open,
+prove, or operate pivot sessions.
 
 ## Schema Validation
 
@@ -113,8 +164,19 @@ It reports added, removed, and changed paths, plus finding additions/removals an
 score movement. Path changes include protocol oracle subclassification and
 route risk changes when those fields are present.
 
+Diff output also reports `exposure_trend`, `score_delta`, `control_trends`,
+`remediation_regressions`, and `remediation_improvements`. This makes repeated
+scans usable as a remediation trend record rather than only a path inventory
+comparison.
+
 ## Remediation Simulation
 
 `relayx simulate-fixes` calculates the path and score reduction if matching
 fixes or RelayX controls are treated as implemented. It does not mutate the
 input result file.
+
+Simulation output is an estimate. It records affected paths, score reduction,
+control dependencies, remaining controls, remaining target families, and
+estimated residual exposure. Dependency records are intentionally conservative:
+they show which related controls still appear on remaining paths, not proof that
+those controls have been implemented or bypassed.

docs/INSTALL.md

@@ -32,9 +32,11 @@ relayx --version
 1. Update `relayx.__version__` and `pyproject.toml`.
 2. Run the full unit test suite.
 3. Run the RelayX quality gate.
-4. Build a wheel and source distribution.
-5. Smoke-test the generated wheel.
-6. Tag the release in GitHub.
+4. Review [`docs/INTEGRATION_TESTS.md`](INTEGRATION_TESTS.md) when lab fixtures
+   or protocol classifications changed.
+5. Build a wheel and source distribution.
+6. Smoke-test the generated wheel.
+7. Tag the release in GitHub.
 
 ```bash
 python3 -m unittest discover -s tests