# syrrus-ali/bantis architecture

> Architecture diagram of the GitHub repository syrrus-ali/bantis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/syrrus-ali/bantis
- Repository: https://github.com/syrrus-ali/bantis

## Overview

Bantis combines a self-hosted target range, attack-simulation scenarios, and an event-ingestion/correlation service. The principal workflow is an operator running a guarded scenario against the range; it emits a structured event, which can be ingested and stored by the Detection Engine. The README says scenario events are not yet consumed in the current M2 setup, so the event-to-engine connection is shown as optional. Correlation code exists, but its invocation is not established by the sampled source. No AI-response implementation is represented.

Main entry points: [`attack-sim/scenarios/base.py`](https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/base.py) (Scenario contract), [`attack-sim/scenarios/replay.py`](https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/replay.py) (Replay registry), [`range/api/app/routers/tasks.py`](https://github.com/syrrus-ali/bantis/blob/main/range/api/app/routers/tasks.py) (Task routes), [`range/api/app/main.py`](https://github.com/syrrus-ali/bantis/blob/main/range/api/app/main.py) (Range API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_range["Target Range"]
  node_nginx["Nginx ingress<br/>[default.conf]"]
  node_range_api["Range API<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_task_routes["Task routes<br/>[tasks.py]"]
  node_security["Token security<br/>[security.py]"]
  node_range_db[("Range database<br/>[db.py]")]
  node_range_cache[("Task cache<br/>[cache.py]")]
end

subgraph group_simulation["Attack Simulation"]
  node_attack_cli["Scenario CLI<br/>[cli.py]"]
  node_replay["Replay registry<br/>[replay.py]"]
  node_scenario_base["Scenario contract<br/>[base.py]"]
  node_dependency["Dependency attack"]
  node_secret["Leaked-secret attack<br/>[leaked_secret.py]"]
  node_ci_step["CI-step attack"]
  node_typosquat["Typosquatting attack<br/>[typosquatting.py]"]
  node_noop["No-op scenario<br/>[noop.py]"]
end

subgraph group_detection["Detection Engine"]
  node_event_api["Event ingestion<br/>[events.py]"]
  node_detection_app["Detection service<br/>[main.py]"]
  node_event_store[("Event store<br/>[event_models.py]")]
  node_correlation["Incident correlation<br/>[correlation.py]"]
  node_incident_store[("Incident records<br/>[incident_models.py]")]
end

node_operator(("Operator"))
node_client(("Range client"))

node_client -->|"sends requests"| node_nginx
node_nginx -->|"proxies requests"| node_range_api
node_range_api -->|"dispatches auth"| node_auth_routes
node_range_api -->|"dispatches tasks"| node_task_routes
node_auth_routes -->|"uses token functions"| node_security
node_task_routes -->|"checks user"| node_security
node_auth_routes -->|"reads/writes users"| node_range_db
node_task_routes -->|"reads/writes tasks"| node_range_db
node_task_routes -->|"reads/writes cache"| node_range_cache
node_operator -->|"runs commands"| node_attack_cli
node_attack_cli -->|"runs scenario"| node_replay
node_attack_cli -->|"checks/cleans up"| node_scenario_base
node_replay -->|"dispatches replay"| node_dependency
node_replay -->|"dispatches replay"| node_secret
node_replay -->|"dispatches replay"| node_ci_step
node_replay -->|"dispatches replay"| node_typosquat
node_replay -->|"dispatches replay"| node_noop
node_dependency -->|"implements contract"| node_scenario_base
node_secret -->|"implements contract"| node_scenario_base
node_ci_step -->|"implements contract"| node_scenario_base
node_typosquat -->|"implements contract"| node_scenario_base
node_noop -->|"implements contract"| node_scenario_base
node_dependency -->|"edits build dependency"| node_range_api
node_scenario_base -.->|"emits event; optional ingestion"| node_event_api
node_detection_app -->|"registers routes"| node_event_api
node_event_api -->|"stores events"| node_event_store
node_correlation -->|"reads events"| node_event_store
node_correlation -->|"writes incidents"| node_incident_store

click node_nginx "https://github.com/syrrus-ali/bantis/blob/main/range/nginx/default.conf"
click node_range_api "https://github.com/syrrus-ali/bantis/blob/main/range/api/app/main.py"
click node_auth_routes "https://github.com/syrrus-ali/bantis/blob/main/range/api/app/routers/auth.py"
click node_task_routes "https://github.com/syrrus-ali/bantis/blob/main/range/api/app/routers/tasks.py"
click node_security "https://github.com/syrrus-ali/bantis/blob/main/range/api/app/security.py"
click node_range_db "https://github.com/syrrus-ali/bantis/blob/main/range/api/app/db.py"
click node_range_cache "https://github.com/syrrus-ali/bantis/blob/main/range/api/app/cache.py"
click node_attack_cli "https://github.com/syrrus-ali/bantis/blob/main/attack-sim/cli.py"
click node_replay "https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/replay.py"
click node_scenario_base "https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/base.py"
click node_dependency "https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/malicious_dependency.py"
click node_secret "https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/leaked_secret.py"
click node_ci_step "https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/compromised_ci_step.py"
click node_typosquat "https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/typosquatting.py"
click node_noop "https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/noop.py"
click node_event_api "https://github.com/syrrus-ali/bantis/blob/main/detection-engine/app/routers/events.py"
click node_detection_app "https://github.com/syrrus-ali/bantis/blob/main/detection-engine/app/main.py"
click node_event_store "https://github.com/syrrus-ali/bantis/blob/main/detection-engine/app/event_models.py"
click node_correlation "https://github.com/syrrus-ali/bantis/blob/main/detection-engine/app/correlation.py"
click node_incident_store "https://github.com/syrrus-ali/bantis/blob/main/detection-engine/app/incident_models.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_nginx,node_range_api,node_auth_routes,node_task_routes,node_security,node_range_db,node_range_cache,node_client toneBlue
class node_attack_cli,node_replay,node_scenario_base,node_dependency,node_secret,node_ci_step,node_typosquat,node_noop toneAmber
class node_event_api,node_detection_app,node_event_store,node_correlation,node_incident_store toneMint
class node_operator toneIndigo
```

## Components

### Target Range

- [Nginx ingress](https://github.com/syrrus-ali/bantis/blob/main/range/nginx/default.conf): `range/nginx/default.conf`
- [Range API](https://github.com/syrrus-ali/bantis/blob/main/range/api/app/main.py): `range/api/app/main.py`
- [Authentication routes](https://github.com/syrrus-ali/bantis/blob/main/range/api/app/routers/auth.py): `range/api/app/routers/auth.py`
- [Task routes](https://github.com/syrrus-ali/bantis/blob/main/range/api/app/routers/tasks.py): `range/api/app/routers/tasks.py`
- [Token security](https://github.com/syrrus-ali/bantis/blob/main/range/api/app/security.py): `range/api/app/security.py`
- [Range database](https://github.com/syrrus-ali/bantis/blob/main/range/api/app/db.py): `range/api/app/db.py`
- [Task cache](https://github.com/syrrus-ali/bantis/blob/main/range/api/app/cache.py): `range/api/app/cache.py`

### Attack Simulation

- [Scenario CLI](https://github.com/syrrus-ali/bantis/blob/main/attack-sim/cli.py): `attack-sim/cli.py`
- [Replay registry](https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/replay.py): `attack-sim/scenarios/replay.py`
- [Scenario contract](https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/base.py): `attack-sim/scenarios/base.py`
- [Dependency attack](https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/malicious_dependency.py): `attack-sim/scenarios/malicious_dependency.py`
- [Leaked-secret attack](https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/leaked_secret.py): `attack-sim/scenarios/leaked_secret.py`
- [CI-step attack](https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/compromised_ci_step.py): `attack-sim/scenarios/compromised_ci_step.py`
- [Typosquatting attack](https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/typosquatting.py): `attack-sim/scenarios/typosquatting.py`
- [No-op scenario](https://github.com/syrrus-ali/bantis/blob/main/attack-sim/scenarios/noop.py): `attack-sim/scenarios/noop.py`

### Detection Engine

- [Event ingestion](https://github.com/syrrus-ali/bantis/blob/main/detection-engine/app/routers/events.py): `detection-engine/app/routers/events.py`
- [Detection service](https://github.com/syrrus-ali/bantis/blob/main/detection-engine/app/main.py): `detection-engine/app/main.py`
- [Event store](https://github.com/syrrus-ali/bantis/blob/main/detection-engine/app/event_models.py): `detection-engine/app/event_models.py`
- [Incident correlation](https://github.com/syrrus-ali/bantis/blob/main/detection-engine/app/correlation.py): `detection-engine/app/correlation.py`
- [Incident records](https://github.com/syrrus-ali/bantis/blob/main/detection-engine/app/incident_models.py): `detection-engine/app/incident_models.py`

### Other components

- **Operator**
- **Range client**

## Connections

- Range client → Nginx ingress: sends requests
- Nginx ingress → Range API: proxies requests
- Range API → Authentication routes: dispatches auth
- Range API → Task routes: dispatches tasks
- Authentication routes → Token security: uses token functions
- Task routes → Token security: checks user
- Authentication routes → Range database: reads/writes users
- Task routes → Range database: reads/writes tasks
- Task routes → Task cache: reads/writes cache
- Operator → Scenario CLI: runs commands
- Scenario CLI → Replay registry: runs scenario
- Scenario CLI → Scenario contract: checks/cleans up
- Replay registry → Dependency attack: dispatches replay
- Replay registry → Leaked-secret attack: dispatches replay
- Replay registry → CI-step attack: dispatches replay
- Replay registry → Typosquatting attack: dispatches replay
- Replay registry → No-op scenario: dispatches replay
- Dependency attack → Scenario contract: implements contract
- Leaked-secret attack → Scenario contract: implements contract
- CI-step attack → Scenario contract: implements contract
- Typosquatting attack → Scenario contract: implements contract
- No-op scenario → Scenario contract: implements contract
- Dependency attack → Range API: edits build dependency
- Scenario contract → Event ingestion: emits event; optional ingestion
- Detection service → Event ingestion: registers routes
- Event ingestion → Event store: stores events
- Incident correlation → Event store: reads events
- Incident correlation → Incident records: writes incidents