SATRAP-DL, short for Semi-Automated Threat Reconnaissance and Analysis Powered by Description Logics, is a sub-project of the CyFORT project, which in turn stands for "Cloud Cybersecurity Fortress of Open Resources and Tools for Resilience". Project CyFORT is carried out in the context of the EC-approved IPCEI-CIS.
SATRAP-DL aims at the development of a platform for carrying out interactive computer-aided analysis of cyber threat intelligence (CTI) driven by logic-based automated reasoning and inference. We call this platform SATRAP, short for "Semi-Automated Threat Reconnaissance and Analysis Platform".
This repository contains the source code and full documentation of SATRAP. The development of SATRAP relies on the C5-DEC method and software, also developed as part of project CyFORT, which is, among other things, characterized by storing, interlinking and processing all software development life cycle (SDLC) artifacts in a unified manner; see our end-to-end traceability web page providing the technical specifications of SATRAP.
- Overview
- Features
- User manual
- Getting Started
- Usage
- Unit and validation tests
- Documentation and technical specifications
- Project status
- Roadmap
- License
- Acknowledgments
- Contact
The main purpose of SATRAP is to (semi-)automate deductive processes to simplify the analysis of CTI. In more realistic terms, considering the analysis stage of the CTI lifecycle, we aspire to advance the state-of-the-art by lowering the barrier to the use of automation powered by reasoning engines and inference.
At its core, SATRAP implements a knowledge representation system (KRS) consisting of a knowledge base of cyber threat intelligence coupled with a reasoning engine for inferring new knowledge. The KRS grounds SATRAP into formal underpinnings, enabling the introduction of semantics into the storage, processing, and analysis of cyber threat intelligence.
Concretely, users execute certain analytic queries over a CTI knowledge base and SATRAP provides an explainable answer, meaning that the deductive steps that lead to such an answer can be traced. Unlike with regular database queries, the answer might include not only information persisted in the CTI knowledge base, but also non-explicit relations logically derived by an automated reasoning engine from the actual information in the CTI knowledge base.
This automation intends to support memory-intensive analytic tasks, typically concerning correlating CTI and drawing logical conclusions from large amounts of information. This in turn enables to better allocate already scarce resources by allowing analysts to shift their expertise to formulating appropriate questions and translating the results into actionable intelligence.
The set of analytic features offered by SATRAP is foreseen to complement features of existing open-source threat intelligence platforms, such as MISP and OpenCTI. Integration with such tools for automated inference over CTI streams is expected in future releases, although manual content transfer between SATRAP and such TIPs is already supported by the current release.
- A toolbox of functions for supporting CTI analysis powered by an inference engine
- An extract-transform-load (ETL) mechanism for ingesting STIX2.1 data from CTI sources into the knowledge base of SATRAP
- A knowledge representation system for CTI implemented on top of TypeDB (v2.29.0)
- A data model based on STIX 2.1, enabling:
- exchange of threat information with repositories and security tools such as MITRE ATT&CK data sets, TIPs (e.g., MISP, OpenCTI), SIEM and IDPS (e.g., IDPS-ESCAPE, Wazuh and Suricata)
- a common language for reasoning over CTI
- A predefined set of inference rules and queries, extensible with user-defined ones
- An intuitive language for defining new derivation rules in terms of STIX2.1 concepts, thanks to the underlying semantic technology
- A CTI knowledge base that can be directly queried in TypeQL, the native language of TypeDB
- A command-line interface (SATRAP CLI) for efficient user interaction
- A light-weight Python library (
CTIAnalysisToolbox) providing a preliminary toolbox of analytic functions for supporting CTI investigations. These functions perform automated reasoning over the information in the knowledge base. - A frontend based on Jupyter Notebooks importing the CTIAnalysisToolbox for creating playbooks or user-defined queries
- TypeDB Studio (third-party, optional), the GUI of TypeDB, for an interactive visualization of explainable queries
- Free/libre and open source
- Cross platform: works on GNU/Linux, MacOS and Windows
- Modular design to promote extensibility
- Based on open data formats such as Markdown, YAML, JSON, and HTML
- Secure by design as per the C5-DEC methodology
- Interoperability with well-established open-source TIPs
To learn more about the fundamentals of SATRAP as well as details on the installation, setup requirements, usage, and overall functionality, please refer to the SATRAP user manual.
Currently, SATRAP offers two deployment options:
- A command-line interface (CLI) in your OS shell of choice
- A containerized analysis environment in VS Code
Below we describe the deployment of the command-line interface. For the deployment of a development environment, please see the installation page of the user manual.
- Docker engine running
-
Clone or download the source code of this repository.
git clone https://github.com/AbstractionsLab/satrap-dl.git
-
In a terminal, go to the project's root folder (when cloning,
satrap-dl) and ensure execution rights on the scripts.cd satrap-dl chmod +x *.sh
-
Run the
init-satrap.shscript to set up and run a TypeDB server connected to asatrap-netDocker network../init-satrap.sh
TypeDB is exposed on port
1729of the TypeDB Docker container. -
Run the
build-satrap.shscript to build a Docker image for SATRAP../build-satrap.sh
At this point, the CLI can be used as described in the Usage section below.
If the typedb container is stopped for any reason, it can be safely launched again by re-running the init-satrap.sh script.
The default configuration parameters, including settings for the connection to TypeDB and logging level, can be modified in the file satrap/assets/satrap_params.yml.
Unless otherwise specified, e.g. by command arguments, the CLI and the Python toolbox run the commands and functions using the knowledge base specified by the TypeDB parameters in the mentioned file.
The command-line interface of SATRAP is primarily intended for setting up a fresh CTI knowledge base and executing an extract-transform-load (ETL) pipeline to ingest content in STIX and populate the said knowledge base.
A minimal set of analytical functions is also available through this interface, however, we recommend the use of the Python library described below for tasks related to the analysis of CTI as it provides a larger set of functions.
To access the SATRAP CLI, simply go the project root folder (cd satrap-dl) and run:
./satrap.shThe help menu is shown if no arguments are provided.
To create and populate a knowledge base with the default parameters run:
./satrap.sh setup
./satrap.sh etl This will create a knowledge base called satrap-skb-alpha and ingest the latest version of the MITRE ATT&CK Enterprise dataset.
For more information about the commands exposed in the CLI, please take a look at the SATRAP interfaces section of the user manual.
We recommend the use of Jupyter Notebooks to interact with the Python toolkit of SATRAP in a structured manner and to implement your own playbooks.
See our "Effective countermeasures against a group of interest" notebook and the "Quick start" in satrap/frontend for examples on the usage of the toolbox.
For instance, we can try to find courses of action that mitigate any of the techniques used by the group "APT29". This function makes use of the inference rules defined in our KRS.
SATRAP provides textual explanations for "explanation functions" in the toolbox. As a complementary frontend, we can leverage the use of TypeDB Studio for an interactive graphical explanation of the inferred knowledge.
For example, we run the explanation function explain_techniques_used_by_group to understand whether and why the group "Orangeworm" (ATT&Ck id "G0071") uses the technique "Domain Groups". Then:
- We retrieve the executed query in the native database language (TypeQL).
- We copy and run the query in TypeDB Studio to see the derivation paths as a graph.
NOTE: integration of visual explanations in Jupyter Notebooks and in the development environment is considered for future releases (see the Roadmap below).
For more information on the topic, see the page on Running investigations in the user manual.
SATRAP comes with an extensive suite of unit tests that can be run with the script run_tests.sh in the development environment. Details are available in the installation page of the user manual.
For software validation test cases and reports, please refer to the test case specifications (TST) and test campaign results (TRA) on our traceability web page.
The technical specifications and project documentation of SATRAP including requirements, architectural and software diagrams, test case specifications, and test reports, are accessible via our traceability web page.
As of March 2025, this repository hosts the Alpha version of SATRAP. For this release, efforts have largely gone into building the core components and foundations of the project, in particular, defining the knowledge base schema, implementing the ETL process and building an initial minimal set of demonstrative functions for the analysis of CTI.
In its current stage, the analytical capabilities of SATRAP can be leveraged primarily through queries written in TypeQL, the native language of TypeDB. The upcoming Beta phase mainly addresses the development and extension of the analysis capabilities of SATRAP and their exposure in the toolkit library.
Disclaimer: use of Alpha software
The SATRAP-DL project is in its Alpha stage and under active development; it may include incomplete features and contain bugs. This software is not intended for use in production environments.
In particular, the schema of the CTI SKB is subject to change as we need to introduce missing STIX metadata objects and deal with updated and revoked STIX objects.
The most immediate tasks on the roadmap include:
- Extend and improve the elementary analysis capabilities of the Alpha release and provide a stable native Python library API.
- Define a platform-independent API (e.g., a REST API) enabling programmatic access to the services provided by SATRAP.
- Add support for ingesting STIX 2.1 custom and metadata objects.
- Transform TypeQL results into STIX2.1 objects (reverse ETL).
- Add support for automated ingestion of data from open-source threat intelligence platforms and from IDPS-ESCAPE, including a strategy for data maintenance.
- Create further playbooks to demonstrate the use of SATRAP for automating reasoning tasks in common CTI investigative scenarios.
- Study the integration of visual explanations in VS Code and Jupyter Notebooks
Future releases consider the integration of data from existing open-source semantic CTI repositories, e.g. MITRE D3FEND.
Copyright (c) itrust Abstractions Lab and itrust consulting. All rights reserved.
SATRAP-DL is licensed under the GNU Affero General Public License (AGPL) v3.0 license.
This project builds on a few ideas related to the inference rules and the analysis functionality found in typedb-cti, an open-source project licensed under Apache License 2.0. During the conceptual phase of SATRAP-DL, we considered the possibility of building on top of typedb-cti, as it is in spirit close to SATRAP. However, we opted to build SATRAP largely from scratch mainly for two reasons:
- the design of typedb-cti was not compatible with the ambitions and architectural requirements of SATRAP
- typedb-cti relies on an outdated version of TypeDB that is incompatible with the latest currently maintained version 2.x. (Note: TypeDB 3.0 has been recently released and we might consider migration after achieving the main tasks on the roadmap)
SATRAP-DL is co-funded by the Ministry of the Economy of Luxembourg, in the context of the CyFORT project.
For more information about the project, feedback, questions or feature requests, feel free to contact us at Abstractions Lab: [email protected]