Irma asynchronous command line tool for API v3
Project description
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.5+ 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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for irmacl_async-3.1.2b3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f1001214d8b13aecb62d0e8093158aa28e65ab62ee5aca1643d36cdfb6b2a8f9 |
|
MD5 | a541e82edfc9e6b6f093d433860523c3 |
|
BLAKE2b-256 | 532ddb3642c94481795ad96a0254929d3d9b108e316e605d4814891e00add84f |