tessl/pypi-stix2

Produce and consume STIX 2 JSON content for cyber threat intelligence

Overview

Eval results

Files

STIX Domain Objects (SDOs)

Name: tessl/pypi-stix2
Author: tessl

STIX Domain Objects represent higher-level cyber threat intelligence concepts including threat actors, attack patterns, malware, indicators, campaigns, and other strategic threat intelligence. These objects form the core building blocks for expressing cyber threat information in a standardized format.

Capabilities

Threat Intelligence Objects

Core objects for representing threat intelligence entities and their characteristics.

class AttackPattern:
    """
    Attack patterns describe methods adversaries use to compromise targets.
    
    Required Properties:
    - name (str): Name of the attack pattern
    
    Optional Properties:
    - description (str): Description of the attack pattern
    - external_references (list): External references (e.g., MITRE ATT&CK)
    - kill_chain_phases (list): Kill chain phases where pattern is used
    """

class ThreatActor:
    """
    Threat actors represent individuals, groups, or organizations conducting attacks.
    
    Required Properties:
    - name (str): Name of the threat actor
    - threat_actor_types (list): Types of threat actor
    
    Optional Properties:
    - aliases (list): Alternative names
    - description (str): Description of the threat actor
    - sophistication (str): Sophistication level
    - resource_level (str): Resource level
    - primary_motivation (str): Primary motivation
    - secondary_motivations (list): Secondary motivations
    - personal_motivations (list): Personal motivations
    - goals (list): Goals of the threat actor
    """

class IntrusionSet:
    """
    Intrusion sets represent grouped activities conducted by threat actors.
    
    Required Properties:
    - name (str): Name of the intrusion set
    
    Optional Properties:
    - description (str): Description of activities
    - aliases (list): Alternative names
    - first_seen (timestamp): First observation time
    - last_seen (timestamp): Last observation time
    - goals (list): Goals of the intrusion set
    - resource_level (str): Resource level
    - primary_motivation (str): Primary motivation
    - secondary_motivations (list): Secondary motivations
    """

class Campaign:
    """
    Campaigns represent series of malicious activities or attacks.
    
    Required Properties:
    - name (str): Name of the campaign
    
    Optional Properties:
    - description (str): Description of the campaign
    - aliases (list): Alternative names
    - first_seen (timestamp): Campaign start time
    - last_seen (timestamp): Campaign end time
    - objective (str): Campaign objective
    """

Usage examples:

from stix2 import AttackPattern, ThreatActor, Campaign

# Create attack pattern
attack_pattern = AttackPattern(
    name="Spear Phishing Attachment",
    description="Adversaries may send spear phishing emails with malicious attachments",
    external_references=[
        {
            "source_name": "mitre-attack",
            "external_id": "T1566.001",
            "url": "https://attack.mitre.org/techniques/T1566/001/"
        }
    ],
    kill_chain_phases=[
        {
            "kill_chain_name": "mitre-attack",
            "phase_name": "initial-access"
        }
    ]
)

# Create threat actor
threat_actor = ThreatActor(
    name="APT1",
    threat_actor_types=["nation-state"],
    aliases=["Comment Crew", "PLA Unit 61398"],
    sophistication="advanced",
    resource_level="government",
    primary_motivation="organizational-gain"
)

# Create campaign
campaign = Campaign(
    name="Operation Aurora",
    description="Cyber attack campaign targeting Google and other companies",
    first_seen="2009-12-01T00:00:00.000Z",
    last_seen="2010-01-12T00:00:00.000Z"
)

Malware and Tools

Objects for representing malicious software and legitimate tools used by adversaries.

class Malware:
    """
    Malware represents malicious software used by adversaries.
    
    Required Properties:
    - name (str): Name of the malware
    - malware_types (list): Types of malware
    
    Optional Properties:
    - is_family (bool): Whether this represents a malware family
    - aliases (list): Alternative names
    - description (str): Description of the malware
    - first_seen (timestamp): First observation time
    - last_seen (timestamp): Last observation time
    - operating_system_refs (list): Supported operating systems
    - architecture_execution_envs (list): Execution environments
    - implementation_languages (list): Programming languages used
    - capabilities (list): Malware capabilities
    """

class Tool:
    """
    Tools represent legitimate software used by adversaries.
    
    Required Properties:
    - name (str): Name of the tool
    - tool_types (list): Types of tool
    
    Optional Properties:
    - aliases (list): Alternative names
    - description (str): Description of the tool
    - tool_version (str): Version of the tool
    - kill_chain_phases (list): Kill chain phases where tool is used
    """

class MalwareAnalysis:
    """
    Malware analysis captures results of analyzing malware samples.
    
    Required Properties:
    - product (str): Analysis product/tool used
    - result (str): Result of the analysis
    
    Optional Properties:
    - version (str): Analysis tool version
    - host_vm_ref (str): Reference to analysis environment
    - operating_system_ref (str): Reference to operating system
    - installed_software_refs (list): Installed software references
    - configuration_version (str): Configuration version
    - modules (list): Analysis modules used
    - analysis_engine_version (str): Analysis engine version
    - analysis_definition_version (str): Analysis definition version
    - submitted (timestamp): Submission time
    - analysis_started (timestamp): Analysis start time  
    - analysis_ended (timestamp): Analysis end time
    - av_result (str): Antivirus result
    - sample_refs (list): Sample references
    """

Usage examples:

from stix2 import Malware, Tool, MalwareAnalysis

# Create malware object
malware = Malware(
    name="Poison Ivy",
    malware_types=["remote-access-trojan"],
    aliases=["Pivy", "PIVY"],
    description="Remote access trojan that allows attackers to control infected systems",
    is_family=True,
    capabilities=["remote-machine-access", "anti-detection", "data-theft"]
)

# Create tool object  
tool = Tool(
    name="PowerShell",
    tool_types=["execution"],
    description="Windows PowerShell command-line shell and scripting language",
    kill_chain_phases=[
        {
            "kill_chain_name": "mitre-attack",
            "phase_name": "execution"
        }
    ]
)

# Create malware analysis
analysis = MalwareAnalysis(
    product="ClamAV",
    result="malicious",
    analysis_engine_version="0.103.2",
    analysis_definition_version="26123",
    submitted="2021-04-23T10:30:00.000Z",
    av_result="Trojan.Win32.PoisonIvy"
)

Indicators and Observables

Objects for representing indicators of compromise and observed data.

class Indicator:
    """
    Indicators contain detection patterns for suspicious or malicious activity.
    
    Required Properties:
    - indicator_types (list): Types of indicator
    - pattern (str): Detection pattern 
    - pattern_type (str): Pattern language type ("stix")
    
    Optional Properties:
    - name (str): Name of the indicator
    - description (str): Description of the indicator
    - pattern_version (str): Pattern language version
    - valid_from (timestamp): Validity start time
    - valid_until (timestamp): Validity end time
    - kill_chain_phases (list): Kill chain phases
    """

class ObservedData:
    """
    Observed data conveys raw information observed on networks or systems.
    
    Required Properties:
    - first_observed (timestamp): First observation time
    - last_observed (timestamp): Last observation time
    - number_observed (int): Number of times observed
    - objects (dict): Observed cyber observables
    
    Optional Properties:
    - object_refs (list): References to observed objects
    """

Usage examples:

from stix2 import Indicator, ObservedData

# Create indicator
indicator = Indicator(
    name="Malicious file hash",
    indicator_types=["malicious-activity"],
    pattern_type="stix",
    pattern="[file:hashes.MD5 = 'd41d8cd98f00b204e9800998ecf8427e']",
    valid_from="2021-04-23T10:30:00.000Z"
)

# Create observed data
observed_data = ObservedData(
    first_observed="2021-04-23T10:30:00.000Z",
    last_observed="2021-04-23T10:35:00.000Z", 
    number_observed=1,
    objects={
        "0": {
            "type": "file",
            "hashes": {
                "MD5": "d41d8cd98f00b204e9800998ecf8427e"
            },
            "name": "malware.exe"
        }
    }
)

Other Domain Objects

Additional domain objects for comprehensive threat intelligence representation.

class Identity:
    """
    Identities represent individuals, organizations, or groups.
    
    Required Properties:
    - name (str): Name of the identity
    - identity_class (str): Class of identity
    
    Optional Properties:
    - description (str): Description
    - roles (list): Roles performed by identity
    - sectors (list): Industry sectors
    - contact_information (str): Contact information
    """

class Vulnerability:
    """
    Vulnerabilities represent flaws in software, firmware, or hardware.
    
    Required Properties:
    - name (str): Name of the vulnerability
    
    Optional Properties:
    - description (str): Description of the vulnerability
    - external_references (list): External references (e.g., CVE)
    """

class CourseOfAction:
    """
    Courses of action represent preventive or corrective actions.
    
    Required Properties:
    - name (str): Name of the course of action
    
    Optional Properties:
    - description (str): Description of the action
    - action_type (str): Type of action
    - os_execution_envs (list): Operating system environments
    - action_bin (str): Executable binary content
    - action_reference (str): Reference to external action
    """

class Report:
    """
    Reports aggregate and contextualize STIX domain objects.
    
    Required Properties:
    - name (str): Name of the report
    - published (timestamp): Publication time
    - object_refs (list): References to reported objects
    
    Optional Properties:
    - description (str): Description of the report
    - report_types (list): Types of report
    """

class Grouping:
    """
    Groupings explicitly assert that referenced objects are related.
    
    Required Properties:
    - context (str): Context for the grouping
    - object_refs (list): References to grouped objects
    
    Optional Properties:
    - name (str): Name of the grouping
    - description (str): Description of the grouping
    """

class Location:
    """
    Locations represent geographic areas.
    
    Optional Properties:
    - name (str): Name of the location
    - description (str): Description
    - latitude (float): Latitude coordinate
    - longitude (float): Longitude coordinate
    - precision (float): Coordinate precision
    - region (str): Geographic region
    - country (str): Country name/code
    - administrative_area (str): Administrative area
    - city (str): City name
    - street_address (str): Street address
    - postal_code (str): Postal code
    """

class Note:
    """
    Notes contain additional information about STIX objects.
    
    Required Properties:
    - content (str): Content of the note
    - object_refs (list): References to annotated objects
    
    Optional Properties:
    - abstract (str): Abstract of the note
    - authors (list): Authors of the note
    """

class Opinion:
    """
    Opinions represent assessments of STIX objects.
    
    Required Properties:
    - opinion (str): Opinion value
    - object_refs (list): References to assessed objects
    
    Optional Properties:
    - explanation (str): Explanation of the opinion
    - authors (list): Authors of the opinion
    """

class Infrastructure:
    """
    Infrastructure represents systems used by adversaries.
    
    Required Properties:
    - name (str): Name of the infrastructure
    - infrastructure_types (list): Types of infrastructure
    
    Optional Properties:
    - description (str): Description
    - aliases (list): Alternative names
    - kill_chain_phases (list): Kill chain phases
    - first_seen (timestamp): First observation time
    - last_seen (timestamp): Last observation time
    """

class Incident:
    """
    Incidents represent actual security incidents.
    
    Required Properties:
    - name (str): Name of the incident
    
    Optional Properties:
    - description (str): Description of the incident
    """

Custom Domain Objects

Create custom domain objects for organization-specific needs:

from stix2 import CustomObject

# Define custom SDO
@CustomObject('x-custom-threat', [
    ('name', stix2.properties.StringProperty(required=True)),
    ('threat_level', stix2.properties.StringProperty()),
])
class CustomThreat:
    pass

# Create instance
custom_threat = CustomThreat(
    name="Custom Threat Type",
    threat_level="high"
)

Install with Tessl CLI