Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Feature] Add cross site scripting #217

Merged
merged 3 commits into from
Mar 27, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
137 changes: 117 additions & 20 deletions docs/functions/scripting.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,20 @@
Tactical RMM supports uploading existing scripts or creating new scripts from within the web interface.

Windows agent languages supported:

- PowerShell
- Windows Batch
- Python
- [Nushell](https://www.nushell.sh/)
- [Deno](https://deno.com/)

There is [RunAsUser](../howitallworks.md#runasuser-functionality) functionality for Windows.

Linux/Mac languages supported:

- Any language that is installed on the remote machine (use a shebang at the top of the script to set the interpreter)
- nu
- deno (Javascript and TypeScript)

## Adding Scripts

Expand All @@ -24,6 +30,8 @@ In the dashboard, browse to **Settings > Scripts Manager**. Click the **New** bu
- Windows Batch
- Python
- Shell (use for Linux/macOS scripts)
- Nushell
- Deno

- **Script Arguments** - Optional way to set default arguments for scripts. These will auto populate when running scripts and can be changed at runtime. Logged on Windows Event Viewer > Applications and Services Logs > Microsoft > Windows> PowerShell > Operational
- **Environment vars** - Optional way to set default arguments for scripts using Environment Variables. These will auto populate when running scripts and can be changed at runtime. Not logged, better to use when passing data you don't want logged
Expand Down Expand Up @@ -131,26 +139,6 @@ Tactical RMM supports getting values from the global key store using the {{globa

See [Global Keystore](keystore.md).

### Example PowerShell Script

The below script takes five named values. The arguments will look like this: `-SiteName {{site.name}} -ClientName {{client.name}} -PublicIP {{agent.public_ip}} -CustomField {{client.AV_KEY}} -Global {{global.API_KEY}}`

```powershell
param (
[string] $SiteName,
[string] $ClientName,
[string] $PublicIp,
[string] $CustomField,
[string] $Global
)

Write-Output "Site: $SiteName"
Write-Output "Client: $ClientName"
Write-Output "Public IP: $PublicIp"
Write-Output "Custom Fields: $CustomField"
Write-Output "Global: $Global"
```

## Script Snippets

Script Snippets allow you to create common code blocks or comments and apply them to all of your scripts. This could be initialization code, common error checking, or even code comments.
Expand Down Expand Up @@ -308,3 +296,112 @@ SyntaxError: invalid syntax
```

[Python 3.10 introduced the "match" term]: https://docs.python.org/3/whatsnew/3.10.html#pep-634-structural-pattern-matching

## Nushell

Nu is a new type of shell. Like PowerShell, Nu passes objects from one command to the next. For example, this script will list processes that are more than 100MB.

```nu
ps | where mem >= 100MB
```

There are some important points to keep in mind when writing Nu scripts. See the [Thinking in Nu](https://www.nushell.sh/book/thinking_in_nu.html) for details. Some highlights:

1. The `>` is the greater-than operator, not redirection. Use `| save some-file.txt`
2. Variables are immutable, or constant. Use [`mut`](https://www.nushell.sh/commands/docs/mut.html#frontmatter-title-for-core) to make a variable mutable.
3. Currently Nu does not support background tasks. `long-running-command &` will not work.

Nu has a [Discord](https://discord.gg/NtAbbGn) server if you have questions.

To disable this feature, add the following to `local_settings.py`:

```python
INSTALL_NUSHELL = False
```

### Example Nushell Script

The below script find processes sorted by greatest cpu utilization.

```nu
ps | sort-by cpu | reverse
```

## Deno

Deno is considered to be the next iteration of Node.js. Deno uses ECMAScript modules (a.k.a ES Modules or ESM) syntax, not CommonJS (CJS). I.e. use `import * from https://example.com/package/module.ts` instead of `require('./local/file.js')`.

Tactical RMM runs Deno scripts with the following permissions:

```
DENO_PERMISSIONS=--allow-all
```

See the [documentation on permissions](https://docs.deno.com/runtime/manual/basics/permissions) for details.

To override this, either:

1. Add the `DENO_DEFAULT_PERMISSIONS` [string variable](https://github.com/amidaware/tacticalrmm/blob/1a325a66b45be4c2b8fb2098abb20ef348848651/api/tacticalrmm/tacticalrmm/settings.py#L81) with the permissions requested to `local_settings.py`
or
2. Set the `DENO_PERMISSIONS` environment variable to the permissions requested in your script.

To disable this feature, add the following to `local_settings.py`:

```python
INSTALL_DENO = False
```

### Example Deno Script

The below script prints basic system information:

```typescript
async function gatherSystemInfo() {
const os = Deno.build.os;
const arch = Deno.build.arch;
const memory = Deno.systemMemoryInfo();


const info = `
OS: ${os}
Architecture: ${arch}
Total Memory: ${(await memory).total / 1024 / 1024} MB
Free Memory: ${(await memory).free / 1024 / 1024} MB
`;

console.log(info);
}

gatherSystemInfo().catch(console.error);
```

## Example Scripts

### Example PowerShell Script

The below script takes five named values. The arguments will look like this: `-SiteName {{site.name}}` `-ClientName {{client.name}}` `-PublicIP {{agent.public_ip}}` `-CustomField {{client.AV_KEY}}` `-Global {{global.API_KEY}}`

```powershell
param (
[string] $SiteName,
[string] $ClientName,
[string] $PublicIp,
[string] $CustomField,
[string] $Global
)

Write-Output "Site: $SiteName"
Write-Output "Client: $ClientName"
Write-Output "Public IP: $PublicIp"
Write-Output "Custom Fields: $CustomField"
Write-Output "Global: $Global"
```

### Example Shell Script

The below script prints the user running the script.

```typescript
#!/usr/bin/env bash
whoami
```