Skip to main content

Run scripts

This guide runs a predefined script with validated parameters through the proxy, using the Script execution mode.

Prerequisites​

  • The proxy is installed and running inside your network.
  • A Proxy account with execution mode Script, connected to a script-mode profile on the proxy. Get started walks through this setup.

Add the script to the profile​

Only scripts on the profile's allowlist can run. Add each script as a [[profile.script]] section in the proxy's conf.toml, directly below the [[profile]] section it belongs to, with the parameter names it accepts:

[[profile.script]]
name = "createUser"
file = "scripts/createUser.ps1"
params = ["-Name", "-Department"]
  • name: the script name a package uses to select it.
  • file: path to the script file to execute.
  • params: array of allowed parameter names, including their - or -- prefix.

A [[profile.script]] section always belongs to the nearest [[profile]] section above it, so keep the scripts of a profile together with that profile.

Restart the proxy service after changing the configuration.

Call the script from a package​

A package selects the script by name and passes named parameters. Parameter names must match the entries in the script's params array exactly, including the - or -- prefix: the name is placed on the command line as the flag, followed by the escaped value.

const result = executeOnProxy("script-proxy", {
  script: "createUser",
  parameters: { "-Name": "jdoe", "-Department": "Finance" },
});

if (result.err) {
  log("createUser failed:", result.err);
} else {
  log(result.data.stdout);
}

The result contains the script's output in data.stdout and data.stderr; err is set when the execution failed. See executeOnProxy for the full description.

What the proxy accepts​

The proxy validates every request against the profile and rejects anything that is not explicitly configured:

  • Unknown script names are rejected.
  • Parameter names that are not listed in the script's params array are rejected.
  • Raw commands are rejected; a script-mode profile never executes arbitrary command lines.
  • All parameter values are shell-escaped before being passed to the script.

See Security and privacy for the details of these restrictions.