# pradhyumnak/oauth_flaw_detection architecture

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

- Interactive diagram: https://gitdiagram.com/pradhyumnak/oauth_flaw_detection
- Repository: https://github.com/pradhyumnak/oauth_flaw_detection

## Overview

This repository is a research application for generating OAuth/OIDC flows with deliberate vulnerabilities, detecting them with protocol rules and machine learning, and inspecting flows through a Flask interface. The primary analysis path is captured traces → rule flags and trace features → merged dataset → trained classifiers → hybrid predictions and evaluation. Separately, the web app lets a user browse traces and view generated flow graphs. The README documents a Flask relying party and Keycloak lab; unsampled components are represented only where the README or tree supports them.

Main entry points: [`app/traces`](https://github.com/pradhyumnak/oauth_flaw_detection/tree/main/app/traces) (HTTP Traces), [`app/app.py`](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/app.py) (Flask RP), [`app/merge_datasets.py`](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/merge_datasets.py) (Dataset Merge), [`app/hybrid_detector.py`](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/hybrid_detector.py) (Hybrid Detector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lab["Flow Lab"]
  node_flowgen["Flow Generator<br/>[flow_generator.py]"]
  node_keycloak["Keycloak IdP"]
  node_traces[("HTTP Traces")]
  node_dummy["Dummy Callback<br/>[dummy_callback.py]"]
end

subgraph group_web["Trace Viewer"]
  node_flask["Flask RP<br/>[app.py]"]
  node_templates["Web Views"]
  node_flowgraph["Flow Graphs<br/>[app.py]"]
  node_graphjs["Graph Interaction<br/>[utils.js]"]
end

subgraph group_analysis["Detection Pipeline"]
  node_rules["Rule Detector<br/>[rule_engine.py]"]
  node_ruledata[("Rule Outputs<br/>[rule_outputs.csv]")]
  node_features["Feature Extractor"]
  node_featuredata[("Feature Dataset<br/>[dataset.csv]")]
  node_merge["Dataset Merge<br/>[merge_datasets.py]"]
  node_merged[("Merged Dataset<br/>[merged_dataset.csv]")]
  node_classifier["Model Training<br/>[classifier.py]"]
  node_models[("Trained Models")]
end

subgraph group_evaluation["Model Evaluation"]
  node_hybrid["Hybrid Detector<br/>[hybrid_detector.py]"]
  node_evaluate["Evaluation<br/>[evaluate.py]"]
  node_outcomes["Outcome Check<br/>[script.py]"]
end

node_user(("Analyst"))

node_flowgen -->|"sends OAuth flows"| node_keycloak
node_flowgen -->|"saves traces"| node_traces
node_user -->|"browses traces"| node_flask
node_flask -->|"reads traces"| node_traces
node_flask -->|"renders views"| node_templates
node_flask -->|"generates graph"| node_flowgraph
node_flowgraph -.->|"uses interaction code"| node_graphjs
node_rules -->|"reads traces"| node_traces
node_rules -->|"writes flags"| node_ruledata
node_features -->|"reads traces"| node_traces
node_features -->|"writes features"| node_featuredata
node_merge -->|"reads features"| node_featuredata
node_merge -->|"reads flags"| node_ruledata
node_merge -->|"writes merged data"| node_merged
node_classifier -->|"trains from"| node_merged
node_classifier -->|"saves models"| node_models
node_hybrid -->|"loads data"| node_merged
node_hybrid -->|"loads models"| node_models
node_evaluate -->|"calls predictions"| node_hybrid
node_evaluate -->|"loads baseline"| node_models
node_outcomes -->|"checks outcomes"| node_traces

click node_flowgen "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/flow_generator.py"
click node_keycloak "https://github.com/pradhyumnak/oauth_flaw_detection/tree/main/keycloak"
click node_traces "https://github.com/pradhyumnak/oauth_flaw_detection/tree/main/app/traces"
click node_flask "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/app.py"
click node_templates "https://github.com/pradhyumnak/oauth_flaw_detection/tree/main/app/templates"
click node_flowgraph "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/app.py"
click node_graphjs "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/lib/bindings/utils.js"
click node_rules "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/rule_engine.py"
click node_ruledata "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/rule_outputs.csv"
click node_features "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/feature_extractor.py"
click node_featuredata "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/dataset.csv"
click node_merge "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/merge_datasets.py"
click node_merged "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/merged_dataset.csv"
click node_classifier "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/classifier.py"
click node_models "https://github.com/pradhyumnak/oauth_flaw_detection/tree/main/app/models"
click node_hybrid "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/hybrid_detector.py"
click node_evaluate "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/evaluate.py"
click node_outcomes "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/script.py"
click node_dummy "https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/dummy_callback.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_flowgen,node_keycloak,node_traces,node_dummy toneBlue
class node_flask,node_templates,node_flowgraph,node_graphjs toneAmber
class node_rules,node_ruledata,node_features,node_featuredata,node_merge,node_merged,node_classifier,node_models toneMint
class node_hybrid,node_evaluate,node_outcomes toneRose
class node_user toneIndigo
```

## Components

### Flow Lab

- [Flow Generator](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/flow_generator.py): `app/flow_generator.py`
- [Keycloak IdP](https://github.com/pradhyumnak/oauth_flaw_detection/tree/main/keycloak): `keycloak`
- [HTTP Traces](https://github.com/pradhyumnak/oauth_flaw_detection/tree/main/app/traces): `app/traces`
- [Dummy Callback](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/dummy_callback.py): `app/dummy_callback.py`

### Trace Viewer

- [Flask RP](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/app.py): `app/app.py`
- [Web Views](https://github.com/pradhyumnak/oauth_flaw_detection/tree/main/app/templates): `app/templates`
- [Flow Graphs](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/app.py): `app/app.py`
- [Graph Interaction](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/lib/bindings/utils.js): `app/lib/bindings/utils.js`

### Detection Pipeline

- [Rule Detector](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/rule_engine.py): `app/rule_engine.py`
- [Rule Outputs](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/rule_outputs.csv): `app/rule_outputs.csv`
- [Feature Extractor](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/feature_extractor.py): `app/feature_extractor.py`
- [Feature Dataset](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/dataset.csv): `app/dataset.csv`
- [Dataset Merge](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/merge_datasets.py): `app/merge_datasets.py`
- [Merged Dataset](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/merged_dataset.csv): `app/merged_dataset.csv`
- [Model Training](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/classifier.py): `app/classifier.py`
- [Trained Models](https://github.com/pradhyumnak/oauth_flaw_detection/tree/main/app/models): `app/models`

### Model Evaluation

- [Hybrid Detector](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/hybrid_detector.py): `app/hybrid_detector.py`
- [Evaluation](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/evaluate.py): `app/evaluate.py`
- [Outcome Check](https://github.com/pradhyumnak/oauth_flaw_detection/blob/main/app/script.py): `app/script.py`

### Other components

- **Analyst**

## Connections

- Flow Generator → Keycloak IdP: sends OAuth flows (evidence: `README.md`)
- Flow Generator → HTTP Traces: saves traces (evidence: `app/flow_generator.py`)
- Analyst → Flask RP: browses traces (evidence: `app/app.py`)
- Flask RP → HTTP Traces: reads traces (evidence: `app/app.py`)
- Flask RP → Web Views: renders views (evidence: `app/app.py`)
- Flask RP → Flow Graphs: generates graph (evidence: `app/app.py`)
- Flow Graphs → Graph Interaction: uses interaction code
- Rule Detector → HTTP Traces: reads traces (evidence: `app/rule_engine.py`)
- Rule Detector → Rule Outputs: writes flags (evidence: `app/rule_engine.py`)
- Feature Extractor → HTTP Traces: reads traces (evidence: `app/feature_extractor.py`)
- Feature Extractor → Feature Dataset: writes features (evidence: `app/feature_extractor.py`)
- Dataset Merge → Feature Dataset: reads features (evidence: `app/merge_datasets.py`)
- Dataset Merge → Rule Outputs: reads flags (evidence: `app/merge_datasets.py`)
- Dataset Merge → Merged Dataset: writes merged data (evidence: `app/merge_datasets.py`)
- Model Training → Merged Dataset: trains from (evidence: `app/classifier.py`)
- Model Training → Trained Models: saves models (evidence: `app/classifier.py`)
- Hybrid Detector → Merged Dataset: loads data (evidence: `app/hybrid_detector.py`)
- Hybrid Detector → Trained Models: loads models (evidence: `app/hybrid_detector.py`)
- Evaluation → Hybrid Detector: calls predictions (evidence: `app/evaluate.py`)
- Evaluation → Trained Models: loads baseline (evidence: `app/evaluate.py`)
- Outcome Check → HTTP Traces: checks outcomes (evidence: `app/script.py`)
