tessl/pypi-mitreattack-python
MITRE ATT&CK python library for accessing, querying, and manipulating ATT&CK threat intelligence data.
—
Pending
collections.mddocs/
Collections Management
Tools for working with ATT&CK Collections, converting between collection formats, and generating documentation from collection data. ATT&CK Collections are curated sets of ATT&CK techniques, groups, software, and other objects organized around specific themes, threat actors, or analytical frameworks.
Capabilities
Collection to Index Conversion
Convert ATT&CK Collection files to index format for easier processing and analysis.
class CollectionToIndex:
def __init__(self):
"""
Initialize collection to index converter.
"""
def convert(self, collection_file: str, output_file: str) -> None:
"""
Convert ATT&CK Collection file to index format.
Args:
collection_file (str): Path to input ATT&CK Collection JSON file
output_file (str): Path to output index file
"""
def parse_collection(self, collection_data: dict) -> dict:
"""
Parse collection data into structured index format.
Args:
collection_data (dict): Raw collection data from JSON file
Returns:
dict: Structured index data with metadata and object listings
"""
def extract_objects(self, collection_data: dict) -> Dict[str, List[dict]]:
"""
Extract and categorize objects from collection.
Args:
collection_data (dict): Collection data
Returns:
Dict[str, List[dict]]: Objects organized by type (techniques, groups, etc.)
"""
def validate_collection(self, collection_data: dict) -> bool:
"""
Validate collection format and required fields.
Args:
collection_data (dict): Collection data to validate
Returns:
bool: True if valid, False otherwise
"""Index to Markdown Conversion
Generate comprehensive Markdown documentation from collection index files.
class IndexToMarkdown:
def __init__(self):
"""
Initialize index to markdown converter.
"""
def convert(self, index_file: str, output_file: str) -> None:
"""
Convert collection index to Markdown documentation.
Args:
index_file (str): Path to collection index file
output_file (str): Path to output Markdown file
"""
def generate_overview(self, index_data: dict) -> str:
"""
Generate overview section with collection metadata.
Args:
index_data (dict): Index data from collection
Returns:
str: Markdown overview section
"""
def generate_object_tables(self, index_data: dict) -> str:
"""
Generate tables for each object type in the collection.
Args:
index_data (dict): Index data with object listings
Returns:
str: Markdown tables for techniques, groups, software, etc.
"""
def generate_relationships_section(self, index_data: dict) -> str:
"""
Generate section documenting relationships between objects.
Args:
index_data (dict): Index data with relationship information
Returns:
str: Markdown section with relationship mappings
"""
def format_technique_table(self, techniques: List[dict]) -> str:
"""
Format techniques as Markdown table.
Args:
techniques (List[dict]): List of technique objects
Returns:
str: Markdown table with technique details
"""
def format_group_table(self, groups: List[dict]) -> str:
"""
Format groups as Markdown table.
Args:
groups (List[dict]): List of group objects
Returns:
str: Markdown table with group details
"""
def format_software_table(self, software: List[dict]) -> str:
"""
Format software as Markdown table.
Args:
software (List[dict]): List of software objects
Returns:
str: Markdown table with software details
"""CLI Functions
Command-line interfaces for collection processing workflows.
def collection_to_index_main(args: List[str]) -> None:
"""
CLI entry point for collectionToIndex_cli command.
Args:
args (List[str]): Command-line arguments
--input: Input collection file path
--output: Output index file path
--validate: Validate collection format
"""
def index_to_markdown_main(args: List[str]) -> None:
"""
CLI entry point for indexToMarkdown_cli command.
Args:
args (List[str]): Command-line arguments
--input: Input index file path
--output: Output markdown file path
--template: Markdown template to use
--include-relationships: Include relationship mappings
"""Usage Examples
Converting Collections to Index Format
from mitreattack.collections import CollectionToIndex
# Initialize converter
converter = CollectionToIndex()
# Convert collection file to index
converter.convert(
collection_file="apt29_collection.json",
output_file="apt29_index.json"
)
print("Collection converted to index format")Working with Collection Data
import json
from mitreattack.collections import CollectionToIndex
# Load and parse collection manually
converter = CollectionToIndex()
with open("threat_collection.json", "r") as f:
collection_data = json.load(f)
# Validate collection
if converter.validate_collection(collection_data):
print("Collection format is valid")
# Extract objects by type
objects_by_type = converter.extract_objects(collection_data)
print(f"Techniques: {len(objects_by_type.get('techniques', []))}")
print(f"Groups: {len(objects_by_type.get('groups', []))}")
print(f"Software: {len(objects_by_type.get('software', []))}")
# Convert to structured index
index_data = converter.parse_collection(collection_data)
with open("structured_index.json", "w") as f:
json.dump(index_data, f, indent=2)
else:
print("Collection format is invalid")Generating Markdown Documentation
from mitreattack.collections import IndexToMarkdown
# Initialize markdown generator
generator = IndexToMarkdown()
# Convert index to markdown documentation
generator.convert(
index_file="apt29_index.json",
output_file="apt29_report.md"
)
print("Markdown documentation generated")Custom Markdown Generation
import json
from mitreattack.collections import IndexToMarkdown
# Load index data
with open("threat_index.json", "r") as f:
index_data = json.load(f)
generator = IndexToMarkdown()
# Generate individual sections
overview = generator.generate_overview(index_data)
object_tables = generator.generate_object_tables(index_data)
relationships = generator.generate_relationships_section(index_data)
# Combine into custom report
custom_report = f"""
# Threat Intelligence Report
{overview}
## Detailed Analysis
{object_tables}
## Relationship Analysis
{relationships}
## Appendix
Additional analysis and recommendations...
"""
with open("custom_threat_report.md", "w") as f:
f.write(custom_report)Working with Specific Object Types
import json
from mitreattack.collections import IndexToMarkdown
# Load index data
with open("collection_index.json", "r") as f:
index_data = json.load(f)
generator = IndexToMarkdown()
# Generate tables for specific object types
if "techniques" in index_data:
techniques_table = generator.format_technique_table(index_data["techniques"])
print("Techniques Table:")
print(techniques_table)
if "groups" in index_data:
groups_table = generator.format_group_table(index_data["groups"])
print("\\nGroups Table:")
print(groups_table)
if "software" in index_data:
software_table = generator.format_software_table(index_data["software"])
print("\\nSoftware Table:")
print(software_table)CLI Usage Examples
# Convert ATT&CK Collection to index format
collectionToIndex_cli --input apt29_collection.json --output apt29_index.json --validate
# Generate comprehensive markdown report
indexToMarkdown_cli --input apt29_index.json --output apt29_report.md --include-relationships
# Batch process multiple collections
for collection in collections/*.json; do
base_name=$(basename "$collection" .json)
collectionToIndex_cli --input "$collection" --output "indices/${base_name}_index.json"
indexToMarkdown_cli --input "indices/${base_name}_index.json" --output "reports/${base_name}_report.md"
doneCollection Validation and Quality Checks
import json
from mitreattack.collections import CollectionToIndex
def analyze_collection_quality(collection_file):
"""Analyze collection for completeness and quality."""
converter = CollectionToIndex()
with open(collection_file, "r") as f:
collection_data = json.load(f)
# Basic validation
is_valid = converter.validate_collection(collection_data)
print(f"Collection valid: {is_valid}")
if not is_valid:
return
# Extract and analyze objects
objects = converter.extract_objects(collection_data)
# Quality metrics
total_objects = sum(len(obj_list) for obj_list in objects.values())
print(f"Total objects: {total_objects}")
for obj_type, obj_list in objects.items():
print(f"{obj_type.capitalize()}: {len(obj_list)}")
# Check for missing descriptions
missing_desc = [obj for obj in obj_list if not obj.get("description")]
if missing_desc:
print(f" - {len(missing_desc)} {obj_type} missing descriptions")
# Check metadata completeness
metadata = collection_data.get("metadata", {})
required_fields = ["name", "version", "description", "created"]
missing_metadata = [field for field in required_fields if not metadata.get(field)]
if missing_metadata:
print(f"Missing metadata fields: {missing_metadata}")
else:
print("All required metadata fields present")
# Analyze collection quality
analyze_collection_quality("my_collection.json")Collection Format
ATT&CK Collections follow a standard JSON format:
{
"id": "collection-uuid",
"spec_version": "2.1",
"type": "x-mitre-collection",
"name": "Collection Name",
"description": "Collection description",
"created": "2023-01-01T00:00:00.000Z",
"modified": "2023-01-01T00:00:00.000Z",
"created_by_ref": "identity--uuid",
"object_refs": [
"attack-pattern--uuid1",
"intrusion-set--uuid2",
"malware--uuid3"
],
"x_mitre_contents": [
{
"object_ref": "attack-pattern--uuid1",
"object_modified": "2023-01-01T00:00:00.000Z"
}
]
}The conversion tools handle this format and extract relevant object references for analysis and documentation generation.
Install with Tessl CLI
npx tessl i tessl/pypi-mitreattack-python