Complete bounded Windows maintenance setup and audited development teardown

This commit is contained in:
2026-11-17 17:10:16 +01:00
parent c0b4b27a3e
commit 82fec967ad
13 changed files with 1148 additions and 9 deletions
+250
View File
@@ -0,0 +1,250 @@
"""Detach one closed development maintenance window from its signed sync head."""
import fcntl
import hashlib
import http.client
import json
import os
from pathlib import Path
import re
import shlex
import socket
import ssl
import stat
import subprocess
from datetime import datetime, timezone
import windows_update_scope as scope
BASE = Path('/opt/rust-discovery/devstate')
PRINCIPAL = 'simulated-testprincipal-a'
SCRIPTS = {
'567d7343eecee57a9232b3549ef7c504260cb26da46436ede61e2f354ff3c874': 30,
'0fa5f513a06b6cf902a3f9ac1989987642c181eedd6c305b3912771bd10f2ebf': 3600,
}
PSQL = ['docker', 'exec', '-i', 'rust-discovery-server-postgres-1', 'psql',
'-XqAt', '-v', 'ON_ERROR_STOP=1', '-U', 'postgres', '-d', 'rmm']
require = scope.require
def sql(statement):
result = subprocess.check_output(PSQL, input=statement.encode(), timeout=15)
return json.loads(result)
def private_read(path, owner=0):
info = path.lstat()
require(stat.S_ISREG(info.st_mode) and stat.S_IMODE(info.st_mode) == 0o600
and info.st_uid == owner and info.st_nlink == 1 and info.st_size <= 512 * 1024,
'Unexpected maintenance record or access mode')
return path.read_bytes()
def public_key():
"""Read the server's own public signing key from its authenticated management API."""
tls = ssl.create_default_context(cafile=str(BASE / 'pki/ca.pem'))
class Loopback(http.client.HTTPSConnection):
def connect(self):
self.sock = self._context.wrap_socket(socket.create_connection(('127.0.0.1', 18443), 5),
server_hostname='rmm-dev.internal')
conn = Loopback('rmm-dev.internal', timeout=5, context=tls)
try:
token = (BASE / 'operator-a.token').read_text().strip()
conn.request('GET', '/api/v1/job-signing-key', headers={'Authorization': 'Bearer ' + token})
reply = conn.getresponse()
require(reply.status == 200, 'Cannot verify the original signed decision against this server')
key = json.loads(reply.read(4097))
raw = bytes.fromhex(key['public_key_hex'])
require(key['algorithm'] == 'Ed25519' and len(raw) == 32
and key['key_id'] == hashlib.sha256(raw).hexdigest(), 'Invalid public signing key')
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
return key['key_id'], Ed25519PublicKey.from_public_bytes(raw)
finally:
conn.close()
def observation(ids, opened, cutoff):
"""Only canonical UUIDs and normalized datetimes reach the query."""
tenant, asset, agent = (ids[k] for k in ('tenant_id', 'asset_id', 'agent_id'))
return f"""
SELECT jsonb_build_object(
'open_jobs',(SELECT count(*) FROM jobs j WHERE j.tenant_id=i.tenant_id AND j.agent_id=i.agent_id
AND j.state NOT IN ('succeeded','failed','cancelled','expired','closed_unknown')),
'journal_id',s.journal_id,'checkpoint',s.checkpoint,'decision_id',s.decision_id,
'helper_id',s.helper_journal_id,'helper_checkpoint',s.helper_checkpoint,
'signed',encode(c.payload,'hex'),'signature',encode(c.signature,'hex'),
'jobs',COALESCE((SELECT jsonb_agg(jsonb_build_object(
'job',j.job_id,'attempt',j.attempt_id,'grant',g.grant_id,'state',j.state,
'payload_sha256',j.payload_hash,'bytes_hash',encode(sha256(j.payload),'hex'),
'payload_binding',p-'action','action',p->'action',
'principal',z.principal,'window_approval',z.created_at BETWEEN '{opened}' AND '{cutoff}',
'dev',z.testsimulation AND z.approval_origin='dev_test_browser_simulation',
'plan_hash',z.plan_hash,'authorization_id',z.authorization_id,
'in_window',g.created_at BETWEEN '{opened}' AND '{cutoff}',
'reserved',j.start_reserved,'result_grant',j.result->>'grant_id','revision',j.revision)
ORDER BY j.job_id)
FROM jobs j JOIN authorizations z USING(tenant_id,operation_id)
CROSS JOIN LATERAL (SELECT convert_from(j.payload,'UTF8')::jsonb AS p) jp
LEFT JOIN execution_permits g USING(tenant_id,job_id,attempt_id)
WHERE j.tenant_id=i.tenant_id AND j.agent_id=i.agent_id AND p->>'execution_identity'='system'
AND (z.created_at BETWEEN '{opened}' AND '{cutoff}' OR g.created_at BETWEEN '{opened}' AND '{cutoff}')),
'[]'::jsonb)) AS observation
FROM agent_installations i JOIN agent_sync_state s USING(tenant_id,agent_id)
JOIN sync_checkpoints c USING(tenant_id,agent_id,decision_id)
WHERE i.tenant_id='{tenant}' AND i.asset_id='{asset}' AND i.agent_id='{agent}' AND i.revoked_at IS NULL
AND i.assignment_version=1 AND i.enrollment_generation=1
AND NOT i.sync_recovery_required AND NOT i.sequence_regressed AND NOT i.restore_blocked
"""
def verify(snapshot, ids):
require(snapshot['open_jobs'] == 0, 'Device has open or uncertain jobs')
require(snapshot['helper_id'] and snapshot['helper_checkpoint'] > 0, 'Expected bound helper journal')
raw = bytes.fromhex(snapshot['signed'])
key_id, public = public_key()
public.verify(bytes.fromhex(snapshot['signature']), raw)
d = json.loads(raw)
fields = ('journal_id', 'checkpoint', 'decision_id', 'helper_checkpoint')
require(d['domain'] == 'rmm.reconciliation-decision' and d['schema_version'] == 1
and d['key_id'] == key_id and all(d[k] == ids[k] for k in ('tenant_id','asset_id','agent_id'))
and d['enrollment_generation'] == d['assignment_version'] == 1
and d['ready'] is True and d['helper_ready'] is True and d['reason'] == 'CONSISTENT'
and d['helper_journal_id'] == snapshot['helper_id']
and all(d[k] == snapshot[k] for k in fields), 'The signed helper decision does not match the current head')
outcomes = {a['job_id']: a for a in d['attempts'] if a['execution_identity'] == 'system'}
require(len(outcomes) == sum(a['execution_identity'] == 'system' for a in d['attempts']),
'Duplicate SYSTEM decision')
attempts = []
for j in snapshot['jobs']:
require(j['grant'], 'A grantless SYSTEM job requires separate reconciliation')
require(j['state'] in ('succeeded','failed'), 'A non-definitive SYSTEM result requires separate reconciliation')
p = j['payload_binding']
act = dict(j['action'])
script = hashlib.sha256(act.pop('script_utf8').encode()).hexdigest()
require(script in SCRIPTS and 0 < p['max_runtime_seconds'] <= SCRIPTS[script]
and act == {'action':'run_script', 'arguments':[], 'expected_stdout':None, 'interpreter':'powershell',
'privileged_script_profile':'full_maintenance_v1','windows_execution_profile':'powershell_51_remote_signed'},
'Job is outside the two maintenance-window scripts')
a = outcomes.pop(j['job'], {})
require(j['dev'] and j['principal'] == PRINCIPAL and j['window_approval'] and j['in_window']
and j['reserved'] and j['result_grant'] == j['grant'] and j['bytes_hash'] == j['payload_sha256']
and all(p[k] == ids[k] for k in ('tenant_id','asset_id','agent_id'))
and p['enrollment_generation'] == p['assignment_version'] == 1
and p['job_id'] == j['job'] and p['attempt_id'] == j['attempt']
and a.get('unlock') is True and a['reason'] == 'DEFINITIVE_OUTCOME_RECONCILED'
and a['attempt_id'] == j['attempt'] and a['grant_id'] == j['grant']
and a['outcome_state'] == j['state'] and a['revision'] == j['revision']
and a['job_payload_hash'] == j['payload_sha256'] and a['authorization_id'] == j['authorization_id']
and a['plan_hash'] == j['plan_hash'] and re.fullmatch('[0-9a-f]{64}',a['outcome_sha256'] or ''),
'Missing signed evidence of exact consumed grant and terminal result')
attempts.append({**{k:j[k] for k in ('job','attempt','grant','state','payload_sha256')},
'outcome_sha256':a['outcome_sha256']})
require(not outcomes, 'The helper still owns SYSTEM attempts outside this window')
return {**ids, **{k:snapshot[k] for k in (*fields,'helper_id')}, 'attempts':attempts}
def server(action, data):
require(action in ('witness','detach'), 'Only witness and detach are supported')
ids = {k:scope.identifier(data[k]) for k in ('case_id','tenant_id','asset_id','agent_id')}
path = scope.policy_location()
case = path.parent.parent.parent / ('update-window-' + ids['case_id'])
lockfd = os.open(BASE / '.windows-system-scope.lock', os.O_RDWR | os.O_NOFOLLOW)
with os.fdopen(lockfd, 'rb') as lock:
fcntl.flock(lock, fcntl.LOCK_EX)
current = private_read(path, 10001)
current_policy = json.loads(current)
require(current_policy['profile'] == 'development' and
(not current_policy['scopes'] or scope.stamp(current_policy['expires_at']) <= scope.utc()),
'Central development policy must be closed on API and gateway')
window = case / 'window.json'
if case.exists():
mode = case.lstat()
require(case.resolve() == case and stat.S_ISDIR(mode.st_mode) and mode.st_uid == 0
and stat.S_IMODE(mode.st_mode) == 0o700, 'Unsafe development window directory')
if not window.exists():
# Even a failed opening can already have registered a real helper journal.
row = sql(f"""SELECT json_build_object('empty',EXISTS (
SELECT 1 FROM agent_installations i LEFT JOIN agent_sync_state s USING(tenant_id,agent_id)
WHERE i.tenant_id='{ids['tenant_id']}' AND i.agent_id='{ids['agent_id']}' AND i.asset_id='{ids['asset_id']}'
AND i.revoked_at IS NULL AND s.helper_journal_id IS NULL AND coalesce(s.helper_checkpoint,0)=0
AND NOT EXISTS (SELECT 1 FROM jobs j WHERE j.tenant_id=i.tenant_id AND j.agent_id=i.agent_id AND
(j.state NOT IN ('succeeded','failed','cancelled','expired','closed_unknown')
OR convert_from(j.payload,'UTF8')::jsonb->>'execution_identity'='system'))))""")
require(row['empty'] and action == 'witness', 'A helper or SYSTEM history exists without an opened scope')
return None
policy = json.loads(private_read(window))
require(private_read(case/'closed') == b'closed\n' and private_read(case/'original.json') == current,
'Expected this closed scope and its original policy')
only, = policy['scopes']
hashes = ('helper_binary_sha256','helper_policy_sha256')
expected_scope = {k:ids[k] for k in ('tenant_id','agent_id','asset_id')}
expected_scope.update(acceptance_evidence_id=ids['case_id'], principals=[PRINCIPAL], allowed_services=[],
enrollment_generation=1, assignment_version=1, max_runtime_seconds=30,
windows_update_max_runtime_seconds=3600)
for k in hashes:
require(re.fullmatch('[a-f0-9]{64}',only[k]) and data.get(k,only[k]) == only[k], 'Helper pin differs')
expected_scope[k] = only[k]
require(policy['schema_version'] == 3 and policy['profile'] == 'development' and only == expected_scope,
'Case identity, privileges or original policy differ')
opened = datetime.fromtimestamp(window.stat().st_mtime, timezone.utc)
cutoff = min(scope.stamp(policy['expires_at']), datetime.fromtimestamp((case/'closed').stat().st_mtime,timezone.utc))
require(opened <= cutoff, 'Invalid maintenance horizon')
query = observation(ids,opened.isoformat(),cutoff.isoformat())
record = sql(query)
require(record['open_jobs'] == 0, 'Open jobs require separate reconciliation')
saved = case/'detach-intent.json'
done = case/'detached.json'
receipt = json.loads(private_read(saved)) if saved.exists() else None
if done.exists():
require(receipt and json.loads(private_read(done)) == receipt, 'Completion receipt differs from detach intent')
return receipt
if record['helper_id'] is None:
require(receipt and receipt['journal_id'] == record['journal_id'] and record['helper_checkpoint'] == 0,
'Missing evidence of the original detach transaction')
if action == 'detach':
scope.atomic(done,scope.encode(receipt))
return receipt
witness = verify(record,ids)
require(receipt in (None,witness) and data.get('witness',witness) == witness, 'Device or witness changed')
if action == 'witness':
return witness
if receipt is None:
scope.atomic(saved,scope.encode(witness))
# Fence a concurrent signed sync (same lock order as the gateway). The server-owned
# approved jobs, outcomes and signed decisions remain immutable throughout detachment.
# PostgreSQL jsonb canonical ordering differs from Python: bind our checked snapshot
# back as JSONB and compare directly under lock, including jobs, grants and head.
observed_hex = scope.encode(record).hex()
statements = f"""BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
SET LOCAL lock_timeout='5s'; SET LOCAL statement_timeout='10s';
DO $$ BEGIN PERFORM 1 FROM agent_installations WHERE tenant_id='{ids['tenant_id']}' AND agent_id='{ids['agent_id']}' FOR UPDATE; END $$;
WITH checked AS ({query}), changed AS (
UPDATE agent_sync_state s SET helper_journal_id=NULL,helper_checkpoint=0
FROM checked WHERE s.tenant_id='{ids['tenant_id']}' AND s.agent_id='{ids['agent_id']}'
AND s.journal_id='{witness['journal_id']}' AND s.decision_id='{witness['decision_id']}'
AND s.checkpoint={witness['checkpoint']} AND s.helper_journal_id='{witness['helper_id']}'
AND s.helper_checkpoint={witness['helper_checkpoint']}
AND checked.observation = convert_from(decode('{observed_hex}','hex'),'UTF8')::jsonb
RETURNING 1)
SELECT to_json(count(*)) FROM changed;
COMMIT;"""
require(sql(statements) == 1, 'Concurrent job or sync transition. Inspect the existing intent before retrying')
scope.atomic(done,scope.encode(witness))
return witness
def remote_server(action, data):
"""Run only the two fixed modules over the existing pinned server SSH transport."""
import dev_stage
modules = [Path(scope.__file__).read_text(), Path(__file__).read_text()]
payload = ('import types,sys,json\n'
'scope=types.ModuleType("windows_update_scope");sys.modules[scope.__name__]=scope\n'
f'exec({modules[0]!r},scope.__dict__)\n'
'detach=types.ModuleType("windows_update_detach")\n'
f'exec({modules[1]!r},detach.__dict__)\n'
f'print(json.dumps(detach.server({action!r},json.loads({scope.encode(data)!r}))))\n')
command = shlex.join(['python3','-I','-'])
return json.loads(subprocess.check_output([*dev_stage.ssh_prefix('server'),command],
input=payload.encode(),timeout=35))
+336
View File
@@ -0,0 +1,336 @@
#!/usr/bin/env python3
"""Open and revoke a device-bound development window for the built-in Windows Update template."""
import argparse
import base64
from datetime import datetime, timedelta, timezone
import fcntl
import gzip
import json
import os
from pathlib import Path
import re
import shlex
import stat
import subprocess
import sys
import tempfile
import time
import uuid
def require(ok, message):
if not ok:
raise ValueError(message)
def identifier(value):
raw = str(value)
parsed = uuid.UUID(raw)
require(parsed.int and str(parsed) == raw, 'A canonical, nonempty UUID is required')
return raw
def utc():
return datetime.now(timezone.utc)
def stamp(value):
result = datetime.fromisoformat(value.replace('Z', '+00:00'))
require(result.tzinfo is not None, 'Timestamp lacks timezone')
return result
def encode(value):
return json.dumps(value, separators=(',', ':'), sort_keys=True).encode()
def atomic(path, data, owner=None):
with tempfile.NamedTemporaryFile(dir=path.parent, delete=False) as handle:
temp = Path(handle.name)
try:
if owner is not None:
os.fchown(handle.fileno(), *owner)
os.fchmod(handle.fileno(), 0o600)
handle.write(data)
handle.flush()
os.fsync(handle.fileno())
os.replace(temp, path)
directory = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY)
try:
os.fsync(directory)
finally:
os.close(directory)
finally:
temp.unlink(missing_ok=True)
def read_registry(data):
tenant, asset, agent = [identifier(data[k]) for k in ('tenant_id', 'asset_id', 'agent_id')]
# Each interpolated value is a canonical UUID; this invocation cannot mutate Postgres.
sql = f"""BEGIN READ ONLY;
SELECT json_build_object('install',(SELECT json_build_object(
'contact',last_contact_at,'ready',sync_ready AND NOT restore_blocked,'helper_ready',helper_sync_ready,
'fresh',last_authenticated_at > now() - interval '2 minutes'
AND certificate_sha256=last_authenticated_certificate_sha256 AND last_contact_at > now() - interval '2 minutes',
'enrollment_generation',enrollment_generation,'assignment_version',assignment_version,'capabilities',capabilities)
FROM agent_installations WHERE tenant_id='{tenant}' AND asset_id='{asset}' AND agent_id='{agent}' AND revoked_at IS NULL),
'open_jobs',(SELECT count(*) FROM jobs WHERE tenant_id='{tenant}' AND agent_id='{agent}'
AND state NOT IN ('succeeded','failed','cancelled','expired','closed_unknown')),
'principal_authorized',EXISTS (SELECT 1 FROM memberships WHERE tenant_id='{tenant}' AND principal='simulated-testprincipal-a'
AND revoked_at IS NULL AND kind='test_human' AND 'scripts:execute'=ANY(permissions) AND 'system:execute'=ANY(permissions)));
COMMIT;"""
raw = subprocess.check_output(['docker', 'exec', '-i', 'rust-discovery-server-postgres-1',
'psql', '-XqAt', '-v', 'ON_ERROR_STOP=1', '-U', 'postgres', '-d', 'rmm'], input=sql.encode())
return json.loads(raw)
def policy_location():
base = Path('/opt/rust-discovery/devstate/windows-system-policy')
mounts = []
for role in ('api', 'gateway'):
container = f'rust-discovery-server-{role}-1'
settings = subprocess.check_output(['docker','exec', container, 'printenv','RMM_PROFILE',
'RMM_DEV_SYSTEM_ENABLED','RMM_DEV_SYSTEM_POLICY_FILE'], text=True).splitlines()
require(settings == ['development','true','/system-policy/policy.json'], 'Development policy unavailable on '+role)
bind = json.loads(subprocess.check_output(['docker','inspect','--format','{{json .Mounts}}', container]))
dirs = [Path(m['Source']) for m in bind if m['Destination']=='/system-policy' and m['Type']=='bind' and not m['RW']]
require(len(dirs)==1 and dirs[0].parent.parent==base and dirs[0].name=='mounted'
and dirs[0].resolve()==dirs[0], 'Unexpected or writable SYSTEM policy mount')
mounts.append(dirs[0])
require(mounts[0]==mounts[1], 'API and gateway must use the same directory')
return mounts[0]/'policy.json'
def usable(observation):
install = observation.get('install') or {}
return (observation['open_jobs']==0 and observation['principal_authorized']
and install.get('fresh') and install['ready']
and install['enrollment_generation']==install['assignment_version']==1)
def scoped(data, observation):
if not usable(observation) or not observation['install']['helper_ready']:
return False
caps=set(observation['install']['capabilities'])
needed={'windows.base/1','rmm.sync.v1','helper.system.v1','system:run_script','script.windows_update.long/1',
'helper.policy.sha256:'+data['helper_policy_sha256'], 'helper.binary.sha256:'+data['helper_binary_sha256'],
'run_script','script.powershell/1','script.powershell.process_remote_signed/1'}
return needed<=caps and not any(c in caps for c in
('script.full_maintenance/1','system:set_service_state','system:ensure_package','system:reboot','linux.base/1'))
def server(action, data):
if action=='read':
return read_registry(data)
case = identifier(data['case_id'])
path = policy_location()
if action=='preflight':
current=json.loads(path.read_bytes())
require(current['profile']=='development' and (stamp(current['expires_at'])<=utc() or not current['scopes']),
'Another live maintenance window is active')
return {'dev_scope_available':True}
history = path.parent.parent.parent/('update-window-'+case)
lockpath = Path('/opt/rust-discovery/devstate/.windows-system-scope.lock')
fd = os.open(lockpath, os.O_RDWR|os.O_CREAT|os.O_NOFOLLOW, 0o600)
with os.fdopen(fd,'rb') as mutex:
fcntl.flock(mutex, fcntl.LOCK_EX)
st=path.lstat()
require(stat.S_ISREG(st.st_mode) and st.st_uid==st.st_gid==10001 and stat.S_IMODE(st.st_mode)==0o600
and st.st_size<=65536 and st.st_nlink==1, 'Unexpected policy file or ownership')
current=path.read_bytes()
if action=='revoke':
history.mkdir(mode=0o700,exist_ok=True)
if history.exists():
original, window=history/'original.json', history/'window.json'
# The candidate is recorded durably before replacing the live policy.
if not window.exists():
require(not original.exists() or original.read_bytes()==current,'Partial opening has a different live policy')
if not (history/'closed').exists():
atomic(history/'closed',b'closed\n')
return {'central_scope_closed':True}
saved=original.read_bytes()
candidate=window.read_bytes()
require(current in (candidate,saved), 'Central policy changed since opening. Reconcile before replacing it.')
if current!=saved:
atomic(path,saved,(st.st_uid,st.st_gid))
if not (history/'closed').exists():
atomic(history/'closed',b'closed\n')
return {'central_scope_closed':True}
require(action=='enable', 'Unsupported central operation')
for key in ('helper_binary_sha256','helper_policy_sha256'):
require(re.fullmatch('[a-f0-9]{64}',data[key]),'Invalid helper hash')
require(scoped(data, read_registry(data)), 'Device has no current authenticated narrow helper capabilities')
expires=stamp(data['expires_at'])
require(utc()<expires<=utc()+timedelta(minutes=120), 'Window expired or exceeds 120 minutes')
if history.exists():
require(not (history/'closed').exists() and (history/'original.json').is_file()
and (history/'window.json').is_file(), 'Case is closed or incomplete')
expected=(history/'window.json').read_bytes()
require(current in (expected,(history/'original.json').read_bytes()), 'Central policy changed while opening')
require(json.loads(expected)['expires_at']==data['expires_at'], 'Cannot extend an existing window')
else:
old=json.loads(current)
require(old['profile']=='development' and (stamp(old['expires_at'])<=utc() or not old['scopes']),
'Another live maintenance window is active')
scope={k:identifier(data[k]) for k in ('tenant_id','asset_id','agent_id')}
scope.update(enrollment_generation=1,assignment_version=1,principals=['simulated-testprincipal-a'],
acceptance_evidence_id=case,allowed_services=[],max_runtime_seconds=30,
windows_update_max_runtime_seconds=3600,
**{k:data[k] for k in ('helper_binary_sha256','helper_policy_sha256')})
expected=encode(dict(schema_version=3,profile='development',expires_at=data['expires_at'],scopes=[scope]))
history.mkdir(mode=0o700)
atomic(history/'original.json',current)
atomic(history/'window.json',expected)
atomic(path,expected,(st.st_uid,st.st_gid))
return {'central_scope_open':True,'expires_at':data['expires_at']}
def remote_server(action, data):
from dev_stage import ssh_prefix
# Only public device bindings and case data travel as arguments.
cmd=shlex.join(['python3','-I','-','--on-server',action,base64.b64encode(encode(data)).decode()])
return json.loads(subprocess.check_output([*ssh_prefix('server'),cmd],input=Path(__file__).read_bytes()))
def windows(file, args):
from dev_stage import ssh_prefix
directory=Path(__file__).resolve().parents[1]/'deploy/windows'
packet={'args':args,'program':(directory/file).read_text()}
payload=base64.b64encode(gzip.compress(encode(packet))).decode()
# Windows OpenSSH does not reliably signal EOF on Console.In; keep the fixed
# local operator and its typed arguments in a compressed, printable packet.
command=("$ErrorActionPreference='Stop';$ProgressPreference='SilentlyContinue';try{$m=[IO.MemoryStream]::new([Convert]::FromBase64String('"+payload+
"'));$z=[IO.Compression.GzipStream]::new($m,[IO.Compression.CompressionMode]::Decompress);"
"$j=[IO.StreamReader]::new($z).ReadToEnd()|ConvertFrom-Json;$a=@{};foreach($v in $j.args.psobject.Properties)"
"{$a[$v.Name]=$v.Value};& ([ScriptBlock]::Create([string]$j.program)) @a}"
"catch{[Console]::Error.WriteLine($_.Exception.Message);exit 1}")
cmd='powershell.exe -NoLogo -NoProfile -NonInteractive -EncodedCommand '+base64.b64encode(command.encode('utf-16-le')).decode()
require(len(cmd)<31000,'Windows operator exceeds native command-line limit')
return json.loads(subprocess.check_output([*ssh_prefix('windows'),cmd],timeout=120))
def guest(action, data):
args={'Action':action, 'CaseId':data['case_id'],'AgentId':data['agent_id'],'AssetId':data['asset_id'],'ReleaseId':data['release_id']}
return windows('Set-DevelopmentWindowsUpdate.ps1',args)
def emit(value):
print(json.dumps(value,ensure_ascii=False),flush=True)
def wait_for(data, predicate, timeout, message):
end=time.monotonic()+timeout
while True:
result=remote_server('read',data)
if predicate(result):
return result
require(time.monotonic()<end,message)
time.sleep(4)
def local():
cli=argparse.ArgumentParser(description=__doc__)
cli.add_argument('action',choices=('inspect','plan','window','close'))
cli.add_argument('--case',type=identifier)
cli.add_argument('--minutes',type=int,default=15,choices=range(1,121),metavar='1..120')
args=cli.parse_args()
state_dir=Path(__file__).resolve().parents[1]/'devstate/windows-update-windows'
if args.action=='close':
require(args.case, 'Pass --case from the opening command')
data=json.loads((state_dir/(args.case+'.json')).read_bytes())
close(data)
return
observed=windows('Inspect-DevelopmentWindowsUpdate.ps1',{})
data={k:identifier(observed[k]) for k in ('tenant_id','agent_id','asset_id','release_id')}
baseline=remote_server('read',data)
if args.action=='inspect':
emit({'device':observed,'server':baseline});return
require(usable(baseline), 'Device must be idle, authenticated, synchronized and bound to an enabled operator')
data.update(case_id=args.case or str(uuid.uuid4()),expires_at=(utc()+timedelta(minutes=args.minutes)).isoformat())
remote_server('preflight',data)
plan=guest('Plan',data)
require(plan['requires_helper_creation'] and not observed['case_id'], 'Another helper or local window is active')
if args.action=='plan':
emit(plan);return
state_dir.mkdir(parents=True,mode=0o700,exist_ok=True)
casefile=state_dir/(data['case_id']+'.json')
with casefile.open('xb') as dst:
dst.write(encode(data));dst.flush();os.fsync(dst.fileno())
emit({'preparing_window':data['case_id'],'expires_at':data['expires_at']})
try:
result=guest('Install',data)
require(result['case_id']==data['case_id'] and result['agent_id']==data['agent_id']
and result['helper_binary_sha256']==plan['helper_sha256'],'Device binding changed')
data.update({k:result[k] for k in ('helper_binary_sha256','helper_policy_sha256')})
atomic(casefile,encode(data))
wait_for(data,lambda row:scoped(data,row),min(180,max(1,(stamp(data['expires_at'])-utc()).total_seconds())),
'No authenticated narrow SYSTEM capabilities received during the preparation window')
# The static capability refresh can precede the first signed helper-role
# clock exchange. Check the actual current probe before exposing this scope.
while True:
probe=windows('Inspect-DevelopmentWindowsUpdate.ps1',{'ClockOnly':True})
fresh=probe.get('observed_at') and timedelta(0)<=utc()-stamp(probe['observed_at'])<timedelta(seconds=46)
if (fresh and probe.get('clock_qualified') and probe.get('helper_ready') and probe.get('authenticated')
and probe.get('agent_id')==data['agent_id'] and probe.get('agent_pid')==probe.get('current_agent_pid')
and probe.get('policy_sha256')==data['helper_policy_sha256'] and probe.get('helper_sha256')==data['helper_binary_sha256']):
break
require(utc()<stamp(data['expires_at']), 'Window expired while waiting for the native signed helper clock')
time.sleep(5)
emit(remote_server('enable',data))
while utc()<stamp(data['expires_at']):
time.sleep(min(4,max(0,(stamp(data['expires_at'])-utc()).total_seconds())))
except KeyboardInterrupt:
pass
finally:
close(data)
def retire_native(action,data,witness):
args={'CaseId':data['case_id'],'AgentId':data['agent_id'],'AssetId':data['asset_id'],
'ReleaseId':data['release_id'],'Witness':witness,'Action':action}
return windows('Retire-DevelopmentWindowsUpdate.ps1',args)
def close(data):
from windows_update_detach import remote_server as detach_server
started=utc()
emit(remote_server('revoke',data))
wait_for(data,lambda row:row['install'] and row['open_jobs']==0,180,
'Attempt still active. Central scope is revoked; retry close when the result is terminal.')
observed=windows('Inspect-DevelopmentWindowsUpdate.ps1',{})
if observed.get('case_id') is not None or observed.get('helper') is not None:
require(observed.get('case_id')==data['case_id'],'Local helper belongs to another maintenance window')
result=guest('Remove',data)
require(result['closed'] and not result['helper_registered'] and result['actor_running'],
'Could not withdraw the helper from this enrollment')
emit(result)
witness=detach_server('witness',data)
if witness and witness.get('helper_id'):
emit(retire_native('Verify',data,witness))
emit(detach_server('detach',{**data,'witness':witness}))
emit(retire_native('Apply',data,witness))
latest=windows('Inspect-DevelopmentWindowsUpdate.ps1',{})
if latest['release_id']==data['release_id']:
resumed=guest('Resume',data)
require(resumed['actor_running'] and resumed['release_pull_running'],'Normal services did not resume')
else:
require(latest.get('agent_id')==data['agent_id'] and latest.get('helper') is None
and latest['release_pull']['state']=='Running' and latest['agent']['state']=='Running',
'Post-close release selection needs review')
ended=wait_for(data,lambda row:usable(row) and stamp(row['install']['contact'])>=started
and not {'helper.system.v1','system:run_script'} & set(row['install']['capabilities']),
180,'Still awaiting a new synchronized non-SYSTEM heartbeat after closing')
emit({'closed_case':data['case_id'],'normal_agent_contact':ended['install']['contact']})
if __name__=='__main__':
try:
if len(sys.argv)==4 and sys.argv[1]=='--on-server':
emit(server(sys.argv[2],json.loads(base64.b64decode(sys.argv[3],validate=True))))
else:
local()
except subprocess.SubprocessError as exc:
sys.exit('Remote command failed: '+type(exc).__name__+' (see target diagnostic above)')
except (ValueError,OSError,KeyError) as exc:
sys.exit(str(exc))