> For the complete documentation index, see [llms.txt](https://witfy.gitbook.io/clowrk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://witfy.gitbook.io/clowrk/knowledge-base/automated-remediation.md).

# Automated Remediation

A troubleshooting article can carry the commands that fix the problem, and run them on the affected host from inside the case.

This page is about the safety model as much as the feature. Running commands on customer machines from a rule is powerful, and every gate described here exists because somebody could otherwise be surprised.

**Requirement:** the [Command Line module](/clowrk/card-modules/command-line.md) and a Priax connector. Commands run through the same agent, on the same hosts, with the same recording.

## The three parts

| Part         | What it is                                                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Commands** | An ordered list of steps on the article. Each step has its own command text and states which operating system it is written for |
| **A rule**   | A statement that this article applies to a particular kind of event — for example, *the Print Spooler service on this server*   |
| **A run**    | One execution against one case, on one host, with its own record                                                                |

## Commands

Add steps to a troubleshooting article. Each step declares whether it is PowerShell or Bash, and only steps matching the target host's operating system are offered — a Bash step is never sent to a Windows machine.

Steps run in order, one at a time, and each waits for the previous one to come back.

## Rules — connecting an article to events

A rule says which events an article applies to. You narrow it on up to five things:

| Dimension                                                 | Example                                   |
| --------------------------------------------------------- | ----------------------------------------- |
| **The item** — either one specific CI, or a whole CI type | *this server*, or *every Windows Service* |
| **The indicator**                                         | *Service Status*                          |
| **The event type**                                        | availability, performance                 |
| **The criticality**                                       | high, down                                |
| **The connector**                                         | which CMDB the event came from            |

Only the item is required. The more you add, the narrower the rule — and the higher it ranks when several articles could apply.

> **One item, one level.** A rule targets either a specific CI **or** a type of CI, never both. The indicator has to match that choice: a specific indicator goes with a specific CI, a type-level indicator goes with a type. Clowrk refuses the mismatched combinations, because they look correct and match nothing.

### Curated rules, and derived ones

|             | Where it comes from                                                             | Shown as            | Can it run commands unattended? |
| ----------- | ------------------------------------------------------------------------------- | ------------------- | ------------------------------- |
| **Curated** | A person created or reviewed it                                                 | no badge            | Yes, if switched on             |
| **Derived** | Clowrk noticed an article being used on a kind of case and recorded the pattern | a **derived** badge | **Never**                       |

Derived rules exist so that suggestions get better on their own, without anybody maintaining them. They are deliberately barred from authorising unattended execution — otherwise using an article once would quietly turn into commands running on customer machines every time a similar event arrived.

**Reviewing a derived rule curates it.** Opening one, checking it and saving it *is* curation — at that point a person has taken responsibility for it, the badge goes away, and it behaves as a curated rule. There is no separate "promote" action; reviewing is the action.

## Suggesting is not authorising

These are two different questions and Clowrk answers them differently on purpose.

* **"Which articles should the analyst read?"** — matched loosely. An article attached to the right item but the wrong indicator still appears, ranked below the exact matches. Reading a near-miss costs a few seconds.
* **"Which article may run commands here?"** — matched strictly. Every dimension you set must match, and the rule must be curated. Running the wrong commands is not recoverable in a few seconds.

So an article can be suggested and still be unable to run anything. That is the system working.

## Running commands

When a case opens with a matching article, the analyst sees the run in the case. By default **every step waits for approval** — the analyst reads the exact command and approves it, one at a time.

The command text shown is the text that will be sent. It was frozen when the run was created, so editing the article afterwards does not change a run already in progress.

### Running without an operator

Unattended execution needs **two** switches on, and either one being off stops it:

1. **On the rule** — this specific rule is marked as allowed to run without an operator.
2. **For the team** — the team-wide switch is on.

The team-wide switch is checked **again before every single command**, not once at the start. Turning it off stops runs that are already in flight at their next step.

> **It stops manual runs too.** If an analyst started a run by hand, the switch still applies — because from the second step onwards nobody is watching anyway: each step fires when the previous result comes back, which may be minutes later. If somebody clicked run by mistake, the switch is what stops the rest.

Turning either switch on is an administrator's decision, and it is worth making per rule rather than globally: a rule that restarts a stuck print spooler is a very different risk from one that touches a database.

## What is recorded

Every run keeps, permanently:

* which article and which version of it,
* why it matched — the rule, or an analyst choosing it by hand,
* the host and its operating system,
* each command exactly as sent, who approved it, when it was dispatched,
* the output and the result.

Editing the article later does not change any of it.

## Reading a failure honestly

Three outcomes look similar in a list and mean different things:

| What you see                                   | What it means                                                   |
| ---------------------------------------------- | --------------------------------------------------------------- |
| The command ran and the host returned an error | The command text is the thing to fix                            |
| The agent refused it                           | Credentials, an unreachable host, or an unsupported machine     |
| **No result after five minutes**               | **Nobody knows whether it ran.** The answer was lost in transit |

The third is the one to be careful with. Before re-running something that would be harmful twice, check the host.

## When nothing runs at all

In rough order of likelihood:

1. **The host's operating system could not be determined**, so no session was opened. Events whose affected item is the machine itself are the common case — the CMDB entry for a bare host often carries no operating system.
2. **No credentials.** An automatic run has no analyst to ask, so it needs team credentials — see [Command Line](/clowrk/card-modules/command-line.md).
3. **The rule is derived, not curated** — it carries the *derived* badge, so it can suggest but not run.
4. **One of the two switches is off.**
5. **The rule does not actually match** — most often an indicator narrower than the events being received.

## Related

* [Command Line module](/clowrk/card-modules/command-line.md)
* [Articles](/clowrk/knowledge-base/articles.md)
* [Priax Connector](/clowrk/connectors/priax.md)