MISP
/
MISP
mirror of https://github.com/MISP/MISP
2
2
Fork 0
Code Issues Releases Wiki Activity

add: [tools] More documentation for the stix ingestion script

pull/6460/head
chrisr3d 2020-10-17 00:07:09 +02:00
parent efb81b5425
commit 4d05a981d4
No known key found for this signature in database
GPG Key ID: 6BBED1B63A6D639F
1 changed files with 14 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
tools/ingest_stix/README.md
View File

@ -1,8 +1,8 @@
## Ingest STIX
# Ingest STIX
Python script to ingest STIX files on MISP.
### Requirements
## Requirements
There are a few requirements for this little python script to run, which are included in the MISP requirements:
- PyMISP
@ -11,7 +11,7 @@ There are a few requirements for this little python script to run, which are inc
The recommended python setup for MISP is described within [the following documentation](https://www.circl.lu/doc/misp/updating-python/).
### Description
## Description
The aim of this small piece of code is to ingest STIX files.
@ -22,12 +22,12 @@ The equivalent is available in PyMISP with the `upload_stix` method. The only di
MISP creates then an event for each file ingested, using the [stix import](https://github.com/MISP/MISP/blob/2.4/app/files/scripts/stix2misp.py) or [stix2 import](https://github.com/MISP/MISP/blob/2.4/app/files/scripts/stix2/stix2misp.py) scripts.
### Usage
## Usage
Depending of the python environment set in your MISP server, you will have to use the correct python command in order to be sure to reach the correct environment containing all the required libraries and dependencies:
- The recommended environment installed by default in most of our installation scripts, and virtual machine is a virtualenv available using `/var/www/MISP/venv/bin/python`
- If any other python environment is set instead, use the corresponding command. As an example, the built-in python3 provided with most of the linux distribution is available with a simple `python3`
**Please replace the python command in the next examples with your own setting if needed**
**Please replace the python command in the next examples with your own settings if needed**
In order to connect to MISP, we need an URL and an API key.
You can either pass those parameters when you call the `ingest_python.py` script, or put them within the `setup.json` file that is passed by default to the script, or event use another setup file as long as it contains the same required fields:
@ -46,7 +46,7 @@ python3 ingest_stix.py --version 1 --path _PATH_TO_YOUR_FILES_/stix_files*.xml
python3 ingest_stix.py --version 2 --path _PATH_TO_YOUR_FILES_/stix_files*.json
```
But you can also overwrite one of the required MISP setups:
But you can also overwrite the required MISP setups:
```
# Overwrite the SSL verification
python3 ingest_stix.py --version 1 --path _PATH_TO_YOUR_FILES_/stix_files*.xml --misp_verifycert
@ -54,3 +54,11 @@ python3 ingest_stix.py --version 1 --path _PATH_TO_YOUR_FILES_/stix_files*.xml -
# Simply define all the parameters without using the setup file
python3 ingest_stix.py --version 1 --path _PATH_TO_YOUR_FILES_/stix_files*.xml --misp_url _MISP_URL_ --misp_key _YOUR_API_KEY_ --misp_verifycert
```
## Important information to be aware of
There are a few reasons why the data you want to ingest may be truncated or there may be missing information:
- The most obvious reason is the impossibility to map 100\% of the STIX objects and fields into MISP format.
- The import of STIX data into MISP is made to keep the uuids when possible. If you import an indicator with an uuid already existing in MISP, it will be skipped.
- If one file raises an error and is not imported at all, there might be an issue in the import script.
Once the ingestion is completed, each ingested file is also saved within the corresponding MISP event, so the initial data is available if needed.