Skip to main content

Assemblyline v4 client library

Project description

Assemblyline Client Library

The assemblyline client library facilitates issuing requests to assemblyline.

Pre-requisites

To install the client you'll need to make sure the you have the folowing installed:

# APT/YUM
libffi-dev
libssl-dev

# pypi
pycryptodome
requests
requests[security]
python-baseconv
python-socketio[client]
socketio-client==0.5.7.4

Using the client

You can instantiate the client using the following snippet of code:

# The new v4 client will test connection to detect if the server is v3 or v4. You should now use the get_client method.
from assemblyline_client import get_client
al_client = get_client("https://localhost:443", auth=('user', 'password'))

# or with an apikey

al_client = get_client("https://localhost:443", apikey=('user', 'key'))

# or with a cert 

al_client = get_client("https://localhost:443", cert='/path/to/cert/file.pem')

# and if your assemblyline server is using a self-signed cert

al_client = get_client("https://localhost:443", auth=('user', 'password'), verify=False)
al_client = get_client("https://localhost:443", auth=('user', 'password'), verify='/path/to/server.crt')

The assemblyline client is fully documented in the docstrings so if you use an interactive client like ipython you can use the help feature.

al_client.search.alert?
Signature: al_client.search.alert(query, *args, **kwargs)
Docstring:
Search alerts with a lucene query.

Required:
query   : Lucene query. (string)

Search parameters can be passed as key/value tuples or keyword parameters.

Returns all results.
File:      /usr/local/lib/python2.7/dist-packages/assemblyline_client/__init__.py
Type:      instancemethod

Examples

Submit a file

Submitting a file to the system is just as simple as passing the file path

al_client.submit('/path/to/my/file.txt')

Getting a key

To get a key of a given bucket, you simply need to pass it it's ID

submission_details = al_client.submission("4nxrpBePQDLH427aA8m3TZ")

Using search

You can use the search engine in the client by simply passing a lucene query

search_res = al_client.search.submission("submission.submitter:user")

Using search iterator

Instead of using a strait search and getting a page of result, you can use the search iterator to go through all results.

for submission in al_client.search.stream.submission("submission.submitter:user"):
    # It only return the indexed fields if you want the full thing you need to go get it
    full_submission = al_client.submission(submission['submission.sid'])

    # Then do stuff with full submission (print for example)
    print(full_submission)

Using search parameters

Version 3

You can pass search parameters for any given query. The following examples a Lucene facet search to get the top users submitting to a server.

kwargs = {'facet':'on', 'facet.field':'submission.submitter', 'facet.sort':'count', 'facet.limit':50, 'rows':0}  # rows=0 so that only facet results return
c.search.submission('times.submitted:[NOW-7DAYS TO NOW]', **kwargs)
Version 4

Version 4 server will support facet query out of the box, no need to learn the Lucene facetting syntax.

c.search.facet.submission('submission.submitter', query='times.submitted:[NOW-7DAYS TO NOW]')

Listen for message instead of querying for data

You can listen on the different message queues and execute a callback on each message.

def callback(callback_data):
    print callback_data

al_client.socketio.listen_on_dashboard_messages(callback)

NOTE: Depending on the volume of data, you might process a ton of messages!


Bibliothèque cliente d’Assemblyline

La bibliothèque cliente d’Assemblyline facilite la soumission de demandes à Assemblyline.

Exigences préalables

Avant de procéder à l’installation du client, vous devez vous assurer d’installer ce qui suit :

# APT/YUM
libffi-dev
libssl-dev

# pypi
pycryptodome
requests
requests[security]
python-baseconv
python-socketio[client]
socketio-client==0.5.7.4

Utilisation du client

Vous pouvez instancier le client au moyen de l’extrait de code suivant :

# Le nouveau client v4 détecte si le serveur est a la version 3 ou 4. Vous devez maintenant utilisé la fonction get_client.
from assemblyline_client import get_client
al_client = get_client("https://localhost:443", auth=('user', 'password'))

# ou d’une clé API :

al_client = get_client("https://localhost:443", apikey=('user', 'key'))

# ou d’un certificat :

al_client = get_client("https://localhost:443", cert='/path/to/cert/file.pem')

# et si votre server assemblyline a un certificat auto-signé

al_client = get_client("https://localhost:443", auth=('user', 'password'), verify=False)
al_client = get_client("https://localhost:443", auth=('user', 'password'), verify='/path/to/server.crt')

Le client d’Assemblyline est pleinement documenté dans les docstrings. Si vous utilisez un client interactif comme ipython, vous serez en mesure d’utiliser la fonction d’aide.

al_client.search.alert?
Signature: al_client.search.alert(query, *args, **kwargs)
Docstring:
Search alerts with a Lucene query.

Required:
query   : Lucene query. (string)

Search parameters can be passed as key/value tuples or keyword parameters.

Returns all results.
File:      /usr/local/lib/python2.7/dist-packages/assemblyline_client/__init__.py
Type:      instancemethod

Exemples

Soumission d’un fichier

Pour soumettre un fichier au système, il suffit d’envoyer le chemin d’accès du fichier.

al_client.submit('/chemin/acces/de/mon/fichier.txt')

Obtention d’une clé

Pour obtenir une clé pour un compartiment donné, il suffit d’envoyer son ID.

submission_details = al_client.submission("4nxrpBePQDLH427aA8m3TZ")

Utilisation de la recherche

Pour utiliser le moteur de recherche du client, il suffit de transmettre une demande Lucene.

search_res = al_client.search.submission("submission.submitter:user")

Utilisation de l’itérateur de recherche

Plutôt que d’utiliser une recherche directe et d’obtenir une page de résultats, vous pouvez utiliser l’itérateur de recherche pour passer à travers tous les résultats.

for submission in al_client.search.stream.submission("submission.submitter:user"):
    # Seuls les champs indexés sont renvoyés. Pour obtenir les résultats dans leur intégralité, vous devez y accéder manuellement,
    full_submission = al_client.submission(submission['submission.sid'])

    # puis faire quelque chose avec la soumission complète (imprimer, par exemple)
    print(full_submission)

Utilisation des paramètres de recherche

Version 3

Vous pouvez transmettre des paramètres de recherche pour une requête donnée. Les exemples suivants démontrent une recherche de facettes Lucene pour obtenir les utilisateurs les plus fréquants soumettant à un server.

kwargs = {'facet':'on', 'facet.field':'submission.submitter', 'facet.sort':'count', 'facet.limit':50, 'rows':0}  # rows=0 pour que seuls les résultats de la facette soient retourné
c.search.submission('times.submitted:[NOW-7DAYS TO NOW]', **kwargs)
Version 4

Le serveur version 4 supporte directement les recherches de facettes, vous navez donc pas besoin den apprendre la syntaxe.

c.search.facet.submission('submission.submitter', query='times.submitted:[NOW-7DAYS TO NOW]')

L’écoute du message plutôt que la recherche de données

Vous pouvez écouter les différentes files d’attente de messages et effectuer un rappel pour chaque message.

def callback(callback_data):
    print callback_data

al_client.socketio.listen_on_dashboard_messages(callback)

REMARQUE : Selon le volume de données, vous pourriez traiter une grande quantité de messages!

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

assemblyline_client-4.0.0b10-py2.py3-none-any.whl (47.4 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page