**IMPORTANT NOTE**: This library will require **at least** Python 3.10 starting the 1st of January 2024. If you have legacy versions of python, please use the latest PyMISP version that will be released in December 2023, and consider updating your system(s). Anything released within the last 2 years will do, starting with Ubuntu 22.04.
# PyMISP - Python Library to access MISP
[](http://pymisp.readthedocs.io/?badge=latest)
[](https://coveralls.io/github/MISP/PyMISP?branch=main)
[](https://www.python.org/downloads/release/python-380/)
[](https://pypi.python.org/pypi/pymisp/)
[](https://pypi.python.org/pypi/pymisp/)
PyMISP is a Python library to access [MISP](https://github.com/MISP/MISP) platforms via their REST API.
PyMISP allows you to fetch events, add or update events/attributes, add or update samples or search for attributes.
## Install from pip
**It is strongly recommended to use a virtual environment**
If you want to know more about virtual environments, [python has you covered](https://docs.python.org/3/tutorial/venv.html)
Only basic dependencies:
```
pip3 install pymisp
```
And there are a few optional dependencies:
* fileobjects: to create PE/ELF/Mach-o objects
* openioc: to import files in OpenIOC format (not really maintained)
* virustotal: to query VirusTotal and generate the appropriate objects
* docs: to generate te documentation
* pdfexport: to generate PDF reports out of MISP events
* url: to generate URL objects out of URLs with Pyfaup
* email: to generate MISP Email objects
* brotli: to use the brotli compression when interacting with a MISP instance
Example:
```
pip3 install pymisp[virustotal,email]
```
## Install the latest version from repo from development purposes
**Note**: poetry is required; e.g., "pip3 install poetry"
```
git clone https://github.com/MISP/PyMISP.git && cd PyMISP
git submodule update --init
poetry install -E fileobjects -E openioc -E virustotal -E docs -E pdfexport -E email
```
### Running the tests
```bash
poetry run pytest --cov=pymisp tests/test_*.py
```
If you have a MISP instance to test against, you can also run the live ones:
**Note**: You need to update the key in `tests/testlive_comprehensive.py` to the automation key of your admin account.
```bash
poetry run pytest --cov=pymisp tests/testlive_comprehensive.py
```
## Samples and how to use PyMISP
Various examples and samples scripts are in the [examples/](examples/) directory.
In the examples directory, you will need to change the keys.py.sample to enter your MISP url and API key.
```
cd examples
cp keys.py.sample keys.py
vim keys.py
```
The API key of MISP is available in the Automation section of the MISP web interface.
To test if your URL and API keys are correct, you can test with examples/last.py to
fetch the events published in the last x amount of time (supported time indicators: days (d), hours (h) and minutes (m)).
last.py
```
cd examples
python3 last.py -l 10h # 10 hours
python3 last.py -l 5d # 5 days
python3 last.py -l 45m # 45 minutes
```
## Debugging
You have two options here:
1. Pass `debug=True` to `PyMISP` and it will enable logging.DEBUG to stderr on the whole module
2. Use the python logging module directly:
```python
import logging
logger = logging.getLogger('pymisp')
# Configure it as you wish, for example, enable DEBUG mode:
logger.setLevel(logging.DEBUG)
```
Or if you want to write the debug output to a file instead of stderr:
```python
import pymisp
import logging
logger = logging.getLogger('pymisp')
logging.basicConfig(level=logging.DEBUG, filename="debug.log", filemode='w', format=pymisp.FORMAT)
```
## Test cases
1. The content of `mispevent.py` is tested on every commit
2. The test cases that require a running MISP instance can be run the following way:
```bash
# From poetry
pytest --cov=pymisp tests/test_*.py tests/testlive_comprehensive.py:TestComprehensive.[test_name]
```
## Documentation
The documentation is available [here](https://pymisp.readthedocs.io/en/latest/).
### Jupyter notebook
A series of [Jupyter notebooks for PyMISP tutorial](https://github.com/MISP/PyMISP/tree/main/docs/tutorial) are available in the repository.
## Everything is a Mutable Mapping
... or at least everything that can be imported/exported from/to a json blob
`AbstractMISP` is the master class, and inherits from `collections.MutableMapping` which means
the class can be represented as a python dictionary.
The abstraction assumes every property that should not be seen in the dictionary is prepended with a `_`,
or its name is added to the private list `__not_jsonable` (accessible through `update_not_jsonable` and `set_not_jsonable`.
This master class has helpers that make it easy to load, and export to, and from, a json string.
`MISPEvent`, `MISPAttribute`, `MISPObjectReference`, `MISPObjectAttribute`, and `MISPObject`
are subclasses of AbstractMISP, which mean that they can be handled as python dictionaries.
## MISP Objects
Creating a new MISP object generator should be done using a pre-defined template and inherit `AbstractMISPObjectGenerator`.
Your new MISPObject generator must generate attributes and add them as class properties using `add_attribute`.
When the object is sent to MISP, all the class properties will be exported to the JSON export.
## Installing PyMISP on a machine with no internet access
This is done using poetry and you need to have this repository cloned on your machine.
The commands below have to be run from inside the cloned directory.
1. From a machine with access to the internet, get the dependencies:
```bash
mkdir offline
poetry export --all-extras > offline/requirements.txt
poetry run pip download -r offline/requirements.txt -d offline/packages/
```
2. Prepare the PyMISP Package
```bash
poetry build
mv dist/*.whl offline/packages/
```
3. Copy the content of `offline/packages/` to the machine with no internet access.
4. Install the packages:
```bash
python -m pip install --no-index --no-deps packages/*.whl
```
# License
PyMISP is distributed under an [open source license](./LICENSE). A simplified 2-BSD license.
Raw data
{
"_id": null,
"home_page": "https://github.com/MISP/PyMISP",
"name": "pymisp",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Rapha\u00ebl Vinot",
"author_email": "raphael.vinot@circl.lu",
"download_url": "https://files.pythonhosted.org/packages/20/08/77400504a986f1b49caf5d714b774e34522a49f7b9de8675492fe3eabe20/pymisp-2.4.190.tar.gz",
"platform": null,
"description": "**IMPORTANT NOTE**: This library will require **at least** Python 3.10 starting the 1st of January 2024. If you have legacy versions of python, please use the latest PyMISP version that will be released in December 2023, and consider updating your system(s). Anything released within the last 2 years will do, starting with Ubuntu 22.04.\n\n# PyMISP - Python Library to access MISP\n\n[](http://pymisp.readthedocs.io/?badge=latest)\n[](https://coveralls.io/github/MISP/PyMISP?branch=main)\n[](https://www.python.org/downloads/release/python-380/)\n[](https://pypi.python.org/pypi/pymisp/)\n[](https://pypi.python.org/pypi/pymisp/)\n\nPyMISP is a Python library to access [MISP](https://github.com/MISP/MISP) platforms via their REST API.\n\nPyMISP allows you to fetch events, add or update events/attributes, add or update samples or search for attributes.\n\n## Install from pip\n\n**It is strongly recommended to use a virtual environment**\n\nIf you want to know more about virtual environments, [python has you covered](https://docs.python.org/3/tutorial/venv.html)\n\nOnly basic dependencies:\n```\npip3 install pymisp\n```\n\nAnd there are a few optional dependencies:\n* fileobjects: to create PE/ELF/Mach-o objects\n* openioc: to import files in OpenIOC format (not really maintained)\n* virustotal: to query VirusTotal and generate the appropriate objects\n* docs: to generate te documentation\n* pdfexport: to generate PDF reports out of MISP events\n* url: to generate URL objects out of URLs with Pyfaup\n* email: to generate MISP Email objects\n* brotli: to use the brotli compression when interacting with a MISP instance\n\nExample:\n\n```\npip3 install pymisp[virustotal,email]\n```\n\n## Install the latest version from repo from development purposes\n\n**Note**: poetry is required; e.g., \"pip3 install poetry\"\n\n```\ngit clone https://github.com/MISP/PyMISP.git && cd PyMISP\ngit submodule update --init\npoetry install -E fileobjects -E openioc -E virustotal -E docs -E pdfexport -E email\n```\n\n### Running the tests\n\n```bash\npoetry run pytest --cov=pymisp tests/test_*.py\n```\n\nIf you have a MISP instance to test against, you can also run the live ones:\n\n**Note**: You need to update the key in `tests/testlive_comprehensive.py` to the automation key of your admin account.\n\n```bash\npoetry run pytest --cov=pymisp tests/testlive_comprehensive.py\n```\n\n## Samples and how to use PyMISP\n\nVarious examples and samples scripts are in the [examples/](examples/) directory.\n\nIn the examples directory, you will need to change the keys.py.sample to enter your MISP url and API key.\n\n```\ncd examples\ncp keys.py.sample keys.py\nvim keys.py\n```\n\nThe API key of MISP is available in the Automation section of the MISP web interface.\n\nTo test if your URL and API keys are correct, you can test with examples/last.py to\nfetch the events published in the last x amount of time (supported time indicators: days (d), hours (h) and minutes (m)).\nlast.py\n```\ncd examples\npython3 last.py -l 10h # 10 hours\npython3 last.py -l 5d # 5 days\npython3 last.py -l 45m # 45 minutes\n```\n\n\n## Debugging\n\nYou have two options here:\n\n1. Pass `debug=True` to `PyMISP` and it will enable logging.DEBUG to stderr on the whole module\n\n2. Use the python logging module directly:\n\n```python\n\nimport logging\nlogger = logging.getLogger('pymisp')\n\n# Configure it as you wish, for example, enable DEBUG mode:\nlogger.setLevel(logging.DEBUG)\n```\n\nOr if you want to write the debug output to a file instead of stderr:\n\n```python\nimport pymisp\nimport logging\n\nlogger = logging.getLogger('pymisp')\nlogging.basicConfig(level=logging.DEBUG, filename=\"debug.log\", filemode='w', format=pymisp.FORMAT)\n```\n\n## Test cases\n\n1. The content of `mispevent.py` is tested on every commit\n2. The test cases that require a running MISP instance can be run the following way:\n\n\n```bash\n# From poetry\n\npytest --cov=pymisp tests/test_*.py tests/testlive_comprehensive.py:TestComprehensive.[test_name]\n```\n\n## Documentation\n\nThe documentation is available [here](https://pymisp.readthedocs.io/en/latest/).\n\n### Jupyter notebook\n\nA series of [Jupyter notebooks for PyMISP tutorial](https://github.com/MISP/PyMISP/tree/main/docs/tutorial) are available in the repository.\n\n## Everything is a Mutable Mapping\n\n... or at least everything that can be imported/exported from/to a json blob\n\n`AbstractMISP` is the master class, and inherits from `collections.MutableMapping` which means\nthe class can be represented as a python dictionary.\n\nThe abstraction assumes every property that should not be seen in the dictionary is prepended with a `_`,\nor its name is added to the private list `__not_jsonable` (accessible through `update_not_jsonable` and `set_not_jsonable`.\n\nThis master class has helpers that make it easy to load, and export to, and from, a json string.\n\n`MISPEvent`, `MISPAttribute`, `MISPObjectReference`, `MISPObjectAttribute`, and `MISPObject`\nare subclasses of AbstractMISP, which mean that they can be handled as python dictionaries.\n\n## MISP Objects\n\nCreating a new MISP object generator should be done using a pre-defined template and inherit `AbstractMISPObjectGenerator`.\n\nYour new MISPObject generator must generate attributes and add them as class properties using `add_attribute`.\n\nWhen the object is sent to MISP, all the class properties will be exported to the JSON export.\n\n## Installing PyMISP on a machine with no internet access\n\nThis is done using poetry and you need to have this repository cloned on your machine.\nThe commands below have to be run from inside the cloned directory.\n\n\n1. From a machine with access to the internet, get the dependencies:\n\n```bash\nmkdir offline\npoetry export --all-extras > offline/requirements.txt\npoetry run pip download -r offline/requirements.txt -d offline/packages/\n```\n\n2. Prepare the PyMISP Package\n\n```bash\npoetry build\nmv dist/*.whl offline/packages/\n```\n\n3. Copy the content of `offline/packages/` to the machine with no internet access.\n\n4. Install the packages:\n\n```bash\npython -m pip install --no-index --no-deps packages/*.whl\n```\n\n# License\n\nPyMISP is distributed under an [open source license](./LICENSE). A simplified 2-BSD license.\n\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "Python API for MISP.",
"version": "2.4.190",
"project_urls": {
"Bug Tracker": "https://github.com/MISP/PyMISP/issues",
"Documentation": "https://pymisp.readthedocs.io",
"Homepage": "https://github.com/MISP/PyMISP",
"Repository": "https://github.com/MISP/PyMISP",
"Source": "https://github.com/MISP/PyMISP"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5cca53ad4630a1870f0bbe11d096a9f6633bb0bc7965ee272f420dcce2705987",
"md5": "255fe2ed9b38d3e4157a1613ffba500c",
"sha256": "0b63b3d7c497239987ad3220eb7bbbe9249e61461278c6c0d6575a6bb8619b40"
},
"downloads": -1,
"filename": "pymisp-2.4.190-py3-none-any.whl",
"has_sig": false,
"md5_digest": "255fe2ed9b38d3e4157a1613ffba500c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 587691,
"upload_time": "2024-04-18T13:18:01",
"upload_time_iso_8601": "2024-04-18T13:18:01.935697Z",
"url": "https://files.pythonhosted.org/packages/5c/ca/53ad4630a1870f0bbe11d096a9f6633bb0bc7965ee272f420dcce2705987/pymisp-2.4.190-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "200877400504a986f1b49caf5d714b774e34522a49f7b9de8675492fe3eabe20",
"md5": "e90671e8f4091e596bb3953601837b68",
"sha256": "e7374295bfd8c7d25f56867e4395a029433360d95420e39b7f78eb1d4f8b48b4"
},
"downloads": -1,
"filename": "pymisp-2.4.190.tar.gz",
"has_sig": false,
"md5_digest": "e90671e8f4091e596bb3953601837b68",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 407847,
"upload_time": "2024-04-18T13:18:05",
"upload_time_iso_8601": "2024-04-18T13:18:05.896632Z",
"url": "https://files.pythonhosted.org/packages/20/08/77400504a986f1b49caf5d714b774e34522a49f7b9de8675492fe3eabe20/pymisp-2.4.190.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-18 13:18:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MISP",
"github_project": "PyMISP",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pymisp"
}
JSON
