Skip to content

armgit / ARES

Public Imported from GitHub
0

ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.

32.4 KB
Raw Blame

ARES API Reference

Base URL: http://127.0.0.1:8080 API endpoints require authentication unless noted otherwise. Non-execution automation endpoints may accept X-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 /health is 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 key immediately - the full API key secret is not recoverable after this response. In the dashboard, the same one-time secret is shown in the Save your key modal. 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, default 1, minimum 1): Page number.
  • per_page (query, integer, default 50, range 1-500): Items per page.
  • severity (query, string, optional): Filter by severity (critical, high, medium, low, info).
  • false_positive (query, boolean, optional): Filter false positives (true or false).

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_json is 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 404 when 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:

  • goal can be domain_admin, enterprise_admin, cloud_admin, data_exfil, persistence, or full_compromise.
  • Legacy llm_backend fields are accepted only as inert request compatibility data in this release; no Claude, OpenAI, Ollama, or other planning connection is opened.
  • X-API-Key does not authorize this endpoint. Supply a current bearer and a canonical lowercase UUIDv4 Idempotency-Key.
  • The response is synchronous. With the production descriptor gate closed it is non-dispatchable; an eligible private test seam may return terminal 200 only 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.