Build and run / Harnesses

Build a harness

Updated 28 Oct 20267 min read

Optimus builds harnesses for you. This guide walks through building one from start to finish, using an AppSec example. The same steps work for SOC, GRC, identity and cloud harnesses.

Time: about 30 to 60 minutes, most of it reviewing.

Before you start

  • Connect the systems the harness will use, such as your code repository, your email or chat tool and your AI model. See Integrations. For a harness that changes code, the repository account needs write access.
  • Know who approves. Have the email of the person, or team, who decides on risky changes.
  • Pick one application to start with, such as one repository or one service.

Step 1: Open the harness builder

Open Guardian > Harnesses and choose Build a harness at the top of the page. Pick a starting template (or Start from scratch), type the application the harness is for, and add anything Optimus should know. Then choose Open in Optimus.

Optimus opens a new conversation on its Build a Harness starter. The starter loads the Harness Guide and Bot Creation Guide skills, which teach Optimus how to plan, build, validate and test a harness, and fills in your request, such as "Build an AppSec harness from the appsec_sca template for application payments-api." Nothing is sent until you press send, so you can add to it first.

You can also start by hand: open a new Optimus conversation, and in its settings open Knowledge and add Harness Guide under Skills. Without the guide, Optimus learns the template by trial and error.

Step 2: Describe the outcome

Tell Optimus what you want in plain words. Include where the work comes from, what "done" means, and who decides. For example:

"Set up a harness for the payments-api repository. Scan it every night at 02:00 UTC with Trivy. Fix High and Critical findings in one pull request per change. Opening the pull request needs no approval, but merging is done by our team in GitHub. After the merge, re-scan to prove the fix. If nobody acts within two days, ask secops@acme.com."

Optimus then asks the questions it still needs, all in one message:

Optimus asks aboutWhy it matters
How findings are bundledOne fix per finding, per package, per repository or per scan. Bundling a scan avoids one bot run per finding.
The lowest severity to work, and the time allowed per severitySets what is routed and when it escalates
Who approves, who is next, and after how longBuilds the escalation path
What the bots may do without askingSteps that can be undone, such as opening a pull request, usually only need a notice. Steps that cannot, such as merging or revoking access, need approval.
What proves the work is doneThe check that runs after the change
When the scan runsOne schedule, owned by the harness
An older setup for the same applicationIt must be retired so two systems don't work the same findings

Step 3: Approve the plan

Optimus writes a plan and shows it to you before it creates anything. Check:

  • each stage, its bot and what each of its answers leads to,
  • the approver and the escalation times,
  • the check that proves a fix,
  • which tools need a person's approval.

Ask for changes until the plan is right, then approve it.

Step 4: Optimus builds and checks

Optimus now:

  1. Checks access with the exact accounts the bots will use, such as a test push to the repository.
  2. Builds the bots one at a time, reading each back to confirm its model, tools, accounts and time limits were saved as asked.
  3. Writes the template and validates it. Validation catches problems such as a stage with no way out, a loop without a limit, or a timeout that can never fire. Optimus fixes every warning before going on.
  4. Tests a bot on its own with a dry run, where every outside change and every task write is saved as a draft instead of being done.

Every bot Optimus creates is a normal bot you can open in Bots.

Step 5: Run preflight

On the Harnesses page, pick the harness and use Preflight (in the sidebar, or under Pending change). Preflight checks what the harness needs before it runs: that every bot exists and is set up, that the accounts work, and that its inputs and memory spaces are ready. Each check is marked pass, warning or fail, with the bot it concerns.

Apply draft runs the same checks. If one fails, the apply is stopped and the failing checks are shown. Fix them and apply again, or use Force apply if you accept the risk.

Step 6: Test in shadow

Optimus switches the harness to shadow and, with your permission, runs one small test, such as one scan or one finding. You can also set the state yourself with the State control on the Harnesses page.

To push one event in yourself, use Test event. Pick the input to send it through (or keep the harness default) and, if you like, paste a JSON payload; leave it empty for a sample event. When the event creates a task, its journey opens straight away; otherwise the event view shows which tasks it created or updated as they appear.

In shadow the bots really run, but anything that changes the outside world, such as opening a pull request or sending a message, is saved as a draft. Open the test task in Guardian and check:

  • the task took the path you expected (see Journey on the task),
  • the drafts look right,
  • every finding in a group got a result.

Step 7: Switch it on

Optimus can't activate a harness; a person does. Open Guardian > Harnesses, pick the harness and use Enable, or set State to Active. This turns on every bot of the harness and makes it active.

If the harness listens to your repository, open VCS webhook setup on the Harnesses page and add the URL and secret to your repository's webhook settings.

Step 8: Read the inventory

Optimus ends with a summary: the application, the harness and its state, each bot with its model, schedule and accounts, the webhook to configure, and what was and wasn't tested. Keep it with your runbook.

Start from a ready template

For common jobs, Optimus starts from a catalog template and fits it to your plan:

TemplateWhat it does
AppSec: dependency vulnerabilitiesGroups each scan, fixes in a pull request, waits for the merge, re-scans per finding
SOC: reported phishingGroups reports of one campaign, triages, contains and purges with approval, watches sign-ins
GRC: control evidenceCollects and reviews evidence per control, sends gaps to the owner
IAMOps: access reviewChecks use, asks the owner, revokes with approval, verifies
Cloud posture: misconfigurationsFixes through infrastructure-as-code pull requests or a direct change with approval, then re-checks

Build a harness on the Harnesses page lists these templates. You can also ask Optimus, for example: "Start from the reported-phishing template for our mail domain."

Roll a harness out with an org template

To run the same harness on many applications, save its template as an org template: on the Harnesses page, open Org templates, choose New org template, and give it a name, the harness type and a selector. The template is prefilled from the harness you have selected.

The selector chooses applications by their tags, for example {"tags": {"tier": "1"}}; empty tags match every application. Saving proposes a draft harness on every matching application, and on applications added later that match. Each draft is reviewed and applied like any other change.

Edit an org template to save a new version. The new version becomes a Pending change on every harness made from it; a person applies it on each.

Change a harness later

Use Edit in Optimus on the Harnesses page. It reopens the conversation that built the harness. Optimus proposes the change as a draft; the Harnesses page shows it under Pending change, where you can Replay 14 days to see how the change would have routed recent work, run Preflight, then Apply draft. Tasks already in a stage finish on the version they started with.

History lists every applied version. To go back, choose Restore as draft on an earlier version: it becomes the pending change, and you replay, preflight and apply it the same way.

Next steps

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