ergonomic builds, real instruments

Author: Protonk

Makefile

@@ -1,11 +1,43 @@
-.PHONY: build clean test
+.PHONY: build clean test notarize
+
+NOTARY_KEYCHAIN_PROFILE ?=
+YOLO ?=
+BUILD_ARGS ?=
+
+ifneq ($(strip $(YOLO)),)
+BUILD_ARGS += --yolo
+endif
 
 build:
-	./build.sh
+	./build.sh $(BUILD_ARGS)
 
 clean:
 	rm -rf tests/out/*
 
 test:
 	@echo "==> [test] run all suites"
 	@./tests/run.sh --all
+
+notarize:
+	@if [ -z "$(NOTARY_KEYCHAIN_PROFILE)" ]; then \
+		echo "ERROR: set NOTARY_KEYCHAIN_PROFILE to your notarytool keychain profile name"; \
+		echo "example: make notarize NOTARY_KEYCHAIN_PROFILE=dev-profile"; \
+		exit 2; \
+	fi
+	@if [ -z "$(IDENTITY)" ] && [ -z "$(YOLO)" ]; then \
+		echo "ERROR: set IDENTITY or opt-in to auto selection with YOLO=1"; \
+		echo "example: make notarize NOTARY_KEYCHAIN_PROFILE=dev-profile IDENTITY='Developer ID Application: ...'"; \
+		echo "example: make notarize NOTARY_KEYCHAIN_PROFILE=dev-profile YOLO=1"; \
+		exit 2; \
+	fi
+	@$(MAKE) build
+	@echo "==> [notarize] submit PolicyWitness.zip"
+	@xcrun notarytool submit "PolicyWitness.zip" --keychain-profile "$(NOTARY_KEYCHAIN_PROFILE)" --wait
+	@echo "==> [notarize] staple PolicyWitness.app"
+	@xcrun stapler staple "PolicyWitness.app"
+	@echo "==> [notarize] validate PolicyWitness.app"
+	@xcrun stapler validate -v "PolicyWitness.app"
+	@spctl -a -vv --type execute "PolicyWitness.app"
+	@echo "==> [notarize] re-zip stapled app"
+	@rm -f "PolicyWitness.zip"
+	@/usr/bin/ditto -c -k --sequesterRsrc --keepParent "PolicyWitness.app" "PolicyWitness.zip"

PolicyWitness.md

@@ -67,6 +67,7 @@ Top-level fields:
 - `policy`: object
 - `probe_plan`: array of steps
 - `runner`: object (optional, for external runners)
+- `instrumentation`: object (optional, instrumentation port)
 
 ### Policy
 
@@ -110,6 +111,83 @@ Example:
 }
 ```
 
+## Instrumentation (opt-in)
+
+Instrumentation ports provide a user-friendly way to exercise the runner’s
+entitlement-backed capabilities. This field is optional; if omitted, behavior
+is unchanged. Results are reported under `instrumentation` in the run JSON and
+do not change the run outcome.
+Each port can specify an optional `phase`:
+
+- `pre_sandbox` (default)
+- `post_sandbox`
+
+Example specimen fragment:
+
+```json
+"instrumentation": {
+  "version": 1,
+  "ports": [
+    { "kind": "debug_wait", "sleep_ms": 5000 },
+    { "kind": "dylib_load", "path": "/path/to/lib.dylib", "symbol": "pw_instrumentation_init" },
+    { "kind": "execmem_probe", "size_bytes": 4096 },
+    { "kind": "dyld_env", "keys": ["DYLD_INSERT_LIBRARIES"] }
+  ]
+}
+```
+
+Notes:
+- `dylib_load` expects an optional no-arg symbol (C `void func(void)`).
+
+Ports (v1):
+- `dylib_load`: load a dylib and optionally call a symbol (uses `com.apple.security.cs.disable-library-validation`).
+- `debug_wait`: sleep before sandbox apply for debugger attach (uses `com.apple.security.get-task-allow`).
+- `execmem_probe`: attempt an RWX `mmap` and report success/failure (uses `com.apple.security.cs.allow-unsigned-executable-memory`).
+- `dyld_env`: report expected `DYLD_*` env vars (uses `com.apple.security.cs.allow-dyld-environment-variables`).
+
+Convenience flag (injects instrumentation into the request JSON at runtime):
+
+```sh
+$PW run /path/to/request.json --instrumentation @/path/to/instrumentation.json
+```
+
+Example specimen (full, minimal):
+
+```json
+{
+  "schema_version": 1,
+  "specimen_id": "instrumentation_debug_wait",
+  "policy": {
+    "format": "sbpl",
+    "sbpl_source": "(version 1) (allow default)"
+  },
+  "instrumentation": {
+    "version": 1,
+    "ports": [
+      { "kind": "debug_wait", "sleep_ms": 1 }
+    ]
+  },
+  "probe_plan": []
+}
+```
+
+Explanation: this pauses briefly before sandbox apply; the run JSON includes an
+`instrumentation` report with the port status and `sleep_ms`, and the overall
+run outcome remains `ok`.
+
+Guide (quick start):
+
+1. Pick a port and add it to your specimen or create a small `instrumentation.json`.
+2. Run with `policy-witness run <request.json> --instrumentation @instrumentation.json`.
+3. Inspect `data.runner_result.instrumentation` in the output JSON for per-port status.
+
+Note: `dyld_env` is a check only. To actually set `DYLD_*` variables, use an
+external runner and set launchd `EnvironmentVariables` at install time:
+
+```sh
+$PW runner install --bundle /path/to/PWRunner.xpc --env DYLD_INSERT_LIBRARIES=/path/to/lib.dylib
+```
+
 ## External runner (BYOSig) flow
 
 Use this when you need entitlements that are not in the built-in runner.
@@ -134,6 +212,7 @@ Notes:
 - Use `--allow-adhoc` for local ad-hoc signing.
 - Use `--scope system` if you want a system-wide service (requires admin).
 - Use `--skip-bootstrap` if you will run `launchctl` manually.
+- Use `--env KEY=VALUE` to set launchd `EnvironmentVariables` (for `DYLD_*`).
 
 The install command writes a launchd plist, bootstraps the service, and records
 the runner in the local registry.
@@ -184,6 +263,7 @@ Registry location:
 
 - `--timeout-ms <n>`: runner RPC timeout (default 240000)
 - `--log-last <dur>`: unified log lookback window for deny capture (default 10s)
+- `--instrumentation <json|@path>`: inject instrumentation ports into the request
 
 ## Troubleshooting
 

README.md

@@ -12,6 +12,15 @@ A specimen run spins up a fresh `PWRunner.xpc` process. The runner begins unsand
 
 Collection is made possible by executing each probe as a small, explicit attempt and recording its direct rc plus errno/kr. For each step, the runner also runs `sandbox_check` using the same operation and filter so you can compare the kernel’s prediction to the attempted outcome. When the policy uses deterministic side effects like `send-signal`, the runner installs a handler and records before/after signal counts so denials can be observed without relying on logs. The runner emits a single structured JSON report for the specimen—run metadata and per-step results—and exits immediately after replying. The result is a per-step record that favors witnessed facts over inferred explanations.
 
+## Instrumentation Port (Opt-in)
+
+PolicyWitness includes an optional instrumentation port that exposes the runner’s hardened‑runtime entitlements in a controlled, auditable way: specimens may include an `instrumentation` object with ports executed `pre_sandbox` or `post_sandbox`, and results are reported in the run JSON without changing the run outcome; for quick experimentation you can inject instrumentation at runtime with `policy-witness run <request.json> --instrumentation <json|@path>` and keep existing callers unchanged.
+
+- `dyld_env`: report expected `DYLD_*` env vars (`com.apple.security.cs.allow-dyld-environment-variables`); to set these, use an external runner with `policy-witness runner install --env KEY=VALUE`.
+- `dylib_load`: load a dylib and optionally call a symbol (`com.apple.security.cs.disable-library-validation`).
+- `debug_wait`: pause before sandbox apply for debugger attach (`com.apple.security.get-task-allow`).
+- `execmem_probe`: attempt RWX `mmap` and report success/failure (`com.apple.security.cs.allow-unsigned-executable-memory`).
+
 ## Evidence Model
 
 `Specimens → Runs → Steps → Evidence`

SIGNING.md

@@ -9,12 +9,17 @@ Preferred entrypoint:
 ```sh
 make build
 # or:
+make build YOLO=1
+# or:
 IDENTITY='Developer ID Application: YOUR NAME (TEAMID)' ./build.sh
+# or:
+./build.sh --yolo
 ```
 
 Key requirements:
 
-- `IDENTITY` must be set to a **Developer ID Application** identity present in your keychain.
+- `IDENTITY` must be set to a **Developer ID Application** identity present in your keychain, or
+  pass `--yolo` / `YOLO=1` to auto-select the first matching identity.
 - Xcode Command Line Tools are required (`swiftc` is discovered via `xcrun`).
 
 ## What `build.sh` signs
@@ -38,5 +43,26 @@ These are derived from the **actual signed binaries on disk** (hashes and entitl
 
 ## Notarization (zip artifact)
 
-The build also produces `PolicyWitness.zip` suitable for notarization submission. Notarytool invocation and stapling are intentionally not automated in this repo; keep those steps in your release checklist.
+The build produces `PolicyWitness.zip` suitable for notarization submission. The
+required order is: sign and zip, submit the zip to notarytool, then staple the
+app bundle. This is what Gatekeeper expects.
+
+Preferred entrypoint:
 
+```sh
+make notarize NOTARY_KEYCHAIN_PROFILE=dev-profile
+# or:
+NOTARY_KEYCHAIN_PROFILE=dev-profile make notarize
+# or (auto-select codesign identity):
+make notarize NOTARY_KEYCHAIN_PROFILE=dev-profile YOLO=1
+```
+
+Manual equivalent:
+
+```sh
+xcrun notarytool submit "PolicyWitness.zip" --keychain-profile "dev-profile" --wait
+xcrun stapler staple "PolicyWitness.app"
+xcrun stapler validate -v "PolicyWitness.app"
+spctl -a -vv --type execute "PolicyWitness.app"
+ditto -c -k --sequesterRsrc --keepParent "PolicyWitness.app" "PolicyWitness.zip"
+```

build.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 # Usage:
 #   ./build.sh
 #   IDENTITY='Developer ID Application: ...' ./build.sh
+#   ./build.sh --yolo
 #   PW_INSPECTION=0 IDENTITY='Developer ID Application: ...' ./build.sh
 #
 # Produces:
@@ -35,6 +36,39 @@ SWIFT_MODULE_CACHE="${SWIFT_MODULE_CACHE:-.tmp/swift-module-cache}"
 SWIFT_OPT_LEVEL="${SWIFT_OPT_LEVEL:-}"
 SWIFT_DEBUG_FLAGS="${SWIFT_DEBUG_FLAGS:-}"
 PW_INSPECTION="${PW_INSPECTION:-1}"
+YOLO=0
+
+usage() {
+  cat <<'EOF'
+usage:
+  ./build.sh
+  IDENTITY='Developer ID Application: ...' ./build.sh
+  ./build.sh --yolo
+  PW_INSPECTION=0 IDENTITY='Developer ID Application: ...' ./build.sh
+
+notes:
+  - --yolo selects the first Developer ID Application identity from:
+      security find-identity -v -p codesigning
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --yolo)
+      YOLO=1
+      shift 1
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "ERROR: unknown argument: $1" 1>&2
+      usage 1>&2
+      exit 2
+      ;;
+  esac
+done
 
 if [[ "${PW_INSPECTION}" == "1" ]]; then
   if [[ -z "${SWIFT_OPT_LEVEL}" ]]; then
@@ -56,16 +90,64 @@ fi
 IDENTITY="${IDENTITY:-}"
 
 if [[ -z "${IDENTITY}" ]]; then
-  cat <<'EOF' 1>&2
+  if [[ "${YOLO}" == "1" ]]; then
+    set +e
+    IDENTITY="$(
+      /usr/bin/python3 - <<'PY'
+import re
+import subprocess
+import sys
+
+proc = subprocess.run(
+    ["/usr/bin/security", "find-identity", "-v", "-p", "codesigning"],
+    capture_output=True,
+    text=True,
+)
+if proc.returncode != 0:
+    sys.exit(2)
+
+for line in (proc.stdout or "").splitlines():
+    if "Developer ID Application:" not in line:
+        continue
+    match = re.search(r'"(Developer ID Application: [^"]+)"', line)
+    if match:
+        print(match.group(1))
+        sys.exit(0)
+
+sys.exit(1)
+PY
+    )"
+    IDENTITY_STATUS=$?
+    set -e
+
+    if [[ ${IDENTITY_STATUS} -ne 0 || -z "${IDENTITY}" ]]; then
+      cat <<'EOF' 1>&2
+ERROR: --yolo could not find a Developer ID Application identity.
+
+Run:
+  security find-identity -v -p codesigning
+
+Then set IDENTITY explicitly or install/unlock the identity in your keychain.
+EOF
+      exit 2
+    fi
+
+    echo "==> Using codesign identity (yolo): ${IDENTITY}"
+  else
+    cat <<'EOF' 1>&2
 ERROR: IDENTITY is not set.
 
 Set it to your Developer ID Application identity string, for example:
   IDENTITY='Developer ID Application: Adam Hyland (42D369QV8E)' ./build.sh
 
+Or re-run with --yolo to auto-select the first Developer ID Application identity:
+  ./build.sh --yolo
+
 You can find valid identities via:
   security find-identity -v -p codesigning
 EOF
-  exit 2
+    exit 2
+  fi
 fi
 
 if ! /usr/bin/security find-identity -v -p codesigning 2>/dev/null | /usr/bin/grep -Fq "\"${IDENTITY}\""; then
@@ -297,8 +379,12 @@ echo "  - ${SANDBOX_LOG_OBSERVER_BIN}"
 echo
 echo "Next (notarize with your saved profile):"
 cat <<EOF
+  make notarize NOTARY_KEYCHAIN_PROFILE=dev-profile
+  # add YOLO=1 to auto-select a codesign identity
+  # or manually:
   xcrun notarytool submit "${ZIP_NAME}" --keychain-profile "dev-profile" --wait
   xcrun stapler staple "${APP_BUNDLE}"
   xcrun stapler validate -v "${APP_BUNDLE}"
   spctl -a -vv --type execute "${APP_BUNDLE}"
+  /usr/bin/ditto -c -k --sequesterRsrc --keepParent "${APP_BUNDLE}" "${ZIP_NAME}"
 EOF

controller/README.md

@@ -24,7 +24,7 @@ Standalone helper tools (embedded into the `.app`):
 The launcher intentionally exposes a minimal surface:
 
 ```text
-policy-witness run <request.json> [--timeout-ms <n>] [--log-last <dur>]
+policy-witness run <request.json> [--timeout-ms <n>] [--log-last <dur>] [--instrumentation <json|@path>]
 policy-witness runner <command> [options]
 ```
 
@@ -39,6 +39,7 @@ Runs a **single runner evaluation** against the selected runner service:
 - Captures supporting evidence (best-effort) using `sandbox-log-observer` and attaches it to the output.
 - Prints a single JSON envelope to stdout (no output directories; stdout is the artifact).
 - Emits `data.runner_provenance` and `data.app_provenance` to keep results auditable.
+- If `--instrumentation` is provided, the controller injects the instrumentation object into the request JSON (without modifying the original file).
 
 Exit codes:
 
@@ -79,6 +80,7 @@ These commands manage external runners signed with user entitlements:
 policy-witness runner install --bundle <path> [--service-name <name>] [--scope user|system]
                              [--identity <codesign-id>] [--entitlements <plist>]
                              [--executable <path>] [--bundle-id <id>] [--allow-adhoc]
+                             [--env KEY=VALUE]
                              [--skip-bootstrap]
 policy-witness runner list
 policy-witness runner status --id <runner-id> | --service-name <name>