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's API client.
This api client is only made for IRMA API version 2.
$ python setup.py installConfiguration file contains the API endpoint (full url) and some optional parameters (max number and delay in second between retries)
[Server]
api_endpoint=https://172.16.1.30/api/v2
max_tries=3
pause=1Optionnally you could add some SSL configuration, ca key unser Server section
if you want to verify server's certificate, and Client section if you have enabled
client certificates.
[Server]
api_endpoint=https://172.16.1.30/api/v2
max_tries=3
pause=1
ca=<path to ca.crt>
[Client]
cert=<path to client.crt>
key=<path to client.key>and is searched in these locations in following order:
- current directory
- environment variable ("IRMA_CONF")
- user home directory
- global directory ("/etc/irma")
Once you set up a working irma.conf settings file, you could run tests on your running IRMA server:
$ python setup.py testInstall it directly with pip:
$ pip install irmacl >>> from irmacl.helpers import *
>>> probe_list()
[u'Comodo', u'TrID']
>>> tag_list()
[Tag malware [1], Tag clean [2], Tag suspicious [3]]
>>> scan_files(["./irma/tests/samples/eicar.com"], force=True, blocking=True)
Scanid: b91c348b-1bc7-43fc-8363-983ef2e613e6
Status: finished
Probes finished: 2
Probes Total: 2
Date: 2018-03-13 11:42:01
Options: Force [True] Resubmit [True]
Mimetype [True]
Results: [<irmacl.apiclient.IrmaFileExt object at 0x7fc50e8ee2d0>]
>>> scan = _
>>> print scan.results[0]
id: 9098500f-6f06-4926-9558-c08608c3be23
Status: 1
Probes finished: 2
Probes Total: 2
Scanid: b91c348b-1bc7-43fc-8363-983ef2e613e6
Scan Date: 2018-03-13 11:42:01
Filename: eicar.txt
SHA256: 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267
ParentFile SHA256: None
>>> print scan_proberesults("9098500f-6f06-4926-9558-c08608c3be23")
id: 9098500f-6f06-4926-9558-c08608c3be23
Status: 1
Probes finished: 2
Probes Total: 2
Scanid: b91c348b-1bc7-43fc-8363-983ef2e613e6
Scan Date: 2018-03-13 11:42:01
Filename: eicar.txt
SHA256: 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267
ParentFile SHA256: None
FileInfo:
Size: 69
Sha1: cf8bd9dfddff007f75adf4c2be48005cea317c62
Sha256: 131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267
Md5: 69630e4574ec6798239b091cda43dca0s
First Scan: 2018-03-13 11:42:00
Last Scan: 2018-03-13 11:42:04
Mimetype: EICAR virus test files
Tags: []
Results: {u'antivirus':{u'Comodo Antivirus (Linux)': {u'status': 1, u'duration': 1.42, u'version': u'1.1.268025.1', u'results': u'Malware', u'virus_database_version': u'2018-03-13'}},
u'metadata': {u'TrID File Identifier': {u'status': 1, u'duration': 0.1, u'version': None, u'results': [{u'ext': u'.COM', u'ratio': u'100.0', u'desc': u'EICAR antivirus test file (7057/5)'}]}}}
>>> file_result = _
>>> print file_result.probe_results
{u'antivirus': {u'Comodo Antivirus (Linux)': {u'duration': 1.42,
u'results': u'Malware',
u'status': 1,
u'version': u'1.1.268025.1',
u'virus_database_version': u'2018-03-13'}},
u'metadata': {u'TrID File Identifier': {u'duration': 0.1,
u'results': [{u'desc': u'EICAR antivirus test file (7057/5)',
u'ext': u'.COM',
u'ratio': u'100.0'}],
u'status': 1,
u'version': None}}}Searching for scans
>>> scan_list()
(2, [Scanid: bec16782-7cc1-4807-b83c-42e23ef483c4
Status: finished
Probes finished: 2
Probes Total: 2
Date: 2018-03-13 11:40:48
Options: Force [True] Resubmit [True]
Mimetype [True] Results: [<irmacl.apiclient.IrmaFileExt object at 0x7fc50ded6610>],
Scanid: b91c348b-1bc7-43fc-8363-983ef2e613e6
Status: finished
Probes finished: 2
Probes Total: 2
Date: 2018-03-13 11:42:01
Options: Force [True] Resubmit [True]
Mimetype [True] Results: [<irmacl.apiclient.IrmaFileExt object at 0x7fc50ded6490>]])
[...]Searching for files
>>> file_search(name="ei")
(1, [<irmacl.apiclient.IrmaResults at 0x7f3f250491d0>])
>>> (total, res) = _
>>> print res[0]
Status: 1
Probes finished: 1
Probes Total: 1
Scanid: 7ae6b759-b357-4680-8358-b134b564b1ca
Filename: eicar.txt
[...]
>>> file_search(hash="131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267")
(1, [<irmacl.apiclient.IrmaFileExt at 0x7fc50df78d50>])
>>> file_search(hash="131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267", tags=[1,2])
(0, [])
# looking for an unexisting tagid raise IrmaError
>>> file_search(hash="131f95c51cc819465fa1797f6ccacf9d494aaaff46fa3eac73ae63ffbdfd8267", tags=[100])
IrmaError: Error 402- IrmaFileInfo
- IrmaFileInfo are the metadata information linked to a IrmaFile
- IrmaScan
- IrmaScan keep tracks of the IrmaFileExt scanned together, probe list used and scan options.
- IrmaFileExt
- IrmaFileExt object are scan results for a IrmaFile. One IrmaFileExt could be linked to only one IrmaScan. If you submit multiple times the same file and scan it each time, you create only one IrmaFile but create multiple IrmaFileExt all linked to the same IrmaFile.
- IrmaTag
- Tag will be directly linked to IrmaFiles, each IrmaFileExt linked to this IrmaFile will be tagged indirectly.
- about(verbose=False)
- Retrieves information about the application
- file_download(sha256, dest_filepath, verbose=False)
- Download file identified by sha256 to dest_filepath
- file_results(sha256, limit=None, offset=None, verbose=False)
- List all results for a given file identified by sha256
- file_search(name=None, hash=None, tags=None, limit=None, offset=None, verbose=False)
- Search a file by name or hash value
- file_tag_add(sha256, tagid, verbose=False)
- Add a tag to a File
- file_tag_remove(sha256, tagid, verbose=False)
- Remove a tag to a File
- probe_list(verbose=False)
- List availables probes
- data_upload(data, filename, verbose=False)
- Upload data, returns a fileext
- file_upload(filepath, verbose=False)
- Upload file, returns a fileext
- scan_cancel(scan_id, verbose=False)
- Cancel a scan
- scan_data(data, filename, force, post_max_size_M=100, probe=None, mimetype_filtering=None, resubmit_files=None, blocking=False,blocking_timeout=60, verbose=False)
- Wrapper around scan_new / scan_add / scan_launch
- scan_files(filelist, force, post_max_size_M=100, probe=None, mimetype_filtering=None, resubmit_files=None, blocking=False,blocking_timeout=60, verbose=False)
- Wrapper around scan_new / scan_add / scan_launch
- scan_get(scan_id, verbose=False)
- Fetch a scan (useful to track scan progress with scan.pstatus)
- scan_launch(file_id_list, force, probe=None, mimetype_filtering=None, resubmit_files=None, verbose=False)
- Launch an existing scan on Filext ids previously uploaded
- scan_list(limit=None, offset=None, verbose=False)
- List all scans
- scan_new(verbose=False)
- Create a new scan
- scan_proberesults(fe_id, formatted=True, verbose=False)
- Fetch file probe results (for a given scan
- one scan <-> one fileext_id
- tag_list(verbose=False)
- List all available tags
- tag_new(text, verbose=False)
- Create a new tag
The full IRMA documentation is available on Read The Docs Website.
Join the #qb_irma channel on irc.freenode.net. Lots of helpful people hang out there.
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.