TimeSide — Timing-Analysis Research Toolkit (Authorized Use Only)

Legal & Ethical Notice
This repository is provided exclusively for authorized security research, lab instruction, and red-team exercises conducted with written permission. Do not use it against TimeSidegram or any other third-party service without formal authorization. Misuse may violate laws and terms of service. The authors and maintainers accept no liability for misuse.

---

Purpose

timeside.py is a research-grade toolkit for studying timing side channels in web authentication flows.
It is designed for:

• Penetration testers performing contractually authorized security audits.
• Academic researchers teaching/demonstrating side-channel theory.
• Red teams simulating adversarial behavior in controlled client environments.

The tool is not for unsanctioned password attacks. Default endpoints must be overridden to lab services or explicit client-owned systems.

---

GDPR & Data Protection by Design (DPbD)

This project is written with privacy-first principles in mind:

• No personal data processing is required. Always use synthetic credentials or pre-agreed test accounts.
• All exports (JSON/CSV) are strictly technical telemetry (latency values, statistical aggregates, run parameters).
• Clients’ real user data must never be included. Ensure anonymization and data minimization in reports.
• All experiments should be logged, documented, and reproducible to meet auditability obligations under GDPR Art. 30 (records of processing activities).
• Use of this toolkit must be embedded in a contractual Data Processing Agreement (DPA) and scoped explicitly to avoid unintended data collection.

---

Scope of Work (Authorized Use Template)

When deploying this toolkit in a client engagement, scope should explicitly state:

• System under test (SUT): e.g., auth-test.example.com (lab environment).
• Test credentials: non-production demo accounts with no personal data.
• Duration: e.g., “Testing permitted between 01–07 September 2025.”
• Objectives: validate resilience to timing attacks; confirm mitigation measures (constant-time comparisons, uniform delays).
• Data handling: all telemetry is retained by the client; consultant deletes local copies after final report delivery.

This makes responsibilities transparent and protects both tester and client.

---

Responsible Use & Research Ethics

1. Authorization First – Never test third-party systems without explicit written approval.
2. Minimization – Collect only the telemetry required to demonstrate timing differences.
3. Non-disclosure of secrets – If accidental access to real secrets occurs, halt immediately and follow the client’s disclosure policy.
4. Disclosure protocol – For discovered vulnerabilities, use coordinated disclosure with the vendor or client.
5. Teaching use – Always run against mock servers or client-approved replicas, never against live production.

---

Auditability & Compliance

To support professional accountability:

• Deterministic exports (JSON + CSV) enable independent verification.
• Configuration snapshots ensure reproducibility of every experiment.
• GUI summaries and logs can be attached to client reports.
• Resume files document partial progress transparently, avoiding data gaps.

These features help demonstrate compliance with ISO 27001, GDPR Art. 25 (privacy by design), and SOC 2 trust principles.

---

Why timing side channels matter (theory in brief)

A timing side-channel exists when a system’s response time varies in a way that correlates with secret-dependent computation. For example, if a server compares user-provided credentials character-by-character and returns earlier for mismatches, a client can infer information (e.g., password length or next character) by carefully measuring round-trip time over repeated trials. In noisy, real networks, the effect is subtle; rigorous experiments require: (1) baseline characterization, (2) careful randomization and jitter control, (3) robust statistics (trimmed means, IQR filtering), and (4) resilience to retries, throttling, and transport anomalies.

---

How the program works (architecture & flow)

timeside.py orchestrates a multi-stage experiment loop:

1. Session setup & hygiene. A hardened requests.Session is configured with retries, connection pooling, realistic headers, optional proxy/Tor routing, and SSL verification toggles.

2. Baseline timing. The tool first measures a baseline using deliberately incorrect passwords to capture ambient network/service latency distribution.

3. Length inference (exploratory). It probes a range of candidate lengths with random strings, looking for systematic shifts in mean latency.

4. Dictionary-first strategy (optional). If a wordlist is provided, candidate passwords are tested first, with progress reporting and pacing controls.

5. Character-by-character timing analysis. Each character position is probed with an alphabet, using trimmed means + IQR filtering to identify top candidates.

6. Persistence, resume & exports. Intermediate state, results, and histories are saved to JSON/CSV, resumable between runs, with GUI summaries.

   

---

TimeSide

Tested with Python 3.9+ on Windows 11. Create a virtual environment and timeside dependencies:

# Linux
python -m venv .timeside
.timeside/bin/activate   
pip3 install -r requirements.txt --force
python3 timeside.py    # CLI

# Windows:
python -m venv .timeside
.timeside\Scripts\activate
pip3 install -r requirements.txt --force
python.exe timeside.py --gui

OS notes for the GUI

• Windows/macOS: PyQt5 wheels typically timeside without additional packages.
• Linux: Some distros require system Qt libraries (e.g., qtbase5-dev).

---

Safe “Lab Mode” (strongly recommended)

A demo Flask server is provided in the README for testing timing vulnerabilities locally. Always point the tool at localhost or lab-controlled environments using:

NOT!    INSTA_LOGIN_URL="http://instagram.com:443/accounts/login/ajax/" python timeside.py --username alice --tests-per-char 4 --debug

DO!    INSTA_LOGIN_URL="http://127.0.0.1:8080/accounts/login/ajax/" python timeside.py --username alice --tests-per-char 4 --debug

---

CLI and GUI entry points

• CLI (default): python timeside.py with flags for username, tests, delays, proxies, output, and resume.
• GUI: python timeside.py --gui starts a PyQt5 interface with Setup, Progress, Results, and Config tabs.

---

Configuration reference

• Endpoint: INSTA_LOGIN_URL (default must be overridden).
• Pacing: --tests-per-char, --delay-min, --delay-max.
• Search space: INSTA_CHAR_SET, INSTA_MIN/MAX_PASSWORD_LENGTH.
• Wordlist: INSTA_WORDLIST_FILE.
• Proxies: --use-proxies, INSTA_USE_TOR.
• Persistence: INSTA_RESULTS_FILE, INSTA_CSV_FILE, INSTA_RESUME_FILE.

---

Interpreting results

• JSON summary with configuration, stats, and summaries.

• CSV output with per-password aggregates.

• GUI visualization for structured progress and summaries.

  

Interpret results statistically; do not rely on single measurements.

---

Robust statistics inside the loop

• Trimmed means and IQR filtering reduce variance.
• Confidence derived from separation between top-ranked candidates.

---

Limitations & pitfalls

• Network noise dominates small effects.
• Server mitigations (constant-time compare, uniform delays) may block inference.
• Unauthorized use may be unlawful.

---

GUI overview

PyQt5 GUI includes: Setup, Progress, Results, Config, and an abort/resume feature.

---

Reproducibility tips

• Isolate your testbed.
• Run against mock servers for teaching.
• Perform multiple independent trials.

---

Responsible disclosure

If vulnerabilities are found in authorized testing, use coordinated disclosure with sufficient remediation time.

---

License

For research and educational use. GNU GENERAL PUBLIC LICENSE Version 3, 29 June 2007, please read the LICENSE.