-
Notifications
You must be signed in to change notification settings - Fork 20
Getting Started
The python-maec library provides an API for developing and consuming Malware Attribute Enumeration and Characterization (MAEC) content. Developers can leverage the API to create applications that create, consume, translate, or otherwise work with MAEC content. This page should help new developers get started with using this library. For more information about MAEC, please refer to the MAEC website.
The python-maec library provides an API for creating or processing MAEC content. As such, it is a developer tool that can be leveraged by those who know Python 2.6/2.7 and are familiar with object-oriented programming practices, Python package layouts, and are comfortable with the installation of Python libraries. To contribute code to the python-maec repository, users must be familiar with git and GitHub pull request methodologies. Understanding XML, XML Schema, and the MAEC language is also incredibly helpful when using python-maec in an application.
The python-maec library relies on some non-standard Python libraries for the processing of MAEC content. Revisions of python-maec may depend on particular versions of dependencies to function correctly. These versions are detailed within the distutils setup.py installation script.
The following libraries are required to use python-maec:
- lxml - A Pythonic binding for the XML processing toolkits, libxml2 and libxslt.
- python-cybox - A library for consuming and producing CybOX content
- python-dateutil - A library for parsing datetime information.
- setuptools - Required for installation of python-maec
The installation of python-maec can be accomplished through a few different workflows.
This is the easiest way to install python-maec. Each release of python-maec is hosted at PyPI and can be installed via the pip utility. Installing python-maec via this manner is as easy as executing the following command pip install MAEC. This will attempt to install python-maec and all dependencies automatically.
Please refer to the pip installation instructions for details regarding the installation of pip.
The python-maec library contains a setup.py script that leverages PyPI's setuptools. To install via this method, follow these steps:
Download and install the dependencies listed above. Please refer to their documentation for installation instructions.
Download python-maec release from its PyPI page.
Unzip the downloaded tarball or zip file. This will leave you with a directory named MAEC-<version>.
Run the installation script. This will install the python-maec library into the site-packages directory of Python installation or virtualenv.
$ cd MAEC-<version>
$ python setup.py installThe python-maec GitHub repository contains several example scripts that help illustrate the capabilities of the APIs. These can be found here: https://github.com/MAECProject/python-maec/tree/master/examples. These scripts are simple command line utilities that can be executed by passing the name of the script to a Python interpreter.
Example:
$ python example1.pyNote that you must install python-maec before running these example scripts.
Once a user has installed python-maec, they are able to start writing Python applications that consume or create MAEC content! To create a MAEC Package with a MAEC Header, a script would look like the following:
from maec.package.package import Package # Import the MAEC Package API
from maec.package.malware_subject import MalwareSubject # Import the MAEC Malware Subject API
from cybox.core import Object # Import the CybOX Object API
maec_package = Package(id='maec-example-pkg-1') # Create an instance of Package
malware_subject = MalwareSubject(id='maec-example-sub-1') # Create an instance of Malware Subject
file_object_dict = {'properties' : {'xsi:type' : 'FileObjectType', 'file_name' : 'example.exe'}} # Create a simple dictionary representing a CybOX File Object
malware_subject.set_malware_instance_object_attributes(Object.from_dict(file_object_dict)) # Set the Malware Instance Object Attributes of the Malware Subject
maec_package.add_malware_subject(malware_subject) # Add the Malware Subject to the Package
maec_package.to_xml_file('example.xml') # Write the XML output for this Package to 'example.xml'To parse existing content, a script would look like the following:
from maec.package.package import Package # Import the MAEC Package API
fn = 'maec_content.xml' # The MAEC content filename
(maec_package, maec_package_binding_obj) = Package.from_xml(fn) # Parse using the from_xml() method
'''
Note that the Package.from_xml() method returns two objects: an API object and a binding object.
The API object provides easy, Pythonic access and interaction with MAEC entities. The binding objects
are leveraged under the hood and provide low-level, more complete implementations of the MAEC data
types. In other words, the API objects are easy to use but lack completeness, while the binding objects
are more cumbersome but are complete in their implementation of MAEC entities.
'''To see more examples, please look at the examples section of the python-maec repository!
If a bug is found, a feature is missing, or something just isn't behaving the way you'd expect it to, please submit an issue to our tracker. If you'd like to contribute code to our repository, you can do so by issuing a pull request and we will work with you to try and integrate that code into our repository.