# The defender's agents

> Golem's investigator works your alerts and undecided inventory as cases, the supervisor checks every step, and you decide what either may close or do without a person.

Flags pile up faster than a security team reads them. Golem's defender works that queue for you. Its investigator files each open alert into a case and explains it from your own records. A second agent, the supervisor, checks every answer before anything comes of it. Each of them closes or acts only as far as you let it: by default they explain and propose, and a person decides.

Everything here is off until a workspace admin turns it on. It calls a model for every case it works, and that costs money.

## The agents

Each agent is its own principal in your workspace. What it reads, and what it may do, is set separately.

| Agent | What it does | Where you set it |
|---|---|---|
| Triage | Reads finished conversations and raises flags (see [Session review](/review)). Also screens undecided inventory, below. | **Defender → Triage** |
| ![](/img/agents/investigator.svg)Investigator | Works the alert queue: files open flags into cases, explains each from the ledger and the security inventory, proposes or takes the case's actions. | **Defender → Investigator** |
| ![](/img/agents/payload-analyst.svg)Payload analyst | Answers a question the investigator could not, from full bodies or an asset's definition. Every body goes through the prompt-injection check first, and one that tries to steer an agent is cited as evidence. | **Defender → Triage → The readers** |
| ![](/img/agents/threat-intelligence.svg)Threat intelligence | Answers a question about a host, domain, package or repository from outside reputation sources. | **Defender → Threat intelligence** |
| ![](/img/agents/supervisor.svg)Supervisor | Checks every answer, approves actions you route to it, and grades the rules the defender drafts. | Runs whenever the investigator does |
| Rules agent | Drafts a detection from a closed case's bad turns no rule caught, or a quieter alert where people keep closing the same one as expected. | **Defender → Investigator → What it may do** |
| ![](/img/agents/reviewer.svg)Reviewer | Decides held calls a rule hands to it. See [Block, hold and contain](/response). | **Protections → Settings** |
| Definition judge | Reads each new version of what an MCP server, skill or plugin tells agents, and lists what it finds. | **Security Inventory → Settings** |
| Responder | Turns findings into measured rules. See [From a finding to a rule](/rules#from-a-finding-to-a-rule). | **Defender → Responder** |

## How a case is worked

```mermaid
flowchart TD
    F["Open alert, or an asset<br/>Triage wants decided"] --> C["Case"]
    C --> I["Investigator explains it"]
    I -- "cannot see enough" --> D["Payload analyst or<br/>threat intelligence"]
    D --> I
    I --> S["Supervisor checks the answer"]
    S -- "kicks it back" --> I
    S -- "agrees" --> O["Close and actions,<br/>as your settings allow"]
    S -- "unsure" --> P["A person"]
```

1. **Filed.** Each pass, open flags no case holds are grouped by what they are about (a conversation, an asset, or a source on one machine) and filed into a case, or into the open case already about the same thing. Flags one rule raised on the same command run against different paths or files are one case.
2. **Explained.** The investigator answers in one of three ways. It explains the case, as expected, a false positive, a true positive (with a root cause) or unclear. It asks one question of the payload analyst or threat intelligence when the answer depends on something it cannot see. Or it says nothing could settle it. Every answer is a comment on the case, with the evidence it cites. It weighs how people decided earlier cases, alerts and assets as its strongest evidence. A case, alert or decision that Golem's own agents closed is only one more opinion, since it may be the very mistake in question; every one it reads says which it was.
3. **Checked.** The supervisor opens the evidence the answer cites and grades it. It agrees, kicks it back with what is missing, approves a deeper question, or hands the case to a person.
4. **Carried out.** What an agreed answer leads to depends on your settings, below.

The case's **Defender** card shows the whole trail. Each case row in **Cases** says where the defender is on it, and **Defender** filters to the cases it is working.

## Turn it on

1. In the console, open **Defender** (under **Detect & Enforce**).
2. Switch on the **Investigator** tile and confirm.
3. Choose **Settings** on the tile.

Only workspace admins change these settings. Each change is signed into your workspace's protection history, and one that lets the defender do more is marked as loosening protection.

### What it works

| Setting | What it does | Default |
|---|---|---|
| **Cases** | **Every open alert**, filed into cases, or **Only cases I bring it into** | Every open alert |
| **Lowest severity it files** | Alerts below it are left for a person | Suspicious |
| **Alert sources it leaves alone** | Rules or readers whose alerts it never files | None |
| **Undecided inventory** | Triage screens undecided assets and opens a case where a decision should change, below. It spends model budget on every undecided asset. | Off |
| **Cases a day** | The most cases the queue opens in a UTC day | 50 |
| **Answers per case** | Rounds of answers before the case goes to a person | 4 |
| **Threat-intelligence lookups per case** | Lookups one case may spend | 3 |
| **Spend per case** | The most one case may spend on model calls before it goes to a person. Raising it is recorded as loosening protection. | $10.00 |

The defender also stops a case that is going round and hands it to you: when the same question goes to the same tier twice, the supervisor gives the same kick-back twice, a round is kicked back citing nothing new, the case uses its answers without settling, or it passes its spend. The case reads **Defender stopped: needs you**, its timeline says why, and you are notified as for the investigator's own closes. **Bring back in** on the case's **Defender** card starts it afresh.

To have it work a case a person opened, use **Bring in** on the case's **Defender** card. **Take off** stops it on that case, deeper questions and actions waiting for the supervisor included.

## Closing cases

By default the investigator proposes each close and a person accepts it in the case's close banner. Under **What it may do**, **Closing cases** lets it close once the supervisor approves its explanation:

| Setting | What happens when the supervisor agrees |
|---|---|
| **Propose only** | The close is proposed for a person to accept or change |
| **Close false alarms** | A case explained as expected or a false positive closes, and its alerts are resolved. A true positive stays open for a person. |
| **Close everything** | Every explained case closes, a true positive with the root cause the investigator named |

The supervisor is told, with each answer it grades, exactly what agreeing will do in your workspace: whether the case closes and which actions run. The investigator's close passes every check a person's does: a true positive needs a root cause, and a dangerous or malicious one records lessons learned. The close waits for a person whatever this says if **Cases → Settings → Second approver** asks for one, or if an action from the same answer is still waiting, since a closed case runs nothing. Raising the setting asks you to confirm. The setting, and that confirmation, show how often people accepted the investigator's proposed closes over the last 30 days. Golem shows that record and leaves the judgement to you: it does not stop you closing on day one.

Each alert source can have its own setting, in the **Last 30 days** table on the same sheet: you might let it close false alarms from a noisy rule while an injection alert always comes to you. A source with no setting of its own follows **Closing cases**. A case with alerts from several sources gets the most cautious of their settings.

## Actions

An explanation may carry actions: the same quick actions a person runs from a case. Each one has its own setting:

| Action | What it does |
|---|---|
| **Quarantine a machine** | Clamps the machine's new agent sessions to Golem's locked-down profile |
| **Safe mode** | Clamps one machine to Golem's locked-down safety profile |
| **Block or alert on an asset** | Refuses an MCP server, skill, plugin or other asset everywhere, or tells you whenever it is used |
| **Allow an asset** | Approves an asset, or accepts an agent settings check |
| **Enforce a rule** | Moves a shadow rule drafted from this case to enforce |
| **Revoke an AI agent** | Revokes an AI agent's access to Golem. Waits for a person unless **Act beyond the case** is on: nothing ties an AI agent to a case |

Each setting has four levels:

| Level | What happens once the supervisor agrees with the answer |
|---|---|
| **Off** | The action is not proposed |
| **A person** | It waits on the case for a person to run |
| **Supervisor** | It waits for the supervisor to approve that one action, below |
| **On its own** | It runs |

Every action starts at **A person**. Raising one to **Supervisor** or **On its own** asks you to confirm.

Two more settings limit what runs:

- **Act beyond the case** (off by default). While it is off, an action on a machine or asset the case is not about, or a rule not drafted from it, waits for a person. What the investigator read may have been written to point it somewhere else. Only links a person or Golem's own agents made count: a machine another agent linked to the case does not. Turning it on lets the investigator act anywhere in the workspace, revoking AI agents included, and counts as loosening protection.
- **Actions an hour.** Golem's agents take at most this many actions on their own in an hour (5 by default, up to 1,000). Past it, the rest wait for a person.

By default the investigator never picks the profile a machine is clamped to; Golem's locked-down one is used. **Let it choose the safety profile** keeps the profile it names, and counts as loosening protection. An action Golem took shows on the case's **Actions** tab as done and proven, with the ledger entry that did it. An action waiting says whom it waits for, and why the investigator wants it.

### The supervisor's approval

An action set to **Supervisor** gets its own check, separate from the supervisor's grade of the answer. It is made from the case's records, without the investigator's comments in front of it. The supervisor approves it only if:

- the target is what the case is about, as the case's records show;
- the evidence supports doing it now;
- no precedent argues against it, such as a person's earlier decision on the same asset or machine.

If it approves, the action runs, after the two limits above are checked again. If it rejects, its reasoning is recorded on the action. When it is unsure it rejects and says what would settle it.

### Who approves

**Who approves** names the members who run or reject what waits for a person. With nobody named, any member working the case can. Workspace owners and admins always can. A named approver can also run an action that is waiting for the supervisor. An approver still needs the permission the action itself needs: quarantining a machine, for instance, takes an owner or admin. Adding someone to the list, or clearing it, counts as loosening protection.

To run a waiting action, open the case's **Actions** tab and choose **Run…**. You are asked why, and the action runs exactly as it was proposed. A proposed action is approved only by running it; **Reject…** turns it down.

## Guardrails

These hold over every close and action the investigator takes by itself, whatever **Closing cases** and the actions' levels say. They are under **Guardrails** on the Investigator settings sheet.

Every guardrail is a setting. A workspace that wants its agents to do everything can turn each one off: no pause, the breaker at 0, nothing protected, no spot checks, containment that never lapses, every source closing everything, every action **On its own**, and **Act beyond the case** on.

| Guardrail | What it does | Default |
|---|---|---|
| **Pause** | The investigator closes nothing and runs nothing by itself. It still files, explains and proposes, so the queue keeps moving and each case waits for a person. Only an owner or admin pauses or resumes it, and resuming counts as loosening protection. | Running |
| **Breaker** | Pauses it when people override it this many times in a day: reopening a case it closed, or undoing an action it took. Golem raises an alert saying why. 0 turns the breaker off. | 3 |
| **Protected** | Machines and assets it never acts on by itself. An action on one waits for a person, and the case says why. | None |
| **Spot checks** | This share of the closes it could make by itself are proposed instead, so a person keeps confirming a sample and the record of how often people agree stays current. The same case is always picked or always not. | 5% |
| **Containment lapses after** | A quarantine, safe mode or block it applied by itself is put back after this many hours unless a person keeps it, below. 0 never lapses. | 24 hours |

Turning the breaker up or off, removing something from the protected list, lowering spot checks, letting containment last longer or never lapse, and letting a source close more all count as loosening protection.

### Undo and keep

Golem records, before an action runs, what undoing it would put back. A done action on the case's **Actions** tab offers:

- **Undo…** puts back what the action changed, whoever took it: an asset gets back the decision it had before, a machine is released, a safety profile is cleared or restored, an enforced rule goes back to shadow. You are asked why. Undoing needs what the reversal itself needs: putting back an asset's decision, a safety profile or a rule, or releasing a machine, takes an owner or admin, as doing it by hand does. Undoing what the investigator did counts toward the breaker.
- **Keep** stops containment the investigator applied by itself from lapsing. Any member can keep it.

Revoking an AI agent cannot be undone: its access is gone, and it signs in again to come back. A quarantine on a machine that was already quarantined changed nothing, so there is nothing to undo.

When containment lapses, Golem puts it back as **Undo** would, records it on the case as undone by Golem, and signs the change into the ledger.

### Hearing about it

Whenever the investigator closes a case or runs an action by itself, or containment it applied lapses, the case's assignee, collaborators and watchers are told, and so is the channel under **Cases → Settings → Case updates go to**. Each message says it was the investigator, so you can tell its work from a colleague's. A page a case opened resolves when the investigator closes it. When the breaker pauses the investigator, Golem raises an **Investigator paused** alert, delivered like any other.


### Outcomes

**Defender → Outcomes** judges each agent working the alert queue by what its work led to, not by how much it did, over 7, 30 or 90 days. Every figure has its explanation behind its (i).

| Agent | Judged on |
|---|---|
| Investigator | How many of its answers explained the alert, and the closes it proposed that a person accepted or overrode |
| Payload analyst, Threat intelligence | How often the investigator's next answer was an explanation, and how many of their answers were "unable" |
| Supervisor | Kick-backs that later led to an agree, agrees a person overrode, and the cases it sent to a person that were closed as false positive |
| Reviewer | The held calls it let through or refused itself, and what a person did with those it handed off |

Above them: cases closed by a person, the median time to a person's close, model spend per closed case, rounds per case, and open cases the defender stopped and handed to a person, by why (same question, same kick-back, nothing new, round limit, spend cap). Only a person's close or refusal counts as a person's decision.

## Undecided inventory

New MCP servers, skills, plugins, subagents, commands and repositories turn up faster than anyone decides them. With **Undecided inventory** on, Triage screens each one that nobody has decided, or that changed since it was decided:

1. Triage reads what the inventory knows of the asset. That covers when it was first seen, on how many machines and how much it was called, its open alerts, and what the scanners found in its current version, by rule and level. Triage never reads the definition's text. Where the definition scanner is on, a new version waits up to a day for the scanner, so Triage sees its findings.
2. It recommends leaving the asset as it is, allowing it, alerting on it, or blocking it.
3. A recommendation that would change the decision opens a case, **Decide: mcp_server …**, with Triage's reasoning as its first comment. If a case about the asset is already open, the recommendation joins it.
4. The investigator works it like any other case. It can look up who publishes the asset and where it runs, ask the payload analyst about the definition, and ask threat intelligence about a host or package it names. It answers with the decision as an action, which runs or waits by your settings for **Block or alert on an asset** and **Allow an asset**.

The asset's page in the **Security Inventory** lists the cases about it and Triage's latest recommendation, so you can get from the asset to its case and back. Screened cases count against **Cases a day**, and screening runs only while **Cases** is set to **Every open alert**.

## Detections it drafts

When a case closes as a true positive and one of its turns was marked bad without any rule catching it, the rules agent drafts a detection. It measures the draft against that evidence and against a week of recent traffic, and the supervisor grades it. **Detections it drafts** decides what an agreed detection does:

- **Shadow first** runs it without acting, where your [Responder](/rules#from-a-finding-to-a-rule) settings allow automatic rules;
- **Wait for me** lists it under **Rules waiting for you** on the Investigator settings sheet.

A draft that makes an alert quieter always waits for you.

## Each agent's model and instructions

Every agent runs your workspace's model choice (see [Your model, your key, your ceiling](/review#your-model-your-key-your-ceiling)). You can give each one its own model on the same provider and key, and your own instructions:

- **Investigator**: **Model and instructions** on the Investigator settings sheet;
- **Triage**'s readers: **Model** and **What each reader should know** on the Triage settings sheet;
- **Reviewer**: under **Golem's reviewer agent** in **Protections → Settings**;
- **Definition judge**: under **Definition scanner** in **Security Inventory → Settings**.

Your instructions are added beneath Golem's own and cannot replace them. Use them for facts about your environment the agent cannot know: which tools are expected to reach production, which machines are build runners, which vendor hostnames are yours. They add context and never remove a rule. Each set holds up to 4,000 characters. An agent with no model of its own uses the workspace's.

Every change to an agent's instructions or model is kept, with who made it, when, and a short version code. Each investigator answer carries the version of Golem's prompt, your instructions and the model that produced it, so after a change you can see whether people accept its closes more or less often than before. The history is under **Model and instructions**, and on each answer in the case's **Defender** card.

## Cost

Every case costs model calls, from the same monthly cap as Triage (see [Session review](/review#your-model-your-key-your-ceiling)). At the cap the defender stops taking work until the month turns. The Investigator settings sheet shows the last 30 days: cases worked, spend, and per alert source how many it closed, how many closes it proposed, and how many of those people accepted or changed.

## On the record and over MCP

What the defender does is signed into your [signed record](/record) under its own principals:

| Principal | Signs |
|---|---|
| `golem-metadata-argument-analyst` | Triage, the investigator, and every action the investigator takes on its own |
| `golem-supervisor` | Grades, approvals and rejections, and every action it approves |
| `golem-payload-analyst` | Answers from full bodies |
| `golem-threat-intelligence` | Each outside lookup |

Every answer, grade, approval and action is also a comment or an event on its case. An agent connected to Golem's MCP server can read the same trail:

| Tool | Returns |
|---|---|
| `get_case_triage` | A case's answers, the evidence each cited, the actions each proposed, and the supervisor's grades |
| `get_case` | The case, with each action's quick action, whom it waits for, and the supervisor's reasoning |
| `get_asset` | An asset, with the cases about it and Triage's latest recommendation; for a flagged shell command, its masked shape and the calls that ran it |
| `list_rule_proposals` | The rules agent's drafts and what came of them |
| `list_precedent` | How people decided alerts like one before: the same rule on the same asset or command shape |
| `get_triage_measurement` | The numbers on the Investigator settings sheet, and every figure under **Outcomes** |
| `list_agent_settings_history` | Every change to an agent's instructions or model, with its version |
| `bring_defender_into_case` | Puts a case a person opened into the investigator's queue |

## What it does not do

- It does not block calls. Allow, refuse and hold are decided on the machine by your [rules](/rules), with no model.
- It does not close or act until you set it to. Out of the box it explains and proposes, and a person decides.
- It does not act on what the case is not about, or past its hourly limit, whatever its settings say.
- It does not get past a second approver your case settings require.
- It does not read definition text when it screens the inventory. The payload analyst reads it only when the investigator asks.
