Operator runbook

Day-to-day operation: roles, the daily routine, handling one incident and one compliance finding. Changes, safety controls and the platform team's tasks follow on two more pages.

How-to · Updated 2026-11-02 · Describes release 0.1.184

Evidence reviewed 2 November 2026; operating baseline 0.1.184 (the release this runbook was checked against; see the release notes).

For the people who run the platform day to day. Sections 1–8 and 16 are the day-to-day part: roles, the daily routine, incidents, findings, changes, runbooks, safety controls, connections and the weekly and monthly checks. Sections 9–15 and 17 are for the platform team: monitoring, platform incidents, releases, backup, licence, security, patching and support.

1. What the platform is and who does what

This runbook describes release 0.1.184. Check the live build before you follow it: curl --fail --silent https://aiops.example.com/healthz returns the running version.

What the platform does

The platform receives signals from your estate, works out what is wrong, proposes a fix and runs it only after the right person allows it.

1. Signals come in. Alerts from monitoring tools, findings from cloud scanners, and tickets arrive through intake webhooks or scheduled pulls.
2. Signals are grouped. Repeats are dropped. Alerts that share a cause join one incident. A compliance finding opens a finding record.
3. An agent analyses. It reads your connected sources with read-only access and writes a root-cause analysis and a proposed fix.
4. A person decides. A write to your estate waits for an approver, unless a certified runbook and your own settings let it run on its own.
5. The fix runs and is checked. The platform records the change, checks the condition cleared, and rolls back or hands the work to a person if it did not.

Every step is written to an append-only audit log.

Agents never write with the credentials they read with. A connection marked as a write connection is invisible to agents and is used only by an approved change.

For the full picture, see What the platform does and How incidents work.

Where you work

The portal is at /portal. The sidebar is in the order of an operator's day:

You only see the pages your role can use. A page you cannot open is not a fault; see Roles.

From 0.1.184:

• Each compliance finding has its own page at /portal/findings/<id>. Old /compliance-findings links redirect there.
• The portal opens in the dark look by default. Use the theme control in the top bar to switch; your choice is kept in your own browser only.

The platform team uses a separate console at /ops for workspaces, model gateways and platform health. It is covered in sections 9–15.

Roles

A role is a named set of permission keys. Five built-in roles ship with every workspace. They are reset from code at every start, so you cannot edit them. Make a custom role if you need a different set.

The one-line description of each role is also shown in the portal under Settings › Members & roles → Role definitions.

The permissions that matter day to day

There are 16 keys in all. The full matrix is in Permissions.

Separation of duties (since 0.1.111)

Since release 0.1.111 the built-in operator role no longer holds approvals.decide. The rule is: the operator requests, the approver decides and runs.

• Every release tier needs approvals.decide. L0, L1 and L2 need one approver. L3 needs two different people.
• An operator may release a fix only when it is a standard change made standard by a matched, certified runbook, it is not an emergency, and its tier needs one approver. Everything else waits for an approver.
• A risk request (accept, suppress) needs an approver other than the person who asked. The requester may approve their own request only when no other approver exists in the workspace; that is recorded in the audit log.
• Approval gates (pillars.manage) are separate from both deciding and acting. Neither the person who approves nor the person who tunes an agent's prompt can widen what an agent may run on their own.
• The executive role gained approvals.decide in 0.1.111, so a manager can be the second approver on an L3 change.

Any member, including a viewer, can Escalate an incident to a person. The audit row records who did it.

See Approval policy for who releases what at each tier.

Give someone a role

When to do it: a person joins the rota, changes job, or leaves.

Who: a member with members.manage (the owner role).

Steps:

1. Open Settings › Members & roles.
2. To add a person, click Invite member, enter Email, pick Role, then click Invite member.
3. To change a role, pick the new role in the Role selector on the member's row.
4. To remove a person, click Remove on their row and confirm Remove member.

How to check it worked: the row shows the new role. The audit log (Settings › Audit log) has a member.add, member.invited, member.role_changed or member.remove row.

If it did not:

• cannot remove or downgrade the only member with members.manage: give a second person the owner role first.
• no role named '<name>' in this tenant: create the custom role first.
• If the person signs in with single sign-on, also disable them in your directory when they leave. Otherwise automatic provisioning can add them back at their next sign-in.
• Removing a member does not delete their personal access tokens. The tokens stop working in this workspace at once.

Details: Members and roles, Single sign-on.

Who is responsible for what

These are operating responsibilities, not response-time commitments. Agree named contacts in section 17.

Details: Architecture and responsibilities, Support access.

2. Daily operator routine

Do these checks at the start of each shift, in this order. They take 10 to 20 minutes on a normal day. Each one says who should do it.

Platform health (runners, intake errors, audit seal) is the platform on-call's daily check, in section 9.

2.1 Read the dashboard

When to do it: first thing in the shift, and after any alert storm.

Who: any member with incidents.view.

Steps:

1. Open Home › Dashboard (/portal/dashboard).
2. Read the six tiles at the top:
   • Unresolved incidents and Needs attention are today's workload.
   • MTTR, MTTA, Alert noise reduced and Auto-handled events compare the last 30 days with the 30 days before.
3. Read the Human gate card. It says how many items wait on a person and how many are P1, and lists the five most urgent.
4. Read the card's last line, Approvals:. It shows the incident writes paused and the change requests pending. Each number opens its list.
5. Look at Opened vs resolved per day. A rising gap means work is piling up.

How to check it worked: the time the figures were read is shown under the tiles. A number that is a link opens a list with the same total.

If it did not:

• The page shows Connect your first data source or a New workspace card: the workspace has no enabled read connection yet. Finish Quick start first.
• The Human gate card says the queue could not be loaded: open Needs you directly. Do not read the empty card as "nothing waiting".
• A tile says too few to compare: fewer than five records in one of the two windows. That is expected in a quiet workspace.
• The dashboard figures can be up to one minute old. The sidebar badges refresh more often.

Details: Dashboard.

2.2 Work the Needs you queue

Needs you is every decision waiting on a person, in one list, most urgent first. You decide on the incident, finding or change page, next to the evidence. The queue itself has no approve buttons.

When to do it: at the start of the shift, then whenever the sidebar badge or the Human gate card shows new items.

Who: members with incidents.act or approvals.decide see Needs you in the sidebar. Some kinds are shown only to the people who can act on them (see the table).

Steps:

1. Click Review queue on the Human gate card, or open Home › Needs you (/portal/approvals).
2. Read the Kinds of decision panel. It names every kind with its count. A greyed kind has nothing waiting.
3. Work the kinds from the top. Each card lists ten rows; click +N more for the rest, or Show all … for that kind alone.
4. On each row, click its button (Open incident, Open finding, Open change, Review suggestion, Review problem). Decide on the page that opens.

What each kind asks of you:

How to check it worked: the item leaves the queue after the decision. The badge count goes down. The decision is in the record's timeline and in Settings › Audit log.

If it did not:

• A banner says Part of the queue could not be loaded: the kinds it names are unknown, not empty. Click Retry.
• The page says deciding needs approvals.decide: your role can see the queue but not decide. Ask an approver, or ask the owner to change your role.
• A P1 item has waited too long: call the approver on duty. The queue does not page anyone; outbound pushes are set under Settings › Notifications & on-call (Notifications).
• From 0.1.184, a risk request that nobody decides before its expiry time becomes expired and leaves the queue. Ask for it again if it is still needed.

2.3 Release or refuse paused writes

Nothing writes to your estate until the right person allows it. This check clears those waits.

When to do it: during 2.2, and at least twice a shift while changes are pending.

Who:

• Approve, deny or release: approvals.decide (owner, approver, executive). L3 needs two different approvers.
• An operator may release a fix only if it is a standard change made standard by a matched, certified runbook, not an emergency, at a one-approver tier.

Steps:

1. On the Human gate card, select Review queue. On Needs you, select Fix to approve in the list of kinds. This opens incidents and findings paused for approval.
2. Open each item. Read the analysis, the proposed action, its risk tier and the rollback plan. Approve or deny it.
3. Back on the queue, select Change approval. This opens changes awaiting release.
4. Open each request. Check the change class (standard, normal or emergency), the maintenance window, the scope and the rollback plan. Release or reject it. Section 5 has the full procedure.

How to check it worked: the incident moves on from paused, or the change status moves from pending approval to approved and then to executing. The approvals ledger on the change shows your name and the time.

If it did not:

• The release is refused with a window message: the change is outside its maintenance window. Wait for the window, or ask for a Window exception.
• An L3 change stays pending after your approval: it needs a second, different approver.
• The release is refused because agents are paused or a budget is spent: see section 7.

Details: Approve and run a fix, Approval policy.

2.4 Follow up failed and rolled-back changes

A change that failed or was rolled back always needs a person to look at it, even when the platform already undid it.

What the platform does on its own:

• A scheduled sweep looks once at each change that failed in the last 24 hours (aiops_rollback_sweep_window_h, default 24). Where the rules allow (for example a GitOps fix that failed verification, at tier L2 or lower), it opens the rollback by itself; otherwise it escalates and sends the rollback notification.
• With Roll back a failed cloud fix automatically off (the default), a failed cloud fix is not undone without a person.
• When a failed fix is settled, an incident or finding that is still escalated is re-analysed by itself, at most twice per record (aiops_reanalyse_after_rollback, default on). From 0.1.184 this run has its own trigger: the incident history calls it an automatic re-analysis, and Agents activity shows it as Re-analysed after a fix was rolled back, not as a person pressing Re-analyse. The new plan still needs approval.

When to do it: every shift.

Who: an operator investigates; Roll back on a change needs approvals.decide.

Steps:

1. Open Changes › Changes. Stay on the Requests through the platform tab.
2. In the Status chips, click failed. Then click rolling back, then rolled back. A chip only shows when it has a count.
3. Open each change. Read its result, its verification and its Rollback plan.
4. For a failed change that was not undone:
   • If Roll back is offered, an approver presses it.
   • If the incident page shows Rollback plan (operator-run), an operator runs the listed commands and records the result on the change.
5. For a rolled back change, open the linked incident. Check the new analysis, and whether the runbook was taken off pre-approval (it will appear in Needs you as Runbook taken off pre-approval).

How to check it worked: the change ends in rolled back or completed; the incident shows a verification that the condition cleared, or a new plan waiting for approval.

If it did not:

• Roll back is not offered: the change has a manual rollback, the rollback is already recorded, or its result is uncertain. Follow the operator-run plan and record what you did.
• A change stays in rolling back: open it and check the restore step. A restore pull request does nothing until someone merges it.
• The same fix fails again after two automatic re-analyses: the platform stops trying. Take the incident by hand and escalate it.

Details: Changes reference, Verify recovery.

2.5 Check agent runs and held findings

When to do it: once a shift, and after a large scanner pull.

Who: any member with incidents.view; starting an analysis needs incidents.act.

Steps:

1. Open Insights › Agents activity. It shows which agents are working now, what each one ran, what failed and what it cost.
2. Look for failed runs. Open the record behind each one.
3. Open Compliance › Findings. Look for findings held with the reason automatic analysis paused: burst limit reached for this workspace.
4. For each held finding that matters now, open it and click Analyse.

From 0.1.184 one workspace starts at most 10 automatic finding analyses in any 15 minutes (Burst limit on Settings › Guardrails & cost; 0 = no cap). This stops one scanner pull from starting hundreds of paid runs. Findings past the limit wait for a person, or for Backlog catch-up if that switch is on.

How to check it worked: the run appears in Agents activity as running, then finished. The finding gets an analysis.

If it did not:

• Runs fail with model or gateway errors across the workspace: raise a platform incident (section 10).
• New runs do not start at all: agents may be paused or a budget spent (section 7).

2.6 Once a month: alert noise

When to do it: the first working day of each month, before the monthly service report.

Who: an operator or the workspace owner (incidents.view; the report needs report.view).

Steps:

1. Open Home › Dashboard.
2. Open the fold Alerts → incidents · per month. It shows the last six months: Alerts received, Duplicates dropped, Joined an incident, Incidents, Grouped, Closed as noise, Noise reduction.
3. Open Scanner findings · per month under it for the same figures on scanner findings.
4. Compare the last full month with the month before. Note sources whose alerts keep turning into Closed as noise.
5. Open Insights › Report for the service-delivery report, which prints the same table.

How to check it worked: the dashboard table and the report show the same numbers for the same month.

If it did not: if one source produces most of the noise, tune it at the source, or mark repeat incidents with Mark as noise so the monthly figure records them (section 3). Weekly and monthly checks are in section 16.

Details: Storms, unmapped and flapping signals, Service delivery report.

3. Handling one incident end to end

This section follows one incident from the moment it opens to the moment it closes. It describes release 0.1.184.

An incident is the unit of work. One or more alerts open it. An agent analyses it and may prepare a fix. A person decides whether the fix runs. A read-only check then confirms whether the problem cleared. A person or the alert source closes it.

Nothing writes to your estate without a person's decision, unless your workspace has switched on pre-approved automatic fixes (see section 7).

Who can do what

The short rule: an operator analyses and requests; an approver decides and runs. An L3 fix needs two different approvers.

Where incidents appear

• Home › Needs you lists every record that waits on a person. The legend card at the top, KINDS OF DECISION · COUNTS FROM THE QUEUE, has one link per kind. The kinds that concern incidents are Fix to approve, Needs attention, Change approval, Unmapped signal and Post-implementation review.
• Incidents › Incidents lists every incident. The filters (Service, Triage and the rest) are behind the outlined Filters button. You can also set them in the URL, for example /portal/incidents?triage=unmapped.
• The Human gate card in the sidebar shows how many items wait on a person and how many are P1.

Read the incident page

Open an incident from either list. The page reads top to bottom:

1. The header card: priority (P1 to P4), severity, status, and WHERE / WHEN / WHO CHANGED IT / HOW WE KNOW / COST.
2. Left: What happened, the agent's conclusion. Under it, WHERE IT STANDS: the steps L1 Ingestion to L7 RCA, each marked done, not reached or not used here.
3. Right: What you need to do. Its headline says the current state. It holds the page's one filled button: the next step.
4. BLAST RADIUS · WHAT DEPENDS ON THE FAILING SERVICE: the services that depend on the failing one.
5. Timeline: the last 6 events. Use Show all N events for the rest.
6. Folds: Evidence, Last known changes, Cost, Fix attempts, Artifacts, Ask about this incident, Diagnostics (for engineers).

Every other whole-record action sits under More actions at the top right. The menu never repeats the panel's filled button.

Rule of thumb: press the filled button in What you need to do, or choose from More actions. Do not look for a status picker; there is none.

For a full tour of the page, see Read an incident and its analysis.

3.1 Open: check the incident started correctly

When: a new incident appears in Needs you or at the top of Incidents.

Who: anyone with incidents.view.

Steps:

1. Open the incident.
2. Read the header card. Check the priority, the service under WHERE and the source under HOW WE KNOW (for example "1 alert · Generic webhook").
3. Read the headline in What you need to do:
   • "Analysing — the agent is working through the evidence": analysis started on its own. Go to 3.2.
   • "Queued — waiting for a runner": no agent has picked it up yet. Wait a few minutes.
   • "Held for triage — unidentified service …": the alert named no service. Go to 3.9.
   • A finding with "No analysis has concluded on this finding yet." and the filled button Analyse: automatic analysis did not start (see section 4).

How to check it worked: within a few minutes the WHERE IT STANDS step L4 Triage shows done, and What happened holds the agent's conclusion.

If it did not:

• Headline "Runner lease expired — waiting for recovery": the runner stopped reporting. The platform resumes or fails the run on its own. If it stays like this, see section 10.
• Headline "Run failed — …": press Re-analyse (3.7). If it fails again, read the error and see section 10 (model gateway errors).
• Nothing started and the incident has no headline: check that agents are not paused and the budget is not spent (section 7).

3.2 Analysis: read what the agent found

When: the agent finished (L4 Triage done).

Who: anyone with incidents.view.

Steps:

1. Read What happened: the root cause in one line.
2. Open Evidence to see what the agent read. Open Last known changes to see recent changes on the service.
3. Read the purple Agent recommendation box in What you need to do. It names the fix and Who signs off.
4. If a fix is ready, the panel holds the Prepared change card. Its headline is "Investigation complete — review the next steps".

How to check it worked: the panel shows one of these states:

If it did not:

• "This run produced no usable conclusion": the wrap-up could not be read. Open Diagnostics (for engineers), then Re-analyse.
• The conclusion is wrong: rate it and send a correction (see Approve and run a fix › Rate an RCA), then Re-analyse.

3.3 Approve: decide on the prepared fix

When: the panel shows the Prepared change card, or Needs you lists the incident under Fix to approve or Change approval.

Who: an operator requests; an approver releases. See the table above.

Steps:

1. In Prepared change, read the change title.
2. Open Review the details. Check Target, Impact (agent's assessment), the connection on each step, Rollback and Verify recovery.
3. Open Exact changes and execution method. Your approval covers only these steps, targets and connection versions.
4. Check Pre-state before each step: it says whether the platform stores each target's current state before the write.
5. Add an Approval note if you want. It is kept with your approval and in the change request document.
6. Press the button. Its label tells you what happens:

Paused actions during analysis: an approval card in the investigation shows the tool name, the tier and the exact command. Press Approve, or type a reason in Reason (sent to the agent on deny) and press Deny. Where the card offers Edit, you can change the command and press Run edited command.

How to check it worked:

• After Approve & run or Run standard change, the headline becomes "Fix applied live via route … — waiting for validation" or "Fix applied — waiting for validation".
• After Approve & create PR, the headline becomes "Waiting for the merge of … — nothing changes until it is merged".
• After Request approval, the incident appears in Needs you under Change approval for an approver.
• Open the change record links to the change, which records who requested and who approved, with times.

If it did not:

• An error appears under the button, and Refresh and review current change appears: something changed since you reviewed it (plan, connection, target). Press it, review again, then approve.
• "Not applicable — no runnable fix" with a list of write connections: a connection is missing or not allowed for approved plans. Fix the connection (section 8), or run the steps by hand and Mark resolved.
• "Release parked — approved by 1 of 2, needs a second, distinct approver": an L3 change. Ask a second approver to open the change record.
• "Re-analyse before preparing a fix": the plan is older than a suppression. Press Re-analyse.

For the approval gate in detail, see Approve and run a fix › The approval gate. Change classes and windows are in section 5.

3.4 Run and verify: confirm the fix held

When: a fix ran, or its pull request was merged.

Who: watching needs incidents.view. Verify now needs incidents.act.

Steps:

1. For a pull request: review and merge it in your own repository. The platform never merges its own pull requests. Let your pipeline deploy it.
2. Wait. A read-only check runs on its own after the fix. The headline reads "Verifying — a read-only agent is checking the estate" while it runs.
3. To check now instead of waiting, press Verify now in What you need to do. It starts a read-only check; no write happens.
4. Read the verdict in WHERE IT STANDS › L6 Validation.

How to check it worked: the headline reads "Recovery verified — the condition cleared after attempt N", and the next step is Mark resolved.

If it did not:

• "Attempt N did not hold — validation found the condition still present": the fix did not work. If it needs undoing, the undo steps are under L6 Validation. If the analysis proposes another fix, the button is Apply fix. Otherwise Re-analyse or Escalate.
• "Execution failed — CHG-…": the change failed before any verdict. Nothing may have been applied. The card Execution failed — what next? offers Give feedback, Mark resolved, Mark as noise, Re-analyse and Hand off to a person. Check the change record before undoing anything. There is no retry. With approvals.decide the link reads Review and roll back.
• "Attempt N was rolled back": the platform does not apply that plan again. If Re-analyse after a failed or rolled-back fix is on (the default), a fresh analysis starts on its own. In 0.1.184 that run shows as "Re-analysed after a fix was rolled back", not as a person's run. Its new fix still needs approval.

Rollback of a change is covered in section 5.

3.5 Close

When: the problem is fixed, or the incident needs no action.

Who: incidents.act.

An incident can close in three ways:

• On its own. When the alert source sends its clear, the incident closes and shows "auto-resolved". You do nothing.
• Mark resolved. You say the issue is fixed.
• Mark as noise. You say it was expected and needs no action (see 3.6).

Steps (Mark resolved):

1. Press Mark resolved. It is the filled button after "Recovery verified", or under More actions otherwise.
2. In the dialog, fill What fixed it? (optional, audited). On an escalated incident your note becomes a draft skill, so the agent can fix it next time.
3. Leave Expected / no action required (known noise) … unticked.
4. Press Mark resolved.

How to check it worked: the status reads resolved. A fresh read-only check runs after the close.

If it did not:

• The incident shows Reopened with a reason: the check found the problem still live. Read the evidence link, then fix it or Escalate.
• "incident already resolved": someone closed it already. Nothing more to do.
• The close is refused while a change is executing. Wait for the change to finish.

A change request nobody released yet is marked rejected when you close the incident. Its approval ledger records Rejected by you.

3.6 Mark as noise

When: the alert was expected (a planned test, a known flapping check) and nothing needs fixing.

Who: incidents.act.

Steps:

1. Open More actions › Mark as noise. The same dialog opens with the known-noise box already ticked.
2. Fill Why is this expected?.
3. Press Close as expected.

How to check it worked: the panel shows "closed as noise". Verification is muted for this incident only.

If it did not: the same alert keeps coming back. Mark as noise does not silence the source. A later alert with the same key opens a new incident with a similar: noise chip. Silence it at the source, or set the flapping rule (section 8).

3.7 Re-analyse

When: the analysis failed, was stopped, proposed no fix, or is out of date (a fix was rolled back, a resource was suppressed after the plan, an exception expired).

Who: incidents.act.

Steps:

1. Press Re-analyse. It is the filled button when it is the next step; otherwise it is under More actions. On a record that was never analysed, the label is Analyse.
2. Wait for the headline "Analysing — …".

How to check it worked: a new run appears and the panel returns to 3.2.

If it did not:

• The button is missing or disabled: a run or a check is in flight, a pull request waits for its merge, a fix is being validated, or the AI budget is spent. Wait, or press Continue analysis (+$5) to grant more budget.
• "Marked awaiting approval but nothing is pending": a stuck run. The next step reads "Stop this run, then re-analyse or resolve". Re-analyse starts only once the stuck run is stopped.

Each run costs money. Normal cost and approval rules apply.

3.8 Escalate

When: you want a person or team to own the incident, and the agent to stop working on it.

Who: anyone with incidents.view. This is deliberately the lowest bar.

Steps:

1. Open More actions › Escalate, or press Escalate if it is the next step.
2. Optionally type a team or person in Assign to (team/user, optional), for example sre-oncall.
3. Press Escalate incident.

How to check it worked: the notice reads "Escalated to <name>." or "Escalated to a human." The incident moves to Needs you under Needs attention. If incident notifications are set up, the escalate event is sent (Settings › Notifications & on-call).

If it did not: Escalate is not offered on an incident that is already escalated or closed. Leaving the assignee blank keeps the existing assignee.

Before you hand an incident to support, collect the items in What to collect before you escalate.

3.9 Unmapped signals and Map this source

An alert that names no service cannot be grouped safely. It opens its own incident and waits in the triage queue. While it waits it starts no analysis, files no ticket, sends no notification and never gets an automatic fix. This is the rule Alerts that match no service go to triage, on by default.

Before it waits, the platform looks the alert's resources up in the estate inventory (on by default). If the inventory finds exactly one owning service, the alert moves to that service's incident. If not, it waits, and the Timeline shows a row such as "Estate inventory checked: no single service". From 0.1.184 that row also says which read-only connections were checked and the outcome, for example "not visible to any read-only connection (checked …) — needs a person", and each hourly re-check is written on the held incident too.

When: Needs you shows Unmapped signal, or an incident headline reads "Held for triage — unidentified service — no service label".

Who: Analyse and Mark resolved need incidents.act. Use … as the service needs members.manage (owner).

Steps:

1. Go to Home › Needs you and click the legend link Unmapped signal. Or open Incidents › Incidents, press Filters and set Triage to "Unidentified service — waiting for triage".
2. Open the incident (Open incident on the row).
3. Read the card Unidentified service — map this source. It names the source and lists the alert's labels that could name the service.
4. Decide:
   • This alert only: press Analyse to investigate it, or close it with Mark resolved / Mark as noise.
   • Every later alert from this source: press Use <label> (<value>) as the service. From then on, an alert from that source that names no service takes that label as its service and groups normally.
5. If the card says the alert carries no label that could name the service, add a service label at the source.

How to check it worked:

• After mapping, the card says "Mapped: from now on an alert from <source> that names no service takes its <label> label as the service, so it groups normally. This incident stays here — analyse it or resolve it."
• The mapping shows under Settings › Alert intake & tokens › Intake rules, service aliases and test alert.
• Send a test alert from the same source and check that it opens under the service.

If it did not:

• Without members.manage, the card lists the candidate labels instead of buttons. Ask an owner.
• "The label … names a place or a field, not the service": choose another label (account and region are not services).
• The card says "… is not in your dependency map": add a service alias under Settings › Alert intake & tokens (Service aliases), or declare the dependency under Incidents › Service dependencies.

Mapping changes only later alerts. The current incident stays as it is. For the intake rules, see Alert sources and intake rules.

4. Handling a compliance finding

This section covers one scanner finding (AWS Security Hub, Microsoft Defender for Cloud, or the platform's built-in detection). It describes release 0.1.184.

A finding is a record of one scanner rule (for example EC2.19) and the resources that fail it. The page and the buttons work like an incident (section 3). The difference is the choice a person makes on each finding:

• Fix via change: fix the resource. The fix goes through a change request.
• Record exception: accept the risk until a date, with a written reason. An approver must approve it.

Who can do what

Every exception is a request first, even when an approver sends it. It takes effect only after an approver approves it.

Where findings appear

• Compliance › Findings. The page Findings · All has domain tabs Vulnerabilities · Patching · Backup · Configuration · All. While you are on it, the sidebar shows the sub-items Vulnerabilities · Patching · Backup · All. The risk cards rank the work; the top card's Open the worst finding opens the worst one. The full list is in the fold All N rules in this view as a table.
• Compliance › Posture. Top posture risks with Review top risk.
• Home › Needs you. Risk exception request, and Needs attention for a finding whose exception expired or whose analysis handed it to a person.

From 0.1.184 a finding's page is at /portal/findings/<id>. Old links to /portal/compliance-findings/<id> (in tickets, notifications and change requests) still open the same page.

Read the finding page

Top to bottom:

1. The header card: priority, severity, status, domain, and WHAT / WHERE / WHO CHANGED IT / HOW WE KNOW / SINCE WHEN. The agent's conclusion is in this card ("No analysis has concluded on this finding yet." until one lands).
2. For a resource finding: EXPOSURE PATH · HOW THE INTERNET REACHES THIS RESOURCE. A red Combined risk call-out means two findings land on the same resource.
3. DECIDE: FIX IT OR ACCEPT THE RISK. Left: Fix via change, with the page's one filled button. Right: Record exception.
4. WHERE IT STANDS: L1 Ingestion to L7 RCA.
5. Fold Exception history ("N decisions").
6. Fold Scanner record: every resource the scanner reported under this rule, each with its own Decide button.
7. Timeline, then folds Evidence, Ask about this finding, Diagnostics (for engineers).

4.1 Analysis: get a fix prepared

When: a new finding opens.

Who: watching needs incidents.view. Analyse needs incidents.act.

By default the platform analyses P1 and P2 findings on its own (Analyse P1/P2 findings automatically, on). A P3 or P4 finding waits for a person.

From 0.1.184 there is a burst limit: at most 10 automatic finding analyses per workspace in any 15 minutes. A large scanner pull opens the rest held, with the reason "automatic analysis paused: burst limit reached for this workspace". This stops one pull of hundreds of findings from starting hundreds of paid runs.

Steps:

1. Open the finding.
2. If the conclusion line is filled and Fix via change holds a Prepared change card, go to 4.2.
3. If Fix via change reads "no analysis" with the filled button Analyse, read the reason under it. Then press Analyse to start one run.

How to check it worked: the conclusion appears in the header card, and WHERE IT STANDS shows L4 Triage done.

If it did not:

• Many findings are held after a scanner pull: press Analyse on the ones you need now. Or ask the owner to turn on Backlog catch-up: also analyse P1/P2 findings already held (off by default; it analyses held findings oldest first, 3 per minute, one paid run each). Both switches and the Burst limit are under Settings › Guardrails & cost › Automatic analysis of P1/P2 findings. A Burst limit of 0 means no cap.
• "Automatic analysis is off, paused or over budget": see section 7.

4.2 Fix via change

When: you want the resource fixed.

Who: operator requests; approver releases. A certified runbook makes it a standard change that an operator can run alone.

Steps:

1. In DECIDE: FIX IT OR ACCEPT THE RISK › Fix via change, open the Prepared change card.
2. Review it exactly as for an incident (section 3.3): Review the details, Exact changes and execution method, Pre-state before each step.
3. Press the button: Run standard change, Approve & run, Request approval, or Approve — runs in the next window (…).
4. Wait for validation (section 3.4).

How to check it worked:

• The change record (Open the change record) shows the run and its approvals.
• When the scanner reports the resource as passed, the finding closes on its own. From 0.1.184 this also happens for a finding that had been escalated, unless a change for it is still waiting, executing or being verified.

If it did not:

• "Not applicable — no runnable fix": no write connection can run it. The panel lists each write connection and what it needs. Fix the connection (section 8), or run the manual steps and Mark resolved.
• "Re-analyse before preparing a fix": a resource was suppressed after the plan was drafted. Press Re-analyse; the new plan leaves the suppressed resources out.
• The scanner still reports the resource as failing after the fix: Security Hub re-checks on its own schedule. Wait for its next evaluation, or press Verify now.

4.3 Record exception: request a risk exception

When: the resource cannot or should not be fixed now, and the business accepts the risk until a date.

Who: anyone with incidents.act or approvals.decide.

Steps:

1. On the finding page, press Record exception (outlined, right half of the DECIDE card). It opens the Scanner record fold.
2. Find the resource. Use Search resources or the Open filter if the list is long.
3. Press Decide on that row (it reads Change decision when the resource is already suppressed).
4. In the dialog Risk decision — <rule> <title>, choose:
   • Fix: opens a change request. The Change agent drafts the fix plan; you review and approve it on the Changes page.
   • Suppress: the risk is yours until the expiry. It is recorded in the risk register against you and left out of every fix.
5. Write the Reason: why the risk is acceptable, who owns it, what would change your mind. At least 10 characters. This is the audit record.
6. Choose the Scope: This finding (this resource) or Whole control (every resource failing this rule).
7. For Suppress, set Expires on. The default is 90 days; the latest is one year. This is the re-review date.
8. For Suppress only, tick Also suppress at the source (Security Hub / Defender) if you want the scanner itself to stop re-sending it (see 4.6).
9. Press Send request (or Record decision if you hold approvals.decide). Both send a request.

How to check it worked:

• The notice reads "Request sent — an approver must approve it before it takes effect."
• Exception history and the resource's Decision history show the decision as requested, with your name, time and expiry.
• Home › Needs you lists it under Risk exception request.
• Compliance › Audit & coverage › Decisions, state Requested, lists it.

If it did not:

• The button stays disabled: the reason is shorter than 10 characters, or the expiry is missing or outside tomorrow to one year.
• "this is a suppression on a compliance control — decide on the control": the finding comes from a platform check, not a scanner. Decide on the control.

4.4 Approve or reject a risk exception request

When: Needs you shows Risk exception request.

Who: approvals.decide, and not the person who sent the request.

Steps:

1. Go to Home › Needs you and click the legend link Risk exception request.
2. On the row, press Open finding. The page opens with the resource's Decision history in Scanner record.
3. Read the reason, the scope and the expiry. Check the header card and the exposure path.
4. Press Approve, or Reject and give a note.

You can also approve or reject from Compliance › Audit & coverage › Decisions, state Requested.

How to check it worked:

• Suppress approved: the finding's alerts resolve, the status reads resolved, and the resource's Risk decision reads "suppressed". Later scanner re-sends are counted, not shown as new work, until the expiry.
• Fix approved: "Decision recorded — the Change agent is drafting the fix plan (see Changes)". A change request opens under Changes; it goes through the normal change approvals (section 5).
• Reject: the request stays in the register as rejected with your note. Nothing changed.
• The register (Decisions, state Approved) shows who approved and when.

If it did not:

• The requester sees "Your request — another approver signs it off." and no Approve. This is by design. Another approver must sign it.
• In a workspace with only one approver, the requester sees Approve as the only approver. It is recorded as self-approved. If the owner has turned on Never let a requester approve their own exception, even that is refused, and the request waits for a second approver.
• "this request has expired — send a new one": the request's expiry date passed before anyone approved it. From 0.1.184 the platform marks such a request expired on its own (audited as risk.request_expired) and it leaves the queue. Send a new request.

4.5 When an exception expires

When: an approved suppression reaches its Expires on date. Watch for it in Compliance › Audit & coverage › Decisions: the expiry date is highlighted when the re-review is due within 14 days.

Who: reviewing needs incidents.view. Acting on it needs the permissions in 4.2–4.4.

What happens depends on the switch Act when an exception expires (owner, Settings › Guardrails & cost › fold Residency & exceptions › Risk exceptions):

Steps (switch on):

1. Go to Home › Needs you › Needs attention. The row carries the chip "exception expired" and the reason "Reopened: the suppression expired …".
2. Press Open finding. The Timeline shows Reopened with the reason. The resource's Decision history reads "expired · the platform reopened 1 finding at … · managed-risk score A% → B%".
3. Decide again:
   • Fix it: press Re-analyse (the filled button) to plan a fix, then 4.2.
   • Keep the exception: send a new request (4.3) with a new reason and expiry.
   • Already fixed: close it with Mark resolved.

To end an exception early: go to Compliance › Audit & coverage › Decisions, state Approved, and press Revoke on the row (approvals.decide). The notice reads "Decision revoked — the finding surfaces again." The row stays in the register with its revoke time.

How to check it worked: the register's state column reads expired (or revoked), and the finding is open again.

If it did not: with the switch off, nothing reopens until the scanner sends the finding again. If you need the reopen on the date, ask the owner to turn the switch on.

4.6 Suppress at source

By default an exception lives only in the platform. Security Hub or Defender keeps reporting the finding, and the platform counts the re-sends quietly. Suppressing at the source also writes the exception to the scanner: Security Hub sets the finding SUPPRESSED, and Defender gets an Azure Policy exemption.

When: the scanner's own console or reports must show the finding as accepted.

Who: the owner sets it up once. Then anyone who sends a request (4.3) can tick it.

Steps (set up once):

1. Make sure the workspace has a write connection for that cloud, allowed for approved plans (section 8).
2. Open Settings › Guardrails & cost › fold Residency & exceptions.
3. In Suppress scanner findings at the source, tick Allow writing accepted scanner findings to Security Hub / Defender. The notice reads "Source suppression on."
4. For accounts that send findings by webhook (not by scanner pull), also filter Workflow.Status in their EventBridge rule. Otherwise the suppressed finding is still sent.

Steps (each exception):

1. Request a Suppress with This finding scope and tick Also suppress at the source (Security Hub / Defender) (4.3).
2. An approver approves it (4.4). The source write runs in the background after the approval.

How to check it worked: the decision in Exception history carries the badge Suppressed at source. In Security Hub, the finding's workflow status is SUPPRESSED.

If it did not:

• The badge reads Source suppression failed: …: the exception holds in the platform only. Read the detail. A common one is "Suppress scanner findings at the source is off in Guardrails". Otherwise check the write connection.
• A Whole control exception never writes to the source. Only a single-finding exception does.

Know the limits:

• Security Hub has no expiry. A finding suppressed there stays quiet after the platform's expiry until the decision is revoked, unless Act when an exception expires is on, which lifts it at expiry.
• A Defender exemption ends with the exception.
• Revoke lifts the source suppression. The badge then reads Source suppression lifted.
• Exceptions on the platform's own checks always stay in the platform.

For the full rules on risk decisions, see Compliance reference › Risk decisions and Security posture.

Next steps

• Next: Operator runbook: changes, runbooks, safety and sources
• All Install and operate the platform pages
• Documentation home