ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
ARES API Reference
Base URL:
http://127.0.0.1:8080API endpoints require authentication unless noted otherwise. Non-execution automation endpoints may acceptX-API-Key; account/security management and every C-LIVE execution endpoint use JWT/browser sessions only. Browser auth is same-origin and CSRF protected;GET /healthis unauthenticated. API keys are the supported automation credential.Note: The web dashboard (
/dashboard/*) has its own authentication using the same tokens - see Dashboard section.
Authentication
POST /auth/token
Create a browser session. First call GET /auth/csrf from the configured
same origin, then submit the form with the readable CSRF cookie copied into
X-ARES-CSRF. The refresh token is returned only as an HttpOnly cookie.
Request: application/x-www-form-urlencoded (OAuth2 password flow)
username=alice&password=changeme
Response:
{
"access_token": "eyJhbGci...",
"token_type": "bearer",
"role": "operator",
"refresh_generation": 0,
"session_coordination_key": "non-secret-cross-tab-key",
"expires_in": 3600
}
The response sets host-only __Host-ares-refresh (HttpOnly) and
__Host-ares-csrf cookies in production. Both use Secure, SameSite=Strict,
and Path=/; no Domain is set. Responses are never cacheable.
Each successful login creates an independent device/session family with a fixed 30-day absolute lifetime. Access JWTs carry the family identifier and current authentication epoch; authorization always resolves the current user, role, family, epoch, and JTI from the database. The JWT role claim is not an authority source.
POST /auth/refresh
Atomically consume the current refresh token and issue generation n + 1 in
the same family. Rate limited per IP (same limit as /auth/token). A known
consumed-token replay, including a concurrent loser or retry after a lost
response, revokes the complete family and returns the same fixed 401 as any
invalid, expired, unknown, or revoked refresh token. No replacement token can
be recovered; the user must sign in again. The request body and query must be
empty, no bearer or refresh-token header is accepted, and the refresh token is
read only from the canonical HttpOnly cookie. Exact Origin and CSRF checks are
required. Success rotates both cookies and returns access/coordination metadata
without a refresh token.
POST /auth/logout
Revoke the family represented by the current refresh cookie. The empty request
requires exact Origin and CSRF checks. A conclusive result returns 204,
clears both browser cookies, and is idempotent for a missing or already-revoked
cookie. Other device families remain active.
POST /auth/logout-all
Require the current access bearer plus Origin and CSRF, increment the current
user's authentication epoch, and revoke every bearer family. Success returns
204 and clears both cookies. Existing bearer HTTP and WebSocket authority
fails on its next database resolution. API keys remain outside bearer families.
GET /auth/me
Return current authenticated user info.
This endpoint accepts either a JWT bearer token or an ARES API key with a compatible read scope. Example:
$headers = @{ "X-API-Key" = "YOUR_ARES_API_KEY" }
Invoke-RestMethod `
-Uri "http://127.0.0.1:8080/auth/me" `
-Headers $headers
POST /auth/register
Create a new user. Requires team_lead role.
{ "username": "bob", "password": "StrongPass1!", "role": "operator" }
Valid roles:
| Role | Intended use |
|---|---|
team_lead |
Engagement lead/admin. Full API access, user registration, security audit, restricted authorization, campaign deletion, and normal operator work. |
operator |
Day-to-day operator. Campaign/module/report workflows. Cannot register users. |
recon |
Read-heavy recon identity. Internal module permissions mark enumeration, fingerprint, and network modules as recon-safe; main dashboard execution remains operator-gated. |
reporter |
Read-only reporting/review account. No module execution or user administration. |
Password requirements: minimum 12 characters with uppercase, lowercase, digit, and special-character content.
PowerShell example:
$origin = "http://127.0.0.1:5173"
$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession
Invoke-WebRequest -Uri "$origin/auth/csrf" -WebSession $session | Out-Null
$csrf = ($session.Cookies.GetCookies($origin) |
Where-Object Name -eq "ares-dev-csrf").Value
$token = (Invoke-RestMethod `
-Method Post `
-Uri "$origin/auth/token" `
-WebSession $session `
-Headers @{ Origin = $origin; "X-ARES-CSRF" = $csrf; "Sec-Fetch-Site" = "same-origin" } `
-ContentType "application/x-www-form-urlencoded" `
-Body "username=admin&password=YOUR_CURRENT_ADMIN_PASSWORD").access_token
$headers = @{ Authorization = "Bearer $token" }
Invoke-RestMethod `
-Method Post `
-Uri "$origin/auth/register" `
-Headers $headers `
-ContentType "application/json" `
-Body (@{
username = "bob"
password = "StrongPass1!"
role = "operator"
} | ConvertTo-Json)
The current dashboard lists users on the Security page, but user role assignment is done through this registration endpoint when the account is created.
GET /auth/sso/init
Initiate an SP-initiated Single Sign-On (SAML 2.0 or OIDC) flow for a specific organization. Returns the authorization redirect URL and registers an ephemeral single-use state token in the database for CSRF and replay protection.
Query Parameters:
org: Organization slug (defaults to"default").
Response: 200 OK
{
"configured": true,
"protocol": "saml",
"redirect_url": "https://idp.example.com/sso/endpoint?...",
"flow_id": "c1f7b8c2-..."
}
POST /auth/sso/saml/acs
SAML 2.0 Assertion Consumer Service (ACS) endpoint (HTTP-POST binding). Receives signed base64-encoded XML assertions from Identity Providers (Okta, Microsoft Entra ID, Ping), verifies digital signatures with the stored IdP x.509 certificate, validates the InResponseTo correlation identifier against active state tokens, JIT-provisions the user, and sets secure browser session cookies (ares-dev-refresh and ares-dev-csrf).
Request: application/x-www-form-urlencoded
SAMLResponse=PHNhbWxwOlJlc3BvbnNlLi4u&RelayState=%2Fdashboard%2F
Response: HTTP 303 See Other redirecting to the target dashboard route with active session cookies.
GET /auth/sso/oidc/callback
OpenID Connect (OIDC) Authorization Code callback endpoint. Exchanges the one-time authorization code with the provider token endpoint, cryptographically verifies ID Token claims (iss, aud, nonce), maps user claims and roles, JIT-provisions the user account, and issues browser session cookies.
Query Parameters:
code: Authorization code issued by the IdP.state: Single-use state parameter generated during initiation.
Response: HTTP 303 See Other redirecting to /dashboard/ with active session cookies.
GET /auth/sso/config/{org_slug}
Retrieve SSO status and metadata for an organization. Requires the team_lead administrative role.
Response: 200 OK
{
"configured": true,
"organization": { "id": "org-1", "slug": "default", "name": "Default Organization" },
"protocol": "saml",
"is_enabled": true,
"issuer_or_entity_id": "https://idp.example.com/entityid",
"sso_url": "https://idp.example.com/sso",
"default_role": "reporter",
"has_certificate": true,
"has_client_secret": false
}
POST /auth/sso/config/{org_slug}
Register or update SSO federation settings for an organization. Requires the team_lead administrative role. All certificates and client secrets are encrypted before persistence via AES-256-GCM AEAD.
Request: application/json
{
"protocol": "saml",
"issuer_or_entity_id": "https://idp.example.com/entityid",
"sso_url": "https://idp.example.com/sso",
"idp_certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
"default_role": "reporter",
"role_mapping": {
"SecAdmins": "team_lead",
"RedTeam": "operator"
},
"is_enabled": true
}
POST /auth/change-password
Change password for the authenticated user.
{ "current_password": "old-password", "new_password": "NewStrongPass1!" }
POST /auth/api-keys
Create an API key for the authenticated user.
API keys are generated inside ARES after a user has authenticated with a JWT/browser session. Existing API keys cannot create, list, revoke, or manage account credentials.
API keys are for automation and integrations that call API endpoints with
X-API-Key. They are separate from deployment secrets such as
ARES_SECRET_KEY and ARES_ENCRYPTION_KEY, which must be generated by the
deployer before startup.
{
"name": "CI pipeline key",
"scopes": "read",
"expires_days": 90
}
scopes may be read, write, or admin. API-key scopes are an additional
restriction on API-key-compatible routes and do not replace RBAC.
Response:
{
"id": "...",
"key": "ares_...",
"note": "Save this key - it will NOT be shown again.",
"prefix": "ares_..."
}
Store
keyimmediately - the full API key secret is not recoverable after this response. In the dashboard, the same one-time secret is shown in theSave your keymodal. The key list shows metadata and a prefix only, not the full secret.
GET /auth/api-keys
List API keys for the authenticated user with a JWT/browser session. The response returns metadata and a key prefix only; it does not return the full secret.
DELETE /auth/api-keys/{key_id}
Revoke an API key with a JWT/browser session.
Campaigns
POST /campaigns
Create a new campaign. Requires operator role or higher.
{
"name": "Corp Red Team Q1",
"client": "ACME Corp",
"targets": ["10.0.0.10"],
"scope_cidrs": ["10.0.0.0/8", "192.168.1.0/24"],
"noise_profile": "normal"
}
Response: 201 Created
{ "id": "abc12345", "name": "Corp Red Team Q1", "status": "created" }
GET /campaigns
List all campaigns. Supports pagination: ?page=1&per_page=50
Response headers: X-Total-Count, X-Page, X-Per-Page
GET /campaigns/{id}
Get campaign details including confirmed findings count.
DELETE /campaigns/{id}
Delete a campaign. Requires team_lead.
The delete operation removes the campaign and stored child data for that campaign, including findings, hosts, credentials, and loot. Use this for lab cleanup or removing test campaigns from the dashboard.
Response: 200 OK
{ "status": "deleted", "campaign_id": "abc12345" }
GET /campaigns/{id}/findings
Get confirmed findings for a campaign with pagination and filtering.
Authentication: JWT Bearer token or X-API-Key with read scope. Requires campaign access.
Parameters:
page(query, integer, default1, minimum1): Page number.per_page(query, integer, default50, range1-500): Items per page.severity(query, string, optional): Filter by severity (critical,high,medium,low,info).false_positive(query, boolean, optional): Filter false positives (trueorfalse).
Response Headers:
X-Total-Count: Total number of matching findings.X-Page: Current page number.X-Per-Page: Current per-page limit.
Response: 200 OK
[
{
"id": "fnd_12345",
"campaign_id": "abc12345",
"module_id": "ad.kerberoast",
"title": "Kerberoastable Service Account Found",
"severity": "high",
"confidence": "confirmed",
"mitre_technique": "T1558.003",
"evidence_json": "{\"redacted\":true}",
"cvss_score": 7.5,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N",
"false_positive": false,
"discovered_at": "2026-09-30T00:00:00Z"
}
]
Forensic Redaction Policy: Campaign finding metadata remains available, but
evidence_jsonis redacted for every caller and contains{"redacted":true}. This endpoint does not provide raw evidence access over HTTP; raw evidence is stored for authorized internal consumers only.
GET /campaigns/{id}/cvss
Get CVSS v3.1 score distribution and summary for a campaign, suitable for compliance reports (PCI-DSS, ISO 27001).
Authentication: JWT Bearer token or X-API-Key with read scope. Requires campaign access.
Response: 200 OK
{
"campaign_id": "abc12345",
"cvss_summary": {
"total_findings": 10,
"mean_score": 6.8,
"max_score": 9.8,
"critical_count": 2,
"high_count": 4,
"medium_count": 3,
"low_count": 1
},
"findings_with_scores": [
{
"id": "fnd_12345",
"title": "Kerberoastable Service Account Found",
"cvss_score": 7.5,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N",
"severity": "high",
"mitre": "T1558.003"
}
]
}
GET /campaigns/{id}/diff/{other_id}
Generate a delta report comparing two campaigns (campaign_id vs other_id). Compares findings matched by normalized title (case-insensitive) to verify remediation progress between assessments.
Authentication: JWT Bearer token or X-API-Key. Caller must have authorized access to both campaigns.
Response: 200 OK
{
"new_findings": [
{
"id": "fnd_67890",
"title": "Unquoted Service Path",
"severity": "medium",
"cvss_score": 6.5,
"cvss_vector": "CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H",
"mitre": "T1574.009"
}
],
"fixed_findings": [
{
"id": "fnd_12345",
"title": "Kerberoastable Service Account Found",
"severity": "high",
"cvss_score": 7.5,
"cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N",
"mitre": "T1558.003"
}
],
"severity_changed": [],
"summary": {
"current_campaign_id": "abc12345",
"base_campaign_id": "prev67890",
"new_count": 1,
"fixed_count": 1,
"net_change": 0,
"risk_improved": true
}
}
POST /campaigns/{id}/run
Preview an execution plan or submit it to the C-LIVE boundary. dry_run=true
is a local preview and executes no module code. A live submission is
bearer-only, requires a canonical lowercase UUIDv4 Idempotency-Key, rejects
raw secret material, and authorizes the complete plan before any child can be
admitted. In C-LIVE-v1 every production descriptor is ineligible, so a
production live request returns 409 descriptor_unavailable with
redispatched=false and performs no module or broadcast effect.
{
"plan": [{"module_id": "ad.kerberoast", "params": {"dc": "dc01.corp.local"}}],
"dry_run": false,
"noise_profile": "normal"
}
An eligible private test seam responds synchronously only after every child is durably terminal:
Response: 200 OK
{ "campaign_id": "abc12345", "modules_run": 1, "children": [] }
POST /campaigns/{id}/restore-vault
Re-hydrate the campaign's CredentialVault from persisted database records into the active runtime engine state. Loads encrypted credentials at rest (AES-256-GCM AEAD or transparent legacy fallback) into the active campaign memory session after a server restart.
Authentication: Requires operator or team_lead role. Rate-limited per IP (vault_restore limit).
Response: 200 OK
{
"restored": 5,
"campaign_id": "abc12345",
"message": "Vault restored into the active campaign runtime state"
}
Modules
GET /modules
List all registered modules with metadata.
[
{
"id": "ad.kerberoast",
"name": "Kerberoasting",
"category": "ad",
"description": "Request Kerberos TGS tickets for service accounts",
"opsec_level": "medium",
"requires": ["domain_creds", "spn_list"],
"outputs": ["kerberos_hashes"],
"mitre": "T1558.003",
"mitre_list": ["T1558.003"],
"source": "builtin",
"param_schema": {
"dc": {
"type": "string",
"description": "DC IP or FQDN",
"required": true,
"secret": false
},
"password": {
"type": "string",
"description": "Password",
"required": true,
"secret": true
}
}
}
]
param_schema is generated by ares/modules/params.py and is the source of
truth for dynamic dashboard forms.
POST /modules/{module_id}/run
Preview one module or submit it to the bearer-only C-LIVE boundary. A live
submission requires a canonical lowercase UUIDv4 Idempotency-Key and accepts
opaque credential identifiers only. Production descriptors are ineligible in
C-LIVE-v1, so the production response is 409 descriptor_unavailable with
redispatched=false; no module code or handler broadcast runs. dry_run=true
returns a local preview without module execution.
{
"campaign_id": "abc12345",
"target": "dc01.corp.local",
"params": {
"domain": "CORP",
"dc": "dc01.corp.local"
},
"dry_run": false
}
POST /modules/{module_id}/feasibility
Pre-flight defense feasibility assessment before module execution. Evaluates target defense posture (EDR, Credential Guard, PPL, MDI, Sysmon), calculates risk score, and recommends stealthy alternatives.
Request: application/json
{
"campaign_id": "abc12345",
"target": "10.0.0.5",
"params": { "share": "C$" }
}
Response: 200 OK
{
"module_id": "lateral.smb_exec",
"campaign_id": "abc12345",
"report": {
"feasible": true,
"risk_score": 45,
"target": "10.0.0.5",
"stealth_recommendations": []
}
}
GET /modules/execution-chains
Return read-only attack execution-chain guidance, capability paths, and multi-stage execution chain templates for the Modules catalog.
Response: 200 OK
[
{
"id": "ad-kerberoast-to-privesc",
"name": "Active Directory Kerberoast to Local Privilege Escalation",
"steps": ["ad.spn_scan", "ad.kerberoast", "windows.privesc"]
}
]
POST /modules/reload
Hot-reload attack modules in-memory from builtin and external module sources. Strictly permitted for loopback origins (127.0.0.1, ::1, localhost) or authenticated operators with administrative privileges.
Response: 200 OK
{
"status": "ok",
"reloaded": true,
"module_count": 66
}
Reports
POST /reports/{campaign_id}
Generate a campaign report.
Query parameters:
| Parameter | Values | Default | Notes |
|---|---|---|---|
fmt |
html, pdf, markdown, json |
html |
Report artifact format. |
include_sensitive_evidence |
true, false |
false |
Includes raw sensitive evidence only when the caller is authorized as team_lead. |
Example:
POST /reports/{campaign_id}?fmt=json&include_sensitive_evidence=false
PDF generation uses the report renderer internally and returns a PDF artifact
for fmt=pdf. The server uses WeasyPrint when available and can fall
back to a local Chromium-compatible browser in local environments where
WeasyPrint native libraries are not installed. On Windows, use Python 3.12.x
from normal non-Administrator PowerShell; WeasyPrint needs native GTK/Pango
libraries in addition to the pip package. Use ares doctor --pdf-smoke to
validate the active PDF backend. HTML and PDF reports render finding evidence
as readable tables and key-value rows where possible.
Report evidence is redacted by default. Do not include raw Kerberoast,
ASREPRoast, password, token, or other secret material in public demos or shared
reports. Use include_sensitive_evidence=true only for intentional,
authorized internal review; non-team_lead callers receive 403.
Use fmt=json when you need machine-readable report data.
Response: 200 OK
{ "filename": "campaign-id_Corp_20260609_1200.html", "format": "html" }
GET /reports/{campaign_id}
List generated report files for a campaign. Results are restricted to files that belong to the campaign and resolve inside the report directory.
GET /reports/{campaign_id}/files/{filename}
Download a generated report file. Filename traversal, absolute paths, encoded traversal, and symlink escapes are rejected.
DELETE /reports/{campaign_id}/files/{filename}
Delete one generated report artifact for the campaign.
- Requires report/campaign authorization.
- Rejects unsafe filenames: traversal, absolute paths, nested paths, path separators, empty filenames, and symlink escapes outside the report directory.
- Returns
404when the report artifact is missing.
Response: 200 OK
{ "status": "deleted", "campaign_id": "abc12345", "filename": "abc12345_Corp_20260714_1200.pdf" }
DELETE /reports/{campaign_id}
Clear generated report artifacts for the campaign.
- Requires report/campaign authorization.
- Deletes only generated report artifact extensions:
.pdf,.json,.html, and.md. - Ignores directories and unrelated files.
Response: 200 OK
{ "status": "deleted", "campaign_id": "abc12345", "deleted": 3 }
Telemetry
GET /telemetry
Get the current operational telemetry snapshot.
The response combines live process metrics with database-backed aggregates for module runs, confirmed findings, and discovered hosts. Queue depth and worker health remain process-local; use the campaign, finding, report, and graph endpoints for durable engagement records.
{
"modules": { "total": 42, "success": 38, "failed": 4, "error_rate": 0.095 },
"queue": { "depth": 0 },
"workers": { "active": 0, "unhealthy": 0 },
"findings": 17,
"hosts": { "discovered": 12, "owned": 3 },
"latency_ms": { "p50": 1200.0, "p95": 8400.0, "p99": 15000.0 },
"throughput": { "tasks_per_min": 3.0, "bytes_sent": 0, "bytes_recv": 0 }
}
GET /telemetry/prometheus
Prometheus-compatible metrics endpoint.
ares_modules_total{status="success"} 38
ares_findings_total 17
ares_hosts_owned 3
Security (team_lead only)
GET /security/audit
Run a dependency vulnerability audit via pip-audit.
GET /security/users
List all users.
Attack Graph
GET /graph/{campaign_id}
Get the attack graph for a campaign. The response hydrates persisted hosts, findings, safe credential metadata, and the campaign graph snapshot. Credential secrets are never returned.
GET /graph/{campaign_id}/attack-paths
Get identified attack paths sorted by severity from persisted campaign data and the campaign graph snapshot.
POST /graph/{campaign_id}/bloodhound
Ingest BloodHound/SharpHound JSON from an allowed local path and persist a sanitized campaign graph snapshot for later requests.
Strategy
GET /strategy/active
List active autonomous engagements.
POST /strategy/engage
Submit a Strategy execution intent to the bearer-only C-LIVE boundary. In C-LIVE-v1 all production descriptors remain disabled/ineligible, so this route returns the frozen synchronous non-dispatchable response and performs no LLM, planning-network, module, or broadcast effect. A production planning provider cannot be selected through this request.
Request body:
{
"campaign_id": "CAMPAIGN_ID",
"goal": "domain_admin",
"max_rounds": 5,
"llm_backend": "claude",
"secondary_backend": "",
"authorizations": [],
"forbidden_modules": [],
"allow_persistence": false
}
Notes:
goalcan bedomain_admin,enterprise_admin,cloud_admin,data_exfil,persistence, orfull_compromise.- Legacy
llm_backendfields are accepted only as inert request compatibility data in this release; no Claude, OpenAI, Ollama, or other planning connection is opened. X-API-Keydoes not authorize this endpoint. Supply a current bearer and a canonical lowercase UUIDv4Idempotency-Key.- The response is synchronous. With the production descriptor gate closed it
is non-dispatchable; an eligible private test seam may return terminal
200only after durable settlement.
EDR/OPSEC
GET /edr/bypass/stats
Return historical bypass outcome statistics.
POST /edr/bypass/report
Record the outcome of an existing technique. This stores telemetry only; it does not add bypass logic.
Telemetry & Statistics
GET /stats/monthly
Return confirmed findings aggregated by day for the current calendar month (UTC). Used for dashboard metric cards, burn-down charts, and velocity tracking.
Authentication: JWT Bearer token or X-API-Key with read scope.
Parameters:
campaign_id(query, string, optional): Filter aggregation to a specific campaign. If omitted, aggregates across all campaigns accessible to the caller.
Response: 200 OK
{
"period": "2026-09",
"label": "Security signals this cycle",
"total": 12,
"confirmed_findings": 12,
"series": [
{ "date": "2026-09-01", "count": 3 },
{ "date": "2026-09-02", "count": 9 }
]
}
Templates
GET /templates
List campaign templates.
POST /templates/{template_name}/plan
Generate an execution plan from a template.
Template plans are deterministic and do not call an LLM. They return a plan for operator review and do not execute modules automatically.
Production LLM-backed planning is inactive in C-LIVE-v1. The
ai.autonomous_planner descriptor cannot be activated through this endpoint or
the dashboard; production planning activation requires separate approval.
Health
GET /health
System health check. Does not require authentication.
{ "status": "ok", "version": "6.0.0", "db": "connected" }
WebSocket
POST /campaigns/{campaign_id}/websocket-ticket
Issue a short-lived ticket for the main campaign WebSocket. Authenticate this
HTTP request with the normal bearer header or X-API-Key; API keys require a
read, write, or admin scope. The response is never cacheable:
{ "ticket": "<one-time-ticket>", "expires_in": 30 }
The ticket is campaign-bound, expires after 30 seconds if unused, and can be consumed successfully only once. Presenting it to a different campaign does not consume it. A successful consume remains spent even if WebSocket accept subsequently fails, so every connection or reconnect must request a new one.
WS /ws/campaigns/{campaign_id}/events?ticket=<one-time-ticket>
Real-time event stream for a campaign. The main route accepts only the exact
single ticket query parameter. Bearer-token and API-key WebSocket query
credentials are removed and have no compatibility fallback. After connection,
ARES revalidates the ticket's original bearer or API-key authority before
connected, pong, keepalive, module, and strategy event delivery. Ticket expiry
or row cleanup does not end a connected session while that source authority
remains valid.
Events:
{ "type": "module_start", "module_id": "ad.kerberoast" }
{ "type": "module_complete", "module_id": "ad.kerberoast", "findings": 2 }
{ "type": "finding_discovered","severity": "high", "title": "..." }
{ "type": "campaign_status_change", "status": "complete" }
{ "type": "connected", "campaign_id": "..." }
{ "type": "keepalive" }
Dashboard
After frontend assets are built, FastAPI serves the production/static React
dashboard at GET /dashboard/, with SPA fallback for routes like
/dashboard/campaigns. The static shell can load without auth so the login
screen works; all sensitive data is fetched from the main authenticated API
routes above.
For local development, run ares dashboard dev --no-reload from the
repository root, or .\.venv\Scripts\ares.exe dashboard dev --no-reload on
Windows, and open the Vite-served dashboard at
http://127.0.0.1:5173/dashboard/. The backend API remains on
http://127.0.0.1:8080 by default.
The dashboard bootstraps CSRF with GET /auth/csrf, uses cookie-only
POST /auth/token and POST /auth/refresh, the main REST API,
POST /campaigns/{campaign_id}/websocket-ticket, and the ticket-only main
campaign WebSocket. Legacy
/dashboard/api/* and /dashboard/ws/live routes are not the primary data
source.
Deploy the backend and frontend atomically and drain existing main WebSocket
connections during rollout. Old-frontend/new-backend and
new-frontend/old-backend combinations are unsupported. Rollback likewise
replaces both components together; the additive ticket migrations remain
installed. Production clients must use HTTPS/WSS directly. The one-time ticket
can still be visible in browser developer tools or to upstream components that
receive the handshake query. The nginx TLS access-log format uses $uri to
omit queries. Its port-80 redirect also uses $uri, deliberately dropping
every query string; production clients must still connect with HTTPS/WSS
directly.
The supported dashboard is /dashboard on the main ARES application. The
older ares.api.dashboard.app:dashboard_app FastAPI application is not mounted
by that supported topology. Under normal ASGI lifespan processing, direct
legacy startup is denied by default; development or test execution requires
both ARES_LEGACY_DASHBOARD_ENABLED=true and ARES_DEBUG=true. All supported
main-application, CLI, Docker, and Compose launch paths use the main ARES
application and normal lifecycle processing. Never enable the legacy
application in production.
Running the legacy target with ASGI lifespan disabled, including
--lifespan off, is unsupported. Unmanaged direct ASGI dispatch that sends
HTTP or WebSocket request scopes without entering lifespan is also unsupported
and bypasses this startup guard. This L2 guard contains accidental or default
exposure through supported launchers; it is not a security boundary against a
malicious or privileged deployment operator deliberately bypassing ASGI
lifespan.
Legacy opt-in does not add modern authentication, campaign-ownership, WebSocket, credential-transport, or deployment parity. In particular, its query-token and global live-WebSocket risks remain. Final retirement of the legacy application is the preferred long-term outcome.
Dashboard shell behavior:
- The left sidebar routes between pages, and the topbar menu collapses or expands it.
- Topbar quick search is client-side navigation over currently loaded page names/routes, campaigns, modules, reports, and templates. It is not a server-backed global search over unloaded historical data.
- The notification bell is the only topbar status surface. Its badge counts unread notifications; opening the drawer marks visible items as read, and dismiss/clear-all remove notifications from the current session.
- Notification state does not store bodies, API keys, tokens, stack traces, or raw payloads.
- Overview has no variation tabs. Other pages use the tabs documented in
docs/dashboard-guide.md.
Error Responses
All errors return structured JSON:
{
"code": 401,
"detail": "Not authenticated. Provide Bearer token or X-API-Key.",
"type": "authentication_error"
}
HTTP status codes:
| Code | Meaning |
|---|---|
| 400 | Bad request / validation error |
| 401 | Authentication required or token invalid |
| 403 | Insufficient role / scope violation |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |
| 503 | Engine not ready |
C-LIVE-v1 execution boundary
Live requests to POST /modules/{module_id}/run,
POST /campaigns/{campaign_id}/run, and POST /strategy/engage are
bearer-only. X-API-Key never authorizes execution. Every non-preview request
must carry Idempotency-Key as a canonical lowercase UUIDv4; missing or
malformed keys return 422 after bearer/role and campaign-existence checks.
Raw credential material is rejected. Callers may provide only opaque credential
identifiers.
C-LIVE-v1 is safety wiring, not descriptor activation. Production descriptors
remain ineligible, so production Strategy performs no LLM/network planning and
returns the generic non-dispatchable response. An eligible private test seam is
synchronous and returns a terminal 200 only after durable settlement.
An exact replay returns 409 execution_replayed_no_redispatch with stable
identifiers and never re-executes module code or emits a handler broadcast.
Changed intent under the same key returns 409 idempotency_conflict. Authority
staleness returns 409, capacity exhaustion 429, inconsistent budget state
503, invalid contracts 422, invariant failures 500, and purged lifecycle
targets 410. An unconfirmed terminal state returns
503 execution_settlement_unconfirmed; clients must inspect status using the
same key rather than submit a new logical execution.