flowrec — Local HTTPS API Flow Recorder & Analyzer

Intercept, classify, and export API flows from any browser or app.
No AI. No cloud. Fully deterministic. Fully local.

---

Screenshots

Main Menu

Flow Browser

Session Summary

---

Features

Component	What it does
Proxy Layer	mitmproxy-based HTTPS interception, HTTP/1.1 + HTTP/2
Filter Engine	Drops static assets, analytics; keeps API/XHR traffic
Auth Detector	Identifies Bearer, Cookie, CSRF, Basic, API-Key auth
Token Tracker	Tracks token birth → usage → refresh across sessions
Intent Classifier	Labels each request (LOGIN, CHAT_SEND, TOKEN_REFRESH…)
Flow Graph	Builds dependency DAG from shared tokens / conversation IDs
Export Engine	Generates curl commands and Python requests snippets
Flat-file Storage	All data in .json + per-flow .md files — no database
Interactive TUI	Full menu-driven terminal UI powered by Rich

---

Installation

git clone https://github.com/mrxvaau/flowrec
cd flowrec
pip install -r requirements.txt

---

Quick Start

python run.py

No arguments needed — launches the interactive TUI menu directly.

Or use CLI directly

python run.py start --port 8888
python run.py list
python run.py show <id>
python run.py graph
python run.py tokens
python run.py summary

---

Setup — MITM Certificate (one time)

1. Start flowrec and set browser proxy to 127.0.0.1:8888
2. Visit http://mitm.it in the proxied browser
3. Download and install the cert for your OS

Windows:  Double-click .cer → Local Machine → Trusted Root CAs
macOS:    Keychain Access → Import → Set Trust to Always
Linux:    sudo cp cert.pem /usr/local/share/ca-certificates/ && update-ca-certificates

---

TUI Menu Options

Key	Action
1	Start capturing — prompts for port, shows live colorized stream
2	Browse flows — filter by intent/method/host/status, inspect detail
3	Flow dependency graph — ASCII DAG showing token chains
4	Token lifecycle — all tracked tokens + refresh event detection
5	Session summary — breakdown by intent, method, status, auth
6	Export all flows to .md or .json
7	Clear all data
8	Certificate setup instructions

---

Intent Labels

Intent	Trigger
LOGIN	Path /login or fields {email, password}
TOKEN_REFRESH	Path /refresh or {grant_type, refresh_token}
CHAT_SEND	Path /chat + POST, or {message} field
AI_COMPLETION	Path /completions + {prompt}
GRAPHQL	Path /graphql + POST
PROFILE_GET	Path /me, /profile + GET
FILE_UPLOAD	Path /upload or {file} field
HEALTHCHECK	Path /ping, /health
DATA_FETCH	Fallback for GET
DATA_POST	Fallback for POST

---

Data Storage

All data lives in flowrec/data/ — no database required:

data/
├── flows.json          ← index of all flows
├── tokens.json         ← tracked tokens
├── graph.json          ← computed dependency graph
├── session.md          ← human-readable session summary
├── export/             ← bulk exports land here
└── flows/
    ├── abc12345.md     ← per-flow markdown
    └── ...

---

Architecture

flowrec/
├── run.py                   ← entry point (TUI or CLI)
├── tui.py                   ← interactive terminal UI
├── proxy/
│   └── interceptor.py       ← mitmproxy addon
├── core/
│   ├── filter.py            ← request filtering rules
│   ├── parser.py            ← body decoding, JSON utils
│   ├── auth.py              ← auth detection
│   ├── token_tracker.py     ← token lifecycle
│   ├── classifier.py        ← intent classification
│   ├── flow_builder.py      ← dependency graph
│   └── exporter.py          ← curl + Python export
├── db/
│   └── models.py            ← FlowRecord, TokenRecord, Store
└── cli/
    └── commands.py          ← CLI interface

---

Requirements

mitmproxy>=10.0.0
brotli>=1.0.9
rich>=13.0.0

---

Author

mrxvaau — github.com/mrxvaau · mrxvaau.github.io

---

License

MIT