Metadata-Version: 2.4
Name: macsfire
Version: 1.0.2
Summary: Model-based Avionics Cybersecurity Framework for Identification of Risk and Evaluation (MACSFIRE)
Author-email: Mario Werthwein <mario.werthwein@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/macsfire/macsfire
Project-URL: Bug Tracker, https://gitlab.com/macsfire/macsfire/-/boards#/
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anytree>=2.13.0
Requires-Dist: dill>=0.3.9
Requires-Dist: eoq2>=2.2.17.2
Requires-Dist: Flask>=3.1.0
Requires-Dist: graphviz>=0.21
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: networkx>=3.4.2
Requires-Dist: openpyxl
Requires-Dist: ortools>=9.15.0
Requires-Dist: plotly>=6.0.0
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: Requests>=2.32.0
Requires-Dist: streamlit>=1.30.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyecore>=0.15.2
Requires-Dist: z3-solver
Requires-Dist: websocket-client
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

<div align="center">

# MACSFIRE Core Engine

[![PyPI Downloads](https://static.pepy.tech/personalized-badge/macsfire?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/macsfire)

Official developer documentation for the **MACSFIRE** (Model-Based Avionics Cybersecurity Framework for Identification of Risk and Evaluation) Core Engine.

</div>

---

## 🎯 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.

```text
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`:

```bash
# 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.
