anti
7f585027b3
- core/README.md: envelope contract, field table, PII discipline, quickstart - BEHAVE-SHELL/README.md: all 76 primitives documented across 9 categories; TLS/SSH/C2 fingerprint sections with [DRAFT — verify] markers on uncertain entries - BEHAVE-TEXT/README.md: all 35 primitives across 6 categories; Rutify calibration notes inline; content.* layer marked EXPERIMENTAL throughout - primitives.py (SHELL): backfilled notes for all previously undocumented primitives - primitives.py (TEXT): backfilled notes for capitalization_habit, emoji_*, length, linebreak_style, sentence_complexity_class, question_formation_style, imperative_style, response_latency_class, message_burst_rate License: CC-BY-SA-4.0 (prose) / GPL-3.0-or-later (code)
behave-core
The shared observation envelope for BEHAVE. Defines the wire format that
behave-shell and behave-text serialize all behavioral observations into.
Every sensor in the BEHAVE ecosystem emits the same Observation structure —
the domain-specific meaning lives in primitive and value; the envelope
provides identity, provenance, time window, and schema versioning.
What it provides
| Symbol | Type | Description |
|---|---|---|
OBSERVATION_SCHEMA_VERSION |
int |
Envelope schema version (currently 1). Bumped when field shapes change; federation gossip receivers reject mismatched versions. |
Observation |
Pydantic model | One behavioral observation: a single primitive measured over a time window. The core class is registry-agnostic — it does not validate primitive or value against any specific domain. Use the registry-aware subclasses in behave-shell or behave-text for full validation. |
ObservationValue |
Union[str, int, float, bool, list[str], list[int], list[float], dict] |
Type alias covering all valid value shapes. |
Window |
Pydantic model | The measurement window: start_ts and end_ts in epoch seconds. Distinct from Observation.ts (the emission time) — a sensor may compute an observation over a past window and emit it later. |
Observation fields
| Field | Type | Required | Description |
|---|---|---|---|
primitive |
str |
✓ | Fully-qualified primitive path, e.g. motor.keystroke_cadence |
value |
ObservationValue |
✓ | The measured value; shape validated by the domain registry |
confidence |
float [0,1] |
✓ | Sensor's confidence in this measurement (not in any attribution verdict) |
window |
Window |
✓ | Measurement time window |
source |
str |
✓ | Canonical sensor identifier, e.g. behave/sniffer/timing.py |
evidence_ref |
str | None |
— | Pointer to underlying raw evidence (session tape, pcap). Never the evidence itself — see PII note below. |
identity_ref |
str | None |
— | AttackerIdentity UUID if the observation is pre-attributed |
ts |
float |
auto | Emission timestamp, epoch seconds |
id |
str |
auto | UUID hex for deduplication |
v |
int |
auto | Envelope schema version (= OBSERVATION_SCHEMA_VERSION) |
PII discipline (non-negotiable)
BEHAVE observations carry categorical labels, timing aggregates, and hashes only. They must never carry:
- Raw keystroke content or command arguments
- Passwords, tokens, session keys, or any authentication material
- File contents or payload bytes
- Raw message text (especially in
behave-text)
evidence_ref is a pointer to underlying evidence held elsewhere. Never the evidence itself.
Install
pip install -e .
# or, as a dependency of behave-shell / behave-text:
pip install -e ../core/
Quickstart
from behave_core.spec import Observation, Window, OBSERVATION_SCHEMA_VERSION
obs = Observation(
primitive="motor.keystroke_cadence",
value="bursty",
confidence=0.82,
window=Window(start_ts=1714000000.0, end_ts=1714003600.0),
source="behave/shell-sensor/timing.py",
)
print(obs.model_dump_json())
Tests
pytest tests/
License
Code: GPL-3.0-or-later