ImmyBot Script Execution

ImmyBot Script Execution

ImmyBot ships a PowerShell script library that runs against managed endpoints in SYSTEM context. This is a privileged, destructive capability — scripts can install/uninstall software, change system settings, access files, and reboot the machine.

API Tools

Tool	Purpose
immybot_scripts_list	List scripts with category/language/status filters
immybot_scripts_get	Full detail for one script by ID
immybot_scripts_search	Search scripts by name
immybot_scripts_categories	List available script categories
immybot_scripts_validate	Validate script syntax before running
immybot_scripts_run	Execute a script on a computer (DESTRUCTIVE)
immybot_scripts_execution_history	Past executions for a computer
immybot_scripts_execution_result	Result of one specific execution

Canonical Workflow

1. Find the script

immybot_scripts_search → immybot_scripts_get

Read the script description and confirm it matches the intended outcome. Prefer global, vetted scripts over ad-hoc ones.

2. Validate syntax (for new or modified scripts)

immybot_scripts_validate checks PowerShell syntax without executing anything. Always validate custom script content first.

3. Confirm the target

immybot_computers_get — confirm the computer is online and is the correct endpoint. Running a script on the wrong machine is the most common and most damaging mistake.

4. Get human approval

immybot_scripts_run is destructive. The MCP server returns a confirmation warning describing SYSTEM-context risk. Surface that warning, name the script and target computer explicitly, and obtain operator approval before proceeding.

5. Execute and capture

Call immybot_scripts_run with the script ID, target computer ID, optional parameters, timeout (default 30 min), and execution context (default System).

6. Review the result

immybot_scripts_execution_result   # this run
immybot_scripts_execution_history  # the computer's run history

Parameters & Timeouts

• Parameters — passed as a parameter object; confirm required parameters from immybot_scripts_get before running.
• Timeout — default 30 minutes. Long-running remediation (large installs, disk operations) may need a higher value.
• Execution context — defaults to System. Only change this if the script explicitly needs a user context.

Safety Rules

• Never run a script without explicit human confirmation.
• Always name the exact script and exact computer in the approval request.
• Validate custom script content with immybot_scripts_validate before it ever runs.
• For fleet-wide remediation, pilot on one endpoint and review the execution result before expanding scope.
• Log the approver, script ID, target, and outcome for every run.

Related Skills

• endpoint-management — pick and verify the target computer
• api-patterns — destructive-operation confirmation pattern