Harden scan security probes and workspace writes

Author: teilomillet

docs/guides/auto.md

@@ -50,6 +50,8 @@ For security-oriented triage, keep the same API and opt into trust-boundary bias
 result = scan_module("myapp.scoring", mode="candidate", security_focus=True)
 ```
 
+With `security_focus=True`, scan also synthesizes small artifact/config mutations for deserialization- and IPC-shaped parameters, so the same call can surface trust-boundary bugs beyond path-only shapers.
+
 ## fuzz
 
 !!! quote "What this unlocks"

docs/guides/cli.md

@@ -81,7 +81,7 @@ Use `--save-artifacts` when you want the full handoff package. In addition to th
 
 `scan` is evidence-first. In `--mode evidence`, it surfaces replayable crashes, weaker exploratory properties, and expected precondition failures without flattening them into one verdict. `--mode candidate` keeps the same search but ranks only the strongest contract-valid issue candidates at the top. If `[[scan]]` or `[[objects]]` leave fixture completeness too low for the module, `scan` will report that as a block instead of pretending it has real leverage. In that case, add a factory, `state_factory`, or `harness = "stateful"` before expecting useful output. If you need stronger validation for a mature codebase, prefer `ordeal audit` for coverage and mutation comparison, and `ordeal mutate` for direct mutation scoring.
 
-`--security-focus` is the opt-in trust-boundary bias for scan. It expands sink inference beyond shell/path/env to import loading, deserialization, filesystem writes, symlink handling, and checkpoint/IPC paths, then adds deterministic low-side-effect probes for pure path/symlink shapers. Saved proof bundles keep that context under `impact.critical_sinks`, `impact.trust_boundary_signal`, and `contract_basis.security_focus`.
+`--security-focus` is the opt-in trust-boundary bias for scan. It expands sink inference beyond shell/path/env to import loading, deserialization, filesystem writes, symlink handling, and checkpoint/IPC paths, then adds deterministic low-side-effect probes for pure path/symlink shapers plus small artifact/config mutations for deserialization- and IPC-shaped inputs. Saved proof bundles keep that context under `impact.critical_sinks`, `impact.trust_boundary_signal`, and `contract_basis.security_focus`.
 
 Promoted crash findings now carry a proof bundle in Markdown, JSON, and agent output: witness input, contract basis, confidence breakdown, minimal reproduction, failure path, and likely impact. Demoted crashes keep the same structure plus an explicit demotion reason.
 
@@ -126,6 +126,8 @@ By default, `init` does not install the bundled skill and does not write draft a
 
 `init` now also reads `[init]` from `ordeal.toml` when present. That lets you keep bootstrap defaults like `target`, `output_dir`, `close_gaps`, and CI generation in versioned config instead of repeating flags in scripts.
 
+For safety, `audit.save_generated`, `audit.write_gaps_dir`, `init.output_dir`, and `init.gap_output_dir` must stay inside the current workspace root.
+
 | Flag | Default | Description |
 |---|---|---|
 | `target` | auto-detect | Package path such as `myapp`; omit to detect from the current directory |

docs/guides/configuration.md

@@ -129,7 +129,7 @@ relation_overrides = { normalize = ["equivalent"] }
 
 When you run `pytest --chaos`, ordeal auto-discovers these entries and smoke-tests every public function in each module. Functions without type hints are skipped unless fixtures are provided or a registry supplies them. Known preconditions stay separate from candidate issue ranking so the output stays epistemic.
 
-`security_focus = true` is the opt-in trust-boundary review setting. It widens the sink taxonomy to include import/deserialization/filesystem-write/IPC paths and adds deterministic probes for pure path/symlink shapers without creating a second scan command.
+`security_focus = true` is the opt-in trust-boundary review setting. It widens the sink taxonomy to include import/deserialization/filesystem-write/IPC paths, adds deterministic probes for pure path/symlink shapers, and synthesizes small artifact/config mutations for deserialization- and IPC-shaped parameters without creating a second scan command.
 
 `targets` now acts as a first-class selector list, not just an exact-callable allowlist. Exact names still work, and glob patterns let package-root scans focus on a subset of exported callables without rewriting the module target.
 
@@ -250,6 +250,8 @@ min_fixture_completeness = 0.5
 
 Use `[[audit.targets]]` when one class needs an audit-specific factory or a narrower method subset:
 
+`save_generated` and `write_gaps_dir` are workspace-local output paths. Ordeal rejects values that escape the current repo root.
+
 ```toml
 [[audit.targets]]
 target = "myapp.envs:ComposableEnv"
@@ -286,6 +288,8 @@ gap_output_dir = "tests/gaps"
 scan_max_examples = 12
 ```
 
+`output_dir` and `gap_output_dir` are also workspace-local output paths; values outside the current repo root are rejected.
+
 ## Tuning guide
 
 !!! quote "Why this matters"

ordeal.toml.example

@@ -122,7 +122,8 @@ verbose = true
 # module = "myapp.scoring"
 # max_examples = 50
 # mode = "evidence"   # or "candidate" for stricter ranking
-# security_focus = true   # opt in to trust-boundary-biased sink detection/probes
+# security_focus = true   # opt in to trust-boundary-biased sink detection, path probes,
+#                        # and small artifact/config mutations for deserialize/IPC inputs
 # include_private = false
 #
 # # Optional: focus scan on a subset of callables instead of the whole module
@@ -244,8 +245,8 @@ verbose = true
 #
 # # Optional outputs / gates.
 # show_generated = false
-# # save_generated = "tests/test_migrated.py"
-# # write_gaps_dir = "tests/gaps"
+# # save_generated = "tests/test_migrated.py"  # must stay under the current workspace root
+# # write_gaps_dir = "tests/gaps"              # must stay under the current workspace root
 # # min_fixture_completeness = 0.5
 # include_exploratory_function_gaps = false
 # require_direct_tests = false
@@ -255,14 +256,14 @@ verbose = true
 #
 # [init]
 # target = "myapp"
-# output_dir = "tests"
+# output_dir = "tests"   # must stay under the current workspace root
 # ci = false
 # ci_name = "ordeal"
 # install_skill = false
 # close_gaps = false
 #
 # # Optional deeper defaults for the bootstrap loop.
-# # gap_output_dir = "tests/gaps"
+# # gap_output_dir = "tests/gaps"   # must stay under the current workspace root
 # mutation_preset = "essential"
 # scan_max_examples = 10