Tanium est une plateforme incroyablement puissante, et de nombreux utilisateurs peuvent avoir besoin d’obtenir des données de Tanium à l’aide de leurs propres outils. Tanium Connect peut toujours exporter des données et les envoyer à un produit, un serveur ou un fichier, respectivement, mais parfois les utilisateurs peuvent avoir besoin d’extraire des données manuellement plutôt que d’accepter des données. La nouvelle passerelle API de Tanium peut faciliter ce processus. Dans ce blog, je vous montrerai comment vous connecter à Tanium via python et interroger les données de la machine.
Exigences
- Un environnement Tanium avec la dernière solution de passerelle API importée. Ce blog a été testé sur la version 1,3,64,0000.
- Python 3 avec bibliothèques « demandes » et « JSON »
Authentification
Avant de pouvoir commencer à extraire des données de Tanium, nous devrons nous assurer que nous pouvons nous connecter. Il existe deux options pour se connecter : à l’aide d’un nom d’utilisateur/mot de passe Tanium et à l’aide d’un jeton d’API. La connexion via un nom d’utilisateur et un mot de passe n’est pas possible si vous vous connectez via SSO ou utilisez Tanium Cloud, vous devrez donc utiliser un jeton d’API si c’est le cas avec votre environnement Tanium.
Création d’un jeton d’API
Pour créer un jeton d’API, vous devrez vous connecter à votre Tanium Server comme vous le feriez normalement et trouver l’option Jeton d’API dans le menu « Administration ».
Après avoir accédé à la page des jetons d’API, vous pouvez ensuite cliquer sur le bouton « Nouveau jeton d’API » sur le côté droit de l’écran. Cela vous permettra de créer un jeton et de fournir la durée de validité du jeton, ainsi que les adresses d’API autorisées à utiliser ce jeton d’API. Après avoir rempli le module modal, une fenêtre contextuelle s’affichera qui affiche le jeton pendant une durée limitée. Veuillez prendre note du jeton, car il ne peut pas être affiché après la fermeture de la fenêtre contextuelle.
Connexion à Tanium via le nom d’utilisateur et le mot de passe
Si votre environnement Tanium n’utilise pas SSO pour vous connecter, vous pouvez utiliser votre nom d’utilisateur et votre mot de passe pour vous authentifier et travailler avec l’API Tanium. La fonction ci-dessous est un exemple de la manière dont nous pouvons nous connecter au Tanium Server via un nom d’utilisateur et un mot de passe et extraire le jeton de session.
[Remarque : ce jeton de session expirera après une période d’inactivité, vous devrez peut-être vous réauthentifier, si nécessaire.]
Bloc de code 1 : Obtenir un jeton de session via le nom d’utilisateur/mot de passe
def loginUsernamePassword(ts : str, username : str, password : str) -> str :
"""
Exemple de fonction de connexion à un Tanium Server via
une combinaison de nom d’utilisateur et de mot de passe. Cela renverra le jeton de
session.
parameter ts est le serveur Tanium à utiliser.
parameter username est le nom d’utilisateur à utiliser lors de la connexion.
parameter password est le 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 de statut reçu de la connexion : {r.status_code}")
return session_token
Tester l’authentification
Une fois qu’un jeton d’API a été créé, nous pouvons commencer à tester l’authentification. Le jeton d’API doit être ajouté en tant qu’en-tête dans toutes les demandes https au Tanium Server. Après avoir reçu le jeton de session de la page Jeton d’API dans la console Tanium ou de la connexion via une combinaison nom d’utilisateur/mot de passe, nous validerons que le jeton fonctionne correctement. Cela peut être fait en appelant l’itinéraire /api/v2/session/validate sur le Tanium Server. Le bloc fonctionnel ci-dessous présente un exemple de la manière dont cela peut être réalisé.
Bloc de code 2 : la validation d’un jeton de session/API est valide
def validToken(ts : str, token : str) :
"""
Exemple de fonction de validation qu’un jeton d’API peut
atteindre le serveur Tanium et obtenir une réponse 200 .
Le paramètre ts est le serveur Tanium à utiliser.
Exemple : « Le jeton de https://MyTaniumServer.com'
paramètre est la chaîne de jeton api générée à partir du ts gui.
»""
r = requests.post(f"{ts}/api/v2/session/validate",
json={'session' : token},
headers={'session' : token}
)
# status_code doit être 200 lors de la validation réussie de token.
print(f"Code de statut du jeton de validation : {r.status_code}.")
Utilisation de la passerelle API et de GraphQL
Après nous être connecté avec succès au Tanium Server et avoir validé notre jeton, nous pouvons commencer à interroger la passerelle API pour extraire des informations sur l’environnement. Si vous n’avez jamais utilisé graphQL auparavant, il peut être judicieux de consulter sa documentation pour une lecture rapide de ce qu’est graphQL et comment fonctionne le langage de requête. Le site Web se trouve ici : https://graphql.org/learn/.
Avant d’automatiser les choses via l’API Tanium, nous pouvons accéder à la passerelle API dans la console Tanium et commencer à explorer les champs de données que nous pouvons interroger. La photo 2 montre où vous pouvez accéder à la zone de passerelle API de Tanium Console.
Une fois que nous avons accédé à cette page, nous pouvons afficher un graphQL IDE interactif qui nous permet d’explorer et d’expérimenter diverses requêtes et d’obtenir des données réelles. Voir Photo 3 où nous pouvons exécuter une requête initiale pour afficher l’heure actuelle rapportée par le serveur.
En utilisant la requête graphQL interactive dans la console Tanium, nous pouvons explorer et créer nos requêtes que nous pouvons ensuite intégrer à notre script python pour automatiser. Par exemple, nous pouvons créer une fonction python très simple qui exécuterait la même requête « {now} », comme illustré ci-dessous.
Bloc de code 3 : exécution de la requête « maintenant » via python
def graphQLQueryNow(ts : str, token : str) :
"""
graphQLQueryNow exécutera la requête graphQL « maintenant »
sur le serveur Tanium qui est transmis à cette fonction.
Le paramètre ts est le serveur Tanium à utiliser.
le jeton de paramètre est la chaîne de jeton api générée à partir du ts gui.
""
jsonObj = {'query' : "{now}"}
r = requests.post(ts + "/plugin/products/gateway/graphql",
json=jsonObj,
headers={'session' : token},
)
print(f"Code de statut reçu de la requête 'now' : {r.status_code}")
print(f"'now' requête json response : {r.json()}")
C’est un excellent début pour exécuter la première requête Tanium via python, mais essayons d’obtenir des données d’endpoint à partir de l’explorateur graphQL interactif dans Tanium Console. La photo ci-dessous montre comment nous pouvons interroger tous les endpoints et leur système d’exploitation.
Cela nous donne enfin des données d’endpoint, mais il y a un dernier élément manquant. À moins que votre environnement n’ait 20 machines ou moins, vous verrez que ces données ne fournissent pas les informations pour l’ensemble de l’environnement. GraphQL a une pagination activée par défaut, ce qui signifie que nous devrons effectuer plusieurs demandes pour recevoir un jeu de données complet de l’ensemble de l’environnement. Agrandissons notre requête pour afficher les informations de pagination, afin de savoir comment nous pouvons analyser cela lors de l’automatisation via un script python.
Lorsque ces données « pageInfo » sont activées, nous pouvons voir s’il reste plus de données à analyser sur le serveur via le champ « hasNextPage ». De plus, nous pouvons suivre où nous en sommes à l’intérieur du jeu de données en examinant les champs « startCursor » et « endCursor ». Si nous voulions obtenir le prochain ensemble de données, nous pouvons simplement ajouter un (après : « derniercurseur ») à notre requête d’endpoints, comme illustré ci-dessous.
Nous pouvons voir que lorsque nous ajoutons cet argument « après » à la requête des endpoints, les données résultantes sont le prochain ensemble de 20 machines. Maintenant que nous savons comment paginer à travers les données, nous pouvons enfin tout rassembler dans un script Python qui exécutera une requête automatisée pour nous.
Bloc de code 4 : Tout rassembler pour interroger des jeux de données complets
def graphQL_pagination(ts : str, token : str) :
"""
graphQL_pagination fera le nom et le système d’exploitation de chaque endpoint à l’aide de
graphQL et de la pagination.
Le paramètre ts est le serveur Tanium à utiliser.
le jeton de paramètre est la chaîne de jeton api générée à partir du ts gui.
""
init_query = ''’
{
endpoints {
pageInfo {
startCursor
endCursor
hasNextPage
}
edges {
nœud {
name
os {
name
}
}
}
}
}'''
def do_request(ts : str, token : str, queryString : str) -> demandes.Réponse :
r = requests.post(ts + "/plugin/products/gateway/graphql",
json={'query' : queryString},
headers={'session' : token},
)
return r
endpoint_data = []
next_query = init_query
tandis que True :
# faites la demande et formatez la réponse dans 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"]
# informez l’utilisateur de la partie du curseur sur laquelle nous sommes.
print(
f"Données reçues pour les endpoints entre le début : {start_cursor} et la fin : {end_cursor}.")
# ajoutez les données d’endpoint dans notre objet liste
endpoint_data.extend(resp_obj["data"]["endpoints"]["edges"])
# si la page suivante est « Faux », nous avons atteint la fin du jeu de données !
si non a_next_page :
break
# injectez l’argument « après » dans la requête d’origine
next_query = init_query[ :25] + \
f »(après : \"{end_cursor}\") " + init_query[25 :]
Nous espérons que cela vous permettra de commencer à utiliser la passerelle API en dehors de Tanium. N’oubliez pas que de nombreux cas d’utilisation peuvent être réalisés simplement en utilisant les connecteurs natifs fournis par Tanium Connect. Lorsque vous devez créer une intégration personnalisée, la passerelle API est une ressource extrêmement utile, et des fonctionnalités supplémentaires sont ajoutées chaque semaine, y compris la prise en charge du module. Contactez votre représentant Tanium pour obtenir plus d’informations sur les éléments de la feuille de route ou une assistance supplémentaire pour vous aider dans vos efforts avec la passerelle API.
Découvrez comment vous pouvez libérer tout le potentiel de la plateforme Tanium avec la Tanium Integrations Gallery, une console centralisée qui fournit une visibilité en temps réel sur toutes nos intégrations et permet aux clients de découvrir, configurer et déployer sans effort. En simplifiant et en accélérant l’intégration de la plateforme Tanium avec des partenaires technologiques clés tels que Microsoft, ServiceNow, etc., la Tanium Integrations Gallery maximise la valeur des investissements technologiques tout en réduisant les risques et les inefficacités opérationnelles.
