Working with Adversaries

Adversaries represent threat actors, intrusion groups, nation-state operators, cybercriminal organizations, and other entities associated with malicious activity. The ThreatQ SDK provides a streamlined interface for managing adversaries programmatically, enabling you to search for existing records, create new adversaries, retrieve adversary data, and enrich records with additional context and attributes. This section demonstrates common adversary management tasks using the ThreatQ SDK and API.

List All Adversaries

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

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

Copy Code

Example output:

{
  "updated_at": "2017-10-03 14:30:53",
  "touched_at": "2017-10-03 14:31:04",
  "created_at": "2017-10-03 14:30:53",
  "id": 2,
  "name": "Comment Panda"
}

Search for a Specific Adversary

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

The following example searches for an adversary named PLA Unit 61398:

Copy Code

Example output:

[
  {
    "updated_at": "2017-10-03 14:30:54",
    "touched_at": "2017-10-03 14:31:04",
    "created_at": "2017-10-03 14:30:54",
    "id": 3,
    "name": "PLA Unit 61398"
  }
]

Searching with the SDK Object Model

The ThreatQ SDK also provides a dedicated search method for adversaries. Unlike the raw API response, this method returns an Adversary object and the corresponding adversary ID.

Copy Code

Example output:

3

This approach is useful when you plan to perform additional operations on the adversary using SDK object methods.

Create a New Adversary

Before creating an adversary, import the required SDK classes:

Copy Code

Create a new adversary by specifying the required name field. You may also provide an optional description.

Copy Code

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

Copy Code

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

Add an Attribute

Attributes can be used to enrich adversary records with additional context and metadata.

The following example adds a custom attribute to the adversary created above:

adv.add_attribute(
    'Vertical',
    'Hospitality',
    sources=Source('Test')
)

Copy Code

This associates the attribute Vertical = Hospitality with the adversary and records the specified source.