How it works
PragmaChange compares a request's recent context with behavior learned from representative data. The decision runs inside Nginx.
Separate parts, different jobs
| Part | What it does |
|---|---|
| Management stack | Defines endpoints and pipelines, imports datasets, trains models, tests them, and exports release archives. |
| Nginx module | Loads a release and evaluates matching requests locally. It needs no database, Python, or network call to the management stack per request. |
The optional application behavior service has its own database and learns named action sequences from application-supplied events. It does not merge Nginx histories across hosts.
The management stack includes a Next.js admin portal, a Rust API, PostgreSQL, artifact storage, and a Python trainer. The public website you are reading is a separate static project.
From request to decision
- Match an endpoint. Nginx applies the module only to locations where you enable it; the release matches a configured host, method, and path.
- Extract fields. The runtime reads only the request values configured by the pipeline, such as a header, path parameter, query value, JSON scalar, or client IP.
- Find a history. A partition key keeps one client's or account's recent requests separate from another's on that endpoint.
- Build features. Time windows become numeric measurements such as count, rate, mean amount, or distinct values. Current request values and body size can also be features.
- Score and act. A validated Isolation Forest scores the ordered numeric vector. Release thresholds map that score to
allow,check, orblock.
New requests update the partition history once before features are evaluated. Even a blocked request contributes to later history.
What a release contains
A release archives selected pipelines, routes, forests, and thresholds. Nginx loads it on configuration start or reload. Model data stays read-only in workers; recent request history lives in a bounded shared-memory zone within that Nginx instance.
Exporting a release does not place it on a server. Use the manual installer or review a deployment through Servers. Both validate before activation; model updates reload Nginx. The portal can verify the loaded release and manage rollback. Native upgrades require a reviewed restart.
A score is a signal
Isolation Forest looks for vectors that are easier to separate from the training distribution. A higher PragmaChange score means a stronger anomaly under this model. It does not tell you the probability of an attack or identify the cause. Threshold suggestions from unlabeled data are starting points, not proof of security efficacy.
During warm-up, missing fields, or capacity problems, the runtime may return check without a score. See decisions and thresholds.
One endpoint at a time
New pipelines select one endpoint. Different operations can have very different normal rates or values, even if they share a client identifier. Pooling them into one baseline can hide endpoint-specific anomalies. Older saved endpoint groups remain compatible with the current runtime, but they are not offered for new pipeline creation.