ThreatDetect

ThreatDetect es un prototipo de detección de amenazas internas basado en Streamlit que analiza datos de actividad de empleados y señala comportamientos potencialmente riesgosos. Utiliza un clasificador XGBoost entrenado junto con un detector de anomalías Isolation Forest para generar resúmenes de riesgo a nivel organizacional e información explicable a nivel de empleado.

Demostración

La aplicación se puede ejecutar localmente con Streamlit. Una demostración desplegada se publicó anteriormente en:

• https://threatdetectcos720.streamlit.app/

Características principales

• Detección de riesgos por lotes a partir de un archivo CSV subido
• Resumen de amenazas organizacional con conteos, distribución de probabilidad y niveles de riesgo
• Explicabilidad por empleado mediante valores SHAP
• Análisis Exploratorio de Datos (EDA) para conjuntos de datos subidos o de muestra
• Exportación de resultados de predicción a CSV
• Visualizaciones de importancia de características, distribución de riesgos y detección de anomalías

Estructura del repositorio

• streamlit_app.py — aplicación principal de Streamlit
• requirements.txt — dependencias de paquetes Python
• AI_Model_Code/insider_threat_model.pkl — pipeline de inferencia guardado y artefactos del modelo entrenado
• AI_Model_Code/insider_threat_clean_dataset.csv — conjunto de datos de muestra incluido para EDA
• AI_Model_Code/cos720_ai_model_FINAL.ipynb — cuaderno de desarrollo del modelo
• assets/app_styling.css — estilos personalizados de UI para la aplicación Streamlit
• unit testing/ — archivos de prueba para la preparación de características y lógica de explicación
• docs/TECHNICAL_DOCUMENTATION.md — documentación técnica del proyecto

Requisitos de software

• Python 3.8 o posterior
• streamlit
• pandas
• numpy
• scikit-learn
• matplotlib
• seaborn
• plotly
• xgboost
• shap

Instale todas las dependencias con:

pip install -r requirements.txt

Instalación

1. Clone el repositorio:

git clone https://github.com/jazbengu/ThreatDetect.git
cd ThreatDetect

2. Cree y active un entorno virtual (recomendado):

python3 -m venv venv
source venv/bin/activate

3. Instale las dependencias:

pip install -r requirements.txt

Ejecutar la aplicación

Inicie la aplicación con:

streamlit run streamlit_app.py

Luego abra la URL local que se muestra en la terminal (generalmente http://localhost:8501).

Usar ThreatDetect

Búsqueda organizacional vía CSV

• Suba un archivo CSV que contenga características de empleados y actividades.
• Haga clic en Ejecutar detección de amenazas para calcular las probabilidades de riesgo de cada registro.
• La aplicación muestra un resumen de predicciones maliciosas vs normales, distribución de probabilidades de riesgo e importancia de características.
• Puede expandir la tabla detallada de resultados y descargar la salida como CSV.
• Use la sección de explicación por registro para inspeccionar por qué un empleado específico fue señalado.

Análisis Exploratorio de Datos

• Suba su propio CSV o use el conjunto de datos de muestra incluido en AI_Model_Code/insider_threat_clean_dataset.csv.
• La página muestra la forma del conjunto de datos, estadísticas descriptivas, información de valores faltantes y gráficos de características.
• Las columnas numéricas se pueden explorar con histogramas, diagramas de caja, relaciones de dispersión y mapas de calor de correlación.
• Un análisis rápido de anomalías con Isolation Forest puede resaltar registros inusuales.

Páginas de la barra lateral

• Búsqueda organizacional vía CSV es el flujo de trabajo principal de detección de amenazas por lotes.
• Búsqueda individual se muestra en la barra lateral pero actualmente no está implementada en la lógica de la aplicación.
• Análisis Exploratorio de Datos está disponible para exploración de conjuntos de datos y comprobaciones rápidas de anomalías.

Artefactos del modelo

AI_Model_Code/insider_threat_model.pkl contiene un paquete de modelo serializado con:

• xgb_model: clasificador XGBoost entrenado
• iso_forest: detector de anomalías Isolation Forest entrenado
• scaler: StandardScaler para entradas numéricas
• label_encoders: codificadores para características categóricas
• feature_columns: lista ordenada de características
• cat_cols, num_cols, bin_cols: agrupaciones de características
• best_threshold: umbral de clasificación utilizado para decisiones de riesgo
• shap_explainer: explicador SHAP para explicabilidad

El archivo del modelo es cargado por streamlit_app.py y se utiliza para preprocesar entradas, calcular probabilidades de riesgo y generar explicaciones.

Pruebas

El repositorio incluye pruebas en unit testing/.

Ejecute el conjunto de pruebas con:

pytest "unit testing/"

Notas y resolución de problemas

• Si Streamlit falla al iniciar, asegúrese de que su entorno virtual esté activo y las dependencias instaladas.
• Si la aplicación informa que faltan columnas requeridas, verifique que su CSV subido incluya los campos esperados de empleados y actividades.
• El archivo del modelo fue serializado con versiones antiguas de scikit-learn, por lo que cargarlo puede generar advertencias de compatibilidad si su entorno usa versiones más recientes.
• Si el conjunto de datos de muestra incorporado no está disponible, suba su propio CSV para seguir usando la página de EDA.

Contribución

Este repositorio está configurado para mejora y pruebas. Las mejoras futuras pueden incluir ampliar la cobertura de características y reentrenar el modelo con datos adicionales de amenazas internas.