Build and run / Harnesses

Harness templates

Updated 28 Oct 20264 min read

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

yaml
apiVersion: 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

SectionWhat it sets
metadataThe harness name, its application and its type
inputsThe bots that bring work in, and how they start
intakeHow new findings are deduplicated, how severity is kept, when a closed finding reopens, the lowest severity that is worked, and grouping
startThe first stage a new task enters
stagesEach step, with the bot that runs it
transitionsWhere a task goes after a stage, based on the stage bot's answer
interruptsRules that move a task from any stage
reactionsBots that run on the side without moving the task
watchersScheduled bots that look across all tasks
limitsVisit and concurrency limits per stage
policyDeadlines, budget, approvers and tool approvals
contextFacts every bot of the harness receives, such as repositories

Inputs

fromMeaning
schedule:<cron>The bot runs on this schedule. The harness owns it.
scheduleThe bot keeps its own schedule.
webhookAn 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 asUse
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 eventno grouping
  • release: on_run_end holds a scan's findings until the scan ends, then groups them.
  • strategy: hint lets the scanner say which findings belong to one change, through a group_hint on each finding.
  • max_size caps a group; larger sets are split, worst severity first. solo severities 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_stages lists final stages where every finding takes the group's outcome, such as an accepted-risk stage.

Stages

FieldMeaning
botThe bot that runs the stage
terminal: trueA 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
statusThe 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

InterruptFires 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

FieldMeaning
sla_hoursThe time allowed per severity
budget.monthly_usdNew runs wait once the month's spend reaches it
approver_sourceowner (the task owner), fixed (default_approver) or on_call
tool_approvalPer 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_timeout interrupt has no stage with a wait.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 otherwise to 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 an idle_for interrupt for a person who doesn't answer.
  • Declare scanners under inputs, so the harness owns their schedule and can group their runs.

Next steps

Need a hand with this?Our engineers can walk through it with you on your own stack.