atklite
=======

atklite is a library intended to help easily determine identifiable attributes 
about files under investigation. With a simple usage syntax, the following 
information can be determined by calling applications:

- MD5 hash
- SHA-1 hash
- SHA-256 hash
- CRC32 checksum
- File size
- File type (from magic bytes)
- Fuzzy hash (CTPH) via ssdeep

atklite is primarily intended for use in analyzing malware samples but may be
useful for anyone looking for a simple API for analyzing files.

Additionally, atklite can be used as a binary storage system, utilizing a standard
filesystem to store the files in a sharded manner using the first n bytes of the
hash that a user chooses to use (md5, sha1, sha256 or sha512).

Setup
=====

Requirements
------------

- Python (tested with Python 2.7)
- python-magic_. On most systems this requires the libmagic library to be
  installed.
- Python ssdeep wrapper, one of either:

  - python-ssdeep_
  - pydeep_

.. _python-magic: https://pypi.python.org/pypi/python-magic/
.. _python-ssdeep: http://github.com/DinoTools/python-ssdeep
.. _pydeep: https://github.com/kbandla/pydeep


Installing Prerequisites
------------------------

Installing the prerequisites on an ubuntu system is fairly easy.

First we must install the prerequisites for python-ssdeep::
    $ apt-get install cython ssdeep python-dev


Installation
------------

Installation with pip is simple::

    $ pip install atklite

If installing from source, unpack the distribution tarball and then install as
follows::

    $ python setup.py build
    $ python setup.py install


Configuration and use
---------------------

Usage::

    From the cli using atk-info:
    jpleger@jupiter:~$ atk-info ~/glyphicons-halflings-white.png
    [-] Using binary store at: /home/jpleger/binary_store
    -- glyphicons-halflings-white.png ----------------------------------------------
      Analyze time: Mon Jul 29 18:23:10 2013
      File name:    glyphicons-halflings-white.png
      File size:    8777
      File type:    PNG image data, 469 x 159, 8-bit colormap, non-interlaced
      CRC-32:       43808ba4
      MD5 hash:     9bbc6e9602998a385c2ea13df56470fd
      SHA1 hash:    a25c4705320fd63c33790e666872910e702b9bf6
      SHA256 hash:  f0e0d95a9c8abcdfabf46348e2d4285829bb0491f5f6af0e05af52bffb6324c4
      Fuzzy hash:   192:41MFu/STZChMGLw/LtI30ukSCeQm9F+xZdqdfQpTTTIyQY7thi7uWB:iMdZ/GLILBmWEiTTTIyQY5hi71
      Stored File:  /home/jpleger/binary_store/9/b/b/9bbc6e9602998a385c2ea13df56470fd
    jpleger@jupiter:~$

    From the python interpreter:
    >>> import atklite
    >>> file_analysis = atklite.FileAnalysis(filename='9ba57b128089f0a5a07b262511307f9c.exe')
    >>> print file_analysis.dump()
    sha1: 63738713f1e22425e06dd1f20e5cd22c630fd7d3
    analyzetime: Sat Mar  2 00:57:50 2013
    ftype: PE32 executable (DLL) (GUI) Intel 80386, for MS Windows
    crc32: 9083b5e6
    ttime: 1362211070.21
    sha256: 04a191e1d7526025ee911f8a55d5c329af456cbd48d507dc2040b4ead1e4a525
    ssdeep: 1536:o+I6XtaJU0ikjlcCGXM6ds6GGA2P+ly+Hmuh81HSR:o+fXtBYcCiX1xP0Hmk8s
    md5: 9ba57b128089f0a5a07b262511307f9c
    size: 77824

    >>> analysis = file_analysis.return_analysis()
    >>> analysis['analyzetime']
    'Sat Mar  2 00:57:50 2013'
    >>> print analysis['md5']
    9ba57b128089f0a5a07b262511307f9c
    >>> print analysis['sha1']
    63738713f1e22425e06dd1f20e5cd22c630fd7d3
    >>> print analysis['sha256']
    04a191e1d7526025ee911f8a55d5c329af456cbd48d507dc2040b4ead1e4a525
    >>> print analysis['size']
    77824
    >>> print analysis['crc32']
    9083b5e6
    >>> print analysis['ftype']
    PE32 executable (DLL) (GUI) Intel 80386, for MS Windows
    >>> print analysis['ssdeep']
    1536:o+I6XtaJU0ikjlcCGXM6ds6GGA2P+ly+Hmuh81HSR:o+fXtBYcCiX1xP0Hmk8s


To Do
=====

Nice to Have
------------
 * Storing the reports with the files
 * Tagging within the saved reports
