CyberAgent.id — API Documentation

> Platform audit keamanan siber otomatis berbasis AI Agent.

> Base URL: https://cyberagent.id · API prefix: /api

> Semua request/response menggunakan application/json.

---

Autentikasi

Sebagian besar endpoint membutuhkan Bearer Token (JWT).


Authorization: Bearer <JWT_TOKEN>

Token didapat dari:

POST /api/auth/register

POST /api/auth/login

OAuth Google / GitHub (redirect callback)

Token berlaku 7 hari (default).

---

Rate Limiting

|---|---|---|

Level	Limit	Scope
Global	300 request / menit / IP	Semua endpoint
Strict	15 request / menit / IP	`auth/login`, `auth/register`, `billing/*`, `agent/deepdive` (POST)

Bypass rate limit via X-Forwarded-For tidak dimungkinkan (key berbasis socket remote address).

---

Error Format


{ "error": "Deskripsi error" }

|---|---|

Status	Arti
400	Validasi gagal / payload tidak valid
401	Token tidak valid / kedaluwarsa
403	Tidak diizinkan
404	Resource tidak ditemukan
409	Konflik (email sudah terdaftar, dst)
429	Rate limit terlampaui
500	Kesalahan server

---

Endpoints

Auth

#### POST /api/auth/register

Membuat akun baru. Wajib: checkbox ToS + verifikasi Turnstile + email non-disposable.


{
  "name": "Nama Lengkap",
  "email": "user@company.com",
  "password": "minimal8karakter",
  "agreeTos": true,
  "turnstileToken": "0.xxxxx"
}

Response 201:


{ "token": "JWT...", "user": { "id": 1, "name": "...", "email": "...", "credits": 1, "tier": "free" } }

Validasi:

agreeTos wajib true — kalau tidak: 400

Email dari disposable/temp-mail ditolak: 400

Turnstile wajib valid (prod keys Cloudflare)

#### POST /api/auth/login


{ "email": "user@company.com", "password": "rahasia", "turnstileToken": "0.xxxxx" }

Response 200: { "token": "...", "user": {...} }

#### GET /api/auth/me

Auth required. Mengembalikan profil user.

#### GET /api/auth/google

Redirect ke Google OAuth consent. Callback: /api/auth/callback/google → redirect dashboard.html?token=JWT.

#### GET /api/auth/github

Redirect ke GitHub OAuth authorize. Callback: /api/auth/callback/github → redirect dashboard.html?token=JWT.

---

Audit

#### POST /api/audit/start

Mulai audit baru. Auth required. SSRF-guarded (domain internal/metadata ditolak).


{
  "domain": "example.com",
  "scope": "medium",
  "engine": "advanced"
}

|---|---|

Field	Nilai
scope	`small` (1 kredit), `medium` (3), `large` (5)
engine	`basic`, `advanced`

Response 201: { "auditId": 30, "status": "pending" }

#### GET /api/audit/:id

Auth required + ownership. Status audit + hasil.

#### GET /api/audit

Daftar audit milik user.

---

Billing

#### GET /api/billing/credits

Saldo kredit user.

#### GET /api/billing/packages

Daftar paket harga.

#### POST /api/billing/topup

Topup kredit. Di production: terintegrasi payment gateway (Midtrans) — saat gateway belum aktif, kredit dev dikunci (501).

---

Webhooks

#### POST /api/webhooks

Buat webhook notifikasi (Slack/Discord/Telegram).


{ "type": "slack", "url": "https://hooks.slack.com/...", "events": "critical" }

SSRF-guarded — URL internal/private ditolak.

#### GET /api/webhooks · DELETE /api/webhooks/:id

List / hapus webhook (ownership).

#### POST /api/webhooks/:id/test

Kirim test notification.

---

Agent (Deepdive)

#### POST /api/agent/deepdive

Trigger deepdive audit AI Agent. Strict rate limit. SSRF-guarded (DNS-resolved).


{ "domain": "example.com", "aggressive": false, "idempotencyKey": "optional-unique-key" }

Kredit: 5. Response: { "jobId": "aud_xxxx", "status": "IN_QUEUE" }

#### GET /api/agent/deepdive/:id

Status + progress stream. Final: { "status": "COMPLETED", "report": {...} }

#### POST /api/agent/deepdive/:id/cancel

Batalkan job.

---

Worker (internal)

#### POST /api/worker/claim — X-Worker-Token required

Claim job deepdive berikutnya.

#### POST /api/worker/:id/log — X-Worker-Token

Push progress line (auto-redacted: API keys, JWT, email, phone, bearer).

#### POST /api/worker/:id/result — X-Worker-Token

Kirim hasil report + commit credits.

---

Keamanan

|---|---|

Area	Implementasi
Anti-bot	Cloudflare Turnstile (login/register) — prod keys
Email	Blokir disposable/temp-mail (200+ domain) + validasi format
SSRF	Guard string-level + DNS-resolution di audit, verify, webhook, deepdive
Rate limit	Global 300/min + strict 15/min + anti-XFF-spoof
CORS	Whitelist origin (cyberagent.id, www, localhost dev)
JWT	Secret kuat via env, fail-fast di production
SQL	Prepared statements (better-sqlite3)
Redaction	API keys / secrets di-redact dari stream worker
Billing	Velocity limit 5x/10menit + freeze fraud + gate production

---

Legal & Compliance

Terms of Service: /terms.html

Kebijakan Privasi: /privacy.html

Signup mewajibkan persetujuan ToS & Privacy (checkbox + validasi server-side)

Kepatuhan: UU PDP No. 27/2022 (privacy by design)

---

Deployment


Web (static + proxy):  BotVPS 43.156.98.120 — Caddy (HTTPS Let's Encrypt)
Backend (API):         129.225.8.16:8080 — Node.js (PM2)
Database:              SQLite (data/cyberagent.db)
Tunnel:                PM2 ca-tunnel (SSH reverse, auto-restart)

Environment Variables (`.env`)


PORT=8080
NODE_ENV=production
JWT_SECRET=<random>
TURNSTILE_SECRET_KEY=<cloudflare>
GOOGLE_CLIENT_ID=<oauth>
GOOGLE_CLIENT_SECRET=<oauth>
GITHUB_CLIENT_ID=<oauth>
GITHUB_CLIENT_SECRET=<oauth>
OAUTH_BASE_URL=https://cyberagent.id
FRONTEND_URL=https://cyberagent.id
WORKER_TOKEN=<random>
CORS_ORIGIN=https://cyberagent.id,http://43.156.98.120
FRONTEND_DIR=/home/opc/cyberagent-landing

Proses PM2

|---|---|

App	Fungsi
`cyberagent-backend`	API server (port 8080)
`ca-tunnel`	SSH reverse tunnel BotVPS → backend

---