Metadata-Version: 1.0
Name: irmacl
Version: 2.0.3
Summary: Irma command line tool for API v2
Home-page: https://github.com/quarkslab/irma-cli
Author: irma-dev
Author-email: irma-dev@quarkslab.com
License: ApacheV2
Description: Irmacl: command-line tool for IRMA API
        --------------------------------------
        
        |docs|
        
        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.**
        
        Installation
        ````````````
        .. code-block:: console
        
           $ python setup.py install
        
        
        Configuration file contains the API endpoint (full url) and some optional parameters (max number and
        delay in second between retries)
        
        .. code-block:: console
        
           [Server]
           api_endpoint=http://172.16.1.30/api/v2
           max_tries=3
           pause=1
        
        Optionnally 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.
        
        .. code-block:: console
        
           [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:
        
        .. code-block:: bash
        
           $ python setup.py test
        
        
        Pip Install
        -----------
        
        Install it directly with pip:
        
        .. code-block:: bash
        
          $ pip install irmacl
        
        
        Usage
        -----
        
        .. code-block:: python
        
           >>> 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
        
        .. code-block:: python
        
           >>> 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
        
        .. code-block:: python
        
           >>> 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
        
        
        Objects (apiclient.py)
        -------
        
        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.
        
        
        Helpers (helpers.py)
        -------
        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
        
        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.
        
        
        .. |docs| image:: https://readthedocs.org/projects/irma/badge/
            :alt: Documentation Status
            :scale: 100%
            :target: https://irma.readthedocs.io
        .. _on Read The Docs Website: https://irma.readthedocs.io
        
Platform: UNKNOWN
