tessl/pypi-mitreattack-python
MITRE ATT&CK python library for accessing, querying, and manipulating ATT&CK threat intelligence data.
—
Pending
excel-export.mddocs/
Excel Export and Data Conversion
Convert ATT&CK STIX data into structured Excel spreadsheets with multiple worksheets for different object types. The Excel export functionality includes pandas DataFrame operations, customizable output formatting, and comprehensive coverage of all ATT&CK object types including techniques, tactics, groups, software, mitigations, and relationships.
Capabilities
High-Level Export Functions
Main functions for loading data and exporting to Excel format.
def get_stix_data(domain: str, version: Optional[str] = None, remote: Optional[str] = None, stix_file: Optional[str] = None) -> MemoryStore:
"""
Load ATT&CK STIX data from various sources.
Args:
domain (str): ATT&CK domain ("enterprise-attack", "mobile-attack", "ics-attack")
version (str, optional): Specific ATT&CK version to load
remote (str, optional): URL to ATT&CK workbench instance
stix_file (str, optional): Path to local STIX file
Returns:
MemoryStore: A stix2.MemoryStore object containing the domain data
"""
def build_dataframes(src: MemoryStore, domain: str) -> dict:
"""
Convert STIX data to pandas DataFrames organized by object type.
Args:
src (MemoryStore): STIX data in MemoryStore from get_stix_data()
domain (str): ATT&CK domain for proper processing
Returns:
dict: Dictionary mapping object types to pandas DataFrames
"""
def write_excel(dataframes: dict, domain: str, version: Optional[str] = None, output_dir: str = ".") -> List[str]:
"""
Write DataFrames to Excel file with multiple worksheets.
Args:
dataframes (dict): DataFrames from build_dataframes()
domain (str): ATT&CK domain for filename generation
version (str, optional): Version for filename
output_dir (str): Output directory path. Defaults to current directory.
Returns:
List[str]: A list of filepaths corresponding to the files written by the function
"""
def export(domain: str = "enterprise-attack", version: Optional[str] = None, output_dir: str = ".", remote: Optional[str] = None, stix_file: Optional[str] = None, mem_store: Optional[MemoryStore] = None) -> None:
"""
Download ATT&CK data from MITRE/CTI and convert it to Excel spreadsheets.
Args:
domain (str): The domain of ATT&CK to download. Defaults to "enterprise-attack".
version (str, optional): The version of ATT&CK to download.
output_dir (str): The directory to write Excel files to. Defaults to current directory.
remote (str, optional): URL of a remote ATT&CK Workbench instance.
stix_file (str, optional): Path to a local STIX file.
mem_store (MemoryStore, optional): Pre-loaded STIX bundle.
"""
def main() -> None:
"""
Entrypoint for attackToExcel_cli.
"""STIX to DataFrame Conversion Functions
Specialized functions for converting different ATT&CK object types to pandas DataFrames.
def remove_revoked_deprecated(stix_objects):
"""Remove any revoked or deprecated objects from queries made to the data source."""
def filter_platforms(stix_objects, platforms):
"""Filter out any objects that don't have a matching platform to one in 'platforms'."""
def format_date(date):
"""Given a date string, return it formatted as %d %B %Y."""
def get_citations(objects):
"""Given a list of STIX objects, return a pandas dataframe for the citations on the objects."""
def parseBaseStix(sdo):
"""Given an SDO, return a dict of field names:values that are common across all ATT&CK STIX types."""Excel Formatting Classes
Helper classes for Excel output formatting.
class CellRange:
def __init__(self, leftCol: int, rightCol: int, topRow: int, bottomRow: int, data=None, format=None):
"""
Helper class for handling ranges of cells in a spreadsheet.
Args:
leftCol (int): Left column (not 0-indexed, starts at 1)
rightCol (int): Right column (not 0-indexed, starts at 1)
topRow (int): Top row (not 0-indexed, starts at 1)
bottomRow (int): Bottom row (not 0-indexed, starts at 1)
data: Optional data to store in the cellrange
format: Optional format dict for XlsxWriter style
"""
def to_excel_format(self) -> str:
"""Return the range in excel format, e.g A4:C7."""Object Type Converters
Individual converter functions for each ATT&CK object type.
def techniquesToDf(src: MemoryStore, domain: str) -> dict:
"""
Parse STIX techniques from the given data and return corresponding pandas dataframes.
Args:
src (MemoryStore): MemoryStore or other stix2 DataSource object holding the domain data
domain (str): domain of ATT&CK src corresponds to, e.g "enterprise-attack"
Returns:
dict: A lookup of labels (descriptors/names) to dataframes
"""
def tacticsToDf(src: MemoryStore) -> dict:
"""
Parse STIX tactics from the given data and return corresponding pandas dataframes.
Args:
src (MemoryStore): MemoryStore or other stix2 DataSource object holding the domain data
Returns:
dict: A lookup of labels (descriptors/names) to dataframes
"""
def datasourcesToDf(src: MemoryStore) -> dict:
"""
Parse STIX Data Sources and their Data components from the given data and return corresponding pandas dataframes.
Args:
src (MemoryStore): MemoryStore or other stix2 DataSource object holding the domain data
Returns:
dict: A lookup of labels (descriptors/names) to dataframes
"""
def softwareToDf(src: MemoryStore) -> dict:
"""
Parse STIX software from the given data and return corresponding pandas dataframes.
Args:
src (MemoryStore): MemoryStore or other stix2 DataSource object holding the domain data
Returns:
dict: A lookup of labels (descriptors/names) to dataframes
"""
def groupsToDf(src: MemoryStore) -> dict:
"""
Parse STIX groups from the given data and return corresponding pandas dataframes.
Args:
src (MemoryStore): MemoryStore or other stix2 DataSource object holding the domain data
Returns:
dict: A lookup of labels (descriptors/names) to dataframes
"""
def campaignsToDf(src: MemoryStore) -> dict:
"""
Parse STIX campaigns from the given data and return corresponding pandas dataframes.
Args:
src (MemoryStore): MemoryStore or other stix2 DataSource object holding the domain data
Returns:
dict: A lookup of labels (descriptors/names) to dataframes
"""
def assetsToDf(src: MemoryStore) -> dict:
"""
Parse STIX assets from the given data and return corresponding pandas dataframes.
Args:
src (MemoryStore): MemoryStore or other stix2 DataSource object holding the domain data
Returns:
dict: A lookup of labels (descriptors/names) to dataframes
"""
def mitigationsToDf(src: MemoryStore) -> dict:
"""
Parse STIX mitigations from the given data and return corresponding pandas dataframes.
Args:
src (MemoryStore): MemoryStore or other stix2 DataSource object holding the domain data
Returns:
dict: A lookup of labels (descriptors/names) to dataframes
"""
def matricesToDf(src: MemoryStore, domain: str) -> list:
"""
Parse STIX matrices from the given data and return parsed matrix structures.
Args:
src (MemoryStore): MemoryStore or other stix2 DataSource object holding the domain data
domain (str): domain of ATT&CK src corresponds to, e.g "enterprise-attack"
Returns:
list: List of dictionaries with matrix, name, description, merge, and columns data
"""
def relationshipsToDf(src: MemoryStore, relatedType: Optional[str] = None) -> dict:
"""
Parse STIX relationships from the given data and return corresponding pandas dataframes.
Args:
src (MemoryStore): MemoryStore or other stix2 DataSource object holding the domain data
relatedType (str, optional): singular attack type to only return relationships with, e.g "mitigation"
Returns:
dict: A lookup of labels (descriptors/names) to dataframes
"""Usage Examples
Basic Excel Export
from mitreattack.attackToExcel import get_stix_data, build_dataframes, write_excel
# Load Enterprise ATT&CK data
stix_data = get_stix_data("enterprise-attack")
# Convert to DataFrames
dataframes = build_dataframes(stix_data, "enterprise-attack")
# Write to Excel file
write_excel(dataframes, "enterprise-attack", output_dir="./output")
# This creates: ./output/enterprise-attack-v[version].xlsxWorking with Individual DataFrames
from mitreattack.attackToExcel.stixToDf import techniquesToDf, groupsToDf
from mitreattack.attackToExcel import get_stix_data
# Load data
stix_data = get_stix_data("enterprise-attack")
# Convert specific object types
techniques_df = techniquesToDf(stix_data, "enterprise-attack")
groups_df = groupsToDf(stix_data)
# Analyze the data
print(f"Total techniques: {len(techniques_df)}")
print(f"Techniques by platform:")
print(techniques_df['platforms'].value_counts())
print(f"\\nTotal groups: {len(groups_df)}")
print("Sample group names:")
print(groups_df['name'].head())Custom Filtering and Export
from mitreattack.attackToExcel.stixToDf import remove_revoked_deprecated, filter_platforms
from mitreattack.stix20 import MitreAttackData
# Load data with MitreAttackData for more control
attack_data = MitreAttackData("enterprise-attack")
# Get techniques and filter
all_techniques = attack_data.get_techniques(remove_revoked_deprecated=False)
active_techniques = remove_revoked_deprecated(all_techniques)
windows_techniques = filter_platforms(active_techniques, ["Windows"])
print(f"All techniques: {len(all_techniques)}")
print(f"Active techniques: {len(active_techniques)}")
print(f"Windows techniques: {len(windows_techniques)}")Relationship Analysis in Excel
from mitreattack.attackToExcel.stixToDf import relationshipsToDf
from mitreattack.attackToExcel import get_stix_data
# Load data
stix_data = get_stix_data("enterprise-attack")
# Get all relationships
all_relationships = relationshipsToDf(stix_data)
# Filter specific relationship types
uses_relationships = relationshipsToDf(stix_data, relatedType="uses")
mitigates_relationships = relationshipsToDf(stix_data, relatedType="mitigates")
print(f"Total relationships: {len(all_relationships)}")
print(f"'Uses' relationships: {len(uses_relationships)}")
print(f"'Mitigates' relationships: {len(mitigates_relationships)}")
# Analyze relationship distribution
print("\\nRelationship types:")
print(all_relationships['relationship_type'].value_counts())Using CLI Tool
# Export latest Enterprise ATT&CK to Excel
attackToExcel_cli --domain enterprise-attack --output ./exports/
# Export specific version
attackToExcel_cli --domain enterprise-attack --version 14.1 --output ./exports/
# Export Mobile ATT&CK
attackToExcel_cli --domain mobile-attack --output ./mobile-exports/
# Export from local STIX file
attackToExcel_cli --stix-file /path/to/local-attack.json --output ./local-exports/Output Structure
The generated Excel file contains multiple worksheets:
- techniques: All techniques with tactics, platforms, detection info
- tactics: Tactic information and kill chain phases
- software: Malware and tools with platform information
- groups: Threat actor groups with aliases and descriptions
- mitigations: Defensive measures and countermeasures
- datasources: Data collection sources and components
- campaigns: Threat campaigns with temporal information
- assets: Target assets by sector and platform
- matrices: ATT&CK framework structure information
- relationships: All STIX relationships between objects
Each worksheet is formatted for analysis with:
- Proper column headers and data types
- Filtered and cleaned data (no revoked/deprecated items by default)
- Comprehensive metadata for each object type
- Relationship mappings preserved where applicable
Install with Tessl CLI
npx tessl i tessl/pypi-mitreattack-python