Overview

Proofant helps you safely simulate abusive traffic (credential stuffing, scraping, brute force, etc.) and prove defenses with goals and artifacts. It includes a visual UI console to design scenarios, generate plans, run them, and review results without hand‑editing JSON everywhere.

The console provides panels for Scenarios, Profiles, Plans, and Credentials, plus an Actions & Output drawer (status, artifacts, quick metrics, summary). Use Run, Save, and open the drawer while a run is active.

Quickstart

1) Start the console

python webui.py
# Open: http://127.0.0.1:8008/

Serves the UI locally (dev/VPN). Artifacts go under results/.

2) Create a scenario

Click Scenarios → “+” → name it demo.json.
Fill in Target & Auth, set Flow, add Success criteria.
Link Profiles for traffic mix (optional).

3) Generate a plan

Open Plans → Generate from Scenario.
Set width/limits (RPS, duration, concurrency).
Click Generate plan from scenario, then Save.

4) Run & review

Click Run. Open the Actions & Output drawer.
Review Quick Metrics and artifacts (CSV/JSON/JUnit).
Use Stop to halt an active run (see “Run, Stop & Schedule”).

Test App (Demo)

The repo ships with a tiny demo web app to exercise scenarios end‑to‑end. It implements a CSRF’d login flow with /login, /account, and /logout.

Run the Test App

# from the repo root
pip install fastapi uvicorn

# default demo creds (optional)
export PROOFANT_DEMO_USER=demo
export PROOFANT_DEMO_PASS=demo

# start the app (port 9001)
uvicorn app:app --reload --port 9001
# Visit: http://127.0.0.1:9001/login

Point a Scenario at it

Set Target URL to http://127.0.0.1:9001.
Use Flow steps with relative URLs (/login, /account, /logout).
Enable CSRF extraction if needed (the console exposes a toggle and token field).

The included flow template in the console mirrors this Test App.

Run the UI Console

The console lives at http://127.0.0.1:8008/ (served by webui.py). It manages files under scenarios/, profiles/, credentials/, plans/ and writes run artifacts under results/.

A built‑in UI makes complex scenarios and multi‑variant plans easy to manage.

CLI Workflow

Use the CLI for quick local runs and CI. Example:

# initialize a project
proofant init

# run a simulation against staging
proofant run --target https://staging.example.com --scenario signup-fraud --rps 120 --duration 5m

# create a report
proofant report --format html --out reports/sprint-27.html

# gate a deployment (CI)
proofant score --min 85

Scenarios

Flow (GET/POST/etc. with templating, CSRF fetch, extract, save).
Success criteria drive pass/fail.
Profiles supply headers, proxies, behavior, credentials.

Profiles

Profiles define traffic mix and behavior (headers, proxies, think time, false starts).

Plans

Plans expand a scenario into N variants (width) with RPS/duration/concurrency limits.

Run, Stop & Schedule

Run a plan or scenario from the console header.
Stop halts the current run. UI aborts the request and the backend sets a stop event.
Schedule recurring runs via the plan header. Stop schedules individually or all at once.

Artifacts & Reports

events.csv — event stream
summary.json — metrics and goals
junit.xml — CI‑friendly pass/fail

Agentic Orchestrator (MVP)

The agent coordinates the lifecycle deterministically today, with room for adaptive strategies later:

Propose a plan from a scenario (POST /api/agent/plan).
Run the plan variant‑by‑variant with limits and a cooperative stop_event (/api/agent/run + /api/agent/stop_run).
Evaluate goals and produce pass/fail + artifacts.

HTTP API (selected)

Scenarios

GET    /api/scenarios
GET    /api/scenarios/<file>
POST   /api/scenarios                  # {filename, from_template?}
PUT    /api/scenarios/<file>           # {dir:"scenarios", scenario:{}}
DELETE /api/scenarios/<file>

Plans & Agent

POST   /api/agent/plan                 # propose plan from scenario
POST   /api/agent/run                  # run plan (variants, limits)
POST   /api/agent/stop_run             # stop active plan run
GET    /api/agent/status               # running flags, schedules
POST   /api/agent/schedule             # every_seconds
POST   /api/agent/stop                 # stop schedule by id
POST   /api/agent/stop_all             # stop all schedules

Project Layout

scenarios/     # scenario JSON
profiles/      # profile JSON
credentials/   # credentials (txt/csv)
plans/         # saved plan JSON
results/       # run artifacts (csv/json/junit)
webui.py       # local UI console
app.py         # demo Test App (FastAPI)

Troubleshooting

Stop didn’t feel immediate? UI aborts fetch; backend sets a stop event. If a request is mid‑flight, it completes then stops. Check /api/agent/status.
403 on demo login? CSRF mismatch. Ensure the token is passed (form field or header) and the cookie is set by the Test App.
Nothing runs? Verify your scenario has at least one profile and credentials.