Engagement profiles

An engagement profile tells rupu what kind of thing an engagement is about — source code, a binary, a network, a web application, a cloud account, a threat model — and therefore what a complete finding about it looks like.

Concepts

A profile is a small TOML file. It declares the asset kinds that exist in its domain, the coordinates that pin each one down, a completeness checklist that every finding must pass, and a depth ladder that records how far each asset has been examined. rupu ships 15 profiles. You can override any of them, or add your own by writing a TOML file — no Rust needed.

• Asset. A finding is always about something: a file, a function at an address, a service on a host, a route, a cloud resource. That thing is an asset. It has a kind, a locator and, optionally, a depth.
• Kind. Every kind belongs to a profile and carries its namespace: network:service, web:route, binary:function. Kinds can form a hierarchy within their profile (a service sits under a host).
• Routing. When a finding names an asset, its kind’s namespace picks the profile that owns it. That profile, and only that profile, judges the finding.
• Validation. The owning profile’s required completeness checks run against the finding’s report and the asset’s locator. A finding that fails is rejected, and the error lists each unmet check, so the agent can fix it and record it again.
• Depth. Each profile has a depth ladder, such as discovered → enumerated → tested → exploited. It records how deeply each asset was examined, separately from any findings about it.

Coordinates

A locator is the set of typed coordinates that pins an asset down. The core knows exactly 13 coordinate types, and every profile builds on them. Each is written as {"t": <tag>, "v": <value>}. A locator can be empty — a threat-model component has no coordinates at all.

Selecting profiles

rupu run --engagement-profile binary  firmware-re "reverse ./dist/updater.bin"
rupu run --engagement-profile network recon       "map 10.20.0.0/24"
rupu run --engagement-profile network,web assessor "..."   # two profiles
rupu run --engagement-profiles pentest assessor    "..."   # a composite
rupu workflow run edge-sweep --engagement-profile network

• No selection gives the native code path. This is not the same as selecting code: no engagement is active, so asset_mark isn’t offered and asset arguments are ignored.
• An unknown id fails the launch. It never falls back to a default.
• A kind claimed twice is an error. pentest,network fails because pentest already includes network.
• Overlay profiles load at launch. If a discovered profile file fails to parse, the launch fails, even if you didn’t select that profile.

The built-in catalog

code is the default. Each asset-kind entry gives its locator coordinates, with its parent kind in parentheses where it has one.

Completeness, evidence and taxonomies

Every built-in check is required, and report_finding enforces them. Evidence blocks and taxonomies are advisory: rupu enforces them only when a check names one. Taxonomy matching ignores case, and a report’s legacy cwe list counts as CWE.

Every built-in profile also declares a [bundle]: the agents and workflows an engagement of that kind typically uses. A bundle never grants tools. The stock security fleet is built from these bundles, and rupu’s own tests keep the two in lockstep.

Composites and routing

A composite is a profile with an includes list. Selecting one is shorthand for selecting its members, and each member stays its own routing target — the members are not merged. During a pentest run, a network:service finding is judged by network’s checks and a web:route finding by web’s. mobile adds its own root kind, mobile:package, alongside binary and web. includes is transitive; an include cycle, or an include of a profile that doesn’t exist, is a load error.

The stock security fleet

A profile says what a complete finding looks like; it doesn’t ship anyone to find them. The stock fleet does: 18 generic security-assessment agents and 3 workflows, one set for every built-in bundle. Install it once and every engagement, in any project, can draw on it.

rupu fleet list                    # what the fleet ships
rupu fleet install                 # into ~/.rupu (or $RUPU_HOME)
rupu fleet install --project       # into this project's .rupu/ instead
rupu fleet install --force         # re-seed files you've edited

The fleet is plain files: agents/<name>.md and workflows/<id>.yaml, written exactly where rupu’s loaders look. A file that already exists is kept, so your edits survive a reinstall; each file is reported as CREATED, SKIPPED or OVERWROTE. --force overwrites them with the shipped versions. --project needs a .rupu/ (run rupu init first), and a project copy shadows the global one, as for any agent or workflow.

• Specialists each do one job inside the authorized scope they’re given. Discovery agents (recon, crawler) map and asset_mark what they find but don’t test; analysts and testers verify before they report_finding, pinned to the asset with the evidence and classification their profile’s checks require; exploit-verifier independently confirms or refutes claimed exposures. Destructive testing is ruled out in every prompt.
• assessment-lead is a generic agentiflow lead. It reads the scope and goals, lists the pool with agents.list / workflows.list rather than assuming names, then works in rounds — map, analyze in parallel batches, verify — until the scope is swept or the budget runs low.
• The workflows chain the same agents for a fixed run: network-assessment is recon → analyze → verify, web-assessment is crawl → test, and api-assessment is a single assess step. Each takes one required input, scope.
• Every fleet agent runs in bypass mode with a wide tool grant (* plus the findings and asset tools). That suits an authorized lab engagement; for anything else, read the files and narrow them before you run them.

Run a workflow under its profile so the asset and findings tools are active:

rupu fleet install
rupu workflow run web-assessment --engagement-profile web \
  --input scope="https://staging.example.test (exclude /admin/billing)"

Or hand the whole pool to the lead in an agentiflow:

# .rupu/agentiflows/lab-sweep.yaml (excerpt)
lead: assessment-lead
engagement_profiles: [network]
pool:
  agents: [assessment-lead, recon, service-analyst, exploit-verifier]
  workflows: [network-assessment]

Recording assets

Two tools write assets, both to the target’s asset ledger, .rupu/coverage/<target>/assets.jsonl, next to findings.jsonl.

report_finding with an asset

When an engagement is active, report_finding takes an optional asset. So does the MCP findings.record tool a workflow action: step calls, with the same schema and handling.

{
  "scope": "edge-sweep",
  "report": { /* a complete finding report */ },
  "asset": {
    "kind": "network:service",
    "coordinates": [
      { "t": "host", "v": "198.51.100.20" },
      { "t": "port", "v": { "number": 8443, "proto": "tcp" } }
    ],
    "label": "198.51.100.20:8443 admin console"
  }
}

When an engagement is active, rupu:

1. Routes the finding by its namespaced kind. If no active profile owns the kind, the call fails, and the error names the active set.
2. Checks completeness. Every required check of the owning profile is evaluated under the full finding profile. If any check fails, the finding is rejected with the labels of the failing checks. Under summary there’s no report to evaluate, so this step is skipped.
3. Stamps the asset into assets.jsonl and the run’s coverage stream, so a coordinator collecting a remote unit receives it. The new line keeps the asset’s existing depth, parent, attributes and label, unless the call supplies a new label.

The finding record itself does not store an asset id. When no engagement is active, asset is ignored. When an engagement is active but the finding has no asset, it records on the plain path without a completeness check. rupu findings import records no asset.

asset_mark

{ "kind": "web:route",
  "coordinates": [ { "t": "url", "v": "https://shop.example.test" },
                   { "t": "http_route", "v": { "method": "POST", "path": "/cart/apply" } } ],
  "depth": "tested" }

depth must be a rung of the owning profile’s ladder; any other value is an error that lists the ladder. Depth only moves forward: if an asset is already at exploited, marking it tested leaves it at exploited, and the tool returns the rung that ends up recorded (effective_depth). The engine offers asset_mark and report_finding to every agent in an engagement run, whatever the agent’s tools: list says. Without an active engagement, asset_mark doesn’t exist.

The ledger and its views

assets.jsonl only ever gets appended to, one full asset per line (id, kind, parent, locator, label, depth, attributes). When the file is read, the last line for each id wins. An asset’s id is <kind>:<16 hex>, derived from the kind plus the sorted locator, so the same host and port always map to the same asset, across reruns too. The profile’s label template is declarative and isn’t rendered: an asset’s label is whatever the caller passed, or else its kind.

Remote units’ asset lines arrive through the coverage stream and are merged into the coordinator. The control plane’s Security → Assets page lists every asset from every registered workspace, and an agentiflow’s Assets tab shows the same data for one run (both use GET /api/assets). Agentiflow coverage goals measure this ledger.

Writing a profile

Where profiles live

rupu identifies a profile by its id field; the file name doesn’t matter. A later source with the same id replaces the earlier profile completely — nothing is merged — so to change one check of a built-in, copy the whole built-in and edit the copy. Within one directory, files load in name order, and the last one wins. Only *.toml files are read, and a missing directory is fine.

Schema

All keys are strict: an unknown key in any table is a parse error. Put the top-level keys before the first [[asset_kinds]], or TOML assigns them to that kind and the file fails to parse.

Predicates

That is the whole predicate grammar. It isn’t meant to grow into a scripting language.

Failure modes

Worked example: an IoT fleet engagement

The profile below is invented for this guide. It covers fleets of embedded devices: a device is found by its address, it exposes services, and each firmware build is identified by its hash. Save it as .rupu/profiles/iot-fleet.toml:

id = "iot-fleet"
name = "IoT device fleet assessment"
evidence_blocks = ["text", "scan_output", "hexdump", "http_exchange", "table"]
classification_systems = ["CWE", "CVE"]

[[asset_kinds]]
id = "device"
coordinates = ["host"]
label = "{host}"

[[asset_kinds]]
id = "service"
parent = "device"
coordinates = ["host", "port"]
label = "{host}:{port}"

[[asset_kinds]]
id = "firmware"
parent = "device"
coordinates = ["host", "sha256"]
label = "{sha256}"

[[completeness]]
id = "pinned"
label = "Pinned to a device service or a firmware build"
satisfied_when = { all = [
  { locator_has_coordinate = "host" },
  { any = [ { locator_has_coordinate = "port" }, { locator_has_coordinate = "sha256" } ] },
] }

[[completeness]]
id = "evidence"
label = "Scan output, hexdump or HTTP exchange attached"
satisfied_when = { any = [
  { has_block_kind = "scan_output" },
  { has_block_kind = "hexdump" },
  { has_block_kind = "http_exchange" },
] }

[[completeness]]
id = "classified"
label = "Classified (CWE or CVE)"
satisfied_when = { any = [ { has_classification_system = "CWE" }, { has_classification_system = "CVE" } ] }

[[completeness]]
id = "has_fix"
label = "Remediation for high-severity issues"
required = false        # informational: not evaluated
satisfied_when = { has_field = "remediation" }

[coverage]
enumerates = ["device", "service", "firmware"]
depth_ladder = ["discovered", "fingerprinted", "tested", "exploited"]

rupu run --engagement-profile iot-fleet fleet-recon "assess the lab segment 192.0.2.0/28"

During the run, the agent might call asset_mark with kind iot-fleet:device, host 192.0.2.7 and depth fingerprinted, then call report_finding with an iot-fleet:service asset pinned by host and port 23/tcp, and a report that has a scan_output block and a CWE classification. If the agent omits the port and the hash, the finding is rejected with Pinned to a device service or a firmware build, and the agent can add the missing coordinates and try again.

Profiles, finding profiles and concern catalogs

Three separate rupu features have names that sound alike. They don’t depend on each other:

Completeness checks run only on a full report (see Findings); under summary an asset is still routed and recorded, but its checks are skipped. Concern catalogs are lists of things to check (see Coverage). They’re independent of the engagement: a code engagement can use owasp-top10-2021, and so can a run with no engagement. The bundled catalogs (rupu coverage templates list, or show <name> to print one):