fiddler-toolkit

A Python toolkit for automating workflows around Fiddler, the web debugging proxy for Windows. Parse session archives, extract HTTP traffic data, and integrate Fiddler captures into your analysis pipelines — all from Python.

Fiddler is a widely used web debugging proxy that captures HTTP/HTTPS traffic on Windows. This toolkit bridges Fiddler's session export formats with Python's data ecosystem, making it straightforward to process, filter, and analyze captured sessions programmatically.

---

Features

• 📦 Parse Fiddler .saz session archives — read and decompress Fiddler's native session format without manual extraction
• 🔍 Extract request/response pairs — access headers, bodies, status codes, and timing metadata from captured traffic
• 🔁 Automate replay workflows — reconstruct and replay captured HTTP sessions using requests or httpx
• 📊 Traffic analysis utilities — summarize endpoints, response times, payload sizes, and status code distributions
• 🧹 Session filtering — filter captures by host, method, status code, content type, or custom predicates
• 📁 Export to standard formats — convert Fiddler sessions to HAR (HTTP Archive), CSV, JSON, or pandas DataFrames
• 🪝 FiddlerScript rule parsing — read and validate .js FiddlerScript rule files programmatically
• 🖥️ Windows automation support — launch and control Fiddler for Windows processes via subprocess integration

---

Requirements

Requirement	Version
Python	3.8 or higher
Operating System	Windows 10/11 (primary), Linux/macOS (parse-only mode)
Fiddler for Windows	5.x or later (for live capture features)
requests	≥ 2.28.0
lxml	≥ 4.9.0
pandas	≥ 1.5.0 (optional, for DataFrame export)
httpx	≥ 0.24.0 (optional, for async replay)

---

Installation

Install the stable release from PyPI:

pip install fiddler-toolkit

To include optional dependencies for DataFrame export and async replay:

pip install "fiddler-toolkit[full]"

For development, clone the repository and install in editable mode:

git clone https://github.com/fiddler-toolkit/fiddler-toolkit.git
cd fiddler-toolkit
pip install -e ".[dev]"

---

Quick Start

from fiddler_toolkit import SazSession

# Load a Fiddler .saz session archive
session = SazSession.load("capture_2024_01_15.saz")

print(f"Total sessions captured: {len(session)}")

# Iterate over all HTTP exchanges
for exchange in session:
    print(f"{exchange.request.method} {exchange.request.url} -> {exchange.response.status_code}")

Example output:

Total sessions captured: 142
GET https://api.example.com/v1/users -> 200
POST https://api.example.com/v1/login -> 200
GET https://cdn.example.com/assets/app.js -> 304
GET https://api.example.com/v1/data -> 401
...

---

Usage Examples

Parse and Filter a Fiddler Session Archive

from fiddler_toolkit import SazSession
from fiddler_toolkit.filters import by_host, by_status, by_method

session = SazSession.load("capture.saz")

# Filter to API calls that returned errors
api_errors = session.filter(
    by_host("api.example.com"),
    by_status(range(400, 600))
)

for exchange in api_errors:
    print(f"[{exchange.response.status_code}] {exchange.request.url}")
    print(f"  Response body: {exchange.response.body[:200]}")
    print()

---

Export Session Data to CSV or JSON

from fiddler_toolkit import SazSession
from fiddler_toolkit.exporters import to_csv, to_json, to_har

session = SazSession.load("capture.saz")

# Export a summary of all requests to CSV
to_csv(session, output_path="traffic_summary.csv", fields=[
    "timestamp", "method", "url", "status_code",
    "response_size_bytes", "elapsed_ms"
])

# Export full session to HAR format (compatible with browser dev tools)
to_har(session, output_path="capture.har")

# Export to JSON for downstream processing
to_json(session, output_path="capture.json", pretty=True)

print("Export complete.")

---

Analyze Traffic Statistics

from fiddler_toolkit import SazSession
from fiddler_toolkit.analysis import SessionAnalyzer

session = SazSession.load("capture.saz")
analyzer = SessionAnalyzer(session)

# Get a summary report
report = analyzer.summary()

print(f"Unique hosts contacted : {report.unique_hosts}")
print(f"Total data transferred : {report.total_bytes / 1024:.1f} KB")
print(f"Average response time  : {report.avg_elapsed_ms:.1f} ms")
print(f"Slowest endpoint       : {report.slowest_request.url}")
print()

# Status code breakdown
print("Status code distribution:")
for code, count in report.status_distribution.items():
    print(f"  HTTP {code}: {count} requests")

Example output:

Unique hosts contacted : 8
Total data transferred : 1,842.3 KB
Average response time  : 214.7 ms
Slowest endpoint       : https://api.example.com/v1/report/generate

Status code distribution:
  HTTP 200: 98 requests
  HTTP 304: 21 requests
  HTTP 401: 12 requests
  HTTP 500: 3 requests

---

Export to a pandas DataFrame

from fiddler_toolkit import SazSession

session = SazSession.load("capture.saz")

# Requires: pip install "fiddler-toolkit[full]"
df = session.to_dataframe()

print(df.head())

# Find the slowest requests
slow_requests = df.nlargest(5, "elapsed_ms")[["method", "url", "status_code", "elapsed_ms"]]
print(slow_requests.to_string(index=False))

---

Automate Fiddler Process on Windows

from fiddler_toolkit.automation import FiddlerProcess

# Launch Fiddler with a specific port and capture filter
fiddler = FiddlerProcess(
    executable_path=r"C:\Program Files\Fiddler\Fiddler.exe",
    listen_port=8888,
    capture_filter="PROCESS==myapp.exe"
)

with fiddler.running():
    print("Fiddler is capturing traffic...")
    # Run your application workflow here
    import time
    time.sleep(30)

# After the context exits, Fiddler stops and saves the session
fiddler.save_session("automated_capture.saz")
print("Session saved.")

---

Replay Captured Requests

from fiddler_toolkit import SazSession
from fiddler_toolkit.replay import SessionReplayer

session = SazSession.load("capture.saz")

# Replay all POST requests against a staging environment
replayer = SessionReplayer(
    base_url="https://staging.example.com",
    filter_method="POST"
)

results = replayer.replay(session)

for result in results:
    match = "✓" if result.status_code == result.original_status_code else "✗"
    print(f"[{match}] {result.url} — original: {result.original_status_code}, replayed: {result.status_code}")

---

Project Structure

fiddler-toolkit/
├── fiddler_toolkit/
│   ├── __init__.py
│   ├── session.py          # SazSession and Exchange models
│   ├── filters.py          # Filtering helpers
│   ├── exporters.py        # CSV, JSON, HAR exporters
│   ├── analysis.py         # SessionAnalyzer
│   ├── replay.py           # SessionReplayer
│   └── automation.py       # FiddlerProcess (Windows)
├── tests/
│   ├── test_session.py
│   ├── test_filters.py
│   └── test_exporters.py
├── examples/
│   └── basic_analysis.py
├── pyproject.toml
└── README.md

---

Contributing

Contributions are welcome and appreciated. Please follow these steps:

1. Fork the repository and create a feature branch:

   git checkout -b feature/your-feature-name

2. Write tests for any new functionality under tests/.

3. Run the test suite before submitting:

   pytest tests/ --cov=fiddler_toolkit

4. Format your code with Black:

   black fiddler_toolkit/

5. Open a Pull Request with a clear description of your changes.

Please read CONTRIBUTING.md for full guidelines, including our code of conduct.

---

Changelog

See CHANGELOG.md for a full list of changes between versions.

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

This toolkit is an independent open-source project and is not affiliated with, endorsed by, or officially connected to Telerik (Progress Software), the developers of Fiddler.

---

Built for developers who work with HTTP traffic analysis, QA automation, and network debugging workflows on Windows.