Metadata-Version: 2.4
Name: fenestra
Version: 0.0.1
Summary: Race-condition research harness for web applications, APIs, and modern services.
License: MIT
Keywords: fuzzing,pentesting,race-condition,security
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# invariant

> Race-condition research harness for web applications, APIs, and modern services.

`invariant` is built for pentesters and security researchers who need more than "fire parallel requests and diff responses." You declare what must remain true about a system under concurrency. The harness proves whether it does — statistically, repeatably, with a confidence interval and an estimated window width in milliseconds.

---

## The problem with existing tools

Every race-condition tool stops at delivery. They fire requests, show you diffs, and leave the rest to you. That's fine for a quick sanity check. It's not enough to distinguish a flaky single win from a reliably exploitable condition, and it tells you nothing about *where* in the stack the window lives.

`invariant` closes that gap with three things existing tools don't have:

1. **An invariant language** — express what must be true: scalar comparisons, aggregations (`sum`, `count`, `min`, `max`), uniqueness, monotonicity, and cross-trial conservation laws.
2. **A localization probe** — before the main race, a short probe measures baseline latency, inspects response headers, fires a small burst, and samples post-race state at increasing delays to rank hypotheses about which layer the window actually lives in.
3. **Rigorous trial accounting** — every trial runs setup, delivery, settlement, state reads, invariant evaluation, and teardown. Findings report trial count, violation rate, confidence interval, and estimated window width.

---

## How it works

You import an endpoint from a curl command or HAR capture, label its endpoint class (auth, financial, coupon, inventory, rate-limit, etc.) and its suspected sub-state layer (DB row, app counter, Redis, queue, CDN, session store), then declare one or more invariants that must remain true under concurrency.

Templates are YAML, designed as a superset of Nuclei and RatRace formats so existing templates import cleanly.

The invariant language supports scalar comparisons, aggregations, uniqueness, monotonicity, and cross-trial conservation laws — the layer where every existing tool stops short.

The harness runs a localization probe first to rank hypotheses about which layer the race window lives in, then executes the main race through a pluggable delivery backend, repeating the full trial cycle many times. Output is structured JSON for automation plus a human-readable report that summarizes each violated invariant, its statistical support, the localization hypothesis, and the reasoning trail.

---

## What invariant does not do

- **No endpoint discovery** — you bring the target, scoped and authorized.
- **No low-level packet reimplementation** — delivery is handled by pluggable backends.
- **No exploit weaponization** — `invariant` proves and measures. Weaponization and scoping are the operator's responsibility.

This tool is intended for authorized security testing, penetration testing engagements, bug bounty research, and CTF competitions.

---

## Status

Under active development. Not yet released.

---

## License

MIT
