Files
napalm-windows/napalm_windows/scheduled_tasks.py
T
Christian Manivong a508b872b0
driver / standard (pull_request) Successful in 14s
driver / lint (pull_request) Successful in 15s
driver / test (3.12) (pull_request) Failing after 14s
driver / types (pull_request) Failing after 23s
driver / test (3.13) (pull_request) Failing after 13s
driver / lowest (pull_request) Failing after 14s
driver / security (pull_request) Failing after 32s
driver / build (pull_request) Successful in 25s
CI / driver (pull_request) Failing after 1m21s
driver / publish (pull_request) Skipped
feat(scheduled-jobs): the Task Scheduler as scheduled jobs (#8)
netOrk shows and controls every scheduled job of a host; on Windows that
is the Task Scheduler. The driver now implements napalm-device-types'
ScheduledJobsMixin over PowerShell Remoting, one script per call as every
getter does.

get_scheduled_jobs reads every task with its run info in one script
(Get-ScheduledTask, Get-ScheduledTaskInfo) as task:<path><name>, its
triggers summarised. Tasks under \Microsoft\ are the platform's, others
the admin's: Windows does not record which software installed a task.
The time zone is mapped to IANA for the common Windows zones, else None.
A reading cut short, or holding fewer tasks than it counted, raises.

manage_scheduled_job switches the task's own flag or starts it;
Start-ScheduledTask returns once the task has started, so the result says
that and no more. A disabled task, or one that refuses a start on demand,
is not offered run.

put_scheduled_job registers an application's task \<name> in the root
folder from XML, so a create and a change write the whole definition the
same way: the command runs in cmd.exe /d /s /c, the principal is SYSTEM
or a local user without a stored password (S4U), and the cron expression
becomes triggers only where Task Scheduler can say it exactly; any other
shape is refused, naming why. The description keeps the job's name and
cron expression, so the reading gives back what was written, and the
digest also covers the triggers, so a change by hand is seen.
delete_scheduled_job unregisters such a task and no other. Every write
reads the task again first, and every value goes into PowerShell
single-quoted with its quotes doubled.

Requires napalm-device-types 4.26.0.

Closes #8
2026-11-03 05:49:12 +01:00

462 lines
18 KiB
Python

"""Scheduled jobs on Windows: the Task Scheduler over PowerShell Remoting (#8).
:class:`WindowsScheduledJobsMixin` implements napalm-device-types'
:class:`~napalm_device_types.scheduled_jobs.ScheduledJobsMixin` for the driver,
which carries each script across ``PsrpTransport.run``.
**Reading** is one script: every task (``Get-ScheduledTask``) with what the host
says of its runs (``Get-ScheduledTaskInfo``), projected onto flat fields, and the
host's time zone; Python only normalises. Every task is a job ``task:<path><name>``
whose schedule is a summary of its triggers. A task under ``\\Microsoft\\`` is the
``platform``'s, any other the ``admin``'s -- Windows does not say which software
installed a task -- and a task in the root folder whose description starts with
``napalm-scheduled-job: <its name>`` is an ``application``'s, read back as the cron
expression and command it was written with (:mod:`napalm_windows.task_xml`). Its
digest covers its triggers as well, so triggers changed by hand are a change. A
reading whose task count does not match, or whose JSON is cut short, raises.
**Switching** is the task's own flag (``Enable-`` / ``Disable-ScheduledTask``);
**running** is ``Start-ScheduledTask``, which returns once the task has started: how
the run ends shows in the next reading. A disabled task, or one that does not allow a
start on demand, is not offered ``run``. A task is addressed by its exact path and
name, never by ``-TaskName``, which takes wildcards.
**An application's own job** is registered from XML (``Register-ScheduledTask -Xml
-Force``), so creating it and changing it write the whole definition the same way;
``delete_scheduled_job`` unregisters it. Before every write the job is read again
and compared with the digest the caller saw; a task of the same name that an
application did not write is never overwritten. Every value goes into PowerShell
single-quoted, its quotes doubled.
"""
from __future__ import annotations
import json
import re
from datetime import UTC, datetime
from typing import TYPE_CHECKING, Any, NamedTuple
from napalm_device_types import (
ScheduledJobChanged,
ScheduledJobDict,
ScheduledJobRefused,
ScheduledJobResultDict,
ScheduledJobsMixin,
ScheduledJobSpecDict,
ScheduledJobsReadingDict,
job_digest,
)
from napalm_device_types.scheduled_jobs import ACTIONS, DELETE, EDIT, check_spec
from napalm_windows._powershell import _as_list, _ps_quote
from napalm_windows.task_xml import JOB_MARKER, SCHEDULE_LINE, own_command, task_xml
from napalm_windows.time_zones import iana_time_zone
from napalm_windows.transport import PowerShellError
# Every task with its run info. Times leave the host as ISO 8601 in UTC; a task
# whose run info cannot be read keeps its definition and loses only its times.
_PS_SCHEDULED_TASKS = r"""
$ErrorActionPreference = 'Stop'
function U($d) { if ($d) { ([datetime]$d).ToUniversalTime().ToString('o') } }
$tasks = @(Get-ScheduledTask)
$rows = @($tasks | ForEach-Object {
$t = $_
$i = $t | Get-ScheduledTaskInfo -ErrorAction SilentlyContinue
[pscustomobject]@{
path = $t.TaskPath
name = $t.TaskName
state = [string]$t.State
user = $t.Principal.UserId
group = $t.Principal.GroupId
on_demand = $t.Settings.AllowDemandStart
description = $t.Description
actions = @($t.Actions | ForEach-Object {
[pscustomobject]@{
class = $_.CimClass.CimClassName
execute = $_.Execute
arguments = $_.Arguments
class_id = $_.ClassId
}
})
triggers = @($t.Triggers | ForEach-Object {
[pscustomobject]@{
class = $_.CimClass.CimClassName
enabled = $_.Enabled
start = [string]$_.StartBoundary
days_interval = $_.DaysInterval
weeks_interval = $_.WeeksInterval
days_of_week = $_.DaysOfWeek
interval = [string]$_.Repetition.Interval
duration = [string]$_.Repetition.Duration
delay = [string]$_.Delay
}
})
last_run = U $i.LastRunTime
last_result = $i.LastTaskResult
next_run = U $i.NextRunTime
}
})
ConvertTo-Json -Compress -Depth 5 -InputObject ([pscustomobject]@{
time_zone = [System.TimeZoneInfo]::Local.Id
count = $tasks.Count
tasks = $rows
})
"""
# One task by its exact path and name, handed to a cmdlet.
_PS_TASK_CMDLET = r"""
$ErrorActionPreference = 'Stop'
$task = @(Get-ScheduledTask | Where-Object {{ $_.TaskPath -eq {path} -and $_.TaskName -eq {name} }})
if ($task.Count -ne 1) {{ throw ('no single scheduled task ' + {path} + {name}) }}
$task[0] | {cmdlet} | Out-Null
"""
_PS_REGISTER = r"""
$ErrorActionPreference = 'Stop'
Register-ScheduledTask -TaskPath {path} -TaskName {name} -Xml {xml} -Force | Out-Null
"""
_PS_UNREGISTER = r"""
$ErrorActionPreference = 'Stop'
Unregister-ScheduledTask -TaskPath {path} -TaskName {name} -Confirm:$false
"""
_CMDLETS = {
"enable": ("Enable-ScheduledTask", "enabled"),
"disable": ("Disable-ScheduledTask", "disabled"),
"run": (
"Start-ScheduledTask",
"started; Start-ScheduledTask returns once it has started, so how the run "
"ends shows in the next reading",
),
}
_ROOT = "\\"
_JOB_NAME = re.compile(r"[a-z0-9][a-z0-9-]{0,62}")
_DOTNET_DATE = re.compile(r"^/Date\((-?\d+)(?:[+-]\d{4})?\)/$")
_BOUNDARY = re.compile(r"^(\d{4}-\d\d-\d\d)T(\d\d:\d\d)(?::\d\d(?:\.\d+)?)?(Z|[+-]\d\d:\d\d)?$")
_DURATION = re.compile(r"^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$")
_DURATION_UNITS = ("day", "hour", "minute", "second")
#: LastTaskResult: SCHED_S_TASK_RUNNING and SCHED_S_TASK_HAS_NOT_RUN.
_RUNNING = 0x41301
_NEVER_RAN = 0x41303
_WEEKDAYS = ("Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat")
_EVENT_TRIGGERS = {
"MSFT_TaskBootTrigger": "at startup",
"MSFT_TaskLogonTrigger": "at logon",
"MSFT_TaskIdleTrigger": "on idle",
"MSFT_TaskEventTrigger": "on an event",
"MSFT_TaskSessionStateChangeTrigger": "session state change",
"MSFT_TaskRegistrationTrigger": "at registration",
}
# ---------------------------------------------------------------------------
# Reading
# ---------------------------------------------------------------------------
def _timestamp(value: Any) -> str | None:
"""A time as the host gave it -- ISO 8601, ``/Date(ms)/`` or epoch seconds -- as
ISO 8601 in UTC; None for none, and for Task Scheduler's never (30 November 1999)."""
if value is None or value == "":
return None
if isinstance(value, int | float):
at = datetime.fromtimestamp(value, UTC)
elif match := _DOTNET_DATE.match(str(value).strip()):
at = datetime.fromtimestamp(int(match[1]) / 1000, UTC)
else:
try:
at = datetime.fromisoformat(str(value).strip())
except ValueError:
return None
at = (at if at.tzinfo else at.replace(tzinfo=UTC)).astimezone(UTC)
return None if at.year < 2000 else at.isoformat()
def _last_result(code: Any, last_run: str | None) -> str | None:
if last_run is None or code is None:
return None
code = int(code) & 0xFFFFFFFF
if code == _NEVER_RAN:
return None
if code == _RUNNING:
return "running"
return "success" if code == 0 else f"0x{code:X}"
def _readable_duration(value: str) -> str:
"""``PT1H30M`` → ``1 hour 30 minutes``; anything else as it is."""
match = _DURATION.match(value)
if not match or not any(match.groups()):
return value
parts = [
f"{n} {unit}{'' if n == '1' else 's'}"
for n, unit in zip(match.groups(), _DURATION_UNITS, strict=True)
if n
]
return " ".join(parts)
def _clock(start: str) -> tuple[str, str]:
"""A trigger's start boundary as its date and its time of day (with its offset)."""
match = _BOUNDARY.match(start)
if not match:
return "", start
return match[1], match[2] + (match[3] or "")
def _every(count: Any, unit: str) -> str:
return f"{unit}ly" if count in (None, 0, 1) else f"every {count} {unit}s"
def _calendar(trigger: dict[str, Any], cls: str) -> str:
date, time = _clock(str(trigger.get("start") or ""))
at = f" at {time}" if time else ""
if cls == "MSFT_TaskDailyTrigger":
days = trigger.get("days_interval")
return ("daily" if days in (None, 0, 1) else f"every {days} days") + at
if cls == "MSFT_TaskWeeklyTrigger":
mask = int(trigger.get("days_of_week") or 0)
days = ",".join(d for i, d in enumerate(_WEEKDAYS) if mask & (1 << i))
return f"{_every(trigger.get('weeks_interval'), 'week')} on {days}{at}"
if cls == "MSFT_TaskTimeTrigger":
return f"once at {date} {time}".rstrip()
return f"trigger{at}"
def _trigger(trigger: dict[str, Any]) -> str:
"""One trigger as a short sentence: its kind, when, how it repeats."""
cls = str(trigger.get("class") or "")
text = _EVENT_TRIGGERS.get(cls) or _calendar(trigger, cls)
if trigger.get("delay"):
text += f" after {_readable_duration(str(trigger['delay']))}"
if trigger.get("interval"):
text += f", every {_readable_duration(str(trigger['interval']))}"
if trigger.get("duration"):
text += f" for {_readable_duration(str(trigger['duration']))}"
if trigger.get("enabled") is False:
text += " (disabled)"
return text
def _action(action: dict[str, Any]) -> str:
if action.get("execute"):
return " ".join(str(p) for p in (action["execute"], action.get("arguments")) if p)
if action.get("class_id"):
return f"COM handler {action['class_id']}"
return str(action.get("class") or "")
class _Own(NamedTuple):
"""What an application's task description and action say of the job."""
name: str
description: str
schedule: str | None
command: str | None
def _own(path: str, name: str, task: dict[str, Any]) -> _Own | None:
"""The application's job this task is; None for any other task."""
lines = str(task.get("description") or "").splitlines()
if path != _ROOT or not lines or not lines[0].startswith(JOB_MARKER):
return None
job_name, _, description = lines[0][len(JOB_MARKER) :].partition(" ")
if job_name != name or not _JOB_NAME.fullmatch(name):
return None
schedule = next(
(ln[len(SCHEDULE_LINE) :] for ln in lines[1:] if ln.startswith(SCHEDULE_LINE)), None
)
actions = _as_list(task.get("actions"))
command = (
own_command(actions[0].get("execute"), actions[0].get("arguments"))
if len(actions) == 1
else None
)
return _Own(name, description.strip(), schedule, command)
def _verbs(task: dict[str, Any], enabled: bool, own: bool) -> list[str]:
verbs = ["enable", "disable"]
if enabled and task.get("on_demand") is not False:
verbs.append("run")
return [*verbs, EDIT, DELETE] if own else verbs
class _Definition(NamedTuple):
"""What a task's fields say it does, as the job shows it."""
schedule: str
schedule_kind: str
command: str
managed_by: str
description: str
def _definition(path: str, task: dict[str, Any], triggers: str, own: _Own | None) -> _Definition:
command = "\n".join(_action(a) for a in _as_list(task.get("actions")))
if own is not None:
kind = "cron" if own.schedule else "triggers"
return _Definition(
own.schedule or triggers, kind, own.command or command, "application", own.description
)
platform = path.lower().startswith("\\microsoft\\")
return _Definition(
triggers,
"triggers",
command,
"platform" if platform else "admin",
str(task.get("description") or "").strip(),
)
def _task_job(task: dict[str, Any]) -> ScheduledJobDict:
path, name = str(task.get("path") or _ROOT), str(task.get("name") or "")
triggers = "; ".join(_trigger(t) for t in _as_list(task.get("triggers")))
enabled = str(task.get("state") or "").lower() != "disabled"
own = _own(path, name, task)
found = _definition(path, task, triggers, own)
last_run = _timestamp(task.get("last_run"))
job: ScheduledJobDict = {
"key": f"task:{path}{name}",
"kind": "task",
"source": f"{path}{name}",
"run_as": str(task.get("user") or task.get("group") or ""),
"schedule": found.schedule,
"schedule_kind": found.schedule_kind,
"command": found.command,
"enabled": enabled,
"managed_by": found.managed_by,
"digest": "",
"actions": _verbs(task, enabled, own is not None),
"last_run": last_run,
"last_result": _last_result(task.get("last_result"), last_run),
"next_run": _timestamp(task.get("next_run")),
}
# An application's task shows its cron line; its triggers are what runs.
job["digest"] = job_digest(dict(job), content=triggers if own else "")
if own is not None:
job["name"] = own.name
if found.description:
job["description"] = found.description
return job
def parse_reading(output: str) -> tuple[list[ScheduledJobDict], str | None]:
"""The jobs and the IANA time zone in what :data:`_PS_SCHEDULED_TASKS` printed.
:raises ValueError: when the reading is cut short or holds fewer tasks than counted.
"""
raw = json.loads(output)
if not isinstance(raw, dict):
raise ValueError("not a scheduled-tasks reading")
tasks = _as_list(raw.get("tasks"))
count = int(raw.get("count") or 0)
if len(tasks) != count:
raise ValueError(f"the reading holds {len(tasks)} of {count} scheduled tasks")
return [_task_job(t) for t in tasks], iana_time_zone(raw.get("time_zone"))
def _path_and_name(source: str) -> tuple[str, str]:
path, _, name = source.rpartition("\\")
return path + "\\", name
# ---------------------------------------------------------------------------
# The mixin
# ---------------------------------------------------------------------------
class WindowsScheduledJobsMixin(ScheduledJobsMixin):
"""The Task Scheduler as scheduled jobs; the driver carries the scripts."""
if TYPE_CHECKING: # pragma: no cover - declared for type checkers only
def _run_raw(self, script: str) -> str: ...
def _sj_read(self) -> tuple[list[ScheduledJobDict], str | None]:
return parse_reading(self._run_raw(_PS_SCHEDULED_TASKS))
def get_scheduled_jobs(self) -> ScheduledJobsReadingDict:
"""Every task of the host, in one round trip.
:raises ValueError: when the reading came back cut short.
"""
jobs, time_zone = self._sj_read()
return {"jobs": jobs, "time_zone": time_zone}
def _sj_job(self, key: str, digest: str) -> ScheduledJobDict:
jobs, _ = self._sj_read()
job = next((j for j in jobs if j["key"] == key), None)
if job is None:
raise LookupError(f"no scheduled job {key}")
if job["digest"] != digest:
raise ScheduledJobChanged(f"{key} changed on the host since it was read")
return job
def _sj_send(self, script: str, done: str) -> ScheduledJobResultDict:
try:
self._run_raw(script)
except PowerShellError as exc:
return {"success": False, "output": str(exc)}
return {"success": True, "output": done}
def manage_scheduled_job(self, key: str, action: str, *, digest: str) -> ScheduledJobResultDict:
"""Enable, disable or start the task *key*; see :class:`ScheduledJobsMixin`."""
if action not in ACTIONS:
raise ScheduledJobRefused(f"unknown action {action!r}; allowed: {list(ACTIONS)}")
job = self._sj_job(key, digest)
if action not in job["actions"]:
raise ScheduledJobRefused(
f"{key} cannot be told to {action}: it is disabled or "
"does not allow a start on demand"
)
cmdlet, done = _CMDLETS[action]
path, name = _path_and_name(job["source"])
script = _PS_TASK_CMDLET.format(path=_ps_quote(path), name=_ps_quote(name), cmdlet=cmdlet)
return self._sj_send(script, f"{key} {done}")
def _sj_own(self, spec: ScheduledJobSpecDict, digest: str | None) -> ScheduledJobDict | None:
key = f"task:{_ROOT}{spec['name']}"
jobs, _ = self._sj_read()
# Task names are case-insensitive: Register -Force would replace "\Name" too.
current = next((j for j in jobs if j["key"].lower() == key), None)
if digest is None:
if current is not None:
raise ScheduledJobChanged(f"a task {current['source']} is there already")
return None
if current is None:
raise LookupError(f"no scheduled job {key}")
if current["managed_by"] != "application":
raise ScheduledJobRefused(f"{current['key']} was not written by an application")
if current["digest"] != digest:
raise ScheduledJobChanged(f"{key} changed on the host since it was read")
return current
def put_scheduled_job(
self, spec: ScheduledJobSpecDict, *, digest: str | None = None
) -> ScheduledJobResultDict:
"""Register or change the application's own task; see :class:`ScheduledJobsMixin`."""
check_spec(spec)
xml = task_xml(spec)
current = self._sj_own(spec, digest)
script = _PS_REGISTER.format(
path=_ps_quote(_ROOT), name=_ps_quote(spec["name"]), xml=_ps_quote(xml)
)
verb = "changed" if current else "created"
return self._sj_send(script, f"task:{_ROOT}{spec['name']} {verb}")
def delete_scheduled_job(self, key: str, *, digest: str) -> ScheduledJobResultDict:
"""Unregister the application's task *key*; see :class:`ScheduledJobsMixin`."""
job = self._sj_job(key, digest)
if job["managed_by"] != "application":
raise ScheduledJobRefused(
f"{key} was not written by an application; it is only switched"
)
path, name = _path_and_name(job["source"])
script = _PS_UNREGISTER.format(path=_ps_quote(path), name=_ps_quote(name))
return self._sj_send(script, f"{key} deleted")