Working with Events

An Event represents a security incident, threat campaign, phishing operation, malware activity, investigation, or other threat intelligence occurrence associated with a specific point in time. Events are managed through the /api/events endpoints, which support full lifecycle operations including retrieval, creation, modification, and deletion. The ThreatQ SDK provides a streamlined interface for working with events, allowing you to search for existing records, create new events, and enrich them with additional context and metadata.

List All Events

To retrieve all events stored in ThreatQ, use the tq.get() method with the /api/events endpoint. This endpoint returns a collection of event objects represented as dictionaries.

The following example retrieves all events and displays the first result:

Copy Code

Example output:

{
  "hash": "3ebe478a05e4a7981f94dfcfab31ee14",
  "description": "Desc for Internal Domain Controller Compromised",
  "title": "Internal Domain Controller Compromised",
  "created_at": "2016-10-21 11:43:37",
  "type_id": 5,
  "updated_at": "2016-10-21 11:43:37",
  "happened_at": "2016-10-21 11:43:35",
  "id": 2
}

Search for a Specific Event

To locate a specific event, pass the event title as a query parameter to the tq.get() method.

The following example searches for an event titled Internal Domain Controller Compromised:

event = tq.get(
    '/api/events',
    params={'title': 'Internal Domain Controller Compromised'}
)
print(event.get('data'))

Copy Code

Example output:

[
  {
    "hash": "3ebe478a05e4a7981f94dfcfab31ee14",
    "description": "Desc for Internal Domain Controller Compromised",
    "title": "Internal Domain Controller Compromised",
    "created_at": "2016-10-21 11:43:37",
    "type_id": 5,
    "updated_at": "2016-10-21 11:43:37",
    "happened_at": "2016-10-21 11:43:35",
    "id": 2
  }
]

Create a New Event

Before creating an event, import the required SDK classes:

Copy Code

Create a new event by defining the required properties:

You may also optionally provide a description.

Copy Code

Upload the event to ThreatQ and capture the newly assigned event ID:

Copy Code

The returned value contains the unique identifier assigned to the newly created event.

Add an Attribute

Attributes can be used to enrich events with additional context, classification details, or operational metadata.

The following example adds a custom severity attribute to the event:

Copy Code

This associates the attribute Severity = High with the event and records the specified source.