IN1-INCIBE

Descripción

Parser Cowrie es un proyecto open source cuya principal funcionalidad consiste en parsear los log en crudo que genera Cowrie, obteniendo un fichero con todas las conexiones en formato JSON. Es capaz de leer todos los ficheros de un directorio ordenándolos por orden cronológico e ir analizándolos individualmente.

Dado que analiza los ficheros individualmente, las conexiones son repartidas entre tres ficheros diferentes:

1. cowrie.completed.json: Es el fichero principal, contiene todas las sesiones que se han iniciado y cerrado en ese fichero.

2. cowrie.session.json: Es un fichero con sesiones iniciadas pero que no se ha encontrado el cierre de la sesión, por lo que estará en otro fichero.

3. cowrie.nosession.json: Es un fichero que tiene sesiones que se han establecido anteriormente, pero que no sabemos cuales son.

Ademas cuenta con una funcionalidad extra para completar las sesiones partidas entre los ficheros cowrie.session.json y cowrie.nosession.json, finalmente las sesiones que no han podido ser completadas por no estar completas en los log son guardadas en un fichero extra llamado cowrie.nosession.json.2.json y que solo contiene la IP y la geolocalización de esa IP, para perder la mínima información posible.
Las características del Parser son:

• Parseo de los log en crudo.

• Recomponer sesiones partidas en ficheros diferentes.

• Añadir geolocalización de las IP registradas (continente, país, coordenadas).

• Etiquetado de las conexiones usando un sistema basado en reglas, que etiqueta según la gravedad de la conexión, si es un escaneo o si es un ataque de fuerza bruta.

• Salida de la información en formato JSON.

• Script para meter los datos en Elasticseach con el mappping necesario para cada tipo de datos.

• JSON compatible con Kibana.

• Script para convertir logs antiguos de Cowrie en logs actuales y poder parsearlos.

Instalación

El Parser esta programado en Python 3, por lo que para usarlo necesitas tener instalado Python 3, junto con las librerías adicionales que no vienen instaladas por defecto, que son:

• geoip2

• elasticsearch>=6.3.1

Las podemos instalar de forma automática ejecutando el comando pip3 sobre el fichero requirements, que esta ubicado en la raíz del proyecto:

sudo pip3 install -r requirements

Uso

Este programa tiene dos funcionalidades básicas, parsear logs y completar sesiones.

Podemos ver la ayuda ejecutando python3 run.py -h

usage: 
  Execute the Parser: python3 run.py -d /mnt/cowrie/ -o output/ -v
  Execute CompleteSession: python3 run.py -o output/ -v

run.py is a script to parse the log generated by the honeypot SSH Cowrie and generate a JSON file with which to import the data into a BD NoSQL.

optional arguments:
  -h, --help                  show this help message and exit
  -d DIR, --dir DIR           Directory where the files are located.
  -o OUTPUT, --output OUTPUT  Directory where the generated files are stored.
  -db MMDB, --mmdb MMDB       Route where the DB is in our SO.
  -v, --verbose                 Verbose flag (boolean).

Parser

El Parser es la funcionalidad básica del programa, al ejecutarlo hay que indicarle el directorio donde se encuentran los log de Cowrie, este los analizara y creara los 3 ficheros JSON con las sesiones encontradas
Tiene una serie de parámetros que podemos pasarle al programa, que son:

• d: Directorio donde se encuentran los ficheros a parsear de Cowrie. (Obligatorio).

• o: Directorio donde se guardaran los ficheros JSON con los datos parseados. Valor por defecto: output. (Opcional).

• db: Ruta de la base de datos GeoIP2 que usamos para la geolocalización de las IPs. Valor por defecto: GeoLite2-City.mmdb. (Opcional).

• v: Modo verbose, booleano. Valor por defecto: false. (Opcional).

Ejemplo de uso:

python3 run.py -d ../log/cowrie -o log/ -db GeoLite2-City.mmdb -v
python3 run.py -d ../log/cowrie

Complete Session

Esta funcionalidad tiene como finalidad analizar cowrie.session.json buscando sesiones que estén en ese fichero y en cowrie.nosession.json para después añadir las sesiones completas al fichero cowrie.completed.json.
Tiene una serie de parámetros que podemos pasarle al programa, que son:

• o: Directorio donde se guardaran los ficheros JSON con los datos parseados. Valor por defecto: output. (Opcional).

• v: Modo verbose, booleano. Valor por defecto: false. (Opcional).

Ejemplo de uso:

python3 run.py -o log -v/
python3 run.py

Machine Learning

Esta clase tiene como funcionalidad convertir los ficheros JSON en un dataset legible para los diferentes algoritmos de clasificación que serán lanzados. Entre los algoritmos que serán utilizados para clasificar las sesiones de Cowrie se encuentra Random Forest, SVM, Decision Tree y K-NN. Destacar que los parámetros de configuración de los algoritmos están ajustados para un entorno de pruebas específico, siendo necesario su ajuste para un entorno distinto al actual. Para lanzar de forma satisfactoria esta clase es necesario tener almacenado en un directorio únicamente los ficheros cowrie.completed.json de cada una de las posibles instancias de Cowrie. Dicha clase únicamente tiene un argumento posible:

• d: Directorio donde se guardaran los ficheros JSON con los datos parseados.

Ejemplo de uso:

python3 machineLearning.py -d ../workingDirWithFilesJSON/

ElasticSearch

Este script esta ubicado en el directorio utils. Su funcionalidad es realizar peticiones REST a la API de ELasticSearch enviándolo los JSON.

Por cuestiones de eficiencia los envía en bloque de 5000 lineas. Se le puede pasar un index y un mapping que asocie a ese index para que Kibana sepa el tipo de datos que tiene ese index.
Podemos ver la ayuda ejecutando python3 elasticsearchLib.py -h

usage: python3 elasticsearchLib.py -f ../output/cowrie.completed.json -ip "127.0.0.1:9200" -i cowrie-s2 -m mapping.json -v

elasticsearchLib.py is a script to enter data in the elasticsearch database.

optional arguments:
  -h, --help               show this help message and exit
  -m MAPPING, --mapping    MAPPING  Path of the file where the mapping of the attributes is defined.
  -ip IP, --ip IP          IP address of the server where ElasticSearch is located.
  -i INDEX, --index INDEX  Name of the index.
  -v, --verbose            Verbose flag (boolean).

required named arguments:
-f FILE, --file FILE  File to upload.

Ejemplo de uso:

python3 elasticsearchLib.py -f log/cowrie.completed.json -i cowrie-s2 -m mapping.json -v
python3 elasticsearchLib.py -f log/cowrie.nosession.json.2.json -i cowrie-s2-ip -m mappingIP.json -v

Convert

Este script esta ubicado en el directorio utils. Su funcionalidad es convertir logs de Cowrie antiguos y que contengan sesiones Telnet en logs actuales con los que trabaja el Parser.
Podemos ver la ayuda ejecutando python3 convert.py -h

usage: python3 convert.py -d scriptzteam

convert.py is a script to convert old records to records compatible with the Parser

optional arguments:
  -h, --help         show this help message and exit

required named arguments:
  -d DIR, --dir DIR  Directory where the logs are located.

Sistemas Operativos soportados

Este programa esta programado en Python 3, ha sido desarrollado para Linux, pero en las pruebas realizadas en Windows 10 ha funciona correctamente, dado que Python es multiplataforma, aunque no se asegura su correcto funcionamiento en posteriores actualizaciones del programa.
El programa ha sido testeado con los siguientes Sistemas Operativos y versiones de Python:

SO	Python
Fedora 29	Python 3.7
Windows 10	Python 3.7
Mac OS	Python 3.7

docker-comspose

## Instalacion y uso de elasticsearch con Docker


bash
docker pull docker.elastic.co/elasticsearch/elasticsearch:6.5.4

docker run -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:6.5.4


La documentacion esta en esta [url][elasticsearch]

[elasticsearch]: https://www.elastic.co/guide/en/elasticsearch/reference/6.5/docker.html



## Instalacion y uso de kibana con Docker


bash
docker pull docker.elastic.co/kibana/kibana:6.5.4

# -dit
docker run -p 5601:5601 -v $(pwd)/kibana.yml:/usr/share/kibana/config/kibana.yml docker.elastic.co/kibana/kibana:6.5.4


La documentacion esta en esta [url][kibana]

[kibana]: https://www.elastic.co/guide/en/kibana/current/docker.html

Otros

## Datos a tener en cuenta a la hora de mostrar informacion y crear filtros acordes

- Location por defecto para ignorar (0,0)
- Success por defecto -1
- Size ttylog por defecto -1
- Clients y shortname unknown