anti
c2891d6cca
v0 Phase 1 of ATTRIBUTION-ENGINE.md:
* AttributionStateRow SQLModel keyed on (identity_uuid, primitive)
per ANTI direction — re-keying state rows when the v1 clusterer
merges attackers is the migration debt v0 should not bake in.
ATTRIBUTION-ENGINE.md updated with the deviation note.
* AttributionMixin: ensure_stub_identity_for_attacker, idempotent
upsert_attribution_state, get_attribution_state[_for_identity],
list_multi_actor_identities (the Phase 5 correlator's read).
* attribution.profile.{state_changed,multi_actor_suspected} bus
topics + builder; wiki Service-Bus.md updated separately.
* attribution_worker.py: subscribes to attacker.observation.>,
ensures stub identity per event, logs and continues. No merger,
no state writes, no derived events — Phase 4 wires those.
* attribution/{aggregate.py,_thresholds.py} skeletons: Phase 2
fills _aggregate_categorical, Phase 3 adds numeric+hash+dispatcher.
79 lines
3.6 KiB
Python
79 lines
3.6 KiB
Python
"""Per-(identity, primitive) attribution state — v0 of the
|
|
attribution engine.
|
|
|
|
Materialised view of the state machine in
|
|
``decnet.correlation.attribution.aggregate``. Re-derivable from
|
|
``observations`` + the DEBT-032 fingerprint-rotation log; this row is
|
|
a cache for cheap dashboard reads, not a source of truth.
|
|
|
|
Keyed on ``identity_uuid``, not ``attacker_uuid``: pre-clusterer,
|
|
every Attacker maps 1:1 to a stub row in ``attacker_identities``
|
|
(``merged_into_uuid = NULL``) so the key is stable across the v0 / v1
|
|
boundary. When v1's clusterer eventually merges identities, the loser
|
|
row's state is recomputed from the union of observations under the
|
|
winner — no schema change, no column-rename migration.
|
|
|
|
This deviates from ``development/ATTRIBUTION-ENGINE.md`` §"Subject of
|
|
attribution in v0" (which resolved on ``attacker_uuid``); the doc gets
|
|
a deviation note in the same commit that ships this file.
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
from datetime import datetime, timezone
|
|
from typing import Any
|
|
|
|
from sqlalchemy import JSON, Column, Index
|
|
from sqlmodel import Field, SQLModel
|
|
|
|
|
|
class AttributionStateRow(SQLModel, table=True):
|
|
"""One state row per (identity, primitive). At most one row per
|
|
pair — composite PK enforces it.
|
|
"""
|
|
|
|
__tablename__ = "attribution_state"
|
|
__table_args__ = (
|
|
Index("ix_attribution_state_state", "state"),
|
|
Index("ix_attribution_state_last_change", "last_change_ts"),
|
|
Index(
|
|
"ix_attribution_state_identity_state",
|
|
"identity_uuid", "state",
|
|
),
|
|
)
|
|
|
|
# ── key ────────────────────────────────────────────────────────────
|
|
identity_uuid: str = Field(
|
|
foreign_key="attacker_identities.uuid", primary_key=True,
|
|
)
|
|
primitive: str = Field(primary_key=True)
|
|
|
|
# ── derived state ──────────────────────────────────────────────────
|
|
# Mirrors the BEHAVE Observation ``value`` column shape so the
|
|
# frontend can render the merger output the same way it renders raw
|
|
# latest-wins values today (BEHAVE-INTEGRATION.md Q3).
|
|
current_value: dict[str, Any] | str | int | float | bool | list = Field(
|
|
sa_column=Column(JSON, nullable=False),
|
|
)
|
|
# 'unknown' | 'stable' | 'drifting' | 'conflicted' | 'multi_actor'.
|
|
# Five states, frozen — see ATTRIBUTION-ENGINE.md §"State machine".
|
|
state: str
|
|
# Engine's confidence in the *state assertion*, not in any verdict
|
|
# about the attacker. ``multi_actor`` is capped at 0.6 by
|
|
# convention; other states use the merger's per-ValueKind formula.
|
|
confidence: float
|
|
# How many observations underlie this row. Used by the API to gate
|
|
# ``unknown`` (< 3 obs) without re-querying ``observations``.
|
|
observation_count: int = Field(default=0)
|
|
# When ``state`` last flipped. Equals ``updated_at`` on insert.
|
|
last_change_ts: float
|
|
# Most recent observation that fed this row. Used by the merger to
|
|
# detect drift windows without a full observation re-scan.
|
|
last_observation_ts: float
|
|
|
|
# ── audit ──────────────────────────────────────────────────────────
|
|
# Mirrors AttackerIdentity convention (federation gossip in v2).
|
|
schema_version: int = Field(default=1)
|
|
updated_at: datetime = Field(
|
|
default_factory=lambda: datetime.now(timezone.utc),
|
|
)
|