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 1.1.

$ python setup.py install

Configuration file contains only the API endpoint address (not the full url).

[Server]
address=172.16.1.30

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 a running IRMA instance:

$ python setup.py test

Install it directly with pip:

$ pip install git+https://github.com/quarkslab/irma-cli.git

>>> from irma.helpers import *
>>> probe_list()
[u'StaticAnalyzer', u'Unarchive', u'VirusBlokAda', u'VirusTotal']

>>>  tag_list()
[Tag malware [1], Tag clean [2], Tag suspicious [3]]

>>>  scan_files(["./irma/tests/samples/eicar.com"], force=True, blocking=True)
Scanid: ca2e8af4-0f5b-4a55-a1b8-2b8dc9ead068
Status: finished
Options: Force [True] Mimetype [True] Resubmit [True]
Probes finished: 2
Probes Total: 2
Date: 2015-11-24 15:43:03
Results: [<irma.apiclient.IrmaResults object at 0x7f3f250df890>]

>>> scan = _
>>> print scan.results[0]
Status: 1
Probes finished: 2
Probes Total: 2
Scanid: ca2e8af4-0f5b-4a55-a1b8-2b8dc9ead068
Scan Date: 2015-12-22 14:36:21
Filename: eicar.com
Filepath: ./irma/tests/samples
ParentFile SHA256: None
Resultid: 572f9418-ca3c-4fdf-bb35-50c11629a7e7
FileInfo: 
None
Results: None

>>> print scan_proberesults("572f9418-ca3c-4fdf-bb35-50c11629a7e7")
Status: 1
Probes finished: 2
Probes Total: 2
Scanid: ca2e8af4-0f5b-4a55-a1b8-2b8dc9ead068
Scan Date: 2015-12-22 14:36:21
Filename: eicar.com
Filepath: ./irma/tests/samples
ParentFile SHA256: None
Resultid: 572f9418-ca3c-4fdf-bb35-50c11629a7e7
FileInfo: 
Size: 68
Sha1: 3395856ce81f2b7382dee72602f798b642f14140
Sha256: 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
Md5: 44d88612fea8a8f36de82e1278abb02fs
First Scan: 2015-11-24 14:54:12
Last Scan: 2015-12-22 14:36:21
Id: 3
Mimetype: EICAR virus test files
Tags: []

Results: [<irma.apiclient.IrmaProbeResult object at 0x7f3f250b9dd0>, <irma.apiclient.IrmaProbeResult object at 0x7f3f250b9850>]

>>> fr = _
>>> print fr.probe_results[0]
Status: 1
Name: VirusBlokAda (Console Scanner)
Category: antivirus
Version: 3.12.26.4
Duration: 1.91s
Results: EICAR-Test-File

Searching for scans

>>> scan_list()
(89, [Scanid: ef0b9466-3132-40b7-990a-415f08377f09
  Status: finished
  Options: Force [True] Mimetype [True] Resubmit [True]
  Probes finished: 1
  Probes Total: 1
  Date: 2015-11-24 15:04:27
[...]

Searching for files

>>> file_search(name="ei")
(1, [<irma.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.com
[...]

>>> file_search(hash="3395856ce81f2b7382dee72602f798b642f14140")
(7,
 [<irma.apiclient.IrmaResults at 0x7f3f250b96d0>,
  <irma.apiclient.IrmaResults at 0x7f3f24fdc1d0>,
  <irma.apiclient.IrmaResults at 0x7f3f24fdca90>,
  <irma.apiclient.IrmaResults at 0x7f3f24fdcdd0>,
  <irma.apiclient.IrmaResults at 0x7f3f24fdc690>,
  <irma.apiclient.IrmaResults at 0x7f3f2504f390>,
  <irma.apiclient.IrmaResults at 0x7f3f24fea350>])

>>> file_search(hash="3395856ce81f2b7382dee72602f798b642f14140", tags=[1,2])
(0, [])

# looking for an unexisting tagid raise IrmaError
>>> file_search(hash="3395856ce81f2b7382dee72602f798b642f14140", tags=[100])
IrmaError: Error 402

Objects (apiclient.py) -------

class irma.apiclient.IrmaFileInfo(id, size, timestamp_first_scan, timestamp_last_scan, sha1, sha256, md5, mimetype, tags)

Bases: "object"

IrmaFileInfo Description for class

Variables:

• id -- id
• timestamp_first_scan -- timestamp when file was first scanned in IRMA
• timestamp_last_scan -- timestamp when file was last scanned in IRMA
• size -- size in bytes
• md5 -- md5 hexdigest
• sha1 -- sha1 hexdigest
• sha256 -- sha256 hexdigest
• mimetype -- mimetype (based on python magic)
• tags -- list of tags

pdate_first_scan -- property, humanized date of first scan

pdate_last_scan -- property, humanized date of last scan

raw()

class irma.apiclient.IrmaProbeResult(kwargs)**

Bases: "object"

IrmaProbeResult Description for class

Variables:

• status -- int probe specific (usually -1 is error, 0 nothing found 1 something found)
• name -- probe name
• type -- one of IrmaProbeType ('antivirus', 'external', 'database', 'metadata'...)
• version -- probe version
• duration -- analysis duration in seconds
• results -- probe results (could be str, list, dict)
• error -- error string (only relevant in error case when status == -1)
• external_url -- remote url if available (only relevant when type == 'external')
• database -- antivirus database digest (need unformatted results) (only relevant when type == 'antivirus')
• platform -- 'linux' or 'windows' (need unformatted results)

to_json()

class irma.apiclient.IrmaResults(file_infos=None, probe_results=None,kwargs)**

Bases: "object"

IrmaResults Description for class

Variables:

• status -- int (0 means clean 1 at least one AV report this file as a virus)
• probes_finished -- number of finished probes analysis for current file
• probes_total -- number of total probes analysis for current file
• scan_id -- id of the scan
• scan_date -- date of the scan
• name -- file name
• path -- file path (as sent during upload or resubmit)
• result_id -- id of specific results for this file and this scan used to fetch probe_results through file_results helper function
• file_infos -- IrmaFileInfo object
• probe_results -- list of IrmaProbeResults objects

to_json()

pscan_date -- property, humanized date of scan date

class irma.apiclient.IrmaScan(id, status, probes_finished, probes_total, date, force, resubmit_files, mimetype_filtering, results=[])

Bases: "object"

IrmaScan Description for class

Variables:

• id -- id of the scan
• status -- int (one of IrmaScanStatus)
• probes_finished -- number of finished probes analysis for current scan
• probes_total -- number of total probes analysis for current scan
• date -- scan creation date
• force -- force a new analysis or not
• resubmit_files -- files generated by the probes should be analyzed or not
• mimetype_filtering -- probes list should be decided based on files mimetype or not
• results -- list of IrmaResults objects

is_finished()

is_launched()

pdate -- property, printable date

pstatus -- property, printable status

class irma.apiclient.IrmaTag(id, text)

Bases: "object"

IrmaTag Description for class

Variables:

• id -- id of the tag
• text -- tag label

Helpers (helpers.py) -------

irma.helpers.file_download(sha256, dest_filepath, verbose=False)

Download file identified by sha256 to dest_filepath

Parameters:

• sha256 (str of 64 chars) -- file sha256 hash value
• dest_filepath (str) -- destination path
• verbose (bool) -- enable verbose requests (optional default:False)

Returns:

return tuple of total files and list of results for the given file

Return type:

tuple(int, list of IrmaResults)

irma.helpers.file_results(sha256, limit=None, offset=None, verbose=False)

List all results for a given file identified by sha256

Parameters:

• sha256 (str of 64 chars) -- file sha256 hash value
• limit (int) -- max number of files to receive (optional default:25)
• offset (int) -- index of first result (optional default:0)
• verbose (bool) -- enable verbose requests (optional default:False)

Returns:

tuple(int, list of IrmaResults)

irma.helpers.file_search(name=None, hash=None, tags=None, limit=None, offset=None, verbose=False)

Search a file by name or hash value

Parameters:

• name (str) -- name of the file ('name' will be searched)
• hash (str of (64, 40 or 32 chars)) -- one of sha1, md5 or sha256 full hash value
• tags (list of int) -- list of tagid
• limit (int) -- max number of files to receive (optional default:25)
• offset (int) -- index of first result (optional default:0)
• verbose (bool) -- enable verbose requests (optional default:False)

Returns:

return tuple of total files and list of matching files already scanned

Return type:

tuple(int, list of IrmaResults)

irma.helpers.file_tag_add(sha256, tagid, verbose=False)

Add a tag to a File

Parameters:

• sha256 (str of (64 chars)) -- file sha256 hash
• tagid (int) -- tag id

Returns:

No return

irma.helpers.file_tag_remove(sha256, tagid, verbose=False)

Remove a tag to a File

Parameters:

• sha256 (str of (64 chars)) -- file sha256 hash
• tagid (int) -- tag id

Returns:

No return

irma.helpers.probe_list(verbose=False)

List availables probes

Parameters:

verbose (bool) -- enable verbose requests (optional default:False)

Returns:

return probe list

Return type:

list

irma.helpers.scan_add(scan_id, filelist, verbose=False)

Add files to an existing scan

Parameters:

• scan_id (str) -- the scan id
• filelist (list) -- list of full path qualified files
• verbose (bool) -- enable verbose requests (optional default:False)

Returns:

return the updated scan object

Return type:

IrmaScan

irma.helpers.scan_cancel(scan_id, verbose=False)

Cancel a scan

Parameters:

• scan_id (str) -- the scan id
• verbose (bool) -- enable verbose requests (optional default:False)

Returns:

return the scan object

Return type:

IrmaScan

irma.helpers.scan_files(filelist, force, probe=None, mimetype_filtering=None, resubmit_files=None, blocking=False, verbose=False)

Wrapper around scan_new / scan_add / scan_launch

Parameters:

• filelist (list) -- list of full path qualified files
• force (bool) -- if True force a new analysis of files if False use existing results
• probe (list) -- probe list to use (optional default: None means all)
• mimetype_filtering (bool) -- enable probe selection based on mimetype (optional default:True)
• resubmit_files (bool) -- reanalyze files produced by probes (optional default:True)
• blocking (bool) -- wether or not the function call should block until scan ended
• verbose (bool) -- enable verbose requests (optional default:False)

Returns:

return the scan object

Return type:

IrmaScan

irma.helpers.scan_get(scan_id, verbose=False)

Fetch a scan (useful to track scan progress with scan.pstatus)

Parameters:

• scan_id (str) -- the scan id
• verbose (bool) -- enable verbose requests (optional default:False)

Returns:

return the scan object

Return type:

IrmaScan

irma.helpers.scan_launch(scan_id, force, probe=None, mimetype_filtering=None, resubmit_files=None, verbose=False)

Launch an existing scan

Parameters:

• scan_id (str) -- the scan id
• force (bool) -- if True force a new analysis of files if False use existing results
• probe (list) -- probe list to use (optional default None means all)
• mimetype_filtering (bool) -- enable probe selection based on mimetype (optional default:True)
• resubmit_files (bool) -- reanalyze files produced by probes (optional default:True)
• verbose (bool) -- enable verbose requests (optional default:False)

Returns:

return the updated scan object

Return type:

IrmaScan

irma.helpers.scan_list(limit=None, offset=None, verbose=False)

List all scans

Parameters:

• limit (int) -- max number of files to receive (optional default:25)
• offset (int) -- index of first result (optional default:0)
• verbose (bool) -- enable verbose requests (optional default:False)

Returns:

return tuple of total scans and list of scans

Return type:

tuple(int, list of IrmaScan)

irma.helpers.scan_new(verbose=False)

Create a new scan

Parameters:

verbose (bool) -- enable verbose requests (optional default:False)

Returns:

return the new generated scan object

Return type:

IrmaScan

irma.helpers.scan_proberesults(result_idx, formatted=True, verbose=False)

Fetch file probe results (for a given scan

one scan <-> one result_idx

Parameters:

• result_idx (str) -- the result id
• formatted (bool) -- apply frontend formatters on results (optional default:True)
• verbose (bool) -- enable verbose requests (optional default:False)

Returns:

return a IrmaResult object

Return type:

IrmaResults

irma.helpers.tag_list(verbose=False)

List all available tags

Returns:

list of existing tags

Return type:

list of IrmaTag

irma.helpers.tag_new(text, verbose=False)

Create a new tag

Parameters:

text (str) -- tag label (utf8 encoded)

Returns:

None

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.