ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
ARES Quickstart
ARES is an operator dashboard and automation framework for authorized red-team validation, lab workflows, campaign orchestration, module execution, telemetry, reporting, RBAC, and security checks.
Use it only on systems you own or have written permission to assess.
Universal first-run workflow
This is the supported path from a fresh clone to a first campaign report. It is not AD-specific. AD/Kerberos, cloud, Windows, Linux, credential, network, and other module families all start with the same campaign, module, findings, and report workflow. Module-specific differences begin at module selection, required optional extras/tools, and parameter values.
A. Prerequisites
- Git.
- Python 3.12.x for the recommended/tested release path.
- Node.js/npm for dashboard development mode.
- Normal non-Administrator PowerShell on Windows.
- Written authorization, an owned lab, or an approved engagement scope.
B. Clone and enter repo
Windows PowerShell:
git clone https://github.com/Mafifrizi/ARES.git
Set-Location .\ARES
Linux/macOS:
git clone https://github.com/Mafifrizi/ARES.git
cd ARES
C. Create virtualenv and install ARES baseline
Windows PowerShell:
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev,pdf]"
Linux/macOS:
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e ".[dev,pdf]"
dev,pdf is the local dashboard/reporting baseline. The base dashboard does
not require every optional module family. Install optional extras only when you
need that module family.
Optional extras examples:
Windows PowerShell:
.\.venv\Scripts\python.exe -m pip install -e ".[ad]"
.\.venv\Scripts\python.exe -m pip install -e ".[ad-support]"
.\.venv\Scripts\python.exe -m pip install -e ".[cloud]"
.\.venv\Scripts\python.exe -m pip install -e ".[windows]"
.\.venv\Scripts\python.exe -m pip install -e ".[full]"
Linux/macOS:
python -m pip install -e ".[ad]"
python -m pip install -e ".[ad-support]"
python -m pip install -e ".[cloud]"
python -m pip install -e ".[windows]"
python -m pip install -e ".[full]"
For AD modules, use .[ad] for a normal full AD install. If ares doctor
already reports impacket as importable from a source/local install, use
.[ad-support] to install the remaining direct AD support libraries
(pyasn1, pyasn1_modules, ldap3, and httpx_ntlm) without forcing another
PyPI Impacket wheel install. After installing AD dependencies, restart
ares dashboard dev --no-reload, rerun ares doctor --pdf-smoke, and confirm
pyasn1, pyasn1_modules, ldap3, and httpx_ntlm are no longer missing.
If .[ad] fails on Windows while importing Impacket example scripts such as
GetNPUsers.py, restore the known-good source/local Impacket checkout and use
.[ad-support] for the direct support libraries instead of repeatedly
retrying the broken wheel install.
D. Install frontend dependencies
Windows PowerShell:
Set-Location frontend
& "C:\Program Files\nodejs\npm.cmd" ci
Set-Location ..
Linux/macOS:
cd frontend
npm ci
cd ..
ares dashboard dev --install can run npm ci for you when
frontend/node_modules is missing.
E. Configure required secrets
ARES requires these values before the first dashboard login:
| Variable | Purpose |
|---|---|
ARES_SECRET_KEY |
Signs API sessions and tokens. Generate a random high-entropy value. |
ARES_ENCRYPTION_KEY |
Encrypts sensitive stored data such as vault/checkpoint material. Keep it stable and backed up. |
ARES_DEFAULT_ADMIN_PASSWORD |
Bootstrap password for the first admin account only when the user table is empty. |
ARES_BROWSER_ORIGIN |
One exact HTTPS production browser origin. Debug mode accepts only the fixed loopback Vite origins. |
Windows PowerShell:
$env:ARES_SECRET_KEY = .\.venv\Scripts\python.exe -c "import secrets; print(secrets.token_urlsafe(48))"
$env:ARES_ENCRYPTION_KEY = .\.venv\Scripts\python.exe -c "import secrets; print(secrets.token_urlsafe(32))"
$env:ARES_DEFAULT_ADMIN_PASSWORD = "replace-with-your-own-strong-admin-password"
Linux/macOS:
export ARES_SECRET_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')"
export ARES_ENCRYPTION_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export ARES_DEFAULT_ADMIN_PASSWORD="replace-with-your-own-strong-admin-password"
For repeated local use, copy .env.example to .env and fill these values
there instead of setting session variables each time.
Browser authentication is same-origin. Production must set
ARES_BROWSER_ORIGIN to the public HTTPS origin that serves both dashboard and
API through nginx. The local dashboard launcher uses the fixed loopback Vite
proxy boundary; it does not enable general cross-origin cookie authentication.
Important:
- The first admin bootstrap password comes from
ARES_DEFAULT_ADMIN_PASSWORDin the current environment or.envfile. - Changing
ARES_DEFAULT_ADMIN_PASSWORDafteradminalready exists does not reset that user's password. - Change the admin password after first login.
- Do not commit, print, record, or share secrets.
- ARES API keys created later in the dashboard are separate from these startup secrets and from LLM provider keys.
F. Run doctor/pdf smoke before starting dashboard
Windows PowerShell:
$env:ARES_PDF_BROWSER = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
.\.venv\Scripts\ares.exe doctor --pdf-smoke
ARES_PDF_BROWSER points ARES PDF export to Microsoft Edge for the current
PowerShell session. This is recommended on Windows when WeasyPrint native
GTK/Pango libraries are not installed. Use normal non-Administrator
PowerShell.
Expected successful fallback lines include:
[OK] PDF ARES_PDF_BROWSER ... exists=True
[OK] PDF browser detected ... msedge.exe
[OK] PDF smoke ... bytes=...
A WeasyPrint GTK/Pango warning on Windows is acceptable when Edge/Chrome fallback and PDF smoke succeed. Importable Impacket from a source/local install can show OK with an unknown version. Missing optional module families/tools may warn until installed. Optional hashcat, john, cloud, Windows, or AD warnings do not block base dashboard/reporting.
Linux/macOS:
ares doctor --pdf-smoke
G. Start dashboard
Windows PowerShell:
.\.venv\Scripts\ares.exe dashboard dev --no-reload
Linux/macOS:
ares dashboard dev --no-reload
URLs:
- Backend API:
http://127.0.0.1:8080 - Dashboard:
http://127.0.0.1:5173/dashboard/
The dashboard dev command is the normal local launcher. --no-reload is
recommended for stable demos and recording.
Useful launcher options:
--no-open: print the URL without opening a browser.--no-reload: start uvicorn without reload.--install: runnpm ciinfrontend/ifnode_modulesis missing.--api-host/--api-port: change the backend bind address.--ui-host/--ui-port: change the Vite bind address.
Manual fallback for troubleshooting:
Terminal 1:
Set-Location "<ARES repo root>"
.\.venv\Scripts\python.exe -m uvicorn ares.api.server:app --host 127.0.0.1 --port 8080 --reload
Terminal 2:
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/
H. Login
- Username:
admin - Password: value of
ARES_DEFAULT_ADMIN_PASSWORD
The launcher prints the username and dashboard URL, but it does not print the
password value. Change the admin password from Security after first login.
Do not show passwords in videos or screenshots.
I. Create users and assign roles
The first account is created automatically:
- Username:
admin - Role:
team_lead - Password source:
ARES_DEFAULT_ADMIN_PASSWORD
The dashboard Security page lists users for review, but the current release
does not include a role editor. Additional users are created by a team_lead
through POST /auth/register, and the role is assigned at account creation.
Valid roles:
| Role | Purpose |
|---|---|
team_lead |
Full local admin/operator lead. Can create users, delete campaigns, view security audit, authorize restricted workflows, and run normal operator work. |
operator |
Daily operator. Can run normal campaign/module/report workflows. |
recon |
Read-heavy recon identity. Main dashboard execution endpoints remain operator-gated. |
reporter |
Read-only reporting and review. No module execution or user administration. |
Create accounts with POST /auth/register from a current team_lead browser
session. Login is same-origin and CSRF protected; use the complete
browser-session example in docs/api-reference.md, not a direct password POST
to the backend origin.
Passwords must be at least 12 characters and include uppercase, lowercase, number, and special-character content.
J. Create and use an ARES API key
API keys are created from the Security page after login. They are ARES
automation credentials, not OpenAI, Anthropic, or Ollama keys.
When you create a key:
- The
Save your keymodal shows the full secret once. - After the modal closes, only prefix/metadata are visible.
- Store the secret securely outside ARES if you need it later.
- Scripts use the
X-API-Keyheader.
Example against a real authenticated endpoint that accepts API keys:
$headers = @{ "X-API-Key" = "YOUR_ARES_API_KEY" }
Invoke-RestMethod `
-Uri "http://127.0.0.1:8080/auth/me" `
-Headers $headers
K. Universal campaign workflow
- Open
Campaigns. - Create a campaign.
- Define campaign name, client, targets, and scope CIDRs.
- Open
Modules. - Choose any module from the catalog.
- Select the campaign.
- Fill backend-generated parameters.
- Run dry-run first where supported.
- Execute only inside authorized scope.
- Review module output in
Results. - Review persisted findings in
Campaigns/Findingsor the relevant findings view. - Open
Reports. - Generate JSON, PDF, HTML, or Markdown.
- Open
Library. - Download artifacts.
- Delete one artifact or use
Delete all/ Clear library.
Module-specific differences begin at module selection, optional extras/tools, and parameter values. AD/Kerberos, cloud, network, credential, Windows, Linux, and other modules follow the same campaign/module/report flow.
L. Reports and Library
Open Reports:
- Select a campaign.
- Generate
json. - Switch to
Libraryand download the JSON artifact. - Generate
pdf. - Switch to
Libraryand download the PDF artifact. - Generate
htmlormarkdownwhere supported. - Use a row's
Deleteaction to remove one artifact after confirming. - Use
Delete all/ Clear library to remove the campaign's generated report artifacts after confirming.
Report evidence is redacted by default. Raw hashes, passwords, tokens, and other secrets should appear only in authorized internal review paths. Do not publish them in public demos or shared reports.
Successful report library delete actions update rows and artifact counts. When
no reports remain, the Library shows No reports generated for this campaign yet.
M. Troubleshooting
| Symptom | Fix |
|---|---|
ares command not found on Windows |
Use .\.venv\Scripts\ares.exe ... from the repository root. |
frontend/node_modules missing |
Run npm ci in frontend/, or start with ares dashboard dev --install. |
| PDF smoke warning on Windows | Use normal non-Administrator PowerShell, set $env:ARES_PDF_BROWSER = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe", then run .\.venv\Scripts\ares.exe doctor --pdf-smoke. |
| Optional module dependency warning | Install the relevant extra only when that module family is needed, for example .[ad], .[cloud], .[windows], or .[full]. For source/local Impacket AD setups, use .[ad-support] for the remaining direct AD support libraries. |
| Impacket source/local install version unknown | OK if Impacket is importable; install .[ad-support] if pyasn1, pyasn1_modules, ldap3, or httpx_ntlm still warn. Missing or too-old Impacket still warns. |
| AD LDAP/Kerberos login fails on Windows | Prefer UPN usernames such as [email protected]. Avoid LAB\alice unless NTLM/MD4 support is known to work in the active Python/OpenSSL environment. |
Invalid credentials |
Use the current admin password. Updating ARES_DEFAULT_ADMIN_PASSWORD after admin exists does not reset that password. |
Target is not in campaign scope |
Add the target CIDR to the campaign scope, for example 127.0.0.1/32 for local testing. |
Report direct URL returns 401 |
Use the authenticated dashboard Download button. |
| Pytest on Windows fails before tests with temp ACL errors | Developer validation only: use a writable temp root or fix the stale %TEMP%\pytest-of-<user> permissions. This is not part of normal first-run use. |
Optional planning and module notes
Templates
Open Templates when you want a repeatable plan. Templates produce
deterministic plan stages, do not call an LLM, and do not execute modules by
themselves.
Strategy and AI planning
Strategy is for goal-based planning against an existing campaign. The default
strategy path expects an LLM provider key unless you configure a local backend.
ARES API keys from the Security page are not LLM keys.
Common LLM environment variables:
export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
Use Strategy only after a campaign exists, scope is correct, authorization notes are clear, and the selected LLM backend is configured.
Public SDK (Next-Gen Autonomous Architecture)
Use the modern, type-safe SDK import path for custom modules, unit testing, and automation:
from ares.sdk import (
BaseModule, ExecutionContext, ModuleResult,
ModuleParams, param, SecretParam,
OpsecLevel, Severity, ares_module,
ModuleTestHarness, AresClient,
)
ares.modules.sdk remains as a 100% backward-compatible shim, but new modules should use ares.sdk.
See:
docs/module_sdk.md(Full v2 SDK Architecture & Client Guide)docs/module-development.md(Step-by-step authoring guide)example_modules/example_modern_v2_module.py(Reference implementation)
Connecting AI Assistants (ARES MCP Gateway)
To connect AI coding environments (Cursor IDE, Claude Desktop, Windsurf, VS Code Cline) directly to ARES under strict ScopeGuard governance:
Launch ARES MCP Console:
.\mcp.bat(Or native PowerShell:
.\mcp)1-Click AI Client Setup:
.\mcp.bat setup --client cursorReload & Verify:
- In Cursor, run
Ctrl + Shift + P→Developer: Reload Window. - Check Settings → Features → MCP Servers (
aresshould be connected).
- In Cursor, run
See ARES MCP Gateway Specification for full architecture and tool guides.
Validation lab
Run the validation lab after changing API or dashboard behavior:
$env:ARES_LAB_PASSWORD="YOUR_CURRENT_ADMIN_PASSWORD"
.\scripts\run_validation_lab.ps1
The lab checks login, profile, campaign validation, dry-run validation, reports, and API key lifecycle.
Safety reminder
ARES is intended for authorized security testing, lab use, and defensive validation only.
Database ownership
Fresh databases initialize through Alembic. If ARES reports that an existing
SQLite or PostgreSQL database requires adoption, stop all workers and follow
docs/database-migrations.md. Do not run a blind
alembic stamp: only audited unversioned generations 6 and 7 are supported, and
SQLite adoption requires a retained verified backup.
The current managed head is revision 0010. It adds an authoritative
execution-lifecycle persistence catalog but does not activate a gateway or
disable legacy execution. Stop every process, take the required backup, run the
canonical upgrade, and deploy the matching 0010-aware backend. Mixed
0009/0010 processes are unsupported. Revision 0009 remains the historical
refresh-family rollout that invalidated existing browser bearer sessions.
The browser transport uses a host-only HttpOnly refresh cookie and a readable
CSRF cookie/header pair. Access tokens remain in memory, API keys remain the
automation credential, and refresh tokens are no longer returned in JSON or
stored in sessionStorage. Deploy the matching backend and frontend together,
drain existing WebSockets, and require existing users to sign in again. A
rollback replaces both components together and does not downgrade the database;
the transport rollout itself remains revision 0009; revision 0010 is the
separate additive lifecycle-persistence release.