ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
ARES Frontend
The dashboard lives in frontend/ and is a React + TypeScript + Vite app built
for the FastAPI backend.
Runtime
- Development: run
ares dashboard dev --no-reloadfrom the repository root. It starts the FastAPI API onhttp://127.0.0.1:8080and the Vite dashboard onhttp://127.0.0.1:5173/dashboard/in one terminal. - Windows virtualenv:
.\.venv\Scripts\ares.exe dashboard dev --no-reload. - Browser open can be skipped with
ares dashboard dev --no-open. - Backend and UI bind addresses can be changed with
--api-host,--api-port,--ui-host, and--ui-port. - Uvicorn reload can be disabled with
--no-reload. - If
frontend/node_modulesis missing, runares dashboard dev --installor runnpm cifromfrontend/. - Production/static serving:
npm run build, then FastAPI servesfrontend/distat/dashboard - Vite base path:
/dashboard/ - API proxy: main FastAPI routes, not legacy dashboard shadow routes
Manual fallback for troubleshooting:
Set-Location "<ARES repo root>"
.\.venv\Scripts\python.exe -m uvicorn ares.api.server:app --host 127.0.0.1 --port 8080 --reload
Set-Location "<ARES repo root>\frontend"
& "C:\Program Files\nodejs\npm.cmd" run dev -- --host 127.0.0.1 --port 5173
Then open http://127.0.0.1:5173/dashboard/.
Auth
- Browser authentication is same-origin only. Login first obtains a pre-login
CSRF cookie from
GET /auth/csrf, then callsPOST /auth/tokenwith the existing form body andX-ARES-CSRF. - Enterprise Single Sign-On (SAML 2.0 / OIDC): The login surface supports SP-initiated
SSO via "Or continue with SSO". Clicking initiates
GET /auth/sso/init?org=default, redirecting to the configured IdP. Upon assertion verification at/auth/sso/saml/acsor/auth/sso/oidc/callback, the backend issues secure session cookies and redirects back to/dashboard/, whereAuthProviderperforms a locked startup refresh and loads the operator profile. - Access tokens are held in module memory only. Refresh tokens exist only in a host-only HttpOnly cookie and never enter JSON, browser-readable storage, React state, messages, logs, or request bodies/headers/queries.
- Refresh acquires the origin-global
ares-refresh-cookie-v2Web Lock, reads the current CSRF cookie immediately before the request, and sends an empty credentialedPOST /auth/refresh. - Startup synchronously deletes the legacy
sessionStoragerefresh-token key before any request, then performs at most one locked refresh rotation. - Logout calls
POST /auth/logoutand revokes only the current device family; Logout all devices callsPOST /auth/logout-all. Both clear local state even when the remote request fails. - Web Locks and writable
localStoragecoordination are mandatory.localStorage, storage events, andBroadcastChannelcarry only a bounded protocol version, non-secret coordination key, refresh generation, and logout tombstone. A tab needing its own in-memory access token performs a sequential locked rotation using the latest shared cookie. - An indeterminate refresh is never retried. The frontend clears in-memory authority and makes at most one locked logout-current attempt; if that is also unavailable, explicit sign-in is required.
- Each main campaign WebSocket connection first requests a 30-second,
single-use ticket with authenticated
POST /campaigns/{campaign_id}/websocket-ticket. The ticket exists only across the asynchronous connection barrier and is never stored in React state,localStorage, orsessionStorage.
Routes
/overview: health, telemetry, campaign summary/campaigns:List,Scope, andFindingstabs for list/create/detail/delete, findings, CVSS, diff, restore, and dry-run plan actions/modules:Catalog,Run Panel, andResultstabs for catalog filters, backend-derived dynamic params, dry-run default, and execution output/reports:Generatetab for report creation;Librarytab for listing artifacts, authenticated download, per-report delete, and Delete all/Clear library cleanup. Successful delete actions update rows and artifact counts without a full page reload./graph: Interactive ARES Tactical Pivot Graph & Beacon Console (Entities,Attack Paths, andIngesttabs) featuring perimeter ingress firewall with animated flames, click-to-lock pathway tracking, slide-over Tactical Inspector Drawer (with deduplicated vulnerability grouping and unified custom dark scrollbar), and multi-tabbed Beacon session terminal dock./templates:TemplatesandPlan Buildertabs for listing templates and generating plans/strategy:Objective,Active, andResulttabs for active engagements and role-gated engagement start/security:Account,API Keys, andAudittabs for profile, password change, API keys, audit, and users/edr:Knowledge BaseandReport Outcometabs for bypass telemetry and outcome reporting/live:StreamandBuffertabs backed by the ticket-onlyWS /ws/campaigns/{campaign_id}/events?ticket=<one-time-ticket>route. Every reconnect requests a fresh ticket; bearer/API-key query credentials are no longer supported.
Shell Controls
- The left sidebar handles route navigation.
- The topbar menu button collapses and expands the sidebar.
- Topbar quick search is client-side navigation over currently loaded page names/routes, campaigns, modules, reports, and templates. It is not a server-backed search across unloaded historical data.
- The notification bell is the health/status surface. There is no separate topbar status pill for online/offline state.
- The bell badge counts unread notifications only. Opening the drawer marks visible notifications as read; individual dismiss and clear-all remove notifications from the current session.
- Notification state must not persist bodies, API keys, tokens, stack traces, or raw payloads.
- The topbar keeps the user identity plus current-device and all-device logout actions.
Enterprise UI & Design Principles
The ARES frontend adheres to strict enterprise-grade product design principles:
- Anti-Slop Restraint: Frivolous sci-fi tropes, fake cipher streams, blinking LED animations, and gratuitous padlock icons are forbidden.
- Authoritative Authentication:
LoginPage.tsxpresents a focused, centered card (width: 380px) with clear input labels, crisp focus rings, and a high-contrast solid action button. - High-Density Cockpit:
DashboardPages.tsxpresents KPI cards with pure numeric values, status deltas, and clean labels without floating decorative icons. Navigation sidebars are kept clean without noisy enclave badges. - Text-First Action Buttons: Operational buttons (
Restore Vault,Dry Run Plan,Create Campaign) use clear, text-first labels rather than confusing icon soup. - Semantic Design Tokens: Styles are governed by HSL tokens in
src/styles.css(--ares-bg,--ares-surface,--ares-surface-elevated,--ares-border,--ares-accent). Monospace fonts are reserved for technical evidence (IPs, hashes, tickets, CVSS vectors).
Safety
Module forms are built from GET /modules param_schema; fields are not
hardcoded in the frontend. Module runs default to dry_run=true, and
high-noise or sensitive modules require explicit UI confirmation. Backend RBAC
remains the enforcement boundary.
Runtime UX State
Dashboard result panels are context-aware. Modules, reports, graph ingest, templates, strategy, and EDR/OPSEC views keep their latest result only while the selected campaign/module/input still matches the action that produced it. Changing page context hides stale output instead of showing old JSON under a new selection.
Long-running actions should show a loading state on the button or result area. Operators should be able to tell that ARES is processing a request without watching the terminal.
The Live page owns a browser WebSocket connection. It checks the captured session revision, campaign, effect, and connection generation after ticket issuance and discards a late response after logout, account replacement, campaign change, cleanup, or unmount. A same-session access-token refresh does not invalidate that barrier. Navigating away closes the connection, so users request a fresh ticket when they return.
Every token response carries a refresh generation and non-secret coordination key. A response is installed only if it belongs to the captured session and is the exact next generation. Logout, account replacement, replay/family revocation, or peer-tab generation advancement increments the session revision, clears credentials, closes bearer-backed WebSockets through normal lifecycle handling, and prevents an infinite refresh loop. A same-family token refresh does not change identity until another tab wins it.
Production frontend and backend versions must roll out atomically, with
existing sockets drained. Mixed old/new versions are unsupported, and rollback
replaces both together while leaving additive migrations installed. Use
HTTPS/WSS directly: one-time tickets can remain visible in browser developer
tools and upstream handshake processing. The nginx TLS access log omits query
strings through $uri; the port-80 redirect also uses $uri and drops
queries. The default-disabled legacy dashboard WebSocket
retains its separate limitations.