CAVISE/CAVISE -- -- --

Attack Configuration Reference

This document describes the YAML format currently supported by the adversary framework in opencda/core/attack/adversary_framework.

Each attack config file must contain one top-level attack object.

Example

attack:
  name: aim_client_request_speed_spoofing

  requirements:
    all:
      - source:
          kind: snapshot
          node_type: rsu
          service_type: aim_server
        verb: exists
      - source:
          kind: snapshot
          node_type: vehicle
          service_type: aim_client
        verb: exists

  start_trigger:
    source:
      kind: snapshot
      node_type: rsu
      service_type: aim_server
      field: tracked_vehicle_count
    verb: increased
    value: 1

  stop_trigger:
    source:
      kind: snapshot
      node_type: rsu
      service_type: aim_server
      field: tracked_vehicle_count
    verb: eq
    value: 0

  targets:
    kind: service_state_field
    source:
      kind: snapshot
      node_type: rsu
      service_type: aim_server
      field: tracked_vehicle_ids
    resolve_to:
      node_type: vehicle
      service_type: aim_client
    selection: all

  stages:
    - id: spoof_aim_client_requests
      type: spoofer
      capabilities:
        - request.submit
      params:
        rewrites:
          - path: payload.speed
            operation: add
            value: 5.0
          - path: payload.yaw
            operation: add
            value: 10.0
      stage_stop_trigger:
        source:
          kind: snapshot
          node_type: rsu
          service_type: aim_server
          field: tracked_vehicle_count
        verb: eq
        value: 0

Top-Level Attack Fields

attack.name

Type: string | Required: yes
Meaning: Unique runtime attack name.

attack.requirements

Type: ConditionSpec | Required: no
Meaning: Preconditions that must be satisfied before the attack may start.
Default: If omitted, requirements are treated as satisfied.

attack.start_trigger

Type: ConditionSpec | Required: effectively yes
Meaning: Condition that starts the attack.
Default: If omitted, the attack never starts.

attack.stop_trigger

Type: ConditionSpec | Required: no
Meaning: Condition that stops an active attack before stage execution on that tick.
Default: If omitted, there is no attack-level stop trigger.

attack.targets

Type: TargetSpec | Required: usually yes
Meaning: Describes how live target services are resolved from the current snapshot.
Default: If omitted, no target services are resolved.

attack.stages

Type: list[StageSpec] | Required: no
Meaning: Ordered list of attack stages.
Default: Empty list.

Condition Specification

Conditions are used by:

  • attack.requirements

  • attack.start_trigger

  • attack.stop_trigger

  • stage.requirements

  • stage.stage_start_trigger

  • stage.stage_stop_trigger

A condition can be:

  • a leaf predicate,

  • an all group,

  • an any group.

Leaf predicate example

source:
  kind: snapshot
  node_type: rsu
  service_type: aim_server
  field: tracked_vehicle_count
verb: increased
value: 1

Grouped condition example

all:
  - source:
      kind: snapshot
      node_type: rsu
      service_type: aim_server
    verb: exists
  - any:
      - source:
          kind: snapshot
          node_type: vehicle
          service_type: aim_client
        verb: exists
      - source:
          kind: snapshot
          node_type: vehicle
          service_type: movement_controller
        verb: exists

Rules

  • A condition must define either a leaf predicate, all, or any.

  • all and any cannot appear at the same level together.

  • Nested condition groups are supported.

Source Fields

Every leaf predicate contains a source object.

source.kind

Type: string | Required: yes
Supported values: snapshot, attack, stage

Snapshot Sources

Snapshot sources read values from the current or previous SimulationSnapshot.

Example:

source:
  kind: snapshot
  node_type: rsu
  node_id: rsu-1
  service_type: aim_server
  field: tracked_vehicle_count

source.node_type

Type: string | Required: no
Supported values: vehicle, rsu
Meaning: Restricts matching nodes by type.
Default: If omitted, both vehicle and RSU nodes are searched.

source.node_id

Type: string | Required: no
Meaning: Restricts matching nodes by exact node id.

source.service_type

Type: string | Required: no
Meaning: Reads data from the state of one behavior service.

source.field

Type: string | Required: no
Meaning: Field to read from the matched object.

Notes:

  • If service_type is set, field is read from that service’s state map.

  • If service_type is omitted, field is read from the matched NodeSnapshot.

  • If field is omitted, the whole matched object is used.

  • Current node-level snapshot fields are node_id, node_type, and service_states.

Attack Sources

Attack sources read runtime fields from the current attack instance.

Example:

source:
  kind: attack
  attack_name: aim_client_response_sniffer
  field: status

source.attack_name

Type: string | Required: no
Meaning: Restricts the condition to a specific attack name.
Default: If omitted, the current attack is used.

source.field

Type: string | Required: usually yes
Stable supported value: status

Stage Sources

Stage sources read runtime fields from one or more stages of the current attack.

Example:

source:
  kind: stage
  attack_name: aim_client_response_sniffer
  stage_id: sniff_aim_client_responses
  field: status

source.attack_name

Type: string | Required: no
Meaning: Restricts the condition to a specific attack name.

source.stage_id

Type: string | Required: no
Meaning: Restricts the condition to one configured stage id.
Default: If omitted, all stages of the current attack are considered.

source.field

Type: string | Required: usually yes
Stable supported value: status

Supported Verbs

Snapshot verbs

The following verbs are supported for source.kind: snapshot:

  • exists

  • eq

  • gt

  • gte

  • lt

  • lte

  • changed

  • increased

  • decreased

  • became

  • added

  • removed

Notes:

  • increased and decreased compare the current snapshot with the previous tick.

  • added and removed are intended for collection-like values.

Runtime verbs

The following verbs are supported for source.kind: attack and source.kind: stage:

  • exists

  • eq

  • gt

  • gte

  • lt

  • lte

  • changed

  • became

  • increased

  • decreased

Notes:

  • added and removed are not supported for runtime sources.

  • increased and decreased use delta 1 if value is omitted.

The value Field

value

Type: any | Required: depends on the verb
Meaning: Comparison target or delta parameter.

Typical usage:

  • eq, gt, gte, lt, lte: value should be provided.

  • increased, decreased: value is the minimum delta.

  • became: value is the new value that must appear this tick.

  • added, removed: value is the specific collection item.

Target Specification

Targets describe how the attack resolves live behavior service instances.

Example:

targets:
  kind: service_state_field
  source:
    kind: snapshot
    node_type: rsu
    service_type: aim_server
    field: tracked_vehicle_ids
  resolve_to:
    node_type: vehicle
    service_type: aim_client
  selection: first

targets.kind

Type: string | Required: yes
Currently supported value: service_state_field

targets.source

Type: TriggerSourceSpec | Required: yes
Meaning: Snapshot source whose value must resolve to one node id or a collection of node ids.

targets.resolve_to

Type: object | Required: yes
Meaning: Describes which live services are resolved for every target node id.

targets.resolve_to.node_type

Type: string | Required: yes
Expected values: vehicle, rsu
Meaning: Informational type hint used by diagnostics and availability logging.

targets.resolve_to.service_type

Type: string | Required: no
Meaning: Optional service filter passed to the runtime service resolver.
Default: If omitted, all behavior services of each resolved node are returned.

targets.selection

Type: string | Required: no
Supported values: all, first
Default: all

Notes:

  • service_state_field target resolution normalizes the source value into a set of node ids.

  • A scalar string becomes one target node id.

  • A tuple, list, set, or frozenset contributes every string item it contains.

Stage Specification

Each item in attack.stages describes one stage in the ordered runtime pipeline.

Example:

stages:
  - id: spoof_selected_aim_client_position
    type: spoofer
    capabilities:
      - request.submit
    params:
      rewrites:
        - path: payload.position.x
          operation: add
          value: -20.0
    requirements: ...
    stage_start_trigger: ...
    stage_stop_trigger: ...

stage.id

Type: string | Required: yes
Meaning: Unique stage id inside the attack.
Notes: Duplicate ids are rejected.

stage.type

Type: string | Required: yes
Currently built-in: sniffer, dropper, replayer, spoofer

stage.capabilities

Type: list[string] | Required: no
Meaning: Explicit capability set used to match target services.
Default: If omitted, the stage’s built-in default capabilities are used.

The current capability vocabulary is:

  • request.observe

  • request.submit

  • response.observe

  • response.submit

  • command.submit

  • state.observe

stage.params

Type: mapping | Required: no
Meaning: Stage-specific configuration payload.

Builtin stage params:

  • sniffer: no params

  • replayer: no params

  • dropper: drop_rate (float in [0.0, 1.0], default 1.0), optional seed

  • spoofer: required rewrites sequence

stage.requirements

Type: ConditionSpec | Required: no
Meaning: Additional preconditions for this stage only.
Default: No extra stage-level requirement.

stage.stage_start_trigger

Type: ConditionSpec | Required: no
Meaning: Explicit condition for starting this stage.
Default: The first stage starts when the attack becomes active. Every later stage starts when the previous stage reaches success.

stage.stage_stop_trigger

Type: ConditionSpec | Required: no
Meaning: Explicit condition for stopping an active stage.
Default: A successful execute() immediately marks the stage as success.

Spoofer Rewrite Rules

spoofer stages use params.rewrites. Each rewrite rule must contain:

  • path: dot-separated field path such as payload.position.x

  • operation: set, add, or multiply

  • value: operand for the selected operation

Example:

params:
  rewrites:
    - path: src_owner_id
      operation: set
      value: cav-spoofed
    - path: payload.speed
      operation: add
      value: 8.0

Runtime Status Values

Use the following values when checking field: status in attack or stage conditions:

  • inactive

  • active

  • success

  • fail

  • stopped

Note:

  • The runtime also uses an internal STARTED state, but condition evaluation normalizes it to active.

Default Runtime Behavior

Attack defaults

  • Omitted requirements means requirements are treated as satisfied.

  • Omitted start_trigger means the attack never starts.

  • Omitted stop_trigger means there is no attack-level stop trigger.

  • Omitted targets means no target services can be resolved.

Stage defaults

  • Omitted requirements means no extra stage-level requirement.

  • Omitted stage_start_trigger means:

    • the first stage starts when the attack is active,

    • later stages start after the previous stage succeeds.

  • Omitted stage_stop_trigger means a successful execute() immediately marks the stage as success.

Target resolution failure

If an attack start trigger fires but target resolution returns no services, the framework reports that attack execution as failed for the current tick.