Skip to main content

Irma asynchronous command line tool for API v3

Project description

Documentation Status

IRMA is an asynchronous and customizable analysis system for suspicious files. This repository is a subproject of IRMA and contains the source code for IRMA API client.

Irmacl-async requires python 3.6+ and an IRMA server with API version 3. The exact expected version is defined in AAPI.IRMA_VERSION.

Installation

From the sources, clone the repository and run

$ pip install .

Or with pip just run

$ pip install irmacl-async

Configuration

Irmacl-async configuration is done with a Config object that should be given to AAPI at initialisation. The details of expected configuration is available with help(Config). A Config object can be initialized from an irma.yml file, which is a yaml file containing the parameters of a Config object. All parameters are optional.

api_endpoint: "https://172.16.1.30/api/v3"
verify: true
ca: /etc/irma/ca.crt
cert: /etc/irma/client.crt
key: /etc/irma/client.key
submitter: kiosk
submitter_id: kiosk-D205

irma.yml is searched in these locations in following order:

  • environment variable IRMA_CONF

  • current directory

  • user home directory

  • global directory /etc/irma

Once you set up a working irma.yml settings file, you could run tests on your running IRMA server:

$ python setup.py test

Usage

Irmacl-async is an asynchronous library. It is meant to ease the development of python code that communicates with an IRMA server.

Hello world

>>> import asyncio
>>> from irmacl_async import AAPI
>>>
>>> async def main():
...     async with AAPI() as api:
...         resp = await api.about()
...         print(resp['version'])
...
>>> loop = asyncio.get_event_loop()
>>> loop.run_until_complete(main())
v2.2.3-20-g06a29b45

The main coroutine just prints the version of the IRMA server counterpart. There is few things to notice in this example.

First, an async context pattern must be opened to create a session and perform requests. Moreover, AAPI will check the version of IRMA and prints a warning if it mismatches the expected one (apicheck=False to prevent this behavior). Irmacl-async uses aiohttp.ClientSession in backend, you can set AAPI().session manually at your own risks but it is not recommenced.

Second, api.about does not return a result but a Future that needs to be awaited before being able to get its result.

Finally, the main coroutine cannot just be called as a regular function but needs to be awaited from another coroutine or run into an event loop.

Basic usage

>>> import asyncio
>>> from pathlib import Path
>>> from irmacl_async import AAPI
>>>
>>> async def scandir(directory):
...     files = (p for p in directory.iterdir() if p.is_file())
...     async with AAPI() as api:
...         scan = await api.scans.scan(files, linger=True)
...         res = await AAPI.fetchall(api.scans.results, scan=scan)
...         files = [api.files.get(fe.file) for fe in res]
...         return await asyncio.gather(*files)
...
>>> loop = asyncio.get_event_loop()
>>> d = Path("irmacl_async/tests/functionals/samples")
>>> loop.run_until_complete(scandir(d))
[FileExt.d13ab478-b24e-43a2-a51a-38c10355e929, ...]

The scandir coroutine is a bit more complex and benefits from the asynchronicity of the irmacl-async library. It scans the contents of a directory and wait for the result (linger=True). Then, it queries all results of the scan. api.scans.results returns a page of result, so, use it with the fetchall helper to get all pages at once. Then, for each result it queries information about the file itself. Instead of a for loop, that would query the files one at a time, it uses asyncio.gather. Finally it waits for every request to be complete and returns the results.

References

AAPI

Every method is -or at least should be- fully documented, use help(AAPI) or help(AAPI().files) to get a exhaustive list of every available method and their parameters.

Objects

irmacl_async makes a heavy use of irma-shared to handle deserialisation and objects construction.

Coverage

Coverage is available on https://irma.doc.qb/irma-shared/coverage. Check the deployed branch in the title of the page.

Other

Documentation

The full IRMA documentation is available on Read The Docs Website.

Getting help

Join the #qb_irma channel on irc.freenode.net. Lots of helpful people hang out there.

Contribute to IRMA

IRMA is an ambitious project. Make yourself known on the #qb_irma channel on irc.freenode.net. We will be please to greet you and to find a way to get you involved in the project.

Project details


Download files

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

Source Distribution

irmacl-async-3.4.1.tar.gz (20.5 kB view hashes)

Uploaded Source

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