Microservices for STPA (System-Theoretic Process Analysis)
This repository contains the source code for MicroSTAMP, a web application based on microservices architecture to support STPA. Out of the 4 steps of STPA, MicroSTAMP supports steps 1, 2, and 3. We estimate to release the microservice implementation for Step 4 by January, 2025.
- Architecture Overview
- How to Run MicroSTAMP
- MicroSTAMP Microservices
- Contributing Guidelines
- Lead developers
- Publications
- Talks
- Contact Information
| Microservice | Port |
|---|---|
| microstamp-step1 | 8091 |
| microstamp-step2 | 8090 |
| microstamp-step3 | 8080 |
| microstamp-service-registry | 8761 |
| microstamp-authorization-server | 9000 |
| microstamp-api-gateway | 9191 |
| User Interface | Port |
|---|---|
| microstamp-ui | 5173 |
This section provides a guide on how to run MicroSTAMP via the command-line using Maven.
To build and run the application, you'll need the following:
- JDK 21
- MySQL 8.0 or higher
- Apache Maven
- Node.js and NPM
1. Set up MySQL Databases
Ensure that MySQL is installed and running on your machine. The default port for MySQL is
3306. If MySQL is not installed, you can download it from the official MySQL website:
Creating the Databases
Once MySQL is installed and running, follow the steps below to create the necessary databases for the project.
-
Open a terminal or command prompt.
-
Log in to MySQL using the following command:
mysql -u root -p -
Create the required databases by running the following SQL commands:
CREATE DATABASE microstamp; CREATE DATABASE step1; CREATE DATABASE step2; CREATE DATABASE step3;
That's it! Your MySQL databases are now set up and ready to use.
2. Clone the Project
-
Open a terminal or command prompt.
-
Navigate to the directory where you want to clone the project.
-
Clone the project repository using the following command:
git clone https://github.com/Micro-STAMP/microstamp.git
3. Run the Microservices
We recommend running this microservice before all others, to ensures that each microservice can register itself properly, making communication between them more reliable.
To run this microservice, open a terminal or command prompt, navigate to its directory, and execute the following command:
mvn spring-boot:run
Figure: Running the service registry in the command-line.
Alternatively, you can also run the microservices directly within an IDE. We use IntelliJ IDEA 2023.3.5 Ultimate Edition, but feel free to use any IDE of your choice that supports Spring Boot.
Follow the same steps to run the remaining microservices. For each one, navigate to its respective directory and execute mvn spring-boot:run or use your IDE.
With the microservices running, open a new terminal window to execute the microstamp-ui. Navigate to its directory and run:
npm i
npm run dev
npm iis needed only when first running the UI.- The user interface will open at the URL http://127.0.0.1:5173.
- You can now access the MicroSTAMP frontend!
We created a user with some example analyses to provide a global picture of how MicroSTAMP supports STPA. The user guest has some pre-stored STPA analyses and control structure from Step 2 of STPA.
Figure: Authenticating with the user guest.
Figure: Pre-stored STPA analyses page from user guest.
If you wish to understand more in-depth details about any specific microservice, you can refer to its respective directory. Each directory contains a comprehensive description of its role and implementation within the MicroSTAMP system. Below is a table with links to the corresponding folders for each microservice:
| Microservice | Description | Link |
|---|---|---|
| MicroSTAMP Service Registry | Registers instances of the microservices for discovery and communication. | Service Registry |
| MicroSTAMP API Gateway | The main entry point, delegating requests to the corresponding microservices. | API Gateway |
| MicroSTAMP Authorization Server | Controls authorization with OAuth2 and authentication with OpenID. | Authorization Server |
| MicroSTAMP STPA Step 1 | Handles the Define Purpose of the Analysis step. | STPA Step 1 |
| MicroSTAMP STPA Step 2 | Handles the Model the Control Structure step. | STPA Step 2 |
| MicroSTAMP STPA Step 3 | Handles the Identify Unsafe Control Actions step. | STPA Step 3 |
Each microservice is detailed in its respective repository directory, outlining its purpose, key functionalities, and implementation.
Additionally, you can find the repository for the MicroSTAMP User Interface here: MicroSTAMP UI.
Note: Some of the specific READMEs are still under development. If you find that a README does not yet exist, it will be added shortly.
You're welcome to contribute to the MicroSTAMP project! If you find any bugs or have suggestions for new features, please feel free to submit them via pull requests or contact us via email.
Maimone, João Hugo Marinho, Thiago Franco de Carvalho Dias, Fellipe Guilherme Rey de Souza, and Rodrigo Martins Pagliares. "MicroSTAMP: Microservices for Steps 1 and 2 of the System-Theoretic Process Analysis (STPA) Technique." In International Conference on Information Technology-New Generations, pp. 469-476. Cham: Springer Nature Switzerland, 2024.
- Maimone, João Hugo Marinho, Thiago Franco de Carvalho Dias, Fellipe Guilherme Rey de Souza, and Rodrigo Martins Pagliares. "MicroSTAMP: Microservices for Steps 1 and 2 of the System-Theoretic Process Analysis (STPA) Technique." In International Conference on Information Technology-New Generations, Las Vegas, NV, USA. April, 2024.
- "MicroSTAMP: Towards a Free and Open-Source STPA Compliant Web Tool Based on Microservices Architecture", STAMP Workshop, MIT Partnership for Systems Approaches to Safety and Security (PSASS), September, 2024.
Rodrigo Martins Pagliares
rodrigo.pagliares@unifal-mg.edu.br
Universidade Federal de Alfenas - UNIFAL
Computer Science Department
Av. Jovino Fernandes Sales, 2600 – Santa Clara, Alfenas/MG - Brazil
CEP: 37133-840
Prédio C – 3º andar (Building C, Third Floor)