Metadata-Version: 2.5
Name: anci_kerno
Version: 0.0.3
Summary: Un conjunto de librerías para gestión de riesgos cuantitativa en ciberseguridad.
Author-email: Cristian Bravo Lillo <cbravo@anci.gob.cl>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: numpy>=2.4.6
Requires-Dist: pandas>=3.0.5
Requires-Dist: pymc>=6.3.1
Requires-Dist: pytensor>=3.3.0
Description-Content-Type: text/markdown

# ANCI-Kerno: librerías para gestión de riesgos en ciberseguridad

Este paquete implementa una serie de clases y funciones para la gestión de riesgos en ciberseguridad. Actualmente tiene dos clases: HawkesModel y IncidentList.

## HawkesModel.py

Esta clase implementa un modelo Hawkes multivariado para la probabilidad instantánea de un conjunto de incidentes, con un kernel gamma para modelar la demora que ocurre entre la ocurrencia de un tipo de incidente y la posible activación de otros tipos de incidentes.

### Base matemática

Un modelo Hawkes multivariado implementa tantos modelos Hawkes como tipos de incidentes existen, y define una función de intensidad que representa la probabilidad instantánea de ocurrencia de un tipo de incidente, basado en la historia de ocurrencias de otros incidentes. El valor de la función de intensidad aumenta cuando ocurren otros incidentes, y disminuye exponencialmente hasta llegar a un nivel base.

El modelo Hawkes "tradicional" usa una función de intensidad que aumenta instantáneamente luego de la ocurrencia de otros incidentes. Un modelo con un kernel gamma (o un *delay kernel*), en cambio, introduce una "demora" entre la ocurrencia de un incidente gatillador y el incidente modelado. Esta demora se utiliza para modelar el hecho de que ningún incidente genera aumentos instantáneos en otros incidentes: la demora depende de cada tipo de incidente, y representa el tiempo que se demoran los atacantes entre el descubrimiento de una vulnerabilidad y su explotación.

Por ejemplo, supongamos que ocurre una filtración de credenciales. Un atacante con acceso a estas credenciales toma un tiempo (desde pocos minutos a varios días) en descubrir cómo utilizar estas credenciales para montar un ataque de (por ejemplo) *ransomware*. Supongamos que en promedio los atacantes se demoran 14 días en este proceso; el aumento en la intensidad del ransomware llegará a su peak 14 días después de la ocurrencia de la filtración de credenciales.

Un modelo Hawkes, a diferencia de un modelo Poisson, no asume:

1. Que la probabilidad de cada tipo de evento es estática;
1. Que los tipos de eventos son independientes entre sí (en ciberseguridad, la ocurrencia de algunos tipos de incidente aumentan la probabilidad de ocurrencia de otros tipos).

La fórmula general de un modelo Hawkes multivariado con un kernel gamma es la siguiente:

$$\lambda_i(t) = \mu_i + \sum_{j=1}^M \sum_{t_{j,k} < t} \alpha_{ij} g_{ij}(t - t_{j,k})$$

Donde:

* $M$ es la cantidad de tipos de incidentes distintos;
* $\mu_i$ es la tasa base de ocurrencia de incidentes del tipo $i$; por ejemplo, en el caso del ransomware, es la tasa de ocurrencia aleatoria de ransomware, independiente de las campañas que puedan estar ocurriendo en un momento dado;
* $t_{j,k}$ es el timestamp del evento $k$-ésimo del incidente de tipo $j$.
* $\alpha_{ij}$ representa los coeficientes de la matriz de activación. Cada escalar $\alpha_{ij}$ representa cuánto aumenta el riesgo $i$ debido a un incidente de tipo $j$.
* $g_{ij}(\tau)$ es el kernel gamma. Esta función representa cuánto demora el riesgo $i$ en llegar a su peak debido al incidente de tipo $j$.

La fórmula para el kernel gamma es:

$$g_{ij}(\tau) = \beta_{ij}^2 \tau e^{-\beta_{ij}\tau}$$

Donde $\beta_{ij}$ representa el inverso del tiempo ($1/t$) que transcurre desde la ocurrencia de un incidente gatillador, y el peak del incidente consecuencia.

### Métodos de la clase

Esta clase tiene tres métodos:

1. El constructor `__init__()`, que recibe un objeto JSON con los valores precalculados a utilizar;
1. `calculate_delay_kernel(i, j, t_event, t_current)`, que calcula la función $g_{ij}(\tau)$, donde `t_event` es $\tau$, y `t_current` es el instante en el que se está calculando la función (por default, el momento actual);
1. `calculate_intensity(i, past_events, t_current)`, que calcula la intensidad $\lambda_i(t)$ del incidente  de tipo `i` a partir de la lista de incidentes `past_events`.

## IncidentList.py

Esta clase implementa una lista de incidentes de ciberseguridad, parseando un payload JSON y calculando los deltas de tiempo (tau) relativos a un timestamp ancla inmutable.

### Métodos de la clase

Esta clase tiene cuatro métodos:

1. El constructor `__init__()`, que recibe un objeto JSON con los valores precalculados a utilizar;
1. `get_raw_events(self, target_event_type: int | None = None, t_current: float | None = None)`, que devuelve una lista de eventos 
1. `get_anchor_time_in_days(self)`
1. `get_indicator(self, target_event_type: int)`
