Skip to content

test: add 52-test suite, GitHub Actions CI with bandit scan, rewrite README #13

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SentinelByte merged 1 commit into from
Jul 22, 2026
Merged

test: add 52-test suite, GitHub Actions CI with bandit scan, rewrite README #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 49 additions & 0 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
name: CI

on:
push:
branches: [main]
pull_request:
branches: [main]

jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.11", "3.12"]

steps:
- uses: actions/checkout@v4

- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}

- name: Install dependencies
run: pip install -e ".[dev]"

- name: Lint (ruff)
run: ruff check cybersim/ tests/ run.py

- name: Run tests
run: pytest --cov=cybersim --cov-report=term-missing

security-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.12"

- name: Install bandit
run: pip install bandit

- name: Static security analysis (bandit)
run: bandit -r cybersim/ -ll
# -ll = only report medium/high severity issues
# Low-severity noise (assert statements etc.) is excluded intentionally
264 changes: 197 additions & 67 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,105 +1,235 @@
# 🛡️ Cyber MAS Sim
# cyber-sim-mas

## Multi Agent System Simulation for CyberSecurity WF
**Adaptive multi-agent cybersecurity simulation** — model real attack chains, tune detection logic, and measure what actually matters: MTTD, MTTR, and blast radius.

SentinelByte 2025 (DCV)

A lightweight simulation framework for modeling attacker and defender agents in a cybersecurity environment. Built from scratch to support reinforcement learning, automation, and cloud security training scenarios.
![CI](https://github.com/SentinelByte/cyber-sim-mas/actions/workflows/ci.yml/badge.svg)
![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
![License: MIT](https://img.shields.io/badge/license-MIT-green)

---

## 🚀 Features
## Why this exists

- Simulated network with vulnerable nodes
- Attacker and defender agents with pluggable logic
- Logs, patching, and basic interaction tracking
- Designed for future expansion: RL, PettingZoo, AWS/K8s integrations
I built this while thinking about a question that comes up a lot in security engineering: **how do you reason about detection coverage before you're under attack?**

Most threat modeling happens on whiteboards. This simulation lets you run an attacker against a defender on a specific network topology and watch the kill chain unfold — which techniques the attacker leans on, how quickly the defender picks up the signal, and what the blast radius looks like by the time containment kicks in.

## 📁 Project Structure
It's not a replacement for real red team exercises, but it's a fast way to prototype detection tuning, model IR response delays, or understand why a supply chain attacker can be in your environment for weeks before anything fires.

```
---

cyber-mas-sim/
├── agents/ # Attacker and Defender agents
│ ├── attacker.py
│ └── defender.py
├── core/ # Simulation engine & utilities
│ ├── simulation.py
│ └── utils.py (optional)
├── env/ # Simulated environment (nodes, network)
│ ├── node.py
│ └── network.py (optional)
├── run.py # Entrypoint to run the simulation
├── requirements.txt # Python dependencies
|__ README.md

````
## Scenarios

Three built-in scenarios, each modeled on real threat patterns:

| Scenario | Threat | Key characteristic |
|---|---|---|
| `lateral_movement` | Perimeter breach → internal pivot | DMZ foothold → internal recon → DC compromise |
| `cloud_iam` | Compromised identity → privilege escalation | Misconfigured IAM roles, IMDS credential theft, silent S3 exfil |
| `supply_chain` | Malicious dependency → CI/CD compromise | Dependency confusion → pipeline takeover → poisoned artifact in prod |

### MITRE ATT&CK coverage

| Technique ID | Name | Scenario |
|---|---|---|
| T1046 | Network Service Scanning | lateral_movement |
| T1190 | Exploit Public-Facing Application | lateral_movement |
| T1110.001 | Brute Force: Password Guessing | lateral_movement |
| T1021.001 | Remote Services: SSH | lateral_movement |
| T1547.001 | Boot or Logon Autostart | lateral_movement |
| T1048 | Exfiltration Over Alternative Protocol | lateral_movement |
| T1078.004 | Valid Accounts: Cloud Accounts | cloud_iam |
| T1580 | Cloud Infrastructure Discovery | cloud_iam |
| T1078 | Privilege Escalation via Misconfigured Role | cloud_iam |
| T1552.005 | Cloud Instance Metadata API (IMDS) | cloud_iam |
| T1530 | Data from Cloud Storage Object | cloud_iam |
| T1195.001 | Supply Chain: Software Dependencies | supply_chain |
| T1552.001 | Unsecured Credentials: CI/CD Secrets | supply_chain |
| T1072 | Software Deployment Tools | supply_chain |

---

## 🧪 Quick Start
## Quick start

### 1. Clone and Setup
```bash
git clone https://github.com/SentinelByte/cyberMasSim.git
cd cyberMasSim
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
````
git clone https://github.com/SentinelByte/cyber-sim-mas.git
cd cyber-sim-mas
pip install -e ".[dev]"

### 2. Run the Simulation
# list available scenarios
python run.py --list-scenarios

```bash
python run.py
# run with verbose round-by-round output
python run.py --scenario lateral_movement --rounds 15 --verbose

# reproducible run — share the seed and anyone gets the same outcome
python run.py --scenario cloud_iam --rounds 20 --seed 42

# supply chain / CI-CD compromise
python run.py --scenario supply_chain --rounds 12 --verbose --seed 7
```

Example output (`--seed 13` gives a run where both attacker and defender are active):

```
$ python run.py --scenario lateral_movement --rounds 15 --seed 13

╭──────────────────────────────── cyber-sim-mas ─────────────────────────────────╮
│ Lateral Movement │
│ Attacker gains DMZ foothold and pivots toward internal assets │
│ │
│ Nodes: 5 · Rounds: 15 · Detection threshold: 3 · Techniques: 7 · │
│ seed=13 │
╰────────────────────────────────────────────────────────────────────────────────╯

Simulation Results — lateral_movement
╭─────────────────────────────┬──────────╮
│ Metric │ Value │
├─────────────────────────────┼──────────┤
│ Total rounds │ 15 │
│ MTTD (mean time to detect) │ 3 rounds │
│ MTTR (mean time to respond) │ 4 rounds │
│ Peak blast radius │ 100.0% │
│ Nodes compromised (final) │ 5 │
│ Attack success rate │ 83.3% │
│ Defender efficiency │ 20.0% │
╰─────────────────────────────┴──────────╯
```

Omit `--seed` for a fresh random run each time. Pass the same seed to anyone you want to discuss the same outcome with.

---

## ✅ TODO
## Architecture

```mermaid
graph TD
CLI[run.py CLI] --> SIM[Simulation Engine]
SIM --> ATK[AttackerAgent]
SIM --> DEF[DefenderAgent]
SIM --> MET[SimulationMetrics]

ATK --> NET[Network]
DEF --> NET
NET --> N1[Node DMZ]
NET --> N2[Node Internal]
NET --> N3[Node Cloud/CICD]

ATK --> TECH[techniques.py\nMITRE ATT&CK]
ATK --> WEIGHTS[Adaptive Weights\nper-technique]

DEF --> PHASES[Response Phases\nMonitor → Investigate\n→ Contain → Remediate]
MET --> MTTD[MTTD]
MET --> MTTR[MTTR]
MET --> BLAST[Blast Radius]

SCEN[Scenarios] --> SIM
SCEN --> S1[lateral_movement]
SCEN --> S2[cloud_iam]
SCEN --> S3[supply_chain]
```

* [ ] Add lateral movement and network graph
* [ ] Introduce Reinforcement Learning (PettingZoo/Gym)
* [ ] Model AWS or K8s-specific attack/defense behavior
* [ ] Visualization (grid or graph)
---

## Adaptive threat model

## 📜 License
The attacker adapts its technique selection across rounds using a simple reinforcement heuristic — not ML, but a meaningful approximation of real adversarial behavior:

MIT License — free to use and modify.
- Each technique starts with equal weight `1.0`
- Success: `weight *= 1.3` (capped at `5.0`)
- Failure: `weight *= 0.75` (floored at `0.1`)
- Technique selection is a **weighted random draw** from applicable candidates for the current stage and node

This means the attacker naturally converges toward techniques that work on the specific network topology it's facing — brute-force SSH gets deprioritized after repeated failures, while silent credential theft techniques get amplified if they succeed early.

## 🙋‍♂️ About
The mechanism is intentionally kept simple. The goal isn't to model a sophisticated APT — it's to demonstrate that even basic strategy adaptation changes detection and response dynamics in measurable ways.

Built by SentinelByte.
---

Exploring Multi Agent Systems (MAS) for autonomous defense, cloud remediation, and adversarial simulation.
## Threat model and assumptions

````
gitignore
**Attacker assumptions:**
- External attacker with no prior knowledge of the network
- Follows a simplified kill chain (Recon → Initial Access → Persistence → Lateral Movement → Exfiltration)
- Adapts technique prioritization based on success history
- Cannot bypass isolation — if a node is isolated, it's unreachable

## Python
__pycache__/
*.pyc
*.pyo
*.pyd
*.log
**Defender assumptions:**
- Detection is probabilistic — depends on technique noise level and node detection difficulty
- Responses are delayed (configurable `response_delay`) to model IR lead time
- Can patch (keep node online, slower) or isolate (fast, breaks availability)
- Alert fatigue modeled via configurable `detection_threshold`

## Envs
venv/
.env
**Limitations:**
- No actual network routing — reachability is zone-based, not graph-based
- Techniques don't chain (no credential reuse across nodes)
- Attacker has perfect knowledge of services once recon succeeds
- No notion of time-of-day, attacker dwell time, or concurrent attacks
- The simulation is discrete-round, not continuous — timing within a round isn't modeled

## IDEs
.vscode/
.idea/
````
These limitations are deliberate scope constraints, not bugs. A simulation that's too complex to understand in 10 minutes doesn't serve the learning purpose.

---

## 🏷️ GitHub Tags and Topics

Repo Tags:
## Project structure

```
cybersecurity, multi-agent-system, red-team, blue-team, simulation, python, cloud-security, SentinelByte
cyber-sim-mas/
├── cybersim/
│ ├── agents/
│ │ ├── attacker.py # Adaptive kill-chain attacker
│ │ └── defender.py # Detection + IR response phases
│ ├── core/
│ │ ├── simulation.py # Engine (decoupled from display)
│ │ └── metrics.py # MTTD, MTTR, blast radius
│ ├── env/
│ │ ├── node.py # Asset model (CVSS, zone, state)
│ │ └── network.py # Topology + reachability
│ ├── scenarios/
│ │ ├── lateral_movement.py
│ │ ├── cloud_iam.py
│ │ └── supply_chain.py
│ └── techniques.py # MITRE ATT&CK technique definitions
├── tests/ # 52 unit + integration tests
├── .github/workflows/ci.yml # Lint, test, bandit scan
├── run.py # CLI entrypoint
└── pyproject.toml
```

---

## Development

```bash
pip install -e ".[dev]"

# run tests
pytest

# lint
ruff check cybersim/ tests/ run.py

# static security analysis
bandit -r cybersim/ -ll
```

Tests cover node state transitions, attacker stage progression, adaptive weight behavior, defender detection phases, and full simulation invariants across all three scenarios. Results are seeded for determinism.

---

## What's next

A few things I'd like to add when time allows:

- **Graph-based reachability** — actual adjacency between nodes rather than zone-level logic
- **Credential reuse** — attacker can pivot credentials stolen on one node to authenticate on another
- **RL-based defender** — a defender that learns optimal response policies across many simulation runs (the current heuristic is a reasonable baseline but it doesn't adapt)
- **JSON output** — structured results for feeding into dashboards or comparing runs programmatically

---

## License

MIT — see [LICENSE](LICENSE).

Built by [SentinelByte](https://github.com/SentinelByte).
Loading
Loading