API Invariants for Anomaly Detection

• The paper introduces a schema-level approach using API invariants synthesized via LLM prompts to accurately detect anomalies in transactional web systems.
• It details a comprehensive method to transform API signatures into enhanced schemas, enabling effective constraint mining across API, database, and environment data.
• Empirical evaluations demonstrate superior precision and recall, validating the efficacy of invariant-based anomaly detection in diverse web applications.

API invariants for anomaly detection constitute a schema-level formalism where predicates over tuples from web API logs, relational database tables, and session/environment records are used to define normality boundaries in transactional web applications. Rather than relying on raw log data, this approach infers database and session constraints that must be satisfied by every API invocation in routine (non-anomalous) workflows. The MINES system operationalizes this concept by synthesizing explainable invariants via LLM prompts, schema augmentation, and data-driven filtering. These invariants underpin anomaly detection, providing both precision and generalizability across diverse web application platforms (Zhang et al., 7 Dec 2025).

1. Formal Notion of API Invariants

An API invariant is expressed as a Boolean predicate over attributes of a relational join among entity types, including API calls, database tables, and environment objects. Let $E_1, ..., E_k$ be entity types, each specified by an attribute set $A_i$. For a join $J = E_1 \bowtie ... \bowtie E_k$ reflecting inter-table relationships—such as foreign-key matches or session-ID correspondences—a candidate invariant $I$ is valid iff $\forall t \in J_{normal}, I(t) = \mathrm{true}$. At runtime, violation $I(t) = \mathrm{false}$ denotes an anomaly.

A canonical example is a referential API–DB invariant:

$$\forall x \in T_{api}, y \in T_{db} \;.\; (x.a_{api} = y.a_{db}) \Rightarrow (y.\text{status} = \text{"paid"})$$

This formulation distinguishes tuples conforming to normal execution (predicate is satisfied) from anomalies (predicate violation).

2. Transformation of API Signatures into Enhanced Schemas

MINES processes inputs from Java-based web applications: API signatures (endpoint identifiers and argument/return types), database schemas, and environment/session data. Each API signature is parsed into a hierarchical field tree (JSON-like), which is then flattened to a normalized set of scalar attributes, typically to depth $d=2$–$3$. For every API endpoint, a new entity type $E_{api}$ is created, with fields corresponding to the flattened parameter/result set (e.g., arguments.orderId, arguments.userId, response.success, time, sessionId). An Env entity augments the schema with session-related attributes (e.g., sessionId→userId, roles, IP addresses). The enhanced schema is the union of the original database tables, these API-derived entities, and the environment entity.

The output is an augmented ER diagram where APIs function as first-class tables, systematically linking transactional traces to persisting states for constraint inference.

3. Schema-Level Constraint Mining via MINES

MINES operates in two distinct schema-based mining phases:

Stage I: Relationship Inference

Using LLM prompt engineering, MINES seeks candidate join keys between API, DB, and environment entity pairs. Prompts communicate an API schema alongside a target table; outputs specify key correspondences (e.g., orderId in API to id in DB). Heuristics filter these candidate relationships:

• Overlap ratio $P_{overlap}$ discards low-frequency API–DB links.
• Sequence-modeling (HMM) limits API–API relationships by conditional probability thresholds.
• API–Env links must be universally observable in session data.

Stage II: Invariant Inference

For each valid entity pair, MINES performs a left outer join and prompts the LLM to produce invariants spanning:

• Common-sense checks (e.g., price > 0)
• Format constraints (regex patterns on emails)
• Referential integrity (e.g., foreign-key matching)
• Environment consistency (user/session matching)
• Cross-API equivalence (returned data consistency).

Candidate invariants are then filtered: only those always satisfied by normal logs are retained ($\sum_{t\in Normal} 1[c(t)=False] = 0$). Counterexamples trigger up to three rounds of LLM prompt-based refinement.

4. Generation of Executable Python Constraints

Accepted invariants are transcribed into Python functions, each operating on joined row tuples representing API, DB, and environment entities. The generated code includes sequential assertion checks:

@invariant("cancelOrder→orders") def inv_cancelOrders(api_row, order_row, env_row): assert api_row["orderId"] == order_row["id"], "FK violation" assert order_row["status"] == "paid", "Refunding unpaid order" assert api_row["userId"] == env_row["userId"], "Session/user mismatch"

The entire suite of invariants is compiled into a batch log checker, executable offline for anomaly analysis.

5. Evaluation Methodology and Empirical Results

MINES is empirically validated using multi-API transactional systems (TrainTicket, NiceFish, Gitea, Mastodon, NextCloud) with injected and manual web-tamper attacks, benchmarked against LogRobust, LogFormer, and WebNorm. All models are assessed via precision, recall, and false positive rate (FPR):

Model	Precision	Recall
LogRobust	0.12	0.65
LogFormer	0.27	0.76
WebNorm	1.00	0.70
MINES	1.00	0.95

On injected attacks, MINES attains recall=1.00; manual attacks yield recall≈0.90. Cost and throughput benchmarks indicate $4\times10^5$ logs/s for Train-Ticket and $2.4\times10^5$ logs/s for NiceFish (LLM training cost <$20 USD). On large, open-source applications, MINES sustains perfect precision and recall ≥0.83; baseline F1 scores drop below 0.6 under domain shift. Ablation reveals that omitting API–DB, API–API, API–Env relationships or binlog history reduces recall by 5–20%; skipping iterative refinement elevates FPR to 89%.

6. Factors Underlying High Recall and Near-Zero False Positives

MINES exploits schema-level reasoning to avert spurious feature learning. The reliance on database and session state yields observability that surpasses superficial log inspection, detecting attacks that appear normal at the instrumentation level but violate core transactional invariants. LLMs assist by proposing semantic constraints; crucially, only invariants repeatedly validated on normal logs are accepted, suppressing overfitting and hallucinated rules. The automated counterexample-driven refinement phase ensures that false positives are eliminated. Compact, schema-only prompts further constrain LLM-generated invariants to relevant features and reduce inference noise and computational expense.

This architecture enables MINES to derive provably correct API invariants using abstract schema and small normal log corpora, achieving both maximal anomaly coverage (recall) and nearly perfect selectivity (precision ≈ 100%) (Zhang et al., 7 Dec 2025).