How Onyx works, end to end.

What is Onyx?

Onyx is an AI-native API penetration-testing platform. You provide a link to any API's documentation, an OpenAPI / Swagger specification, and it autonomously verifies ownership, parses every endpoint, generates schema-aware attack payloads with Google Gemini 2.5 Flash, fires them through a rate-limited distributed queue, and streams severity-scored results back live.

Unlike a generic fuzzer, Onyx reads your actual schema: request bodies, path parameters, query strings, and asks an LLM to reason about what would break each specific endpoint. The result is context-sensitive coverage across the OWASP Top 10 without writing a single test case by hand.

Quick start

Five steps take you from sign-up to a live, scored attack run. Each one is covered in more depth further down.

What you can paste

Every modern API ships a machine-readable spec describing its endpoints, parameters, and response formats, written in OpenAPI (formerly Swagger). Most APIs expose it at a path like /openapi.json, /swagger.json, or /v2/api-docs.

Can't find your spec URL?

If your team uses Swagger UI, the spec is the JSON the UI loads. Open the network tab and look for the .json request, or try appending one of these common paths to your API's base URL:

/openapi.json
/swagger.json
/v2/api-docs
/v3/api-docs
/swagger/v1/swagger.json

Domain ownership verification

Before Onyx fires a single payload, you must prove you own the target domain. Without it, anyone could point Onyx at someone else's API. Verification closes that liability and is required once per domain, per account.

https://your-domain.com/.well-known/onyx-verify.txt

onyx-verify-a3f9c2b1...

What actually happens

Onyx extracts the hostname from your URL, generates a unique onyx-verify-<token>, and stores it against your account. When you click Check Verification, it probes the file over HTTPS first (retrying over HTTP if the connection fails), then falls back to a DNS TXT lookup. Whichever it finds first wins, and the run button unlocks.

Until a domain is verified, every attempt to scan it is rejected before a single request leaves the server:

POST /api/test-runs  ->  403 Forbidden

{
  "error": "DOMAIN_NOT_VERIFIED",
  "domain": "target-api.com",
  "message": "You must verify ownership of
              \"target-api.com\" before scanning it."
}

The attack flow

End to end, from clicking Execute Run to receiving live results:

1. 01

   Parse. The spec is fetched with WAF-bypass headers, then every endpoint, parameter, and request body is extracted.

2. 02

   Generate. Gemini crafts up to 20 schema-aware payloads per endpoint (with a 35-payload static fallback).

3. 03

   Queue. Payloads are added to a BullMQ Redis queue: 5 concurrent workers, 10 jobs/second, 10s timeout each.

4. 04

   Fire. Each worker re-checks SSRF, fires the payload, and records status code, latency, and a response snippet.

5. 05

   Score. Every result is classified with CVSS-inspired severity and folded into an overall 0-100 API security score.

6. 06

   Stream. Results broadcast live to your dashboard over WebSockets as each attack completes.

Run status phases

As a run progresses, its status moves through four phases, and the dashboard reflects each one live:

Attack types generated

Gemini produces strictly-typed JSON payloads across eight categories, each tuned to the endpoint under test:

Live results

HTTP polling is too slow for watching attacks land. Onyx opens an authenticated WebSocket and streams every result the instant a worker records it, and the dashboard's metrics, charts, and endpoint rows update without a refresh.

Each event carries the method, endpoint, payload, status code, latency, and computed severity. A typical ATTACK_RESULT frame looks like this:

{
  "type": "ATTACK_RESULT",
  "data": {
    "method": "POST",
    "endpoint": "/users/login",
    "statusCode": 500,
    "latency": 412,
    "attackType": "SQL_INJECTION",
    "severity": "CRITICAL"
  }
}

CVSS severity scoring

Each result is classified by status code and response content. The overall score starts at 100 and deducts per finding, giving you a single 0-100 number to track.

The final number maps to a label: CLEAN (100), LOW (76-99), MEDIUM (51-75), HIGH (26-50), and CRITICAL (0-25).

Security & resilience

Every run is fenced by layered guards, checked before and during the attack, so Onyx only ever hits the API you own.

Architecture

Onyx is a decoupled pipeline: a React client, a guarded Express API, an AI payload stage, a Redis-backed queue, and a worker pool, with Postgres for persistence and WebSockets for telemetry. Each stage hands off to the next, so a slow target never blocks the UI.

1. 01

   Client. React + Vite on Vercel. Submits the spec URL and subscribes to the run over a WebSocket.

2. 02

   API + guards. Express on Render. Auth, rate-limit, quota, domain gate, and SSRF checks run before anything fires.

3. 03

   Gemini. Generates the payload set per endpoint, with a static fallback if the model is unavailable.

4. 04

   BullMQ + Redis. A job queue fans payloads out to 5 concurrent workers at 10/sec, surviving restarts.

5. 05

   Workers. Fire each payload, score the response by CVSS severity, and persist it.

6. 06

   Postgres + WS. Results are written to Neon Postgres via Prisma and broadcast live to the browser.

Built on React 18, Express 4, Prisma 7 + Neon Postgres, BullMQ 5 + Redis, Google Gemini 2.5 Flash, and Razorpay for billing.

Plans & quotas

Quotas are checked per calendar month before a run is created. Exceeding a limit returns a 429 QUOTA_EXCEEDED with an upgrade link.

Billing runs through Razorpay with webhook-verified plan upgrades, with no manual provisioning. Prices are charged in INR (₹900 / ₹1800 per month).

Frequently asked

Glossary

Plain-English definitions for the terms used throughout these docs.

OpenAPI / Swagger

A machine-readable description of an API's endpoints, parameters, and responses. Onyx's only required input.

SSRF

Server-Side Request Forgery, which tricks a server into calling internal resources. Onyx blocks it via DNS resolution on every URL.

CVSS

Common Vulnerability Scoring System. The industry standard Onyx's severity labels are inspired by.

BullMQ

A Redis-backed job queue. Onyx uses it to fire attacks concurrently without overwhelming the target or Node.js.

WebSocket

A persistent two-way connection. Onyx streams every attack result over it so the dashboard updates in real time.

Domain verification

Proof that you own a target, via a file probe or DNS TXT record, required once before scanning.