SkillAegis is a platform to design, run, and monitor exercise scenarios, enhancing skills in applications like MISP and training users in best practices for information management and protective tools. Its gamification system makes learning engaging, ensuring users acquire essential technical skills and adhere to industry standards.
- Design exercise scenarios: Build training exercises in the tool-agnostic Common Exercise Format (CEXF) with the Editor — a drag-driven scenario map, a guided inject designer, and a completion-rule builder with a live test.
- Run training sessions: Launch a scenario with the Dashboard and track every participant's progress in real time against MISP, Suricata, webhook and Python targets.
- Live monitoring: A real-time leaderboard, a streaming activity feed and a per-player drill-down give facilitators both an at-a-glance and an in-depth view of the session.
- Gamification: Scoring, trophies, "on fire" streaks and a Hall of Fame keep participants engaged, with a fullscreen big-screen view for the room.
To get started with SkillAegis, follow these steps:
-
Ensure Python 3.10 or higher is installed.
python -V
-
Install dependencies
sudo apt install screen jq git
-
Clone the repository:
git clone https://github.com/MISP/SkillAegis.git
-
Navigate to the project directory:
cd SkillAegis -
Initialize the submodules
git submodule update --init --recursive
-
Clone the configuration file
cp config.json.sample config.json
- [optional] Update the configuration
-
Install the submodule dependencies
# Editor pushd SkillAegis-Editor python3 -m venv venv source venv/bin/activate pip install -U setuptools pip pip install -r requirements.txt cp config.py.sample config.py # [recommended] Update the configuration's MISP part deactivate popd # Dashboard pushd SkillAegis-Dashboard python3 -m venv venv source venv/bin/activate pip install -U setuptools pip pip install -r backend/requirements.txt cp backend/config.py.sample backend/config.py # [recommended] Update the configuration's MISP connection and admin-panel credentials deactivate popd
The Dashboard reads its MISP connection (
misp_url,misp_apikey,misp_skipssl) and optional admin-panel credentials (admin_email,admin_password) fromSkillAegis-Dashboard/backend/config.py. If no admin credentials are set, a random password is generated at startup and printed to the console /SkillAegis.log. -
Start the project
bash SkillAegis.sh
To update the project, follow these steps:
-
Pull the latest changes in the main entry repository
git pull
-
Pull the latest changes for all submodules
git submodule update --recursive
-
Compare the current config with the sample config
diff -u config.json.sample config.json
-
Update the submodule dependencies
# Editor pushd SkillAegis-Editor source venv/bin/activate pip install -U setuptools pip pip install -U -r requirements.txt diff -u config.py.sample config.py deactivate popd # Dashboard pushd SkillAegis-Dashboard source venv/bin/activate pip install -U setuptools pip pip install -U -r backend/requirements.txt diff -u backend/config.py.sample backend/config.py deactivate popd
If you get the error below you can simply recreate the venv with python3 -m venv venv.
$ pip install -U -r requirements.txt
Traceback (most recent call last):
File "/home/steve/SkillAegis/SkillAegis-Editor/venv/bin/pip", line 5, in <module>
from pip._internal.cli.main import main
ModuleNotFoundError: No module named 'pip'You can alternatively run it in Docker, following those steps :
-
Initialize the submodules
git submodule update --init --recursive
-
Build the image
# or use docker-compose docker compose build -
Copy and update the config
cp template.env .env vim .env
-
[optional] Allow the application to reach services on the host
# Create a docker override file and add the host as extra_hosts tee docker-compose.override.yml > /dev/null <<EOF services: skillaegis-dashboard: extra_hosts: - "host.docker.internal:host-gateway" EOF
-
Run the application
docker compose up
```
## Contributing
We welcome contributions from the community. To contribute:
1. Fork the repository.
2. Create a new branch:
```bash
git checkout -b feature/your-feature-name
```
3. Make your changes and commit them:
```bash
git commit -m 'new: Added fancy feature doing fancy things'
```
4. Push to the branch:
```bash
git push origin feature/your-feature-name
```
5. Open a pull request.
## Development environment
If you want a development environment within the 'SkillAegis' entry repository you could do the following.
```bash
# Clone your SkillAegis fork and switch to the integration branch
git clone https://github.com/<fork_user>/SkillAegis.git
cd SkillAegis
git checkout develop
# Add the official remote for easy syncing
git remote add upstream https://github.com/MISP/SkillAegis.git
# Initialize submodules (will pull from upstream MISP repos)
git submodule update --init --recursive
# Now reconfigure submodules to point to YOUR forks
cd SkillAegis-Editor
git remote set-url origin https://github.com/<fork_user>/SkillAegis-Editor.git
git remote add upstream https://github.com/MISP/SkillAegis-Editor.git
cd ..
cd SkillAegis-Dashboard
git remote set-url origin https://github.com/<fork_user>/SkillAegis-Dashboard.git
git remote add upstream https://github.com/MISP/SkillAegis-Dashboard.git
cd ..
# `submodule update` leaves each submodule in a detached HEAD at the pinned
# commit — switch them onto a branch before committing any work in them.
git submodule foreach 'git checkout develop'This should allow you to easily work on all 3 repositories for your development environment.
Keep the three repos in sync by syncing each from its upstream remote (git fetch upstream && git merge upstream/develop).
The project is composed of three applications:
- SkillAegis: The main application that configures and starts the two other projects. It also contains all created scenarios.
- SkillAegis Editor: The scenario builder to create new training exercises.
- SkillAegis Dashboard: The application to start training sessions and track participants' progress in real time.
SkillAegis is the primary application that configures, launches the two other projects, and houses the scenarios. While not essential for the overall project to function, it significantly simplifies the process.
The Editor is used to design and edit scenarios. A scenario is a set of injects (tasks a trainee performs in a target tool) plus a parallel flow describing when each fires, what it depends on, and how it is scored. Authoring stays tool-agnostic — MISP, Suricata, webhook and Python targets are all first-class.
List of all available scenarios, with their CEXF validity, target namespace and inject count.
The Scenario Map is a drag-driven overview of the whole exercise: injects are laid out by dependency depth, and you wire up the flow by direct manipulation — drop a card onto another to set a prerequisite, or onto the start rail / timed lane to change when it fires.
Each inject is edited through a focused Task → Flow → Completion stepper — separating what the trainee does, when it runs, and how it is scored.
Writing evaluations used to be the hardest part of authoring. Build a completion rule as field → operator → values rows (or with the FROM / WHERE / CHECK query builder), and the panel on the right re-runs it against sample data as you type — showing a pass/fail verdict and per-condition breakdown without leaving the page.
The Dashboard is used to run a training session and visualize the progress of participants in real-time. It offers:
- Real-time leaderboard — ranks every participant live with per-task progress and scores, plus a task-completion chart that flags the hardest task.
- Live activity feed — a streaming log of participant activity (MISP events, webhooks and tool calls) with verbose / API-only filters and per-user or per-target search.
- Player drill-down — click any participant for a detailed view of their task-by-task timing, activity timeline and searchable event history.
- Gamification — scoring, trophies, "on fire" streaks, a Hall of Fame podium and celebratory all-clear bursts keep sessions engaging.
- Presentation & operations — a fullscreen big-screen overview, a live-connection health indicator (LIVE / NO LIVE DATA / OFFLINE), an authenticated admin panel and a reduce-motion accessibility toggle.
Short demo of SkillAegis-Dashboard: once the application starts, the user selects an exercise. From that point, the application tracks the real-time progression of each player.
On the dashboard main page, you can monitor the progress of all participants for the selected exercise and view real-time logs of their activity feed.
Click any participant to open their drill-down: task-by-task timing, badges and scoring streaks, and a searchable history of their events, webhooks and tool calls.
The fullscreen view provides an overview of the status of all users in a single, easily accessible display.
A set of ready-to-run scenarios ships in the scenarios/ folder. Point the Editor or
Dashboard at that folder (the default) to open, run or use them as a starting point for your own.
| Scenario | Level | Focus |
|---|---|---|
| API: Simple Data Creation | beginner | Create a MISP event through the API |
| API: Basic Filtering | beginner | Filter MISP data through the API |
| MISP Encoding Exercise: Scam Call | beginner | Encode a scam-call incident in MISP |
| MISP Encoding Exercise: Spearphishing Incident | beginner | Encode a spearphishing incident in MISP |
| MISP Encoding Exercise: Flubot Malware | beginner | Encode the Flubot malware case using the MISP data model |
| MISP Encoding Exercise: Ransomware infection via e-mail | advanced | Encode a ransomware-via-email incident in MISP |
| Campaign Targeting Multiple ISACs | advanced | Model a campaign spanning several ISACs in MISP |
| Protect the network! | advanced | Turn IoCs into Suricata protection rules |
| SOC Analysis Workshop | advanced | Investigate PCAPs, correlate, and feed protective tools (NGSOTI) |
| Hack.lu Workflow Exercises | advanced | Learn to build MISP workflows |
| Workflow Exercise | expert | Advanced MISP workflow authoring |
The format used to describe the scenarios is the Common Exercise Format (CEXF).
The format description outlines the JSON format including its overall structure and the semantics for each key. While scenarios can be written manually, we strongly recommend using the SkillAegis-Editor to simplify this process.
Sample exercise
{
"exercise": {
"description": "Simple Spear Phishing e-mail example, mimicing a fraud case",
"expanded": "# Simple Spear Phishing e-mail example, mimicing a fraud case",
"meta": {
"author": "MISP Project",
"level": "beginner"
},
"name": "Phishing e-mail",
"namespace": "phishing",
"tags": [
"exercise:software-scope=\"misp\"",
"state:production"
],
"total_duration": "7200",
"uuid": "75d7460-af9d-4098-8ad1-754457076b32",
"valid_until": "20310611",
"version": "20210611"
},
"inject_flow": [...],
"injects": [...],
}This software is licensed under GNU Affero General Public License version 3
Copyright (c) 2025 Steve Clement
Copyright (c) 2024-2025 Sami Mokaddem
Copyright (c) 2024 CIRCL - Computer Incident Response Center Luxembourg