Skip to main content

​
Overview

Event types represent security events detected by Garnet agents. Events use the V2 ashkaal format and include detections, flows, and informational events.

​
Event

Represents a security event with full agent details (V2 format). 
type Event struct {
    ID        string       `json:"id"`
    Agent     Agent        `json:"agent"`
    Data      ongoing.Base `json:"data"`
    Kind      kind.Kind    `json:"kind"`
    CreatedAt time.Time    `json:"created_at"`
    UpdatedAt time.Time    `json:"updated_at"`
}
​
id
string
required
Unique event identifier
​
agent
Agent
required
Full agent details that generated this event
​
data
ongoing.Base
required
Event data in ashkaal format
​
kind
kind.Kind
required
Event kind: flows, detections, infos, or netpolicy
​
created_at
time.Time
required
When the event was created
​
updated_at
time.Time
required
When the event was last updated

​
Methods

  • Validate() error - Validates event has required fields and valid kind

​
EventV2

V2 event representation with ashkaal format. 
type EventV2 struct {
    ID        string         `json:"id"`
    AgentID   string         `json:"agent_id"`
    Agent     Agent          `json:"agent"`
    Kind      eventkind.Kind `json:"kind"`
    Data      ongoing.Base   `json:"data"`
    CreatedAt time.Time      `json:"created_at"`
    UpdatedAt time.Time      `json:"updated_at"`
}
​
id
string
required
Unique event identifier (UUID format)
​
agent_id
string
required
ID of the agent that generated this event
​
agent
Agent
required
Full agent details
​
kind
eventkind.Kind
required
Event kind from ashkaal
​
data
ongoing.Base
required
Event data payload

​
Methods

  • Validate() error - Validates event structure

​
CreateOrUpdateEventV2

Request to create or update a V2 event. 
type CreateOrUpdateEventV2 struct {
    ID   string         `json:"id"`
    Kind eventkind.Kind `json:"kind"`
    Data ongoing.Base   `json:"data"`
}

​
Methods

  • Validate() error - Validates ID is UUID and kind is valid
  • AgentID() string - Returns the agent ID (populated from JWT)
  • SetAgentID(agentID string) - Sets the agent ID

​
Validation Rules

  • id must be a valid UUID
  • kind must be one of: flows, detections, infos, netpolicy
  • Agent ID is populated from JWT token, not provided in request

​
EventV2CreatedOrUpdated

Response after creating or updating an event. 
type EventV2CreatedOrUpdated struct {
    ID        string    `json:"id"`
    Created   bool      `json:"created"`
    UpdatedAt time.Time `json:"updated_at"`
}
​
id
string
required
The event ID
​
created
bool
required
True if event was created, false if updated
​
updated_at
time.Time
required
When the event was created or updated

​
ListEvents

Request to list events with filtering and pagination. 
type ListEvents struct {
    ProjectID string             `json:"-"`
    Filters   *ListEventsFilters `json:"filters"`
    PageArgs  PageArgs           `json:"pageArgs"`
    Sort      *Sort              `json:"sort,omitempty"`
}

​
Methods

  • Validate() error - Validates filters and pagination

​
ListEventsFilters

Filters for listing events. 
type ListEventsFilters struct {
    Kind          *eventkind.Kind  `json:"kind"`          // Deprecated: use Kinds
    Kinds         []eventkind.Kind `json:"kinds"`
    AgentID       *string          `json:"agentID"`
    MetadataNames []string         `json:"metadataNames"`
    Cluster       *string          `json:"cluster"`
    Namespace     *string          `json:"namespace"`
    Node          *string          `json:"node"`
    TimeStart     *time.Time       `json:"timeStart"`
    TimeEnd       *time.Time       `json:"timeEnd"`
}

​
Metadata Names

Metadata names identify specific event types: Network Events:
  • dropip - IP drop events
  • dropdomain - Domain drop events
  • flow - Network flow events
  • adult_domain_access - Adult content domain access
  • threat_domain_access - Threat domain access
  • badware_domain_access - Malware domain access
  • dyndns_domain_access - Dynamic DNS domain access
  • fake_domain_access - Fake domain access
  • gambling_domain_access - Gambling domain access
  • piracy_domain_access - Piracy domain access
  • plaintext_communication - Unencrypted communication
  • tracking_domain_access - Tracking domain access
  • vpnlike_domain_access - VPN-like domain access
Execution Events:
  • capabilities_modification - Linux capabilities changed
  • binary_executed_by_loader - Binary executed by loader
  • code_on_the_fly - Dynamic code execution
  • data_encoder_exec - Data encoder execution
  • denial_of_service_tools - DoS tool execution
  • exec_from_unusual_dir - Execution from unusual directory
  • hidden_elf_exec - Hidden ELF execution
  • interpreter_shell_spawn - Shell spawned by interpreter
  • net_filecopy_tool_exec - Network file copy tool
  • net_mitm_tool_exec - MITM tool execution
  • net_scan_tool_exec - Network scanning tool
  • net_sniff_tool_exec - Network sniffing tool
  • net_suspicious_tool_exec - Suspicious network tool
  • net_suspicious_tool_shell - Suspicious tool shell spawn
  • passwd_usage - Password utility usage
  • runc_suspicious_exec - Suspicious runc execution
  • webserver_exec - Webserver execution
  • webserver_shell_exec - Webserver shell spawn
  • crypto_miner_execution - Crypto miner execution
File System Events:
  • code_modification_through_procfs - Code modified via procfs
  • crypto_miner_files - Crypto miner files detected
  • auth_logs_tamper - Authentication logs tampered
  • file_attribute_change - File attributes changed
  • global_shlib_modification - Global library modified
  • package_repo_config_modification - Package repo config changed
  • pam_config_modification - PAM config changed
  • shell_config_modification - Shell config changed
  • sudoers_modification - Sudoers file modified
Information Gathering:
  • cpu_fingerprint - CPU fingerprinting
  • filesystem_fingerprint - Filesystem fingerprinting
  • machine_fingerprint - Machine fingerprinting
  • os_fingerprint - OS fingerprinting
  • os_network_fingerprint - OS network fingerprinting
  • os_status_fingerprint - OS status fingerprinting
System Access:
  • core_pattern_access - Core pattern access
  • credentials_files_access - Credentials file access
  • java_debug_lib_load - Java debug library loaded
  • java_instrument_lib_load - Java instrumentation loaded
  • sched_debug_access - Scheduler debug access
  • ssl_certificate_access - SSL certificate access
  • sysrq_access - SysRq access
  • unprivileged_bpf_config_access - Unprivileged BPF access
  • environ_read_from_procfs - Environment read from procfs
  • binary_self_deletion - Binary deleted itself

​
Methods

  • Validate() error - Validates filter values
  • IsEmpty() bool - Checks if all filters are empty

​
Validation Rules

  • Maximum 20 metadata names allowed
  • Metadata names must be 1-64 characters, ASCII letters/numbers/underscores only
  • timeStart must be before timeEnd

​
EventAction

Action to perform on an event. 
type EventAction struct {
    ActionType       EventActionType       `json:"action_type"`
    Scope            NetworkPolicyScope    `json:"scope"`
    Reason           string                `json:"reason"`
    UserID           *string               `json:"-"`
    DestinationType  NetworkPolicyRuleType `json:"-"`
    DestinationValue string                `json:"-"`
}

​
Methods

  • Validate() error - Validates action type, scope, and reason

​
EventActionPerformed

Result of performing an action on an event. 
type EventActionPerformed struct {
    EventID           string            `json:"event_id"`
    ActionType        EventActionType   `json:"action_type"`
    NetworkPolicyID   string            `json:"network_policy_id"`
    NetworkPolicyRule NetworkPolicyRule `json:"network_policy_rule"`
    CreatedAt         time.Time         `json:"created_at"`
}
​
event_id
string
required
The event ID the action was performed on
​
action_type
EventActionType
required
The action that was performed
​
network_policy_id
string
required
ID of the created network policy
​
network_policy_rule
NetworkPolicyRule
required
The network policy rule that was created
​
created_at
time.Time
required
When the action was performed

​
Error Constants

const (
    ErrInvalidEventKind        = errs.InvalidArgumentError("invalid event kind")
    ErrIDcannotBeEmpty         = errs.InvalidArgumentError("id is required")
    ErrInvalidEventV2Kind      = errs.InvalidArgumentError("invalid v2 event kind")
    ErrIDcannotBeEmptyV2       = errs.InvalidArgumentError("v2 event id is required")
    ErrInvalidEventV2ID        = errs.InvalidArgumentError("v2 event id must be a valid UUID")
    ErrMetadataNameEmpty       = errs.InvalidArgumentError("metadataName cannot be empty")
    ErrMetadataNameTooLong     = errs.InvalidArgumentError("metadataName too long, maximum 64 characters allowed")
    ErrMetadataNameInvalidChars = errs.InvalidArgumentError("metadataName must contain only ASCII letters, numbers, and underscores")
    ErrTooManyMetadataNames    = errs.InvalidArgumentError("too many metadata names, maximum 20 allowed")
    ErrEventNotFound           = errs.NotFoundError("event not found")
    ErrInvalidEventActionType  = errs.InvalidArgumentError("invalid event action type")
    ErrInvalidEventActionScope = errs.InvalidArgumentError("invalid event action scope")
    ErrInvalidEventReason      = errs.InvalidArgumentError("invalid event reason")
    ErrEventHasNoNetworkDestination = errs.InvalidArgumentError("event has no network destination")
)

Build docs developers (and LLMs) love

Get started for freeTalk to us