This README document is designed to help the viewer understand the structure of the overall repository. The tool contains files related to the playbook management tool used to input/edit/query the mediawiki with new information. The readme-images folder simply contains any image files that are used in the many readme files of the project.
The playbook management tool is designed to provide a wide variety of functionalities around cyber security playbooks. Such as playbook creation, management, limited automatic execution and easy sharing. However, the open-source version does not contain all the functionalities.
This is a proof-of-concept prototype and is not suitable for production use. The code has not been thoroughly reviewed for security vulnerabilities. For further information and support regarding production use, commercial applications, and advanced features, please contact the DPS group at Fraunhofer FIT: https://www.fit.fraunhofer.de/en/business-areas/data-science-and-artificial-intelligence/data-protection-and-sovereignty.html
As a scientific library in the Python ecosystem, we rely on external libraries to offer our features. In the /third_party folder, we list all the licenses of our direct dependencies. Please check the /third_party/licenses.json file to get a full list of dependencies and the corresponding licenses.
- You need to download and install Semantic Mediawiki (SMW) instance. For that, you need to have Docker, and then install the SMW.
- Python, v3.10.13 was used for the development. Anything later should work fine too. Previous versions may work but are not tested. Python 2 is not supported.
All the required packages are listed in the requirements.txt file. They can be installed using the following command:
python -m pip install -r requirements.txtMake sure all requirements listed in requirements.txt are available in your environment.
This section concerns the creation of a Semantic Media Wiki instance which is a prerequisite for SASP. If you are updating from a previous version or connecting to an existing instance, you can skip this section.
You can use the provided script in mediawiki/pymediawikidocker/build.py to automatically download and setup a dockerized Mediawiki instance.
Otherwise you need to download and install a SMW instance. For that, you need to have Docker, and then install the SMW.
Once Mediawiki is set up obtain a bot login for the tool. If you used our script a bot has already been created, you just need to reset the password once ({mediawiki_url}/index.php/Special:BotPasswords). Add the login to the config files as described in the Configuration section.
In order for SASP to work, the mediawiki setup must have been fully completed and the Mediawiki must be active. After the setup procedure is done, make sure the docker containers are running and then proceed with the installation of the tool. The tool is being developed using Python 3.10.13 and Django 5.1 and should be compatible with Python 3.10 and above. The tool is currently being developed on Windows 10, but should be compatible with Linux and MacOS as well.
You'll find the projects configuration files under SASP/config.
The project uses a config.ini and keys.ini to store configuration and sensitive information.
In the SASP/config/ folder, there is a config_example.ini and keys_example.ini file that can be used as a template for the actual config.ini and keys.ini files. Below is an overview of the variables used in the project and installation.
The program was developed to use SSO solution Keycloak for user management. For demonstration purposes this is bypassed in this release, but can be enabled by setting BYPASS_KEYCLOAK=False in SASP/sasp/auth/keycloak_integration.py.
| Section | Variable | Description | Optional | Notes |
|---|---|---|---|---|
| Wiki | url |
The base url of the connected Mediawiki instance | No | - |
| Wiki | api_path |
Path to the mediawiki api | No | - |
| Wiki | user_path |
Path to the mediawiki user pages | No | - |
| Wiki | bot_user |
Username of the mediawiki system user | No | The username of the wiki user who created the bot |
| MISP | url |
URL to the MISP instance | Yes | Used for sharing playbooks via MISP, not essential for the tool to work if not used |
| Keycloak | url |
URL to the Keycloak instance for SSO | No | - |
| Keycloak | client |
Client ID for the Keycloak instance | No | - |
| Keycloak | realm |
Realm for the Keycloak instance | No | - |
| Kafka | client |
Client ID for the Kafka instance | Yes | Used for sharing playbooks via Kafka, not essential for the tool to work if not used |
| Kafka | bootstrap_server |
URL to the Kafka instance | Yes | Used for sharing playbooks via Kafka, not essential for the tool to work if not used |
| Kafka | registry_url |
URL to the Kafka registry instance | Yes | Used for sharing playbooks via Kafka, not essential for the tool to work if not used |
| Kafka | consumer |
Consumer group ID for the Kafka instance | Yes | Used for sharing playbooks via Kafka, not essential for the tool to work if not used |
| Kafka | ssl_ca |
Path to the Kafka CA certificate | Yes | Used for sharing playbooks via Kafka, not essential for the tool to work if not used |
| Kafka | ssl_certificate |
Path to the Kafka client certificate | Yes | Used for sharing playbooks via Kafka, not essential for the tool to work if not used |
| Kafka | ssl_key |
Path to the Kafka client key | Yes | Used for sharing playbooks via Kafka, not essential for the tool to work if not used |
| Kafka | ssl_registry_key |
Path to the decrypted Kafka client key | Yes | Used for sharing playbooks via Kafka, not essential for the tool to work if not used |
| SASP | app_application_id |
An identifier for this application | No | - |
| Section | Variable | Description | Optional | Notes |
|---|---|---|---|---|
| Wiki | bot_password |
Password of the mediawiki bot user | No | Should be of the form bot_name@bot_password |
| MISP | key |
API key for the MISP instance | Yes | - |
| Kafka | ssl_key_pwd |
Password for the Kafka client key | Yes | - |
| Keycloak | client_secret |
Secret token for connected Keycloak instance | No | - |
- Install all the prerequisites from the previous chapter
- Make sure the mediawiki is running and the connection information is correct in the config files.
- Execute the following commands
cd SASP
python setup.py- Install all the prerequisites from the previous chapter
- Make sure the mediawiki is running and the connection information is correct in the config files.
- Execute the following commands
cd SASP
# Creates the database
python manage.py migrate
# Creates the default user with the configuration information from the `*.ini` files
python manage.py make_default_user
# Compiles the forms and pushes them to the wiki
python manage.py update_formsUnless otherwise instructed you only need to update the database and the default user, so use the provided switches in the setup.py script to skip the form update and playbook import steps.
Assuming everything is set up correctly, you can run the program with the following steps:
- Run SASP from the terminal while in the project's folder
You can also specify address and port to run the server on. For example:
python manage.py runserver
python manage.py runserver 0.0.0.0:8000
- Open the browser and navigate to the URL that is printed in the terminal. By default this is
http://localhost:8000/sasp/
There are a few additional commands that can be used to interact with the tool all are invoked with python manage.py <command>.
import_playbook: Imports a playbook from a json file into the tool--path: Path to the json file (Required)
make_default_user: Creates a default user with the configuration information from the*.inifiles or overwrites the existing onecreatesuperuser: Django command to create a superuser. With this user you can access the admin interface of the tool athttp://localhost:8000/admin/and manage the database
The tool code is located in the sasp folder.
To give an overview of each file/folder:
auth: Contains methods for SSO using Keycloaklocalization: Contains localization filesmanagement: Contains definitions of Django management commandsmigrations: Contains Django migrations. Djangos migration system is used to keep the database in sync with the modelsmisp_sharing_tool: Contains the original and modified versions of the MISP sharing tool that was used as a base for the SASP's MISP sharing functionalitymodels: Contains the Django models, that represent the database tablessasp_exceptions: Contains custom exceptions for the toolsharing_kafka: Contains current efforts to implement sharing via Kafkastatic: Contains static files like CSS, JS and imagestemplates: Contains the HTML templates for the tooltemplatetags: Contains custom template tags for use in Django's templating systemutil: Contains utility functionsviews: Contains the views, that provide the bulk of the interfaces and logicwiki_forms: Contains the forms that define the playbooks on the wikiadmin.py: Django admin interface configurationapps.py: Django app configurationbpmn_util.py: functions related to generating BPMN diagramsdb_syncs.py: functions for syncing the tool database with the mediawikifile_export_util.py: functions for exporting playbooks to jsonfile_import_util.py: functions for importing playbooks from jsonforms.py: Django forms, that provide user input for the toolknowledge.py: Location for information like paths or formats that is available to the entire projectlogic_management.py: functions too complex to be in the viewsMISPInterface.py: functions for interacting with the MISP instancesanitizer_util.py: functions for sanitizing playbooks before exportingserializers.py: Django serializers, that provide a way to convert complex data types to and from native Python data types. Mostly used for the REST APItests.py: Django testsurls.py: Django URLs, that map URLs to viewsutils.py: utility functionsvocabulary_translator.py: contains a variety of functions and data structures for translating between the tool, the mediawiki and the CACAO standardwiki_forms.py: functions for interacting with the forms that define the playbooks on the wikiwiki_interface.py: functions for interacting with the mediawiki
The UI was designed using Django. There are a variety of tutorials online that can help you get started with Django. The official documentation is also a good resource.
To track the incremental updates, please refer to the CHANGELOG file.
This section should list all the major technologies that are used to develop the project within the repository.
This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreements No 833418 (SAPPAN) and No 101020560 (CyberSEAS). To reference our work in your publications, please use the following papers:
Playbook management tool: Mehdi Akbari Gurabi, Avikarsha Mandal, Jan Popanda, Robert Rapp, and Stefan Decker. "SASP: a Semantic web-based Approach for management of Sharable cybersecurity Playbooks." In Proceedings of the 17th International Conference on Availability, Reliability and Security, pp. 1-8. 2022. DOI
Integration with security tools, automation and reporting effort: Mehdi Akbari Gurabi, Lasse Nitz, Andrej Bregar, Jan Popanda, Christian Siemers, Roman Matzutt, and Avikarsha Mandal. "Requirements for Playbook-Assisted Cyber Incident Response, Reporting and Automation." Digital Threats: Research and Practice (2024). DOI
