Attack Framework

The adversary framework executes declarative, event-driven attacks against live behavior services in the simulation runtime. Attack behavior is described in YAML, converted into structured specs, and evaluated on every simulation tick against a normalized snapshot of vehicle and RSU service state.

The framework is generic at the orchestration layer. See module-level architecture, Behavior Services for the behavior-service lifecycle and development template, Available Attacks for the builtin attack catalog, and Attack Configuration Reference for the YAML reference.

Enabling Attacks

Scenario configs enable attacks through the top-level attacks list:

attacks:
  - aim_server_response_jamming
  - aim_client_identity_spoofing

Each attack name is resolved to:

opencda/core/attack/adversary_framework/attacks/<attack-name>/config.yaml

At scenario startup, each YAML file is loaded, parsed into an AttackSpec, and converted into a runtime Attack object via Attack.from_spec(...).

Runtime Integration

The framework is evaluated from the main scenario loops. On each tick, the scenario code:

1. updates vehicle and RSU behavior services,

2. builds a SimulationSnapshot,

3. calls AttackManager.evaluate(...),

4. resolves live target services through CavWorld.resolve_behavior_services.

The overall per-tick attack evaluation workflow is shown below.

The snapshot passed to the attack framework has the following structure:

@dataclass(frozen=True, slots=True)
class NodeSnapshot:
    node_id: str
    node_type: str
    service_states: dict[str, Any]

@dataclass(frozen=True, slots=True)
class SimulationSnapshot:
    tick: int
    vehicle_nodes: tuple[NodeSnapshot, ...]
    rsu_nodes: tuple[NodeSnapshot, ...]

service_states contains the latest get_state() outputs of attached behavior services, keyed by service_type.

Core Components

AttackManager

AttackManager owns the previous snapshot and advances all configured attacks against the current snapshot. It is responsible for:

• checking attack start and stop triggers,

• resolving target services for attacks that should run,

• executing active stages,

• emitting AttackResult objects,

• logging success, stop, and failure outcomes.

If an attack start trigger fires but no target services can be resolved for that tick, the manager reports that attack execution as failed.

Attack

Attack is the runtime object built from AttackSpec. It stores:

• the parsed spec,

• runtime lifecycle state,

• ordered stage runtimes,

• per-stage last results.

The default lifecycle is:

• an inactive attack may start when its requirements and start trigger are satisfied,

• the first stage starts when the attack becomes active,

• every later stage starts after the previous stage reaches success,

• an attack stops when its stop trigger fires,

• an attack succeeds when all stages complete successfully.

ConditionEvaluator

Conditions are evaluated against:

• the current and previous SimulationSnapshot,

• the current attack runtime,

• the current stage runtimes.

Supported source kinds are snapshot, attack, and stage.

TargetResolver

Target resolution currently supports one strategy: service_state_field. The resolver:

1. reads one snapshot field,

2. normalizes its value into one or more node ids,

3. resolves live behavior services for those node ids,

4. optionally filters by service_type.

Builtin Stages

Builtin stages are auto-registered through AttackStageRegistry when the framework module is imported.

sniffer

Passive observer that records outputs returned by matched capability handlers.

• Default capability: response.observe

• Supported capabilities: request.observe, request.submit, response.observe, response.submit, command.submit, state.observe

• Parameters: none

dropper

Replaces selected outputs with an empty batch or probabilistically drops items from iterable outputs.

• Default capability: response.submit

• Supported capabilities: request.observe, request.submit, response.observe, response.submit, command.submit

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

replayer

Replays the previous output seen on each matched service/capability binding.

• Default capability: response.submit

• Supported capabilities: request.observe, request.submit, response.observe, response.submit, command.submit

• Parameters: none

spoofer

Rewrites selected fields inside TransportMessage envelopes or payloads.

• Default capability: request.submit

• Supported capabilities: request.submit, response.submit, command.submit

• Parameters: required rewrites list with per-rule path, operation, and value

Capabilities

The current cross-service capability vocabulary is:

• request.observe

• request.submit

• response.observe

• response.submit

• command.submit

• state.observe

Stages declare the capabilities they need, and the framework matches them against each target service’s capability_bindings map.

Interception Model

Stages do not mutate the framework itself. Instead, they temporarily wrap the bound methods exposed by behavior-service capability bindings.

In practice, builtin stages install output interceptors on the resolved target service instances and remove them later through deactivate() or when the attack is stopped.

Results and Logging

The framework emits AttackResult objects with:

• attack_name

• status

• reason

• stage_history

Result statuses are:

• success

• fail

• stop

Attack and stage runtime conditions use lifecycle status values such as inactive, active, success, fail, and stopped. Internally, the runtime also has a STARTED state, but condition evaluation normalizes it to active.

The scenario loop currently relies on framework logging for visibility into attack execution.