Metadata-Version: 2.4
Name: fair-risk-engine
Version: 1.1.0
Summary: Monte Carlo simulation engine for FAIR cyber risk quantification
Author: Laura Voicu
License: CC-BY-NC-SA-4.0
Project-URL: Repository, https://github.com/security-decision-science/security-decision-labs
Project-URL: Documentation, https://github.com/security-decision-science/security-decision-labs/blob/main/tools/fair-simulator/docs/MODEL_REFERENCE.md
Project-URL: Changelog, https://github.com/security-decision-science/security-decision-labs/blob/main/tools/fair-simulator/CHANGELOG.md
Keywords: fair,cyber-risk,risk-quantification,monte-carlo,crq,information-risk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Provides-Extra: ui-test
Requires-Dist: pytest>=7.4; extra == "ui-test"
Requires-Dist: playwright>=1.40; extra == "ui-test"
Provides-Extra: api
Requires-Dist: fastapi>=0.109.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.27.0; extra == "api"
Requires-Dist: pydantic>=2.0.0; extra == "api"
Dynamic: license-file

# fair-risk-engine

Monte Carlo simulation engine for FAIR (Factor Analysis of Information Risk) cyber risk
quantification. You describe a loss scenario with P10/P50/P90 ranges; the engine simulates many
years and returns the distribution of annual loss.

```bash
pip install fair-risk-engine
```

```python
from fair_risk_engine import FAIRCalculator, FAIRInputs

inputs = FAIRInputs(
    tef_p10=1, tef_p50=3, tef_p90=5,                 # threat events per year
    susc_p10=20, susc_p50=40, susc_p90=70,           # % of threat events that become loss events
    productivity_p10=50_000, productivity_p50=150_000, productivity_p90=500_000,
    response_p10=20_000, response_p50=75_000, response_p90=250_000,
)
r = FAIRCalculator(n_simulations=100_000, random_state=42).calculate(inputs)

print(f"Mean annual loss: ${r.ale_mean:,.0f} ± ${r.ale_mean_se:,.0f} (Monte Carlo error)")
print(f"P90: ${r.ale_p90:,.0f}   P99: ${r.ale_p99:,.0f}   ES99: ${r.ale_es99:,.0f}")
print(f"Years with no loss: {r.to_dict()['p_no_loss']:.0%}")
```

## What it computes

- **Compound annual loss.** Each simulated year draws its own number of loss events and a
  separate loss for each; the year's loss is their sum. Years without loss and years with several
  losses both occur.
- **The six FAIR loss forms** (productivity, response, replacement, fines & judgments, competitive
  advantage, reputation), with secondary loss occurring per event with probability SLEF.
- **Outputs:** mean, percentiles, VaR and expected shortfall, the loss exceedance curve, the share
  of years without loss, each loss form's share of the mean, and Monte Carlo standard errors.
- **Sensitivity:** curves, coupled changes and a tornado ranking of the inputs.
- **Portfolios:** independent or correlated (Gaussian copula) aggregation of scenarios.

**Bursty attack counts:** threat event frequency is Poisson (default), negative binomial or a
lognormal rate. `tef_dispersion` adds a year-to-year shock on the rate, which widens the tail
(and, with the lognormal rate, keeps the mean); it takes the `annual_shape` that
[tef-estimator](https://github.com/security-decision-science/security-decision-labs/tree/main/tools/tef-estimator)
estimates. With the Poisson default the tail is understated when counts are bursty
([model reference](https://github.com/security-decision-science/security-decision-labs/blob/main/tools/fair-simulator/docs/MODEL_REFERENCE.md),
[limitations](https://github.com/security-decision-science/security-decision-labs/blob/main/tools/fair-simulator/docs/LIMITATIONS.md)).

```python
# Example values in the form tef-estimator prints them ("For fair-risk-engine: ..."; in Python,
# FAIRInputs(**result.fair_risk_engine_inputs(), ...))
bursty = FAIRInputs(tef_model="lognormal", tef_p10=1.2, tef_p50=3.0, tef_p90=7.5, tef_dispersion=2.4,
                    susc_p10=20, susc_p50=40, susc_p90=70,
                    response_p10=20_000, response_p50=75_000, response_p90=250_000)
```

## Reproducibility

Every result stores its inputs, seed and engine version; a seeded result reproduces itself exactly. Any input
the engine adjusts before use is listed in `result.clamps`.

## Validation

The simulated loss distribution is tested against an exact (FFT) calculation. The engine is
self-assessed against the 24 checks of the CRQ Vendor Validation Checklist: **Level 2** (control
prioritisation, scenario planning). It is not Level 1: there is no independent validation and no
calibration against observed loss data yet. Every number comes from your inputs; the engine shows
how uncertain the result is given those inputs.

## Documentation

- [Model reference](https://github.com/security-decision-science/security-decision-labs/blob/main/tools/fair-simulator/docs/MODEL_REFERENCE.md): how inputs become loss estimates
- [Limitations](https://github.com/security-decision-science/security-decision-labs/blob/main/tools/fair-simulator/docs/LIMITATIONS.md)
- [CRQ validation](https://github.com/security-decision-science/security-decision-labs/blob/main/tools/fair-simulator/docs/CRQ_VALIDATION.md): the self-assessment and how to read it
- [Testing](https://github.com/security-decision-science/security-decision-labs/blob/main/tools/fair-simulator/docs/TESTING.md)
- [Changelog](https://github.com/security-decision-science/security-decision-labs/blob/main/tools/fair-simulator/CHANGELOG.md)

The engine also powers the FAIR Risk Quantification Tool, a web app in the same repository.

## Licence

CC BY-NC-SA 4.0: free for non-commercial use with attribution; adaptations under the same licence.
This is an independent implementation of the FAIR methodology; FAIR is a trademark of the FAIR
Institute.
