scripts/post_sdp.py
"""One local build/deploy/capture/report/tutorial command after owner SDP setup.
Uses documented QNX GDB target/upload/download, never SSH or credential files.
The owner starts a private development VM with qconn/pdebug beforehand.
--dry-run creates a fake SDP and launches fake tools, with no target connection.
"""
import argparse
from datetime import datetime, timezone
import hashlib
import ipaddress
import json
import os
from pathlib import Path
import re
import shutil
import subprocess
import sys
import uuid
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT))
from scripts import build_qnx
from scripts.check_evidence import check
from waitlens.cli import load_snapshot
from waitlens.core import compare
from waitlens.report import render
FILES = ['waitlens_probe', 'platform.txt', 'probe.log', 'send.txt', 'reply.txt', 'capture-complete.txt']
SLOTS = {'SETUP', 'BUILD', 'PLATFORM', 'PROBE', 'SEND', 'REPLY', 'CHECK', 'COMPARISON'}
def write(path, content):
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(content, encoding='utf-8')
def json_write(path, value):
write(path, json.dumps(value, indent=2, ensure_ascii=True) + '\n')
def endpoint(value):
try:
host, port = value.split(':')
ip = ipaddress.IPv4Address(host)
if not (ip.is_private or ip.is_loopback) or ip.is_unspecified or ip.is_multicast:
raise ValueError()
if not port.isdecimal() or not 1 <= int(port) <= 65535:
raise ValueError()
except (ValueError, ipaddress.AddressValueError):
raise argparse.ArgumentTypeError('use the private development VM IPv4:port, for example 192.168.56.101:8000')
return f'{ip}:{int(port)}'
def gdb_script(address, remote, nonce, target_shell):
# All interpolated values have a fixed alphabet; captured text is never a command.
commands = ['set confirm off', 'set pagination off', 'set auto-load off',
'set nto-timeout 30', 'target qnx ' + address, 'set nto-inherit-env 1',
'download ' + target_shell + ' target-shell', 'file target-shell',
'set nto-executable ' + target_shell,
'set args -c "umask 077; mkdir ' + remote + '"', 'run',
'upload waitlens_probe ' + remote + '/waitlens_probe',
'upload capture.sh ' + remote + '/capture.sh',
'set nto-executable ' + target_shell, 'set nto-cwd ' + remote,
'set args -c "chmod 700 waitlens_probe && sh capture.sh ' + nonce + '"', 'run']
commands += [f'download {remote}/{name} capture/{name}' for name in FILES]
return '\n'.join(commands + ['disconnect', 'quit']) + '\n'
def fill_tutorial(template, values, *, synthetic=False):
pattern = re.compile(r'\[\[REAL OUTPUT REQUIRED: ([A-Z]+)\]\]')
found = set(pattern.findall(template))
if found != SLOTS or set(values) != SLOTS:
raise ValueError('tutorial placeholder contract changed; update the filler before running')
def replace(match):
content = values[match[1]]
# Keep captured Markdown inert, even if it contains fence-like strings.
fence = '`' * max(3, max((len(s) for s in re.findall(r'`+', content)), default=0) + 1)
label = 'SYNTHETIC CONTROL-FLOW PREVIEW; NOT QNX OUTPUT\n' if synthetic else ''
return fence + 'text\n' + label + content.rstrip() + '\n' + fence
result = pattern.sub(replace, template)
if '[[REAL OUTPUT REQUIRED:' in result:
raise ValueError('unresolved tutorial placeholder; no completed tutorial written')
if synthetic:
result = '# SYNTHETIC PREVIEW — NOT FOR PUBLICATION\n\n' + result
return result
def run_pipeline(args):
nonce = uuid.uuid4().hex
kind = 'dry-run' if args.dry_run else 'run'
stamp = datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')
base = ROOT / ('build' if args.dry_run else 'evidence/local')
run_dir = base / f'{kind}-{stamp}-{nonce[:8]}'
run_dir.mkdir(parents=True)
state = {'schema_version': 1, 'status': 'started', 'evidence_mode': 'synthetic' if args.dry_run else 'target-capture',
'runtime_verified': False, 'submission_ready': False, 'completed_stages': []}
json_write(run_dir / 'pipeline.json', state)
print('Run directory:', run_dir)
def stage(name):
state['completed_stages'].append(name)
json_write(run_dir / 'pipeline.json', state)
print('Completed:', name, flush=True)
try:
address = args.target
setup = args.setup_note
if args.dry_run:
from scripts.fake_sdp import create
qcc, gdb = create(run_dir / 'fake-sdp')
address, setup = '127.0.0.1:8000', 'SYNTHETIC fake SDP/VM; no QNX tools or OS executed.'
else:
host = os.environ.get('QNX_HOST')
if not host:
raise ValueError('QNX_HOST is unset; owner must initialize the licensed SDP environment first')
suffix = '.exe' if os.name == 'nt' else ''
qcc = Path(host) / ('usr/bin/qcc' + suffix)
gdb = Path(host) / ('usr/bin/ntox86_64-gdb' + suffix)
if not qcc.is_file() or not gdb.is_file():
raise ValueError('SDP qcc/ntox86_64-gdb missing; install the x86-64 tools personally; no download attempted')
stage('preflight')
def invoke(command, **kw):
if args.dry_run:
command = [sys.executable] + command
return subprocess.run(command, **kw)
build = run_dir / 'build'
if build_qnx.main(['--qcc', str(qcc), '--out-dir', str(build)], runner=invoke):
raise ValueError('qcc build failed; inspect compiler diagnostics, then rerun after correction')
receipt_path = build / 'build-receipt.json'
receipt = json.loads(receipt_path.read_text(encoding='utf-8'))
if args.dry_run:
receipt['evidence_mode'] = 'synthetic'
receipt['toolchain'] = 'SYNTHETIC fake SDP, not QNX'
json_write(receipt_path, receipt)
versions = invoke([str(qcc), '--version'], capture_output=True, timeout=30, check=False)
if versions.returncode:
raise ValueError('qcc --version failed; owner must check installed toolchain/licence')
version_text = (versions.stdout + versions.stderr).decode('utf-8', errors='replace')
if '\ufffd' in version_text:
raise ValueError('compiler version output is not UTF-8; preserve original output and resolve encoding')
write(run_dir / 'toolchain.txt', setup + '\n' + version_text)
stage('qcc-build')
shutil.copyfile(build / 'waitlens_probe', run_dir / 'waitlens_probe')
shutil.copyfile(ROOT / 'target/capture.sh', run_dir / 'capture.sh')
capture = run_dir / 'capture'
capture.mkdir()
remote = '/tmp/waitlens-' + nonce
script = gdb_script(address, remote, nonce, args.target_shell)
write(run_dir / 'transfer.gdb', script)
# -nx/-nh and early auto-load disabling avoid saved debugger init files.
# No host credential variables are inherited by the debugger or target.
env = {key: os.environ[key] for key in ['SystemRoot', 'WINDIR', 'COMSPEC', 'QNX_HOST', 'QNX_TARGET'] if key in os.environ}
env.update(TEMP=str(run_dir), TMP=str(run_dir), PATH=str(qcc.parent) + os.pathsep + os.defpath)
try:
process = invoke([str(gdb), '--batch', '-nx', '-nh', '-iex', 'set auto-load off', '-x', 'transfer.gdb'],
cwd=run_dir, env=env, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
stderr=subprocess.STDOUT, timeout=180, check=False)
except subprocess.TimeoutExpired as error:
write(run_dir / 'transport.log', (error.stdout or b'').decode('utf-8', errors='backslashreplace'))
raise
write(run_dir / 'transport.log', process.stdout.decode('utf-8', errors='backslashreplace'))
if process.returncode:
raise ValueError('GDB deploy/capture failed; inspect local transport.log. Confirm private VM, qconn/pdebug, devc-pty and shell path; no credential fallback')
if (capture / 'capture-complete.txt').read_text(encoding='utf-8').strip() != nonce:
raise ValueError('target completion marker missing or stale; rerun in a new capture directory')
if args.dry_run:
write(capture / 'SYNTHETIC.txt', 'Fake tool output for control-flow testing only.\n')
stage('deploy-capture-download')
evidence = check(build, capture, allow_synthetic=args.dry_run)
json_write(run_dir / 'check.json', evidence)
stage('evidence-check')
report = compare(load_snapshot(capture / 'send.txt', 'synthetic' if args.dry_run else 'target-capture'),
load_snapshot(capture / 'reply.txt', 'synthetic' if args.dry_run else 'target-capture'))
json_write(run_dir / 'comparison.json', report)
write(run_dir / 'comparison.html', render(report))
stage('waitlens-comparison')
values = {'SETUP': (run_dir / 'toolchain.txt').read_text(encoding='utf-8'),
'BUILD': json.dumps(receipt, indent=2), 'CHECK': json.dumps(evidence, indent=2),
'COMPARISON': json.dumps(report['changes'], indent=2)}
for key, filename in [('PLATFORM', 'platform.txt'), ('PROBE', 'probe.log'), ('SEND', 'send.txt'), ('REPLY', 'reply.txt')]:
values[key] = (capture / filename).read_text(encoding='utf-8')
template = (ROOT / 'docs/tutorial-draft.md').read_text(encoding='utf-8')
tutorial = fill_tutorial(template, values, synthetic=args.dry_run)
if not args.dry_run:
tutorial = tutorial.replace('**Status: draft awaiting real SDP/target output.**',
'**Status: local capture outputs inserted; owner review and learner reproduction required before publication.**')
write(run_dir / ('tutorial-preview.md' if args.dry_run else 'tutorial-filled.md'), tutorial)
manifest = {}
for path in [receipt_path, run_dir / 'toolchain.txt', run_dir / 'transfer.gdb', run_dir / 'capture.sh', run_dir / 'target-shell',
ROOT / 'target/waitlens_probe.c', ROOT / 'docs/tutorial-draft.md'] + [capture / name for name in FILES]:
label = str(path.relative_to(run_dir)) if path.is_relative_to(run_dir) else str(path.relative_to(ROOT))
manifest[label.replace('\\', '/')] = hashlib.sha256(path.read_bytes()).hexdigest()
json_write(run_dir / 'manifest.json', manifest)
stage('tutorial-fill')
state.update(status='synthetic-control-flow-only' if args.dry_run else 'consistent-local-evidence',
target_capture_checked=not args.dry_run)
json_write(run_dir / 'pipeline.json', state)
print('Result:', state['status'])
print('Report:', run_dir / 'comparison.html')
print('Tutorial:', run_dir / ('tutorial-preview.md' if args.dry_run else 'tutorial-filled.md'))
return 0
except (OSError, ValueError, subprocess.TimeoutExpired) as error:
state.update(status='failed', error=str(error))
json_write(run_dir / 'pipeline.json', state)
print('Post-SDP stopped: ' + str(error), file=sys.stderr)
print('Artifacts retained for inspection. No tutorial completion or submission status was claimed.', file=sys.stderr)
return 2
def main(argv=None):
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--target', type=endpoint, help='Owner-provided private development VM IPv4:port')
parser.add_argument('--setup-note', help='Reviewed SDP update and VM type/version, no credentials')
parser.add_argument('--target-shell', default='/bin/sh', help='Absolute target sh path (default /bin/sh)')
parser.add_argument('--dry-run', action='store_true', help='Execute fake SDP tools locally, never connect to a target')
args = parser.parse_args(argv)
if args.dry_run and (args.target or args.setup_note):
parser.error('--dry-run must not be combined with real target/setup options')
if not args.dry_run and (not args.target or not args.setup_note):
parser.error('real execution needs --target and --setup-note after owner SDP/VM setup')
if not re.fullmatch(r'/[A-Za-z0-9_/.-]+', args.target_shell) or '..' in args.target_shell.split('/'):
parser.error('--target-shell must be a plain absolute target executable path')
return run_pipeline(args)
if __name__ == '__main__':
raise SystemExit(main())