From 7ad360719c26a0b5d913a986cda22f7459ffde78 Mon Sep 17 00:00:00 2001
From: Felipe Luis Quezada Valenzuela <fquezadav@interior.gob.cl>
Date: Wed, 4 Dec 2024 12:59:11 -0300
Subject: [PATCH] first commit

---
 README.md | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 155 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9f16e85
--- /dev/null
+++ b/README.md
@@ -0,0 +1,155 @@
+## Descripción
+
+Este proyecto permite conocer el estado de conexión de las comunidades (servidores) conectadas a un MISP mediante alertas que se envian a través de correo electrónico. El envio de estas alertas puede ser programado en diferentes intervalos de tiempo (cada x minutos, cada x horas, etc)
+
+
+### Características:
+
+- Envio de alertas del estado de conexión de servidores conectados y/o no conectados.
+- Programación de envio se puede configurar en diferentes intervalos (minutos, horas, semanas, meses).
+- Utiliza cualquier servidor SMTP estándar (Microsoft (O365), Google (Gmail)).
+- Excel adjunto con alertas (opcional)
+
+
+## Componentes
+
+- Libreria SMTP clásica de python (smtplib)
+- Libreria PyMISP (pymisp): https://pypi.org/project/pymisp/
+- Libreria para programar tareas en crontab: https://pypi.org/project/python-crontab/
+
+## Configuración inicial
+
+1. En el archivo settings.py se debe definir los parametros según caso:
+
+``` python
+
+WORK_DIR = os.getcwd()
+
+# Si desea adjuntar datos como un archivo adjunto en cada alerta
+DATA_ATTACH = False
+
+# Solo servidores desconectados
+SERVERS_OFF = True
+
+
+# Si no va a ejecutar entorno virtual, puede llamar directo a main.py, sino cambiar por .sh
+FNAME = 'run.sh'
+PATH_EXEC = os.path.join(WORK_DIR, FNAME)
+COMANDO_CRON = "echo 'TEST'"
+
+if FNAME.endswith(".py"):
+    COMANDO_CRON = "cd "+WORK_DIR+" && python3 "+FNAME
+elif FNAME.endswith(".sh"):
+    COMANDO_CRON = "bash "+PATH_EXEC
+
+
+MISP_CONFIG = {
+    'URL_MISP':'<URL MISP>',
+    'AUTHKEY':'<AUTHKEY>'
+}
+
+EMAIL_CONFIG = {
+    'server_smtp_host':'<SMTP HOST>',
+    'server_smtp_port': 587,
+    'smtp_username': '<SMTP USERNAME>',
+    'smtp_password': '<SMTP PASSWORD>',
+    'email_recipient':'<SMTP EMAIL TO>',
+    'tls': True, # si utiliza TLS, sino False
+    'email_subject':'<EMAIL SUBJECT>',
+    'output_color_status':'#16b606',# Color HEX alerta conectado
+    'output_color_status_error':'#f71005'# Color HEX alerta
+}
+
+CRON_CONFIG = {
+    "interval": {
+        "minutes": None,
+        "hours": 1,  # Esto indica "cada hora" (Por defecto)
+        "days": None,
+        "months": None
+    },
+    "command": COMANDO_CRON
+}
+
+```
+En settings.py podemos configurar:
+
+- DATA_ATACH: En True, se adjuntará un excel con los mismos datos que vienen en el cuerpo del correo de las alertas. Caso contrario (False), se enviara correo de alerta sin adjunto.
+- SERVERS_OFF: En True, solo se enviarán alertas con los servidores MISP no conectados.
+- MISP_CONFIG: Configuración asociada a MISP
+- FNAME: Nombre de archivo ejecutable (main.py). Si utiliza entorno virtual de Python, se debe llamar a plantilla "run.sh"
+- EMAIL_CONFIG: Configuración de SMTP que se utilizará para enviar alertas.
+- CRON_CONFIG: Configuración de intervalos que serán agregados a crontab. Se debe solo utilizar un parametro (por defecto).
+    - minutes (cada cuantos minutos)
+    - hours (cada cuantas horas)
+    - days (cada cuantos dias. Se ejecuta por defecto a las 00:00)
+    - months (cada cuantos meses. Se ejecuta por defecto el dia 1 de cada mes a las 00:00)
+
+## Instalación en entorno virtual
+
+Una vez configurado "settings.py" procedemos con la instalación
+
+1. Se crea entorno virtual de Python
+``` shell
+cd ./misp-alertas
+python3 -m venv venv
+```
+2. Se activa entorno virtual:
+``` shell
+source venv/bin/activate
+```
+3. Instalar librerias de Python:
+``` shell
+pip install -r requirements.txt
+```
+
+
+## Agengar
+
+Podemos agendar utilizando el archivo "save_job.sh":
+```shell
+#!/bin/bash
+
+# Activate 
+source /home/user/misp-alertas/venv/bin/activate
+
+# Enter folder
+cd /home/user/misp-alertas/
+
+# Llamar al script Python
+python save_job.py
+
+# Deactivate
+deactivate
+```
+1. Debe ajustar las rutas en "source" y "cd" para la ejecución correcta del archivo.
+
+2. Ejecutamos:
+```shell
+bash save_job.sh
+```
+
+Esto creara en crontab una entrada con la ejecución programada, dependiendo que usuario del sistema operativo ejecuto el script. (Si fue como 'root', quedará en crontab de 'root')
+
+``` shell
+@hourly bash ./misp-alertas/run.sh
+```
+
+La entrada se creara para que se ejecute el archivo "run.sh":
+```shell
+#!/bin/bash
+
+# Activate 
+source /home/user/misp-alertas/venv/bin/activate
+
+# Enter folder
+cd /home/user/misp-alertas/
+
+# Llamar al script Python
+python main.py
+
+# Deactivate
+deactivate
+```
+Al igual que en el archivo "save_job.sh", debe ajustar las rutas en "source" y "cd" para la ejecución correcta del archivo.
+
+Cada vez que se quiera modificar el agendamiento dentro de settings.py se debe volver a ejecutar punto 2.
\ No newline at end of file