Skip to content

Commit

Permalink
fix checks/tasks docs
Browse files Browse the repository at this point in the history
  • Loading branch information
wh1te909 committed Nov 26, 2024
1 parent cca98fc commit 50b15cb
Show file tree
Hide file tree
Showing 3 changed files with 51 additions and 51 deletions.
32 changes: 14 additions & 18 deletions docs/functions/automated_checks.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,27 @@

![Checks](images/automated_checks.png)

The maximum time between check runs is 86400 seconds (aka 24 hrs).

Checks are run based on scheduled (celery) timers triggered from the TRMM server. Agents [must be online](../howitallworks.md#understanding-trmm) to receive the script payload to trigger the event.

## Checks vs Tasks

Reasons to use Checks for scripts:
### When to Use Checks for Scripts
- Define custom return codes for **Information** and **Warning** levels.
- Configure alerts only after a specified number of consecutive failures.

- You can define custom return codes for: Information and Warning return codes.
- You can specify more than 1 consecutive failures before getting alerts
### When to Use Tasks for Scripts
- Execute multiple commands and/or scripts in sequence.
- Leverage advanced scheduling options for flexibility.

Reasons to use Tasks for scripts:
## How Often Are Checks Run?

- You can run multiple scripts in sequence
- You can have something run just once instead of at an interval
The frequency of checks is controlled at two levels:

## How often is it run?
1. **Per Check Configuration**
Each check has a **Run Check Every (seconds)** setting. Setting this to 0 defaults to the agent's global value.

It is controlled at 2 levels:

- In a check, there's a Run Check every (seconds). `0` means the default value.
- Default value is defined per Agent under Edit Agent > General pane: Run checks every. Default is 120 seconds.
2. **Agent Default Configuration**
The default check frequency for the agent is set under **Edit Agent > General** in the **Run Checks Every** field. The default value is 120 seconds.

## Best Practices

Use [Automation Policies](automation_policies.md) to apply checks

Customize the frequency of checks running per Check
- Use [Automation Policies](automation_policies.md) to apply checks efficiently.
- Customize the frequency of individual checks as needed.
68 changes: 36 additions & 32 deletions docs/functions/automated_tasks.md
Original file line number Diff line number Diff line change
@@ -1,55 +1,59 @@
# Automated Tasks

![alt text](images/automated_tasks.png)
![Automated Tasks](images/automated_tasks.png)

An Automated Task in TRMM is an item that is created in the Windows Task Scheduler.

You can hover your mouse over the Task name to see what the Task Scheduler item is for that event.

![Task Name](images/tasks_name.png)

As with [all things relating to agent events](../howitallworks.md#understanding-trmm) they must be online and connected to TRMM.
An **Automated Task** allows you to run scripts and/or commands on an agent, with flexible scheduling options.

## Task Triggers

### Time Based

**Daily, Weekly, or Monthly**: All those are just as you'd expect

**Run Once**: Future times are run in an obvious manner. If set in the past, it's actually created for 5 mins after the Windows Task is created on the agent. This is to make that task run at least once because the Windows Task scheduler will never run a task that as a run once date in the past.
### Time-Based
- **Daily, Weekly, or Monthly**: Schedule tasks to run at regular intervals, as expected.
- **Run Once**:
- For future dates, tasks run as scheduled.
- For past dates, tasks are created to run 5 minutes after being registered with the Windows Task Scheduler. This ensures the task runs at least once, as the scheduler will not execute tasks with past "Run Once" dates.

### On check failure
### On Check Failure
Automatically trigger a script to address issues when a Check fails.

This is a secondary script run for any kind of Check failure to fix problems.

eg. If you have a Memory Check that warns at 80% and Errors at 90%. You can create a Task that would run. If 80-89% memory usage popup a Toast message saying something like "You are using more memory than you have RAM for. Your computer will start slowing down, please close some programs or browser tabs to use less RAM". For 90%+ memory usage you can say "Free memory extremely low, please reboot. Contact support to discuss purchasing more RAM if you see this message frequently".

### Onboarding
Use this type of task to execute "Run Once" scripts during agent onboarding. These tasks run immediately after the task is created on the agent, which happens a few minutes after the install of a new agent.

This is your primary Task type to do Run once onboarding tasks. As soon as the Windows Task is created on the agent, it is immediately triggered to run. Use this for setting defaults on workstations, install software, and otherwise configure machines. Adding these with [Automation Policies](automation_policies.md) that are applied to appropriate machines is a great way to setup machines for the first time.

### Manual
Ideal for:
- Setting workstation defaults
- Installing software
- Configuring machines

As the name implies, it's a manual only task that must be manually triggered.
Integrate these tasks with [Automation Policies](automation_policies.md) to streamline the setup of new devices.

eg. I have a manual Defender cleanup task. When I receive an alert about a Windows Defender detection it's brought to my attention with SMS and support ticket creation (see [webhooks](webhooks.md)). Because Defender is constantly adding more items to it's spyware detection list my backup system will frequently find items in the Download folder of installers that contain Adware/browser toolbar installers etc. Once I review the detection to make sure manual intervention isn't required, I have a manual task I'll trigger that will:
### Manual
Manually triggered tasks for on-demand operations.
Example:
A **Windows Defender Cleanup Task** might perform the following when manually triggered:
1. Delete all Shadow Copies from VSS.
2. Create a new VSS Snapshot.
3. Clear Defender logs to prevent duplicate alerts.
4. Run a full Defender scan.

- Delete all Shadow Copies from VSS (to clean out any other versions inside VSS snapshots)
- Create a new VSS Snapshot
- Clean the Defender logs so I won't get more alerts about this event from my Event Log based Defender monitoring script
- Run a Full Defender scan on the machine
This is useful for addressing alerts about Defender detections (e.g., malware or adware in download folders).

## Task Actions

You can run any script from your Script library or Batch or Powershell command. You can run multiple scripts/commands in sequence and have it continue, or stop depending on if it errors.
- Execute any script from your **Script Library**, or use Batch or PowerShell commands.
- Configure multiple scripts/commands to run sequentially.
- Optionally continue or halt the sequence based on errors.

## Collector Tasks

Collector tasks allow saving data from script output directly to a custom field. The collector task will only save the last line of standard output of the script.
Collector tasks allow you to save script output directly to a custom field.

You can create collector tasks by adding it to an Automation Policy or adding it directly to an agent. During creation, select the **Collector** checkbox and select the custom field to save to.
### How to Create Collector Tasks
1. Add the task to an [Automation Policy](automation_policies.md) or directly to an agent.
2. During task creation:
- Select the **Collector** checkbox.
- Choose the custom field where the output should be saved.

!!!note
You can only save to agent custom fields at this time.
!!! note
Currently, you can only save data to agent-level custom fields.

See [Custom Fields](custom_fields.md) and [Scripting](scripting.md) for more information
For more details, see [Custom Fields](custom_fields.md) and [Scripting](scripting.md).
2 changes: 1 addition & 1 deletion mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ nav:
- "Global Settings": functions/global_settings.md
- "Alerting": functions/alerting.md
- "API Access": functions/api.md
- "Automated Checks": functions/automated_checks.md
- "Checks": functions/automated_checks.md
- "Automated Tasks": functions/automated_tasks.md
- "Automation Policies": functions/automation_policies.md
- "Custom Fields": functions/custom_fields.md
Expand Down

0 comments on commit 50b15cb

Please sign in to comment.