Tanium est une plateforme extrêmement puissante, et de nombreux utilisateurs peuvent avoir besoin d'extraire des données de Tanium à l'aide de leurs propres outils. Tanium Connect permet toujours d'exporter des données et de les envoyer respectivement vers un produit, un serveur ou un fichier, mais il arrive parfois que les utilisateurs aient besoin d'extraire les données manuellement plutôt que de les recevoir. La nouvelle API Gateway de Tanium peut vous faciliter considérablement cette tâche. Dans cet article, je vais vous montrer comment vous connecter à Tanium via Python et interroger les données des machines.
Conditions requises
- Un environnement Tanium dans lequel la dernière solution API Gateway a été importée. Ce blog a été testé sur la version 1,3,64,0000.
- Python 3 with “requests” and “JSON” libraries
Authentification
Avant de pouvoir commencer à extraire des données de Tanium, nous devons nous assurer que nous pouvons nous connecter. Il existe deux options pour se connecter : à l'aide d'un identifiant et d'un mot de passe Tanium, ou à l'aide d'un jeton API. La connexion à l'aide d'un nom d'utilisateur et d'un mot de passe n'est pas possible si vous vous connectez via l'authentification unique (SSO) ou si vous utilisez Tanium Cloud ; vous devrez donc utiliser un jeton API si tel est le cas dans votre environnement Tanium.
Création d'un jeton API
Pour créer un jeton API, vous devez vous connecter à votre serveur Tanium comme d'habitude, puis sélectionner l'option « Jetons API » dans le menu « Administration ».
Une fois que vous avez accédé à la page « Jeton API », vous pouvez cliquer sur le bouton « Nouveau jeton API » situé à droite de l'écran. Cela vous permettra de créer un jeton, de définir sa durée de validité et de préciser quelles adresses API sont autorisées à utiliser ce jeton API. Une fois la fenêtre modale remplie, une fenêtre contextuelle s'affichera pour vous indiquer le jeton pendant un laps de temps limité. Veuillez noter le jeton, car il ne sera plus visible une fois la fenêtre contextuelle fermée.
Connexion à Tanium à l'aide d'un nom d'utilisateur et d'un mot de passe
Si votre environnement Tanium n'utilise pas l'authentification unique (SSO) pour la connexion, vous pouvez utiliser votre nom d'utilisateur et votre mot de passe pour vous authentifier et utiliser l'API de Tanium. La fonction ci-dessous illustre comment se connecter au serveur Tanium à l'aide d'un nom d'utilisateur et d'un mot de passe, puis extraire le jeton de session.
[Remarque : ce jeton de session expirera après une période d'inactivité ; vous devrez donc peut-être vous réauthentifier, le cas échéant.]
Bloc de code 1 : Obtention d'un jeton de session à l'aide d'un nom d'utilisateur et d'un mot de passe
def loginUsernamePassword(ts: str, username: str, password: str) -> str:
"""
Exemple de fonction permettant de se connecter à un serveur Tanium via
à l'aide d'un identifiant et d'un mot de passe. Cela renverra le jeton de session
.
Le paramètre « ts » correspond au serveur Tanium à utiliser.
Le paramètre « username » correspond au nom d'utilisateur à utiliser lors de la connexion.
Le paramètre « password » correspond au mot de passe à utiliser lors de la connexion.
"""
payload = {}
payload["username"] = username
payload["password"] = password
r = requests.post(f"{ts}/api/v2/session/login",
json=payload
)
session_token = r.json()['data']['session']
print(f"Code d'état reçu lors de la connexion : {r.status_code}")
return session_token
Test de l'authentification
Une fois que nous avons créé un jeton API, nous pouvons commencer à tester l'authentification. Le jeton API doit être ajouté en tant qu'en-tête dans toutes les requêtes HTTPS adressées au serveur Tanium. Une fois que nous aurons reçu le jeton de session, soit depuis la page « Jetons API » de la console Tanium, soit après nous être connectés à l'aide d'un identifiant et d'un mot de passe, nous vérifierons que ce jeton fonctionne correctement. Pour ce faire, il suffit d'appeler la route /api/v2/session/validate sur le serveur Tanium. Le bloc fonctionnel ci-dessous présente un exemple illustrant comment y parvenir.
Bloc de code 2 : Vérification de la validité d'un jeton API/de session
def validateToken(ts: str, token: str):
"""
Exemple de fonction permettant de vérifier qu'un jeton API est en mesure
d'accéder au serveur Tanium et d'obtenir une réponse 200 .
Le paramètre « ts » correspond au serveur Tanium à utiliser.
Exemple : 'https://MyTaniumServer.com'
Le paramètre « token » correspond à la chaîne de caractères du jeton API générée à partir de l'interface graphique de Tanium.
"""
r = requests.post(f"{ts}/api/v2/session/validate",
json={'session': token},
headers={'session': token}
)
# Le code d'état (status_code) doit être égal à 200 si la validation du jeton réussit.
print(f"Code d'état issu de la validation du jeton : {r.status_code}.")
Utilisation d'API Gateway et de GraphQL
Une fois que nous nous sommes connectés avec succès au serveur Tanium et que nous avons validé notre jeton, nous pouvons commencer à interroger l'API Gateway afin d'extraire des informations sur l'environnement. Si vous n'avez jamais utilisé GraphQL auparavant, il peut être utile de consulter leur documentation pour découvrir rapidement ce qu'est GraphQL et comment fonctionne son langage de requête. Vous trouverez le site web aux adresses suivantes : https://graphql.org/learn/ (s'ouvre dans un nouvel onglet).
Avant d'automatiser certaines tâches via l'API Tanium, vous pouvez accéder à l'API Gateway depuis la console Tanium et commencer à explorer les champs de données que vous pouvez interroger. La photo 2 indique où vous pouvez accéder à la section « API Gateway » de la console Tanium.
Une fois sur cette page, vous pouvez accéder à un IDE GraphQL interactif qui vous permet d'explorer et de tester diverses requêtes, ainsi que d'extraire des données réelles. Reportez-vous à la photo 3 , où nous pouvons exécuter une requête initiale pour afficher l'heure actuelle indiquée par le serveur.
En utilisant la requête GraphQL interactive dans la console Tanium, vous pouvez explorer et créer vos requêtes, que vous pourrez ensuite intégrer à votre script Python afin de les automatiser. Par exemple, nous pouvons créer une fonction Python très simple qui exécuterait la même requête « {now} », comme indiqué ci-dessous.
Bloc de code 3 : Exécution de la requête « now » via Python
def graphQLQueryNow(ts: str, token: str):
"""
La fonction `graphQLQueryNow` exécutera la requête GraphQL « now »
sur le serveur Tanium qui lui est transmis.
Le paramètre « ts » correspond au serveur Tanium à utiliser.
Le paramètre « token » correspond à la chaîne de caractères du jeton API générée à partir de l'interface graphique de « ts ».
"""
jsonObj = {'query' : "{now}"}
r = requests.post(ts + "/plugin/products/gateway/graphql",
json=jsonObj,
headers={'session': token},
)
print(f"Code d'état reçu suite à la requête « now » : {r.status_code}")
print(f"Réponse JSON à la requête « now » : {r.json()}")
C'est un excellent début pour exécuter la première requête Tanium via Python, mais essayons maintenant d'extraire les données des points de terminaison à partir de l'explorateur GraphQL interactif de la console Tanium. La photo ci-dessous montre comment vous pouvez rechercher tous les terminaux et leur système d'exploitation.
Cela nous fournit enfin des données sur les points d'extrémité, mais il manque encore un dernier élément. À moins que votre environnement ne compte 20 machines ou moins, vous constaterez que ces données ne fournissent pas les informations relatives à l'ensemble de l'environnement. La pagination est activée par défaut dans GraphQL, ce qui signifie que nous devrons effectuer plusieurs requêtes pour obtenir l'ensemble complet des données de l'environnement. Élargissons notre requête afin d'afficher les informations de pagination ; nous saurons ainsi comment les analyser lors de l'automatisation à l'aide d'un script Python.
Lorsque ces données « pageInfo » sont activées, le champ « hasNextPage » permet de vérifier s'il reste des données à analyser sur le serveur. De plus, vous pouvez suivre votre position au sein de l'ensemble de données en consultant les champs « startCursor » et « endCursor ». Si nous souhaitons récupérer la série de données suivante, il suffit d'ajouter un (après : « lastcursor ») dans notre requête vers les points de terminaison, comme indiqué ci-dessous.
On constate que lorsque l'on ajoute cet argument « after » à la requête sur les points d'extrémité, les données obtenues correspondent au lot suivant de 20 machines. Maintenant que nous savons comment parcourir les données par pages, nous pouvons enfin rassembler tous ces éléments dans un script Python qui exécutera une requête automatisée à notre place.
Bloc de code 4 : tout mettre en œuvre pour interroger des ensembles de données complets
def graphQL_pagination(ts: str, token: str):
"""
graphQL_pagination répertorie le nom et le système d'exploitation de chaque point de terminaison à l'aide de
, du langage GraphQL et de la pagination.
Le paramètre « ts » correspond au serveur Tanium à utiliser.
Le paramètre « token » correspond à la chaîne de caractères du jeton API générée à partir de l'interface graphique de « ts ».
"""
init_query = '''
{
endpoints {
pageInfo {
startCursor
endCursor
hasNextPage
}
edges {
node {
name
os {
name
}
}
}
}
}
'''
def do_request(ts: str, token: str, queryString: str) -> requests.Response:
r = requests.post(ts + "/plugin/products/gateway/graphql",
json={'query': queryString},
headers={'session': token},
)
return r
endpoint_data = []
next_query = init_query
while True:
# Envoyez la requête et convertissez la réponse au format JSON
r = do_request(ts, token, next_query)
resp_obj = r.json()
# extraire les informations de page de l'objet JSON
has_next_page = resp_obj["data"]["endpoints"]["pageInfo"]["hasNextPage"]
end_cursor = resp_obj["data"]["endpoints"]["pageInfo"]["endCursor"]
start_cursor = resp_obj["data"]["endpoints"]["pageInfo"]["startCursor"]
# Indiquez à l'utilisateur à quel endroit du curseur nous nous trouvons.
print(
f"Données reçues pour les points d'extrémité compris entre le début : {start_cursor} et la fin : {end_cursor}.")
# Ajouter les données relatives aux points d'extrémité dans notre objet liste
endpoint_data.extend(resp_obj["data"]["endpoints"]["edges"])
# if the next page is "False" then we reached the end of the dataset!
if not has_next_page:
break
# insérer l'argument « after » dans la requête d'origine
next_query = init_query[:25] + \
f"(after: \"{end_cursor}\") " + init_query[25:]
Nous espérons que cela vous aidera à vous familiariser avec l'utilisation de l'API Gateway en dehors de Tanium. N'oubliez pas que de nombreux cas d'utilisation peuvent être mis en œuvre simplement en utilisant les connecteurs natifs fournis par Tanium Connect. Lorsque vous devez mettre en place une intégration personnalisée, l'API Gateway constitue une ressource extrêmement utile, et de nouvelles fonctionnalités sont ajoutées chaque semaine, notamment la prise en charge des modules. N'hésitez pas à contacter votre représentant Tanium pour obtenir de plus amples informations sur les éléments de la feuille de route ou pour bénéficier d'une assistance supplémentaire dans le cadre de vos projets liés à API Gateway.
Découvrez comment exploiter pleinement le potentiel de la plateforme Tanium grâce à la galerie d’intégrations Tanium d’ : (s’ouvre dans un nouvel onglet). Il s’agit d’une console centralisée qui offre une visibilité en temps réel sur l’ensemble de nos intégrations et permet aux clients de les découvrir, de les configurer et de les déployer en toute simplicité. En simplifiant et en accélérant l'intégration de la plateforme Tanium avec des partenaires technologiques clés tels que Microsoft, ServiceNow et bien d'autres, la « Tanium Integrations Gallery » optimise la valeur des investissements technologiques tout en réduisant les risques et les inefficacités opérationnelles.
