Every harness is defined by one template in the harness/v1 format. Optimus writes it for you; this page explains what each part means so you can review it.
A complete example
yamlapiVersion: harness/v1 metadata: {name: payments-api-sca, application: payments-api, type: appsec} inputs: - {id: trivy, bot: <scanner bot>, from: "schedule:0 2 * * *"} intake: dedup_key: [cve, package] severity_policy: max reopen_window_days: 30 min_severity: High grouping: {release: on_run_end, key: [application], strategy: hint, max_size: 15, solo: [Critical]} start: fix stages: fix: {bot: <fix bot>} merge: {bot: <pr watch bot>, wait: {for: [pr.merged, pr.closed], timeout: 72h}} verify: {bot: <verify bot>, status: VERIFYING} escalate: {bot: <escalation bot>} risk: {terminal: true} close: {terminal: true} transitions: fix: - {when: "outputs.result == pr_opened", go: merge} - {otherwise: true, go: escalate} merge: - {when: "outputs.state == merged", go: verify} - {otherwise: true, go: escalate} verify: - {when: "outputs.passed == true", go: close} - {when: "outputs.passed == false", go: fix} - {otherwise: true, go: escalate} escalate: - {when: "outputs.decision == retry", go: fix} - {when: "outputs.decision == accept_risk", go: risk} - {otherwise: true, go: escalate} interrupts: - {on: task.timer, kind: sla_breached, go: escalate} - {on: task.timer, kind: wait_timeout, go: escalate} limits: max_visits: {fix: 3, merge: 3, escalate: 2} max_concurrent: {fix: 5} policy: sla_hours: {Critical: 24, High: 72} budget: {monthly_usd: 200} approver_source: fixed default_approver: secops@acme.com tool_approval: {merge_pull_request: needs_approval} context: repos: [{repo_url: github.com/acme/payments-api, base_branch: main}]
Sections
| Section | What it sets |
|---|---|
metadata | The harness name, its application and its type |
inputs | The bots that bring work in, and how they start |
intake | How new findings are deduplicated, how severity is kept, when a closed finding reopens, the lowest severity that is worked, and grouping |
start | The first stage a new task enters |
stages | Each step, with the bot that runs it |
transitions | Where a task goes after a stage, based on the stage bot's answer |
interrupts | Rules that move a task from any stage |
reactions | Bots that run on the side without moving the task |
watchers | Scheduled bots that look across all tasks |
limits | Visit and concurrency limits per stage |
policy | Deadlines, budget, approvers and tool approvals |
context | Facts every bot of the harness receives, such as repositories |
Inputs
from | Meaning |
|---|---|
schedule:<cron> | The bot runs on this schedule. The harness owns it. |
schedule | The bot keeps its own schedule. |
webhook | An outside system sends events; switching the harness on creates the listener. |
github.*, gitlab.*, jira.*, servicenow.*, ticket.* | An event from the harness's repository or ticket webhook starts the bot. |
Grouping
| Work arrives as | Use |
|---|---|
| A run that records many findings, such as a scan | {release: on_run_end, key: [application], strategy: hint, max_size: 15} |
| Events that trickle in about one thing, such as reports of one phishing campaign | {key: [sender_domain, subject_hash], window_minutes: 60} |
| One independent item per event | no grouping |
release: on_run_endholds a scan's findings until the scan ends, then groups them.strategy: hintlets the scanner say which findings belong to one change, through agroup_hinton each finding.max_sizecaps a group; larger sets are split, worst severity first.soloseverities are always worked alone.- A group never mixes applications or repositories.
- Each finding closes on its own result. Unfixed findings wait for the next group, and go to a person after
max_rounds(2 by default). follow_stageslists final stages where every finding takes the group's outcome, such as an accepted-risk stage.
Stages
| Field | Meaning |
|---|---|
bot | The bot that runs the stage |
terminal: true | A final stage; the task closes here |
wait: {for: [...], timeout: ...} | After its bot works, the stage waits for an event, such as pr.merged, or the timeout |
status | The task status while in the stage, such as VERIFYING |
A stage named escalate marks the task as escalated, and is where a task goes when a stage reaches its visit limit.
Transitions and conditions
Transitions are checked in order; the first that matches wins, and each stage ends with otherwise. Conditions can test the stage bot's declared outputs (outputs.*), task fields (task.*, before.*, after.*) and event fields (event.*), with == != > >= < <= in, not in, contains, AND, OR, NOT.
Interrupts
| Interrupt | Fires when |
|---|---|
{on: task.timer, kind: sla_breached} | The task's deadline passes |
{on: task.timer, kind: idle_for, status: WAITING_HUMAN, hours: 48} | A task has waited on a person for 48 hours |
{on: task.timer, kind: wait_timeout} | A stage's wait.timeout passes |
{on: task.external, kind: pr.merged} | An event arrives for the task's linked pull request or ticket |
{on: task.reopened} | A closed finding is seen again |
{on: task.changed, watch: [severity], when: ...} | A watched field changes |
Policy
| Field | Meaning |
|---|---|
sla_hours | The time allowed per severity |
budget.monthly_usd | New runs wait once the month's spend reaches it |
approver_source | owner (the task owner), fixed (default_approver) or on_call |
tool_approval | Per tool: needs_approval or deny. It can only tighten what a bot is allowed. |
Rules the platform checks
A template can't be saved if:
- a stage has no bot and isn't final, or doesn't end with
otherwise, - a stage can't be reached from
start, - a loop has no
max_visits, - a condition tests an output the stage's bot doesn't declare,
- a
wait_timeoutinterrupt has no stage with await.timeout, - a stage or reaction bot has a schedule of its own, or the same bot is both an input and a stage.
Switching a harness on also needs every bot turned on.
The platform warns, without blocking, when an answer a bot can give has no route of its own and falls into an otherwise that closes the task, or when a template declares no inputs.
Good practice
- Never send
otherwiseto a final stage. Send it to a stage where a person looks, so an unexpected answer is never closed as done. - Give every answer a bot can give its own route.
- Follow every change with a verify stage run by a different bot.
- Give every wait a way out: a
wait.timeout, or anidle_forinterrupt for a person who doesn't answer. - Declare scanners under
inputs, so the harness owns their schedule and can group their runs.