🎯 Overview

This repository houses the mathematical and logical core of the MACSFIRE Security Risk Assessment (SRA) engine. Designed as a modular, domain-driven standalone library, it processes complex architectural topologies, calculates threat propagation vectors, and evaluates residual risk for avionics architectures aligned with RTCA DO-326A / ED-202A and DO-356A / ED-203A standards.

Because the engine is fully decoupled from the presentation layer, it can be seamlessly integrated into interactive dashboards, automated CI/CD security evaluation pipelines, or headless analytical scripts.

🏗️ Core Architecture & Package Structure

The engine is strictly organized into decoupled, domain-driven packages handling model transformation, graph-theoretic propagation, formal theorem proving, and global optimization.

macsfire/
├── domain/            # Foundational Data Models & Domain Enums
├── engine/            # Core Risk Assessment, Traversal & Propagation Logic
├── adapters/          # Architecture Model Importers (OAAM, IR Transformation)
├── verification/      # Z3 SMT Formal Theorem Prover for DO-326A Scopes
├── solvers/           # CP-SAT Global Security Architecture Optimizer
├── quantification/    # Game-Theoretic & Dynamic NVD Risk Assessment
├── api_server/        # Flask REST API & Headless Listener Service
├── ui/                # Streamlit Interactive Dashboard
├── unittests/         # Comprehensive Automated Test Suite
└── utility.py         # Helper Utilities, LaTeX Rendering & Graph Visualizers

📦 Module Breakdown

1. macsfire.domain (Domain Data Layer)

Contains pure, thread-safe data structures and domain definitions.

• base.py: Generic in-memory database abstraction (Database[T]) with O(1) indexing and federated identity mixins (ExternalIdentifiable).
• elements.py: Fundamental system topology nodes (Asset, AssetDB) and connections (Connection, IntConnection, LogicalConnection, SignalConnection).
• enums.py: Strict type definitions (CIA attributes, Asset Types, Severity tiers, Protection Effectiveness scales, SAL levels, Privilege Levels).
• risk.py: Risk-specific entities (Threat, FailureCondition, ThreatCondition, CybersecurityNeeds, LevelOfProtection).
• scope.py: DO-326A perimeter mappings (SecurityPerimeter, SecurityEnvironment, SecurityScope, PreCondition, PostCondition).
• security.py: Defensive measures (SecurityMeasure, SecurityMeasureInstance) including DO-356A effectiveness scoring.

2. macsfire.engine (Evaluation & Execution Engine)

Orchestrates path traversal, logic gate resolution, and risk calculation.

• sra.py: The main SRA execution controller. Manages scenario evaluations, severity inheritance, statistics, and LaTeX/Excel artifact generation.
• scenario.py: Generates and manages individual ThreatScenario instances targeting specific failure conditions.
• topology.py: Graph-theory algorithms built on NetworkX to compute topological attack paths and cutsets.
• logic.py: Boolean DNF (Disjunctive Normal Form) reduction and minimum cutset derivation for system failure conditions.
• propagation/: Extensible threat propagation engine containing CIA flow simulations (RealisticCiaPropagationLayer), DSML kill-chain evaluation (FullKillChainPropagationLayer), and OAAM rule models (OaamPropagationModel).

3. macsfire.adapters (Model Transformation)

Intermediate Representation (IR) layer decoupling external modeling tools from the MACSFIRE core.

• base.py: Abstract adapter contract (AbstractModelAdapter) and IR dataclasses (NodeIR, EdgeIR, ThreatIR, ScopeIR).
• oaam/: Importer and adapter for Object-Oriented Architecture Models (.oaam) using eoq2 and pyecore.

4. macsfire.verification (Formal Scope Verification)

• scope_evaluator.py & formal.py: Translates DO-326A scope Assume-Guarantee contracts into SMT formulas and executes formal proofs via the Z3 Theorem Prover.

5. macsfire.solvers (Global Architecture Optimization)

• optimization.py: Solves multi-objective optimization problems using Google OR-Tools (CP-SAT) to select cost-optimal security measures while guaranteeing DO-356A score capping and mandatory SAL constraints.

6. macsfire.api_server & macsfire.services & macsfire.ui

• api.py: Flask REST API providing asynchronous execution boundaries, model uploads, and live memory inspection.
• listener.py: Headless event-driven listener for automated loop calculations.
• dashboard.py: Interactive Streamlit web interface for 3D topology visualization, database inspection, and scenario simulation.

🧪 Testing

Run the automated unittest suite with pytest:

# Run all unit tests
pytest unittests/ -v

Note on Version 1.0.X: This release focuses on core attack graph generation, DO-356A Level of Protection (LoP) evaluation, and CP-SAT Architecture Optimization. Formal Z3 Scope Verification and Game-Theoretic Quantification are included as preview features and disabled by default.