Le dev dans QRadar #1 – Ma première application

1. Introduction

Nous allons voir aujourd’hui comment créer votre première application dans QRadar. Nous avions vu précédemment comment installer tous les outils nécessaires pour ce développement, passons maintenant au vif du sujet.

Dans cet article, vous allez voir comment développer les premières briques d’une application dans QRadar, n’étant en aucun cas un développeur aguerri, le code sera sommaire et assez basique, l’idée étant de vous présenter les bases ainsi que comment débuguer si cela ne fonctionne pas.

Pour ce premier exemple nous allons faire une application qui va nous apporter des informations supplémentaires au quotidien dans QRadar. Plus particulièrement, nous allons afficher une infobulle lorsqu’un utilisateur va survoler la valeur d’un port sur des logs. En effet, il n’est pas naturel de connaître la fonctionnalité de tous les ports en informatique. Qui plus est, nous allons être en mesure d’afficher des données personnalisées pour des ports métiers qui sont spécifiques à un contexte client par exemple.

2. Création du fichier manifest

Prérequis : Avoir installé l’application d’IBM pour les développeurs, je vous renvoie vers cet article avec tous les détails.

Pour pouvoir créer le manifest de votre application, autrement dit le fichier qui va définir les grandes lignes de son fonctionnement, il faut créer votre environnement. Pour cela, nous allons utiliser « QRadar App Editor » et faire comme ceci :

Nous avons choisi l’exemple « IP Tooltip Metadata Example » que nous allons modifier pour obtenir ce que nous souhaitons. Une fois que l’installation est faite, vous allez avoir un nouvel onglet dans votre console QRadar, cliquez sur cet onglet puis vous allez avoir l’affichage suivant :

En résumé :

Le manifest qui est ce qu’est l’application en somme, c’est là que nous allons définir le fonctionnement primaire de l’application, est-ce que je veux une application qui se déclenche lorsque l’utilisateur survole une valeur ou est-ce que je veux un nouvel onglet permanent dans la console QRadar
Ce dossier va contenir toute la partie visuelle, vous verrez par la suite que cela correspond à du web comme on peut le voir pour la création d’un site web basique
C’est le code de votre application, tous les calculs, manipulations vont se faire ici

Avant de passer à la modification du code nous allons comment modifier notre manifest pour qu’il soit en accord avec ce que l’on souhaite faire. Pour cela il faut modifier la section « metadata_providers » comme illustré dans la capture ci-dessous :

On remarque qu’il y a deux occurrences dans cette section, effectivement, nous souhaitons que l’infobulle se déclenche pour les ports source mais également destination. Il faut donc bien spécifier les valeurs de ces deux propriétés sous le format suivant :

ariel:<nom_de_la_propriete>

Enfin, il faut bien spécifier la fonction du code qui va être appelée dans le cas où un port (source ou destination) est survolé par un utilisateur. Dans notre cas nous appelons la fonction « getPortMedata« , c’est la fonction que nous allons étudier dans la partie suivante. Vous pouvez bien entendu, la renommer à votre guise, il faut seulement qu’il y ait une concordance entre le nom de la fonction et ce qui est appelé dans le fichier manifest.

3. Modification du code

Maintenant que nous avons le manifest configuré, il nous faut modifier le code pour qu’il exécute ce que l’on souhaite. Comme dit plus haut, le code va se retrouver dans le fichier « views.py » et donc doit être écrit en Python. Sans rentrer dans les détails du code que vous retrouverez en annexe, voici la structure :

Récupération des informations dans le référentiel QRadar qu’il faudra avoir créé au préalable.
Génération du lien « Speed Guide » en rajoutant le port en question.
Génération de logs à des fins de développement. Il faut bien penser à importer le module « qpylib » pour pouvoir faire cette partie.
Création du json qui sera utilisé pour la partie visuelle juste après.

Nous avons parlé de logs de débug ci-dessus, je vais vous montrer comment y accéder pour pouvoir trouver d’où vient un dysfonctionnement ou tout simplement logger des informations pour cette application dans les logs.

Se connecter à QRadar en CLI
Lancer l’application par le biais de la GUI ou en CLI
Se rendre dans le dossier « /store/docker/volumes/qapp-<APP_ID>/log/app.log«
Afficher en temps réel le contenu du fichier « app.log«

4. Mise en place du visuel

Dans cette dernière partie, nous allons récupérer les informations que nous avons générées dans la partie précédente et les mettre en forme via du code HTML. Pour afficher les variables il faut les mettre entre double accolades comme ceci.

Il faut également bien faire attention à ce que cela soit le même nom que ce que vous avez défini dans la configuration du json retourné dans la fonction dans votre code. Une fois que votre code HTML est prêt et que vous souhaitez tester votre application il faut la déployer en appliquant la procédure suivante.

Ensuite, l’interface va vous proposer de télécharger l’application et de valider le déploiement. Une fois ces actions faites et le déploiement fini, votre application est prête à l’usage et voici ce que cela donne en conditions réelles.

5. Conclusion

Pour conclure, vous retrouverez sur mon GitHub l’application dans sa première version. Elle est bien entendue perfectible et je suis preneur de retours pour avoir une application encore plus intéressante et ergonomique.

Cet article est le premier d’une série sur le développement dans QRadar, que cela soit dans le développement d’applications comme celle que nous avons vu ici, mais également des scripts de personnalisation de QRadar.

N’hésitez pas à me faire part d’améliorations possibles ou encore d’idée d’applications qui mériteraient d’être créées.

6. Bibliographie

Documentation IBM sur la création d’application : https://ibmsecuritydocs.github.io/qradar_appfw_v2/docs/
GitHub : App Custom

7. Annexes

manifest.json

{
	"console_ip": "<CONSOLE_IP>",
	"description": "Application showing how to add a custom tooltip to appear over port in QRadar.",
	"metadata_providers": [
		{
			"rest_method": "getPortMetadata",
			"metadata_type": "ariel:sourceport"
		},
		{
			"rest_method": "getPortMetadata",
			"metadata_type": "ariel:destinationport"
		}
	],
	"app_id": 1105,
	"name": "Port Tooltip Metadata Example",
	"version": "1.24",
	"areas": [
		{
			"url": "app_editor/editor",
			"required_capabilities": [
				"ADMIN"
			],
			"text": "Port Tooltip Metadata Example Development",
			"id": "editorArea_1679093642",
			"description": "Port Tooltip Metadata Example Development"
		}
	],
	"rest_methods": [
		{
			"url": "/port_metadata_provider",
			"method": "GET",
			"argument_names": [
				"context"
			],
			"name": "getPortMetadata"
		}
	],
	"resources": {
		"memory": 200
	},
	"uuid": "d2a26e77-45fd-4c70-99bf-69ad83bc0b7d"
}

views.py

"""Licensed Materials - Property of IBM
5725I71-CC011829
(C) Copyright IBM Corp. 2017, 2018. All Rights Reserved.
US Government Users Restricted Rights - Use, duplication or
disclosure restricted by GSA ADP Schedule Contract with IBM Corp."""
__author__ = 'staze0'



from app import app
from flask import render_template
from flask import request
from qpylib import qpylib

import json

@app.route('/port_metadata_provider', methods=['GET'])
def getPortMetadata():
    
    ref_map_of_sets_name = 'Port List'
    
    try:
        headers = {'SEC':'97c2a032-41a6-4e7c-b0b4-4f4f3ecb70e3', 'Accept' : 'application/json'}
        response = qpylib.REST( 'get', '/api/reference_data/map_of_sets/{0}'.format(ref_map_of_sets_name), headers = headers )
    except Exception as e:
        qpylib.log( "Error "  + str(e) , 'error')
        raise
    
    response_json = json.loads(response.text)
    app_id = qpylib.get_app_id()
    port_number = request.args.get('context')
    
    try:
        information_port = response_json["data"][port_number]
    except KeyError:
        information_port_parsed = "No informations found in refs. You can add information about this port in {0} ref map of sets.".format(ref_map_of_sets_name)
    else:
        information_port_parsed = ""
        for info in information_port:
            information_port_parsed += "{0} ".format(info["value"])
        information_port_parsed += ""
        
    information_appendix = "https://www.speedguide.net/port.php?port={0}".format(port_number)
    
    qpylib.log("### DEBUG ### : {0}".format(information_port_parsed))
    qpylib.log("### DEBUG ### : {0}".format(information_appendix))

    metadata_dict = {
        'key': 'PortMetadataProvider',
        'label': '',
        'value': 'Metadata value',
        'html': render_template('metadata_port.html', port_information=information_port_parsed, appendix=information_appendix, app_id=app_id)
    }

    return json.dumps(metadata_dict)

metadata_port.html

<!--Licensed Materials - Property of IBM
5725I71-CC011829
(C) Copyright IBM Corp. 2017, 2018. All Rights Reserved.
US Government Users Restricted Rights - Use, duplication or
disclosure restricted by GSA ADP Schedule Contract with IBM Corp.-->

<p>Port informations :</p>
<ul>
    <li>
        {{ port_information }}
    </li>
</ul>
<p>Appendix :</p>
<ul>
    <li>
        You'll find more information <a href="{{ appendix }}" target="_blank">here</a>
    </li>
</ul>

Merci d’avoir suivi ce petit tuto, en espérant que cela vous ait été utile. N’hésitez pas à me communiquer vos ressentis, tips…etc via le formulaire ci-dessous.

MENU PRINCIPAL