Domain types

domain

Our internal domain shapes -- the input side of the builder.

Callers construct these from their own data and hand them to build_detection_finding. They deliberately use our vocabulary (the enums in defaults) and hide OCSF's *_id integers, so producing services never touch OCSF field names directly.

ObservableType

Bases: Enum

Every OCSF observable type_id (schema 1.5.0), by our vocabulary name.

Members mirror the full observable.type_id enum; each maps to its OCSF type_id int in _OBSERVABLE_TYPE_TO_ID (builders). The member value is the human name used as the fallback observable.name when a caller doesn't supply one. Kept in sync with the schema by tests/test_observables.py.

Observable dataclass

Observable(
    type: ObservableType,
    value: str,
    name: str | None = None,
)

An entity a finding refers to (host, IP, user, hash, ...).

MitreAttack dataclass

MitreAttack(
    technique_uid: str,
    technique_name: str | None = None,
    tactic_uid: str | None = None,
    tactic_name: str | None = None,
)

A MITRE ATT&CK reference (technique, optionally its tactic).

Maps to an entry in OCSF finding_info.attacks.

UserRef dataclass

UserRef(
    name: str | None = None,
    uid: str | None = None,
    email: str | None = None,
    domain: str | None = None,
    full_name: str | None = None,
)

A user/principal a finding refers to. Maps to an OCSF user object.

Used by the IAM classes (Authentication 3002, Account Change 3001) and, where relevant, other classes. All fields optional -- OCSF user has no required attributes.

DeviceRef dataclass

DeviceRef(
    hostname: str | None = None,
    uid: str | None = None,
    type_id: int = 0,
    os_name: str | None = None,
    os_version: str | None = None,
    os_type_id: int = 0,
    os_sp_name: str | None = None,
    os_sp_ver: str | None = None,
)

A device/host a finding refers to. Maps to an OCSF device object.

Used by Operating System Patch State (5004), which additionally constrains "at least one of os.sp_name / os.sp_ver / os.version". Supply os_version (and/or the sp fields) to satisfy it. OCSF device requires type_id; it defaults to 0 (Unknown) when not given.

FileRef dataclass

FileRef(
    name: str,
    type_id: int = 1,
    mime_type: str | None = None,
    uid: str | None = None,
    path: str | None = None,
)

A file a finding refers to. Maps to an OCSF file object.

Used by File Hosting Activity (6006). OCSF file requires name and type_id (1 = Regular File by default).

ApiCall dataclass

ApiCall(
    operation: str,
    service: str | None = None,
    version: str | None = None,
)

An API operation a finding refers to. Maps to an OCSF api object.

Used by API Activity (6003). OCSF api requires operation.

WebResourceRef dataclass

WebResourceRef(
    name: str | None = None,
    type: str | None = None,
    uid: str | None = None,
    url_string: str | None = None,
)

A web resource a finding refers to. Maps to an OCSF web_resource object.

Used by Web Resources Activity (6001). All fields optional in OCSF.

EndpointRef dataclass

EndpointRef(
    ip: str | None = None,
    hostname: str | None = None,
    port: int | None = None,
    uid: str | None = None,
)

A network endpoint a finding refers to. Maps to an OCSF network_endpoint.

Used as src_endpoint by API Activity (6003) and File Hosting (6006). All fields optional in OCSF.

ComplianceRef dataclass

ComplianceRef(
    standards: list[str],
    control: str | None = None,
    status: str | None = None,
)

A compliance assessment. Maps to an OCSF compliance object.

Used by Compliance Finding (2003). OCSF compliance requires standards (a list of standard identifiers, e.g. ["CIS", "PCI DSS"]).

ProcessRef dataclass

ProcessRef(
    name: str | None = None,
    pid: int | None = None,
    cmd_line: str | None = None,
    uid: str | None = None,
)

A process. Maps to an OCSF process object (no required sub-fields).

EmailRef dataclass

EmailRef(
    from_addr: str | None = None,
    to: list[str] | None = None,
    subject: str | None = None,
    uid: str | None = None,
)

An email message. Maps to an OCSF email object (no required sub-fields).

VulnerabilityRef dataclass

VulnerabilityRef(
    title: str | None = None,
    severity: str | None = None,
    desc: str | None = None,
    cve_uid: str | None = None,
    cwe_uid: str | None = None,
    advisory_uid: str | None = None,
)

A vulnerability. Maps to an OCSF vulnerability object.

OCSF requires just_one of cve / cwe / advisory -- supply exactly one of cve_uid / cwe_uid / advisory_uid.

ConnectionInfoRef dataclass

ConnectionInfoRef(
    direction_id: int = 0,
    protocol_name: str | None = None,
    uid: str | None = None,
)

A network connection. Maps to network_connection_info (requires direction_id).

GroupRef dataclass

GroupRef(
    name: str | None = None,
    uid: str | None = None,
    type: str | None = None,
)

A group. Maps to an OCSF group object (no required sub-fields).

JobRef dataclass

JobRef(
    name: str,
    file: FileRef,
    cmd_line: str | None = None,
    desc: str | None = None,
)

A scheduled job. Maps to an OCSF job object (requires name and file).

KernelRef dataclass

KernelRef(
    name: str, type_id: int = 0, path: str | None = None
)

A kernel resource. Maps to an OCSF kernel object (requires name, type_id).

ModuleRef dataclass

ModuleRef(
    load_type_id: int = 0,
    base_address: str | None = None,
    file: FileRef | None = None,
)

A loaded module. Maps to an OCSF module object (requires load_type_id).

ScriptRef dataclass

ScriptRef(
    script_content: str,
    type_id: int = 0,
    name: str | None = None,
)

A script. Maps to an OCSF script object (requires script_content, type_id).

ScanRef dataclass

ScanRef(
    type_id: int = 0,
    name: str | None = None,
    uid: str | None = None,
)

A scan. Maps to an OCSF scan object (requires type_id).

OsintRef dataclass

OsintRef(
    value: str, type_id: int = 0, desc: str | None = None
)

OSINT indicator. Maps to an OCSF osint object (requires type_id, value).

ManagedEntityRef dataclass

ManagedEntityRef(
    name: str | None = None,
    uid: str | None = None,
    type: str | None = None,
    type_id: int | None = None,
)

A managed entity. Maps to an OCSF managed_entity object (no required sub-fields).

QueryEvidenceRef dataclass

QueryEvidenceRef(
    query_type_id: int = 0,
    query_type: str | None = None,
    user: UserRef | None = None,
    process: ProcessRef | None = None,
)

Live-evidence query result. Maps to query_evidence (requires query_type_id).

OCSF requires just_one queried object -- supply exactly one of user / process (the subset we model).

KernelDriverRef dataclass

KernelDriverRef(file: FileRef)

A kernel driver. Maps to an OCSF kernel_driver object (requires file).

DatabaseRef dataclass

DatabaseRef(
    name: str | None = None,
    uid: str | None = None,
    type_id: int = 0,
)

A database/table datastore. Maps to an OCSF database object.

OCSF requires type_id and at_least_one of name / uid.

ResourceDetailsRef dataclass

ResourceDetailsRef(
    name: str | None = None,
    uid: str | None = None,
    type: str | None = None,
)

A cloud resource. Maps to an OCSF resource_details object.

OCSF requires at_least_one of name / uid.

UasRef dataclass

UasRef(
    uid: str | None = None,
    name: str | None = None,
    model: str | None = None,
    serial_number: str | None = None,
)

An unmanned aerial system. Maps to unmanned_aerial_system (no required sub-fields).

DetectionSignal dataclass

DetectionSignal(
    uid: str,
    title: str,
    severity: Severity,
    message: str,
    activity: Activity = CREATE,
    status: Status = NEW,
    observables: list[Observable] = list(),
    description: str | None = None,
    time_ms: int | None = None,
    data_sources: list[str] = list(),
    confidence: Confidence | None = None,
    confidence_score: int | None = None,
    risk_level: RiskLevel | None = None,
    risk_score: int | None = None,
    attacks: list[MitreAttack] = list(),
    count: int | None = None,
    first_seen_ms: int | None = None,
    last_seen_ms: int | None = None,
)

A detection our services produce, in our own terms.

This is the single input shape build_detection_finding maps from. It is intentionally small and OCSF-agnostic; the builder is responsible for the translation to class_uid 2004.