From 50b15cb95cace6de2a910c18692d647be969e78c Mon Sep 17 00:00:00 2001 From: wh1te909 <7434746+wh1te909@users.noreply.github.com> Date: Tue, 26 Nov 2024 01:23:27 +0000 Subject: [PATCH] fix checks/tasks docs --- docs/functions/automated_checks.md | 32 ++++++-------- docs/functions/automated_tasks.md | 68 ++++++++++++++++-------------- mkdocs.yml | 2 +- 3 files changed, 51 insertions(+), 51 deletions(-) diff --git a/docs/functions/automated_checks.md b/docs/functions/automated_checks.md index 63ed2808..ea274441 100644 --- a/docs/functions/automated_checks.md +++ b/docs/functions/automated_checks.md @@ -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. diff --git a/docs/functions/automated_tasks.md b/docs/functions/automated_tasks.md index 5c53b410..96bcc7d2 100644 --- a/docs/functions/automated_tasks.md +++ b/docs/functions/automated_tasks.md @@ -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). diff --git a/mkdocs.yml b/mkdocs.yml index 3e48d7ac..9635294e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -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