README.rst
1python-maec
2===========
3
4A Python library for parsing, manipulating, and generating `Malware Attribute Enumeration and Characterization (MAEC™) <https://maecproject.github.io/>`_ v4.1 content.
5
6:Source: https://github.com/MAECProject/python-maec
7:Documentation: https://maec.readthedocs.io/
8:Information: https://maecproject.github.io/
9:Download: https://pypi.python.org/pypi/maec/
10
11|travis badge| |landscape.io badge| |version badge| |downloads badge|
12
13.. |travis badge| image:: https://api.travis-ci.org/MAECProject/python-maec.svg?branch=master
14 :target: https://travis-ci.org/MAECProject/python-maec
15 :alt: Build Status
16.. |landscape.io badge| image:: https://landscape.io/github/MAECProject/python-maec/master/landscape.svg?style=flat
17 :target: https://landscape.io/github/MAECProject/python-maec/master
18 :alt: Code Health
19.. |Version Badge| image:: https://img.shields.io/pypi/v/maec.svg?maxAge=3600
20 :target: https://pypi.python.org/pypi/maec/
21.. |Downloads Badge| image:: https://img.shields.io/pypi/dm/maec.svg?maxAge=3600
22 :target: https://pypi.python.org/pypi/maec/
23
24
25Overview
26--------
27
28A primary goal of the python-maec library is to remain faithful to both the
29MAEC standard and to customary Python practices. There are places where these
30will conflict, and the goal is to make the library intuitive both to those
31familiar with the XML schemas (but less familiar with Python) and also to
32experienced Python developers who want to add MAEC support to their programs.
33
34There are currently two levels of APIs for dealing with MAEC content:
35
36- A low-level API is provided by auto-generated XML Schema - Python class
37 bindings. These bindings were generated using `generateDS
38 <http://www.rexx.com/~dkuhlman/generateDS.html>`_. With these, any MAEC
39 content can be parsed from or written to XML, but requires a bit more
40 knowledge of the actual MAEC schemas. These "binding classes" are all located
41 in the ``maec.bindings`` package.
42- A higher-level API consisting of manually designed Python classes. These
43 "native classes" are intended to behave more like Python programmers would
44 expect. As they are designed manually, they currently do not support the
45 entire MAEC standard, but rather those object types we expect are used most
46 frequently. These "native classes" also support exporting their content as
47 Python dictionaries and lists, which can easily be converted to JSON.
48 Importing from JSON is also supported.
49
50Compatibility
51-------------
52The python-maec library is tested against Python 2.7 and 3.4+.
53
54Versioning
55----------
56
57Releases of the python-maec library will be given version numbers of the form
58``major.minor.update.revision``, where ``major``, ``minor``, and ``update``
59correspond to the MAEC version being supported. The ``revision`` number is used
60to indicate new versions of the python-maec library itself.
61
62Installation
63------------
64
65The python-maec library can be installed via the distutils setup.py script
66included at the root directory:
67
68 $ python setup.py install
69
70The python-maec library is also hosted on `PyPI
71<https://pypi.python.org/pypi/maec/>`_ and can be installed with `pip
72<https://pypi.python.org/pypi/pip>`_:
73
74 $ pip install maec
75
76Dependencies
77------------
78
79The ``maec`` package depends on the following Python libraries:
80
81* ``lxml``
82
83* ``python-cybox``
84
85* ``setuptools`` (only if installing using setup.py)
86
87For Windows installers of the above libraries, we recommend looking here:
88http://www.lfd.uci.edu/~gohlke/pythonlibs. python-cybox can be found at
89https://github.com/CybOXProject/python-cybox/releases.
90
91To build ``lxml`` on Ubuntu, you will need the following packages from the
92Ubuntu package repository:
93
94* python-dev
95
96* libxml2-dev
97
98* libxslt1-dev
99
100* zlib1g-dev
101
102For more information about installing lxml, see
103http://lxml.de/installation.html.
104
105Feedback
106--------
107
108Bug reports and feature requests are welcome and encouraged. Pull requests are
109especially appreciated. Feel free to use the issue tracker on GitHub, join the `MAEC Community Email Discussion List <https://maec.mitre.org/community/discussionlist.html>`_, or send an email directly to maec@mitre.org.
110
