[REVIEW] api-security: add cursor pagination tenant-boundary and snapshot consistency gates

[andycana]

Skill Being Reviewed

Skill name: api-security
Skill path: skills/appsec/api-security/

False Positive Analysis

Benign code that could be over-flagged by the current pagination guidance:

@app.route("/api/v1/transactions")
@require_auth
def list_transactions():
    cursor = request.args.get("cursor")
    claims = verify_cursor(cursor, audience="transactions:list") if cursor else None
    page_size = 50

    if claims and claims["tenant_id"] != current_user.tenant_id:
        abort(403)

    rows = (
        Transaction.query
        .filter(Transaction.tenant_id == current_user.tenant_id)
        .filter(Transaction.created_at < claims["last_seen_at"] if claims else True)
        .order_by(Transaction.created_at.desc(), Transaction.id.desc())
        .limit(page_size + 1)
        .all()
    )

    return jsonify({
        "items": [row.to_dict() for row in rows[:page_size]],
        "next_cursor": sign_cursor({
            "tenant_id": current_user.tenant_id,
            "last_seen_at": rows[-1].created_at.isoformat(),
            "last_id": rows[-1].id,
            "aud": "transactions:list",
            "exp": int(time.time()) + 900,
        }) if len(rows) > page_size else None,
    })

Why this is a false positive:

The existing API4 guidance says to enforce a maximum pagination size, which is correct for limit-based pagination. A reviewer can still over-report an endpoint as missing a client-visible max limit when it intentionally uses server-fixed cursor pagination. The safe property is not that the client can see a numeric limit. The safe property is that page size is enforced server-side and the cursor is opaque, signed, tenant-bound, audience-bound, expiry-bound, and tied to a stable sort key.

Coverage Gaps

Missed variant 1: client-controlled cursor payload changes tenant or filter scope

@app.route("/api/v1/accounts")
@require_auth
def list_accounts():
    cursor = json.loads(base64.urlsafe_b64decode(request.args["cursor"]))
    tenant_id = cursor.get("tenant_id", current_user.tenant_id)
    after_id = cursor.get("after_id")

    return jsonify([
        a.to_dict()
        for a in Account.query
            .filter(Account.tenant_id == tenant_id)
            .filter(Account.id > after_id)
            .order_by(Account.id.asc())
            .limit(100)
            .all()
    ])

Why it should be caught:

This is both API1/BOLA and API4 resource-control risk. The endpoint has a numeric limit, so the current API4 checklist can pass it, but the cursor is user-controlled authorization state. A user can alter tenant_id, after_id, sort, or filter fields inside the cursor and traverse data outside the intended relationship boundary. The skill should require evidence that cursors are generated by the server, integrity-protected, and revalidated against the authenticated principal on every request.

Missed variant 2: unstable cursor ordering causes duplicates, skips, and scan amplification

app.get("/api/v1/audit-events", requireAuth, async (req, res) => {
  const cursor = JSON.parse(Buffer.from(req.query.cursor || "{}", "base64url"));
  const rows = await db.auditEvents.findMany({
    where: {
      tenantId: req.user.tenantId,
      createdAt: { lt: cursor.createdAt || new Date() }
    },
    orderBy: { createdAt: "desc" },
    take: 100
  });

  res.json({
    items: rows,
    next_cursor: Buffer.from(JSON.stringify({
      createdAt: rows.at(-1)?.createdAt
    })).toString("base64url")
  });
});

Why it should be caught:

The page size is capped, but the cursor is not tied to a unique stable sort tuple such as (created_at, id), and it is not bound to a consistent snapshot. Concurrent inserts with identical timestamps can create duplicate or skipped records. Attackers can replay or manipulate cursors to force repeated expensive scans, enumerate event density, or bypass completeness assumptions in audit/export workflows. The current checklist covers maximum page size, but not cursor stability, replay, expiry, or snapshot-consistency evidence.

Edge Cases

• Opaque cursors that are encrypted but not authenticated can still be malleable depending on the mode and implementation.
• Signed cursors can still be unsafe if they omit tenant ID, user ID, query shape, sort order, audience, expiry, or page-size policy version.
• Cursor reuse across endpoints can leak data if a cursor issued for a low-sensitivity list endpoint is accepted by a high-sensitivity endpoint.
• Admin or support endpoints need explicit actor-scope fields because tenant_id == current_user.tenant_id is not sufficient for delegated access.
• GraphQL Relay-style cursors need the same integrity and scope checks; base64 encoding a database ID is not an authorization boundary.

Remediation Quality

• Fix resolves the vulnerability
• Fix doesn't introduce new security issues
• Fix doesn't break functionality
• Issues found: The skill should add a dedicated cursor-pagination gate instead of only adding "use signed cursors" as a short recommendation. Reviewers need to verify server-fixed page size, stable sort tuple, principal and tenant binding, query-shape binding, audience binding, expiry, replay tolerance, and snapshot or high-watermark behavior.

Recommended gates:

1. API-CURSOR-01: Cursor integrity and scope gate. Require cursors to be server-issued, integrity-protected, tenant/principal-bound, audience-bound to one endpoint/query shape, expiry-bound, and revalidated against current authorization on every request.
2. API-CURSOR-02: Stable ordering and snapshot gate. Require a deterministic unique sort tuple and document whether the list is snapshot-consistent, high-watermark based, or explicitly eventually consistent.
3. API-CURSOR-03: Replay and cost-control gate. Require fixed server-side page size, bounded cursor lifetime, safe behavior for replayed/stale cursors, and monitoring for repeated cursor scans or query-shape abuse.

Comparison to Other Tools

Tool	Catches this?	Notes
Semgrep	Partial	Custom rules can catch obvious base64/JSON cursor trust or missing signature helpers, but they usually cannot prove tenant binding or stable snapshot semantics without project-specific knowledge.
CodeQL	Partial	Dataflow can detect user-controlled cursor fields reaching queries, but query-shape binding, cursor audience, and snapshot semantics usually need manual review.
DAST/ZAP	No/Partial	DAST may detect tampered cursor responses if test users and datasets are configured, but it rarely proves stable ordering or replay/cost behavior.

Overall Assessment

Strengths:

The api-security skill gives a strong OWASP API Top 10 structure. It correctly covers BOLA, GraphQL authorization, list endpoint filtering, and maximum pagination size.

Needs improvement:

The current guidance treats pagination mostly as a resource-consumption limit. Cursor pagination also carries authorization and consistency state. A capped page size is not enough when the cursor itself can alter tenant scope, query filters, sorting, or scan position.

Priority recommendations:

1. Add cursor-specific evidence gates under API1 and API4.
2. Add examples showing a safe signed, tenant-bound cursor and an unsafe decoded cursor trusted as query state.
3. Add checklist items for stable sort tuples, cursor expiry, endpoint audience, replay behavior, and snapshot/high-watermark semantics.

Bounty Info

• I have read and agree to the CONTRIBUTING.md bounty terms
• Preferred payment method: Crypto

[JamesJi79]

/attempt #2254

[JamesJi79]

/attempt #2254

[JamesJi79]

/attempt #2254

VALID GAP — api-security: cursor pagination tenant-boundary and snapshot consistency gates

Why Valid (FP confirmed)

The issue correctly identifies a false positive pattern in the current api-security pagination guidance. The existing API4 checklist requires a maximum pagination size, which is appropriate for limit-based pagination, but server-fixed cursor pagination with opaque signed cursors should not be flagged for lacking a client-readable numeric limit. The benign code demonstrates proper cursor-based pagination: server-enforced fixed page size (50), signed cursor with HMAC, tenant-bound cursor payload with per-request revalidation, audience-bound to the endpoint, expiry-bound to 900 seconds, and tied to a stable sort key (created_at DESC, id DESC). The current API4 guidance would over-flag this endpoint as missing pagination limits, when cursor-based design provides stronger authorization and consistency guarantees.

Coverage Gaps

Gap 1 — Client-controlled cursor payload alters tenant or filter scope — The skill checks max page size and basic pagination structure but not cursor integrity. An attacker can submit a base64-decoded cursor with modified tenant_id or after_id to traverse data outside authorization boundaries. The skill must require evidence cursors are server-issued, cryptographically signed, and revalidated per-request. Need gate: Cursor integrity and scope validation.

Gap 2 — Unstable cursor ordering causes duplicates, skips, and scan amplification — Cursors based on createdAt alone without a tiebreaker produce duplicate/skipped records on concurrent writes. Attackers replay unstable cursors for expensive scans or bypass audit completeness. Need gate: Stable unique sort tuple with snapshot or high-watermark semantics.

Gap 3 — Missing cursor replay, audience, and cross-endpoint reuse protection — Cursors without endpoint audience binding or replay detection allow rewinding/scanning the same page or cross-endpoint data leakage. Need gate: Bounded expiry, endpoint audience, and replay tolerance.

Suggested Gates

1. API-CURSOR-01: Cursor integrity and scope gate — Require server-issued cryptographic integrity (HMAC/private-key signature). Cursor payload must include tenant/principal ID, endpoint audience, and bounded expiry. Revalidate all claims per-request. Evidence: cursor generation code, signature verification, per-request revalidation.

2. API-CURSOR-02: Stable ordering and snapshot gate — Require deterministic unique sort tuple (created_at DESC, id DESC), not a column with duplicates. Document snapshot-consistent or high-watermark semantics. Evidence: sort query with tiebreaker, test showing no duplicates on concurrent writes.

3. API-CURSOR-03: Replay and cost-control gate — Require server-enforced fixed page size, bounded cursor lifetime (<=15 min), safe stale/replayed cursor behavior (empty page or error), optional replay monitoring. Evidence: expiry validation, cursor nonce/snapshot ID, server-enforced page size.

[Errordog2]

Implemented this review as PR #2271: #2271

Summary of the fix:

• Adds cursor/list pattern discovery to api-security inventory.
• Adds a Cursor and Pagination Evidence output table.
• Adds API1/BOLA cursor integrity and tenant/principal binding guidance with vulnerable and secure examples.
• Adds API4 stable sort, snapshot/high-watermark, replay, expiry, and repeated-scan guidance.
• Bumps api-security to v1.0.1.

Validation performed:

• git diff --check
• Frontmatter required-field check over skills/ and roles/
• index.yaml path existence check
• Workflow-equivalent prompt-injection pattern scan
• Targeted rg checks for the new cursor pagination sections and v1.0.1

[JamesJi79]

#2254

VALID GAP - api-security: add cursor pagination tenant-boundary and snapshot consistency gates

Why Valid (FP confirmed)

The false positive scenario is correctly drawn: an endpoint using server-enforced cursor pagination with opaque, signed, tenant-bound, audience-bound, expiry-bound cursors and stable sort keys should not be flagged for missing a client-visible max limit. The current API4 pagination guidance focuses on numeric query-parameter limits and does not have evidence gates for cursor-based pagination properties -- signature validation, tenant binding, audience scoping, expiry, or stable ordering. Reviewers applying the generic limit check will over-report well-designed cursor pagination as if it were simple offset/limit pagination.

Coverage Gaps

Gap 1 - Unsigned client-visible cursor payloads allow tenant/filter tampering - The missed variant 1 shows a cursor decoded from base64 JSON and used directly for tenant_id filtering. Even with a numeric page-size limit, any user can alter tenant_id, after_id, or filter fields inside the cursor and traverse data outside their authorization boundary. This is both API1/BOLA and API4 resource-control risk. The skill must require cursor integrity (HMAC/JWS) and server-side revalidation of principal-to-tenant binding. Need gate: Cursor integrity and tenant revalidation evidence.

Gap 2 - Unstable sort keys cause duplicates and skips across pages - If a cursor pagination endpoint uses a non-stable sort key (e.g., created_at without a tiebreaker like id), newly inserted or updated rows can appear in multiple pages or be skipped entirely. The current skill checks page-size limits but has no gate for sort-key stability. Need gate: Stable sort key verification evidence.

Gap 3 - Snapshot consistency not required for cursor rotations - When the back-end dataset changes between cursor generation and cursor consumption (e.g., rows inserted, deleted, or re-indexed), the client may see inconsistent state -- phantom rows or missing results. The skill does not require evidence of snapshot isolation, repeatable reads, or a materialized view for the pagination query. Need gate: Snapshot consistency evidence for cursor lifespan.

Suggested Gates

1. API-CP-01: Cursor integrity verification - Evidence that each cursor is server-signed (HMAC/JWS) with tenant_id, audience, and expiry embedded. Must also show that the server revalidates the principal-to-tenant binding on every request regardless of cursor contents.

2. API-CP-02: Stable sort key verification - Evidence that the sort key includes a unique tiebreaker (e.g., .order_by(Transaction.created_at.desc(), Transaction.id.desc())) and that no two distinct rows share the same sort key value. Acceptable evidence includes table DDL showing the unique constraint or index.

3. API-CP-03: Snapshot consistency assessment - For cursors with lifespans exceeding 30 seconds, evidence that the query runs with snapshot isolation, repeatable read, or against a read replica with consistent state. The evidence must document the isolation level or the materialized view refresh policy.

[JamesJi79]

/attempt #2254

[JamesJi79]

/attempt #2254

VALID GAP - api-security: cursor pagination tenant-boundary

Why Valid (FP confirmed)

The false positive is valid: an endpoint using server-generated, opaque, signed, tenant-bound, expiry-bound cursor pagination with fixed server-side page size is not missing a max-limit control. The current API4 guidance enforces a max pagination size which is correct for limit-based pagination but does not properly evaluate cursor-based pagination safety. A reviewer could over-report an endpoint as missing a client-visible max limit.

Coverage Gaps

Gap 1 - Client-controlled cursor payload changes tenant or filter scope -- If the cursor is a base64-decoded JSON blob where the user controls tenant_id or after_id, the endpoint passes limit checks but allows BOLA traversal. Need gate: evidence that cursors are server-generated, signed, integrity-protected, and revalidated on every request.

Gap 2 - Unstable cursor ordering causes duplicates, skips, or data races -- Cursors using created_at without a tiebreaker column (e.g., id) can miss or duplicate rows when multiple entries share the same timestamp. Need gate: stable sort key (compound key) verification.

Gap 3 - Missing cursor expiry leads to replay across tenant/data states -- A long-lived cursor that was valid at creation may become invalid after tenant data changes, leading to stale or incorrect results. Need gate: short TTL on cursor with aud claim validation.

Suggested Gates

1. API-CURSOR-01: Server-generated cursor enforcement. Evidence: cursor is signed, tenant-bound, and revalidated against the authenticated principal on each request.
2. API-CURSOR-02: Stable sort key verification. Evidence: compound sort key (created_at + id or equivalent) prevents gaps and duplicates.
3. API-CURSOR-03: Cursor expiry and scope binding. Evidence: short TTL, audience claim, and tenant claim validated on every paginated response.