Documentation / Running scripts

Running scripts

PowerShell plays the role Bash plays on Landscape. Scripts run as SYSTEM, in an isolated execution host, with a full audit trail - and running one is a permission distinct from writing one.

The script library

Scripts are stored, versioned entities with optional file attachments. Editing a script creates a new version; a run records exactly which version executed. The library lives in an access group, and script.read / script.write are genuinely access-group-scoped - you can keep a set of scripts visible only to the team that owns a given subtree.

Writing or editing a script (script.write) does not authorise running it. That is a separate, sensitive permission.

Ad-hoc versus scheduled

A script can be run two ways:

• Ad hoc - pick a script, give it a target query, dispatch. This creates an activity group with one child per resolved host; the parent aggregates results and each child is addressable individually. Landscape has no inline/ad-hoc mode, which tends to orphan one-off scripts in the library forever - Portrait keeps the one-off as a first-class action.
• Scheduled - a script profile runs a library script on a cron schedule against whatever hosts match its query at evaluation time. A script profile requires both script_profile.manage and script.execute_as_system.

Run identity: SYSTEM only

Scripts always run as the local SYSTEM account. There is no “run as” field, and a request that supplies a non-null run-as identity is rejected outright rather than silently ignored. This is permanent, not a limitation awaiting work: Windows has no sudo-equivalent, and a local credential store for arbitrary run-as identities was considered and deliberately rejected. If a task needs a particular user context, the script itself is responsible for establishing it.

This is why script.execute_as_system is a sensitive permission. Authorising a script run is authorising arbitrary code as the most privileged account on the target machine.

Isolation and limits

Execution happens in a separate process from the agent service - a dedicated execution host, constrained with a Windows job object - so a runaway or misbehaving script cannot take down the agent itself. Each run has a timeout and a cap on captured output; exceeding the timeout marks the activity timed-out, and output beyond the cap is truncated rather than buffered without bound.

Audit

Every run is an activity: who (or which profile) initiated it, which script version, which hosts, when, and the per-host exit code and captured output. The audit log is queryable and exports to a SIEM in CEF or NDJSON - see Monitoring & alerts.