# fportantier/vulpy architecture

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

- Interactive diagram: https://gitdiagram.com/fportantier/vulpy
- Repository: https://github.com/fportantier/vulpy

## Overview

Vulpy is a Flask/SQLite security-training lab with paired BAD and GOOD implementations. A browser user reaches each version’s Flask app, which dispatches to route modules; login and MFA use authentication/session services, while post pages and API routes read or publish posts. The README also identifies CSP and TLS capabilities, and the tree includes standalone cryptography/security utilities. Some unsampled modules are represented from the tree and README; their internal calls are not inferred.

Main entry points: [`bad/vulpy.py`](https://github.com/fportantier/vulpy/blob/master/bad/vulpy.py) (BAD Flask app), [`good/vulpy.py`](https://github.com/fportantier/vulpy/blob/master/good/vulpy.py) (GOOD Flask app), [`bad/mod_user.py`](https://github.com/fportantier/vulpy/blob/master/bad/mod_user.py) (BAD user routes), [`good/mod_user.py`](https://github.com/fportantier/vulpy/blob/master/good/mod_user.py) (GOOD user routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Web apps"]
  node_bad_app["BAD Flask app<br/>[vulpy.py]"]
  node_good_app["GOOD Flask app<br/>[vulpy.py]"]
  node_bad_hello["BAD hello page<br/>[mod_hello.py]"]
  node_good_hello["GOOD hello page<br/>[mod_hello.py]"]
end

subgraph group_identity["Identity and MFA"]
  node_bad_user_routes["BAD user routes<br/>[mod_user.py]"]
  node_good_user_routes["GOOD user routes<br/>[mod_user.py]"]
  node_bad_user_service["BAD user service<br/>[libuser.py]"]
  node_good_user_service["GOOD user service<br/>[libuser.py]"]
  node_bad_sessions["BAD sessions<br/>[libsession.py]"]
  node_good_sessions["GOOD sessions<br/>[libsession.py]"]
  node_bad_mfa_routes["BAD MFA routes<br/>[mod_mfa.py]"]
  node_good_mfa_routes["GOOD MFA routes<br/>[mod_mfa.py]"]
  node_bad_mfa_service["BAD MFA service<br/>[libmfa.py]"]
  node_good_mfa_service["GOOD MFA service<br/>[libmfa.py]"]
  node_bad_user_db[("BAD user database<br/>[db_init.py]")]
  node_good_user_db[("GOOD user database<br/>[db_init.py]")]
end

subgraph group_content["Posts and API"]
  node_bad_posts_routes["BAD post routes<br/>[mod_posts.py]"]
  node_good_posts_routes["GOOD post routes<br/>[mod_posts.py]"]
  node_bad_posts_service["BAD post service<br/>[libposts.py]"]
  node_good_posts_service["GOOD post service<br/>[libposts.py]"]
  node_bad_api_routes["BAD API routes<br/>[mod_api.py]"]
  node_good_api_routes["GOOD API routes<br/>[mod_api.py]"]
  node_bad_api_service["BAD API service<br/>[libapi.py]"]
  node_good_api_service["GOOD API service<br/>[libapi.py]"]
  node_bad_post_db[("BAD post database<br/>[db_init.py]")]
  node_good_post_db[("GOOD post database<br/>[db_init.py]")]
end

subgraph group_protection["Security controls"]
  node_bad_csp["BAD CSP<br/>[mod_csp.py]"]
  node_good_csp["GOOD CSP<br/>[mod_csp.py]"]
  node_bad_tls["BAD TLS server<br/>[vulpy-ssl.py]"]
  node_good_tls["GOOD TLS server<br/>[vulpy-ssl.py]"]
end

subgraph group_utilities["Security utilities"]
  node_crypto_tools["Crypto utilities"]
  node_brute_tools["Brute-force tools<br/>[httpbrute.py]"]
end

node_browser(("Browser user"))

node_browser -->|"uses"| node_bad_app
node_browser -->|"uses"| node_good_app
node_bad_app -->|"registers"| node_bad_user_routes
node_bad_app -->|"registers"| node_bad_posts_routes
node_bad_app -->|"registers"| node_bad_mfa_routes
node_bad_app -->|"registers"| node_bad_api_routes
node_bad_app -->|"registers"| node_bad_csp
node_bad_app -->|"registers"| node_bad_hello
node_good_app -->|"registers"| node_good_user_routes
node_good_app -->|"registers"| node_good_posts_routes
node_good_app -->|"registers"| node_good_mfa_routes
node_good_app -->|"registers"| node_good_api_routes
node_good_app -->|"registers"| node_good_csp
node_good_app -->|"registers"| node_good_hello
node_bad_app -->|"loads"| node_bad_sessions
node_good_app -->|"loads"| node_good_sessions
node_bad_user_routes -->|"authenticates"| node_bad_user_service
node_bad_user_routes -->|"creates session"| node_bad_sessions
node_bad_user_routes -->|"validates OTP"| node_bad_mfa_service
node_good_user_routes -->|"authenticates"| node_good_user_service
node_good_user_routes -->|"creates session"| node_good_sessions
node_good_user_routes -->|"validates OTP"| node_good_mfa_service
node_bad_mfa_routes -->|"manages MFA"| node_bad_mfa_service
node_good_mfa_routes -->|"manages MFA"| node_good_mfa_service
node_bad_posts_routes -->|"serves posts"| node_bad_posts_service
node_good_posts_routes -->|"serves posts"| node_good_posts_service
node_bad_api_routes -->|"creates keys"| node_bad_api_service
node_bad_api_routes -->|"reads and writes"| node_bad_posts_service
node_bad_api_routes -->|"authenticates"| node_bad_user_service
node_good_api_routes -->|"creates keys"| node_good_api_service
node_good_api_routes -->|"reads and writes"| node_good_posts_service
node_good_api_routes -->|"authenticates"| node_good_user_service
node_bad_user_service -.->|"reads and writes"| node_bad_user_db
node_bad_mfa_service -.->|"reads and writes"| node_bad_user_db
node_bad_posts_service -.->|"reads and writes"| node_bad_post_db
node_good_user_service -.->|"reads and writes"| node_good_user_db
node_good_mfa_service -.->|"reads and writes"| node_good_user_db
node_good_posts_service -.->|"reads and writes"| node_good_post_db

click node_bad_app "https://github.com/fportantier/vulpy/blob/master/bad/vulpy.py"
click node_good_app "https://github.com/fportantier/vulpy/blob/master/good/vulpy.py"
click node_bad_user_routes "https://github.com/fportantier/vulpy/blob/master/bad/mod_user.py"
click node_good_user_routes "https://github.com/fportantier/vulpy/blob/master/good/mod_user.py"
click node_bad_user_service "https://github.com/fportantier/vulpy/blob/master/bad/libuser.py"
click node_good_user_service "https://github.com/fportantier/vulpy/blob/master/good/libuser.py"
click node_bad_sessions "https://github.com/fportantier/vulpy/blob/master/bad/libsession.py"
click node_good_sessions "https://github.com/fportantier/vulpy/blob/master/good/libsession.py"
click node_bad_mfa_routes "https://github.com/fportantier/vulpy/blob/master/bad/mod_mfa.py"
click node_good_mfa_routes "https://github.com/fportantier/vulpy/blob/master/good/mod_mfa.py"
click node_bad_mfa_service "https://github.com/fportantier/vulpy/blob/master/bad/libmfa.py"
click node_good_mfa_service "https://github.com/fportantier/vulpy/blob/master/good/libmfa.py"
click node_bad_posts_routes "https://github.com/fportantier/vulpy/blob/master/bad/mod_posts.py"
click node_good_posts_routes "https://github.com/fportantier/vulpy/blob/master/good/mod_posts.py"
click node_bad_posts_service "https://github.com/fportantier/vulpy/blob/master/bad/libposts.py"
click node_good_posts_service "https://github.com/fportantier/vulpy/blob/master/good/libposts.py"
click node_bad_api_routes "https://github.com/fportantier/vulpy/blob/master/bad/mod_api.py"
click node_good_api_routes "https://github.com/fportantier/vulpy/blob/master/good/mod_api.py"
click node_bad_api_service "https://github.com/fportantier/vulpy/blob/master/bad/libapi.py"
click node_good_api_service "https://github.com/fportantier/vulpy/blob/master/good/libapi.py"
click node_bad_user_db "https://github.com/fportantier/vulpy/blob/master/bad/db_init.py"
click node_good_user_db "https://github.com/fportantier/vulpy/blob/master/good/db_init.py"
click node_bad_post_db "https://github.com/fportantier/vulpy/blob/master/bad/db_init.py"
click node_good_post_db "https://github.com/fportantier/vulpy/blob/master/good/db_init.py"
click node_bad_csp "https://github.com/fportantier/vulpy/blob/master/bad/mod_csp.py"
click node_good_csp "https://github.com/fportantier/vulpy/blob/master/good/mod_csp.py"
click node_bad_hello "https://github.com/fportantier/vulpy/blob/master/bad/mod_hello.py"
click node_good_hello "https://github.com/fportantier/vulpy/blob/master/good/mod_hello.py"
click node_bad_tls "https://github.com/fportantier/vulpy/blob/master/bad/vulpy-ssl.py"
click node_good_tls "https://github.com/fportantier/vulpy/blob/master/good/vulpy-ssl.py"
click node_crypto_tools "https://github.com/fportantier/vulpy/tree/master/utils"
click node_brute_tools "https://github.com/fportantier/vulpy/blob/master/utils/httpbrute.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_bad_app,node_good_app,node_bad_hello,node_good_hello,node_browser toneBlue
class node_bad_user_routes,node_good_user_routes,node_bad_user_service,node_good_user_service,node_bad_sessions,node_good_sessions,node_bad_mfa_routes,node_good_mfa_routes,node_bad_mfa_service,node_good_mfa_service,node_bad_user_db,node_good_user_db toneAmber
class node_bad_posts_routes,node_good_posts_routes,node_bad_posts_service,node_good_posts_service,node_bad_api_routes,node_good_api_routes,node_bad_api_service,node_good_api_service,node_bad_post_db,node_good_post_db toneMint
class node_bad_csp,node_good_csp,node_bad_tls,node_good_tls toneRose
class node_crypto_tools,node_brute_tools toneIndigo
```

## Components

### Web apps

- [BAD Flask app](https://github.com/fportantier/vulpy/blob/master/bad/vulpy.py): `bad/vulpy.py`
- [GOOD Flask app](https://github.com/fportantier/vulpy/blob/master/good/vulpy.py): `good/vulpy.py`
- [BAD hello page](https://github.com/fportantier/vulpy/blob/master/bad/mod_hello.py): `bad/mod_hello.py`
- [GOOD hello page](https://github.com/fportantier/vulpy/blob/master/good/mod_hello.py): `good/mod_hello.py`

### Identity and MFA

- [BAD user routes](https://github.com/fportantier/vulpy/blob/master/bad/mod_user.py): `bad/mod_user.py`
- [GOOD user routes](https://github.com/fportantier/vulpy/blob/master/good/mod_user.py): `good/mod_user.py`
- [BAD user service](https://github.com/fportantier/vulpy/blob/master/bad/libuser.py): `bad/libuser.py`
- [GOOD user service](https://github.com/fportantier/vulpy/blob/master/good/libuser.py): `good/libuser.py`
- [BAD sessions](https://github.com/fportantier/vulpy/blob/master/bad/libsession.py): `bad/libsession.py`
- [GOOD sessions](https://github.com/fportantier/vulpy/blob/master/good/libsession.py): `good/libsession.py`
- [BAD MFA routes](https://github.com/fportantier/vulpy/blob/master/bad/mod_mfa.py): `bad/mod_mfa.py`
- [GOOD MFA routes](https://github.com/fportantier/vulpy/blob/master/good/mod_mfa.py): `good/mod_mfa.py`
- [BAD MFA service](https://github.com/fportantier/vulpy/blob/master/bad/libmfa.py): `bad/libmfa.py`
- [GOOD MFA service](https://github.com/fportantier/vulpy/blob/master/good/libmfa.py): `good/libmfa.py`
- [BAD user database](https://github.com/fportantier/vulpy/blob/master/bad/db_init.py): `bad/db_init.py`
- [GOOD user database](https://github.com/fportantier/vulpy/blob/master/good/db_init.py): `good/db_init.py`

### Posts and API

- [BAD post routes](https://github.com/fportantier/vulpy/blob/master/bad/mod_posts.py): `bad/mod_posts.py`
- [GOOD post routes](https://github.com/fportantier/vulpy/blob/master/good/mod_posts.py): `good/mod_posts.py`
- [BAD post service](https://github.com/fportantier/vulpy/blob/master/bad/libposts.py): `bad/libposts.py`
- [GOOD post service](https://github.com/fportantier/vulpy/blob/master/good/libposts.py): `good/libposts.py`
- [BAD API routes](https://github.com/fportantier/vulpy/blob/master/bad/mod_api.py): `bad/mod_api.py`
- [GOOD API routes](https://github.com/fportantier/vulpy/blob/master/good/mod_api.py): `good/mod_api.py`
- [BAD API service](https://github.com/fportantier/vulpy/blob/master/bad/libapi.py): `bad/libapi.py`
- [GOOD API service](https://github.com/fportantier/vulpy/blob/master/good/libapi.py): `good/libapi.py`
- [BAD post database](https://github.com/fportantier/vulpy/blob/master/bad/db_init.py): `bad/db_init.py`
- [GOOD post database](https://github.com/fportantier/vulpy/blob/master/good/db_init.py): `good/db_init.py`

### Security controls

- [BAD CSP](https://github.com/fportantier/vulpy/blob/master/bad/mod_csp.py): `bad/mod_csp.py`
- [GOOD CSP](https://github.com/fportantier/vulpy/blob/master/good/mod_csp.py): `good/mod_csp.py`
- [BAD TLS server](https://github.com/fportantier/vulpy/blob/master/bad/vulpy-ssl.py): `bad/vulpy-ssl.py`
- [GOOD TLS server](https://github.com/fportantier/vulpy/blob/master/good/vulpy-ssl.py): `good/vulpy-ssl.py`

### Security utilities

- [Crypto utilities](https://github.com/fportantier/vulpy/tree/master/utils): `utils`
- [Brute-force tools](https://github.com/fportantier/vulpy/blob/master/utils/httpbrute.py): `utils/httpbrute.py`

### Other components

- **Browser user**

## Connections

- Browser user → BAD Flask app: uses
- Browser user → GOOD Flask app: uses
- BAD Flask app → BAD user routes: registers (evidence: `bad/vulpy.py`)
- BAD Flask app → BAD post routes: registers (evidence: `bad/vulpy.py`)
- BAD Flask app → BAD MFA routes: registers (evidence: `bad/vulpy.py`)
- BAD Flask app → BAD API routes: registers (evidence: `bad/vulpy.py`)
- BAD Flask app → BAD CSP: registers (evidence: `bad/vulpy.py`)
- BAD Flask app → BAD hello page: registers (evidence: `bad/vulpy.py`)
- GOOD Flask app → GOOD user routes: registers (evidence: `good/vulpy.py`)
- GOOD Flask app → GOOD post routes: registers (evidence: `good/vulpy.py`)
- GOOD Flask app → GOOD MFA routes: registers (evidence: `good/vulpy.py`)
- GOOD Flask app → GOOD API routes: registers (evidence: `good/vulpy.py`)
- GOOD Flask app → GOOD CSP: registers (evidence: `good/vulpy.py`)
- GOOD Flask app → GOOD hello page: registers (evidence: `good/vulpy.py`)
- BAD Flask app → BAD sessions: loads (evidence: `bad/vulpy.py`)
- GOOD Flask app → GOOD sessions: loads (evidence: `good/vulpy.py`)
- BAD user routes → BAD user service: authenticates (evidence: `bad/mod_user.py`)
- BAD user routes → BAD sessions: creates session (evidence: `bad/mod_user.py`)
- BAD user routes → BAD MFA service: validates OTP (evidence: `bad/mod_user.py`)
- GOOD user routes → GOOD user service: authenticates (evidence: `good/mod_user.py`)
- GOOD user routes → GOOD sessions: creates session (evidence: `good/mod_user.py`)
- GOOD user routes → GOOD MFA service: validates OTP (evidence: `good/mod_user.py`)
- BAD MFA routes → BAD MFA service: manages MFA (evidence: `bad/mod_mfa.py`)
- GOOD MFA routes → GOOD MFA service: manages MFA (evidence: `good/mod_mfa.py`)
- BAD post routes → BAD post service: serves posts (evidence: `bad/mod_posts.py`)
- GOOD post routes → GOOD post service: serves posts (evidence: `good/mod_posts.py`)
- BAD API routes → BAD API service: creates keys (evidence: `bad/mod_api.py`)
- BAD API routes → BAD post service: reads and writes (evidence: `bad/mod_api.py`)
- BAD API routes → BAD user service: authenticates (evidence: `bad/mod_api.py`)
- GOOD API routes → GOOD API service: creates keys (evidence: `good/mod_api.py`)
- GOOD API routes → GOOD post service: reads and writes (evidence: `good/mod_api.py`)
- GOOD API routes → GOOD user service: authenticates (evidence: `good/mod_api.py`)
- BAD user service → BAD user database: reads and writes
- BAD MFA service → BAD user database: reads and writes
- BAD post service → BAD post database: reads and writes
- GOOD user service → GOOD user database: reads and writes
- GOOD MFA service → GOOD user database: reads and writes
- GOOD post service → GOOD post database: reads and writes
