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.

docs: add universal first-run workflow

Mafifrizif4b85325e1a2
diff --git a/QUICKSTART.md b/QUICKSTART.md
index af7dac8..dc49b97 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -1,124 +1,210 @@
# 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.
+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.
-## 1. Clone And Enter The Project
+## 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:
+
+```powershell
+git clone https://github.com/Mafifrizi/ARES.git
+Set-Location .\ARES
+```
+
+Linux/macOS:
```bash
git clone https://github.com/Mafifrizi/ARES.git
cd ARES
```
-## 2. Install The Local Environment
+### C. Create virtualenv and install ARES baseline
+
+Windows PowerShell:
+
+```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:
```bash
-bash scripts/setup.sh
+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:
```powershell
-python -m venv .venv
-.\.venv\Scripts\Activate.ps1
-python -m pip install -e ".[dev,pdf]"
+.\.venv\Scripts\python.exe -m pip install -e ".[ad]"
+.\.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]"
```
-Notes:
+Linux/macOS:
-- The setup script is the Linux/macOS bootstrap path. On Windows, use the
- PowerShell commands above to create `.venv` and install the editable package.
-- Use Python 3.12.x for the release path. Package metadata allows Python
- 3.10-3.12, but the dashboard and Windows AD/Impacket lab validation are
- tested on Python 3.12.x.
-- Some offensive-security integrations are optional. `ares doctor` will tell you which optional packages or native tools are missing for AD, cloud, container, or password-cracking workflows.
-- PDF support uses WeasyPrint when available and has a local Edge/Chrome/Chromium browser fallback in the API. On Windows, use Python 3.12.x from normal non-Administrator PowerShell. If needed, set `ARES_PDF_BROWSER=C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe` for the current user or shell. WeasyPrint on Windows needs native GTK/Pango libraries in addition to the pip package.
+```bash
+python -m pip install -e ".[ad]"
+python -m pip install -e ".[cloud]"
+python -m pip install -e ".[windows]"
+python -m pip install -e ".[full]"
+```
-## 3. Configure Secrets
+### D. Install frontend dependencies
-ARES requires three local environment values before the API starts.
+Windows PowerShell:
-These values are created by the operator or deployment owner. ARES does not provide shared public secrets.
+```powershell
+Set-Location frontend
+& "C:\Program Files\nodejs\npm.cmd" ci
+Set-Location ..
+```
-### Linux/macOS
+Linux/macOS:
```bash
-export ARES_SECRET_KEY="$(python - <<'PY'
-import secrets
-print(secrets.token_urlsafe(48))
-PY
-)"
-
-export ARES_ENCRYPTION_KEY="$(python - <<'PY'
-from cryptography.fernet import Fernet
-print(Fernet.generate_key().decode())
-PY
-)"
+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. |
+
+Windows PowerShell:
+
+```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 "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+$env:ARES_DEFAULT_ADMIN_PASSWORD = "replace-with-your-own-strong-admin-password"
+```
+
+Linux/macOS:
+
+```bash
+export ARES_SECRET_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')"
+export ARES_ENCRYPTION_KEY="$(python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
export ARES_DEFAULT_ADMIN_PASSWORD="replace-with-your-own-strong-admin-password"
```
-### Windows PowerShell
+For repeated local use, copy `.env.example` to `.env` and fill these values
+there instead of setting session variables each time.
+
+Important:
+
+- The first admin bootstrap password comes from `ARES_DEFAULT_ADMIN_PASSWORD`
+ in the current environment or `.env` file.
+- Changing `ARES_DEFAULT_ADMIN_PASSWORD` after `admin` already 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:
```powershell
-$env:ARES_SECRET_KEY = python -c "import secrets; print(secrets.token_urlsafe(48))"
-$env:ARES_ENCRYPTION_KEY = python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-$env:ARES_DEFAULT_ADMIN_PASSWORD = "replace-with-your-own-strong-admin-password"
+$env:ARES_PDF_BROWSER = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
+.\.venv\Scripts\ares.exe doctor --pdf-smoke
```
-What each value does:
+`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.
-| Variable | Purpose | Keep Stable? |
-| --- | --- | --- |
-| `ARES_SECRET_KEY` | Signs API sessions and tokens. | Yes, for a deployed instance. Rotating it invalidates sessions. |
-| `ARES_ENCRYPTION_KEY` | Encrypts sensitive local data such as credential vault material. | Yes. Losing or changing it can make existing encrypted data unreadable. |
-| `ARES_DEFAULT_ADMIN_PASSWORD` | Password for the first bootstrap `admin` account when the user table is empty. | Change after first login. Updating this value later does not reset an existing admin. |
+Expected successful fallback lines include:
-For repeated local use, copy `.env.example` to `.env`, fill these values once, and start ARES from the same project directory.
+```text
+[OK] PDF ARES_PDF_BROWSER ... exists=True
+[OK] PDF browser detected ... msedge.exe
+[OK] PDF smoke ... bytes=...
+```
-## 4. Start The API And Dashboard
+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.
-Recommended local startup from the repository root:
+Linux/macOS:
```bash
-ares dashboard dev
+ares doctor --pdf-smoke
```
-Windows virtualenv example:
+### G. Start dashboard
+
+Windows PowerShell:
```powershell
-.\.venv\Scripts\ares.exe dashboard dev
+.\.venv\Scripts\ares.exe dashboard dev --no-reload
```
-This starts the FastAPI backend and the Vite dashboard dev server in one
-terminal. It prints:
+Linux/macOS:
-- Backend API URL: `http://127.0.0.1:8080`
-- Dashboard URL: `http://127.0.0.1:5173/dashboard/`
-- Login username: `admin`
-- Login password: value of `ARES_DEFAULT_ADMIN_PASSWORD` in the current
- environment or `.env` file
+```bash
+ares dashboard dev --no-reload
+```
-The launcher opens the dashboard by default and does not print the password
-value.
+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`: run `npm ci` in `frontend/` if `node_modules` is missing.
- `--api-host` / `--api-port`: change the backend bind address.
- `--ui-host` / `--ui-port`: change the Vite bind address.
-- `--install`: run `npm ci` in `frontend/` if `node_modules` is missing.
-
-For example:
-
-```bash
-ares dashboard dev --install
-```
Manual fallback for troubleshooting:
@@ -142,139 +228,157 @@ Then open:
http://127.0.0.1:5173/dashboard/
```
-Health check:
+### H. Login
-```bash
-curl http://127.0.0.1:8080/health
-```
+- Username: `admin`
+- Password: value of `ARES_DEFAULT_ADMIN_PASSWORD`
-Expected result:
+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.
-```json
-{"status":"ok","version":"6.0.0","db":"connected"}
-```
+### I. Create users and assign roles
-Login with:
+The first account is created automatically:
- Username: `admin`
-- Password: your `ARES_DEFAULT_ADMIN_PASSWORD`
+- Role: `team_lead`
+- Password source: `ARES_DEFAULT_ADMIN_PASSWORD`
-Then change the admin password from the `Security` page.
+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.
-The first `admin` user is created only when the user table is empty. If you
-already have a local database, use the current admin password. Changing
-`ARES_DEFAULT_ADMIN_PASSWORD` after the account exists will not update that
-password. For disposable local data, recreate the local `ares.db`; otherwise,
-change the password from the dashboard after login.
+Valid roles:
-Local development reset warning: this deletes local dashboard data in
-`ares.db`. Do not use it on real or shared deployments.
+| 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. |
+
+PowerShell example:
```powershell
-New-Item -ItemType Directory -Force ".\_db_backup" | Out-Null
-if (Test-Path ".\ares.db") {
- Copy-Item ".\ares.db" ".\_db_backup\ares.db.before-reset" -Force
-}
-Remove-Item ".\ares.db" -Force -ErrorAction SilentlyContinue
+$token = (Invoke-RestMethod `
+ -Method Post `
+ -Uri http://127.0.0.1:8080/auth/token `
+ -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 http://127.0.0.1:8080/auth/register `
+ -Headers $headers `
+ -ContentType "application/json" `
+ -Body (@{
+ username = "alice"
+ password = "StrongPass1!"
+ role = "operator"
+ } | ConvertTo-Json)
```
-Dashboard shell:
-
-- The left sidebar routes between Overview, Campaigns, Modules, Reports, Graph,
- Templates, Strategy, Security, EDR/OPSEC, and Live.
-- The topbar menu button collapses or expands the sidebar.
-- Topbar quick search navigates over currently loaded page names/routes,
- campaigns, modules, reports, and templates. It is not a backend global search
- over unloaded history.
-- The notification bell is the only topbar status surface. Its badge counts
- unread notifications; opening the drawer marks visible items as read, and the
- drawer supports individual dismiss plus clear-all.
-- The topbar also provides signed-in identity and logout.
-- Current tabs are: Campaigns `List`/`Scope`/`Findings`, Modules
- `Catalog`/`Run Panel`/`Results`, Reports `Generate`/`Library`, Graph
- `Entities`/`Attack Paths`/`Ingest`, Templates `Templates`/`Plan Builder`,
- Strategy `Objective`/`Active`/`Result`, Security `Account`/`API Keys`/`Audit`,
- EDR/OPSEC `Knowledge Base`/`Report Outcome`, and Live `Stream`/`Buffer`.
- Overview has no variation tabs.
+Passwords must be at least 12 characters and include uppercase, lowercase,
+number, and special-character content.
-## 5. Create A Campaign
+### J. Create and use an ARES API key
-Open `Campaigns` and create a scoped campaign.
+API keys are created from the `Security` page after login. They are ARES
+automation credentials, not OpenAI, Anthropic, or Ollama keys.
-Example local demo values:
+When you create a key:
-| Field | Example |
-| --- | --- |
-| Name | `ARES Local Finding Demo` |
-| Client | `Internal` |
-| Targets | `127.0.0.1` |
-| Scope CIDRs | `127.0.0.1/32` |
-
-Scope matters. Targeted modules will refuse to run if the target is outside the selected campaign scope.
-
-## 6. Run A Module Safely
-
-Open `Modules`:
+- The `Save your key` modal 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-Key` header.
-1. Select the campaign.
-2. Search for a module.
-3. Fill the generated parameter fields.
-4. Run with `Dry run` first when available.
-5. Run live only when the target and scope are authorized.
+Example against a real authenticated endpoint that accepts API keys:
-The dashboard catalog loads the built-in module metadata from the backend.
-Module IDs, names, categories, OPSEC labels, and parameter schemas come from
-that catalog. High-noise or sensitive modules remain guarded by authorization
-and confirmation checks; do not run destructive, credential, lateral movement,
-exfiltration, persistence, or bypass workflows outside an approved lab or
-engagement.
+```powershell
+$headers = @{ "X-API-Key" = "YOUR_ARES_API_KEY" }
-Port behavior is module-specific. Some modules require explicit ports because they fingerprint a service. Broader discovery belongs in enumeration modules such as port scanning, then the discovered services can be used by more specific modules.
+Invoke-RestMethod `
+ -Uri "http://127.0.0.1:8080/auth/me" `
+ -Headers $headers
+```
-## 7. Generate Reports
+### K. Universal campaign workflow
+
+1. Open `Campaigns`.
+2. Create a campaign.
+3. Define campaign name, client, targets, and scope CIDRs.
+4. Open `Modules`.
+5. Choose any module from the catalog.
+6. Select the campaign.
+7. Fill backend-generated parameters.
+8. Run dry-run first where supported.
+9. Execute only inside authorized scope.
+10. Review module output in `Results`.
+11. Review persisted findings in `Campaigns` / `Findings` or the relevant
+ findings view.
+12. Open `Reports`.
+13. Generate JSON, PDF, HTML, or Markdown.
+14. Open `Library`.
+15. Download artifacts.
+16. 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`:
1. Select a campaign.
-2. Choose `json`.
-3. Click `Generate`.
-4. Switch to `Library` and use `Download` to save/open the JSON artifact.
-5. Return to `Generate`, choose `pdf`, and click `Generate`.
-6. Switch to `Library` and use `Download` to save/open the PDF artifact.
+2. Generate `json`.
+3. Switch to `Library` and download the JSON artifact.
+4. Generate `pdf`.
+5. Switch to `Library` and download the PDF artifact.
+6. Generate `html` or `markdown` where supported.
7. Use a row's `Delete` action to remove one artifact after confirming.
8. Use `Delete all` / Clear library to remove the campaign's generated report
artifacts after confirming.
-Do not open report file URLs directly in the browser address bar. Report downloads are authenticated, so direct unauthenticated URLs return `401`.
-
-Report evidence is redacted by default. Do not expose raw Kerberoast,
-ASREPRoast, password, token, or other secret material in demos or public
-reports; include sensitive evidence only for authorized internal review.
-
-## 8. Use Templates
+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.
-Open `Templates` when you want a repeatable plan.
+Successful report library delete actions update rows and artifact counts. When
+no reports remain, the Library shows `No reports generated for this campaign
+yet.`
-Templates:
+### M. Troubleshooting
-- Generate deterministic plan stages.
-- Do not call an LLM.
-- Do not execute modules by themselves.
-- Are useful as a checklist before running campaign modules.
+| 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]`. |
+| Impacket source/local install version unknown | OK if Impacket is importable; missing or too-old Impacket still warns. |
+| `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. |
-Typical flow:
+## Optional planning and module notes
-1. Select a built-in template such as `internal_pentest`.
-2. Optionally provide JSON parameters.
-3. Click `Generate Plan`.
-4. Review the returned stages and module IDs.
-5. Execute approved modules manually from the campaign workflow.
+### Templates
-## 9. Use Strategy And AI Planning
+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 is for goal-based planning against an existing campaign.
+### Strategy and AI planning
-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.
+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:
@@ -283,75 +387,10 @@ export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
```
-Use Strategy only after:
-
-- A campaign exists.
-- Scope is correct.
-- Authorization notes are clear.
-- The required LLM provider key is configured, or a supported local backend is selected through the API.
-
-## 10. API Keys In The Security Page
-
-Dashboard API keys authenticate scripts and integrations to ARES itself.
-
-Use them as:
-
-```bash
-curl http://127.0.0.1:8080/campaigns \
- -H "X-API-Key: ares_YOUR_KEY"
-```
-
-They are not OpenAI, Anthropic, or Ollama keys.
-
-When you create a key, the dashboard opens the `Save your key` modal and shows
-the full secret once. Use `Copy`; after a successful copy the button changes to
-`Copied`. `Done` closes the modal and clears the in-memory new-key state. The
-API key list shows metadata and a prefix only, so the full secret cannot be
-retrieved later.
-
-## 11. Roles
-
-The first user is `admin` with the `team_lead` role.
-
-| Role | Purpose |
-| --- | --- |
-| `team_lead` | Full local admin/operator lead. Can create users, delete campaigns, view security audit, and authorize higher-risk workflows. |
-| `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. |
-
-Create users through `POST /auth/register` with a team-lead token. See `docs/dashboard-guide.md` for a PowerShell example.
-
-## 12. Doctor And Optional Dependencies
-
-Run:
-
-```bash
-ares doctor
-```
-
-Windows virtualenv example:
-
-```powershell
-.\.venv\Scripts\ares.exe doctor
-```
-
-`ares doctor` checks Python, key dependencies, optional module integrations, native tools, PDF export capability, network socket support, environment configuration, and the local database.
-
-A yellow warning means an optional integration is missing. A red failure means a required dependency or configuration item needs attention.
+Use Strategy only after a campaign exists, scope is correct, authorization
+notes are clear, and the selected LLM backend is configured.
-Common examples:
-
-| Message | Meaning |
-| --- | --- |
-| `impacket` missing or old | AD/SMB modules need the optional impacket dependency. |
-| `Windows AD/Impacket Python` warning | Windows AD lab validation is tested on Python 3.12.x. |
-| `PDF smoke` failed | Run `ares doctor --pdf-smoke` from normal non-Administrator PowerShell and check the WeasyPrint GTK/Pango or Edge/Chrome fallback guidance. |
-| `pip-audit not installed` | Dependency audit is unavailable; core API can still start. |
-| `hashcat not in PATH` | Password-cracking helpers cannot use hashcat until installed. |
-| `.env configured` failed | Required environment values are missing. |
-
-## 13. Public SDK
+### Public SDK
Use the public SDK import path for custom modules:
@@ -359,7 +398,8 @@ Use the public SDK import path for custom modules:
from ares.sdk import BaseModule, ExecutionContext, Finding, ModuleResult
```
-`ares.modules.sdk` remains as a compatibility shim, but new code should use `ares.sdk`.
+`ares.modules.sdk` remains as a compatibility shim, but new code should use
+`ares.sdk`.
See:
@@ -367,7 +407,7 @@ See:
- `docs/module_sdk.md`
- `docs/examples/example_http_enum.py`
-## 14. Validation Lab
+### Validation lab
Run the validation lab after changing API or dashboard behavior:
@@ -376,20 +416,10 @@ $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.
-
-## Troubleshooting
-
-| Symptom | Check |
-| --- | --- |
-| `ARES not configured` | Set `ARES_SECRET_KEY`, `ARES_ENCRYPTION_KEY`, and `ARES_DEFAULT_ADMIN_PASSWORD`. |
-| `Invalid credentials` | Use the current admin password, not the placeholder or a newly changed `ARES_DEFAULT_ADMIN_PASSWORD` value after the admin already exists. |
-| `Request failed with 422` | A required field is missing or a target/scope value is invalid. |
-| `Target is not in campaign scope` | Add the target CIDR to the campaign scope, for example `127.0.0.1/32`. |
-| `Global rate limit exceeded` | Wait briefly, then retry. Avoid repeatedly clicking actions while a request is pending. |
-| Report direct URL returns `401` | Use the authenticated dashboard Download button. |
-| Strategy does nothing useful | Confirm the campaign, authorization notes, and LLM provider key. |
+The lab checks login, profile, campaign validation, dry-run validation,
+reports, and API key lifecycle.
-## Safety Reminder
+## Safety reminder
-ARES is intended for authorized security testing, lab use, and defensive validation only.
+ARES is intended for authorized security testing, lab use, and defensive
+validation only.
diff --git a/README.md b/README.md
index 95d3b72..b88d735 100644
--- a/README.md
+++ b/README.md
@@ -55,6 +55,38 @@ assess.
---
+## Start Here: Fast Path
+
+For the complete first-run walkthrough, use [QUICKSTART.md](QUICKSTART.md).
+The short Windows PowerShell path is:
+
+```powershell
+git clone https://github.com/Mafifrizi/ARES.git
+Set-Location .\ARES
+
+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]"
+
+Set-Location frontend
+& "C:\Program Files\nodejs\npm.cmd" ci
+Set-Location ..
+
+$env:ARES_PDF_BROWSER = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
+.\.venv\Scripts\ares.exe doctor --pdf-smoke
+
+.\.venv\Scripts\ares.exe dashboard dev --no-reload
+```
+
+Configure `ARES_SECRET_KEY`, `ARES_ENCRYPTION_KEY`, and
+`ARES_DEFAULT_ADMIN_PASSWORD` before first login. Open
+`http://127.0.0.1:5173/dashboard/`, log in as `admin` with the
+`ARES_DEFAULT_ADMIN_PASSWORD` value, create a campaign/scope, run a module,
+review findings, then generate, download, or delete reports from the Report
+Library.
+
+---
+
## Why It Exists
Offensive security work can become messy fast: scattered scripts, loose notes,
@@ -89,13 +121,13 @@ ARES has two dashboard serving modes:
Recommended local development command:
```bash
-ares dashboard dev
+ares dashboard dev --no-reload
```
Windows virtualenv example:
```powershell
-.\.venv\Scripts\ares.exe dashboard dev
+.\.venv\Scripts\ares.exe dashboard dev --no-reload
```
Dashboard preview:
@@ -311,9 +343,14 @@ Security page, but role assignment is done at account creation time through
browser fallback for local environments that do not have WeasyPrint native
libraries installed.
- On Windows, use Python 3.12.x from a normal non-Administrator PowerShell for
- dashboard PDF export. If auto-detection needs help, set
- `ARES_PDF_BROWSER=C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`
- for the current user or shell.
+ dashboard PDF export. If auto-detection needs help, set the fallback for the
+ current PowerShell session:
+
+ ```powershell
+ $env:ARES_PDF_BROWSER = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
+ .\.venv\Scripts\ares.exe doctor --pdf-smoke
+ ```
+
- WeasyPrint on Windows needs native GTK/Pango libraries in addition to the pip
package; run `ares doctor --pdf-smoke` to verify the active PDF backend.
- ARES branding in generated reports with footer-safe page spacing.
@@ -347,194 +384,24 @@ See [docs/validation-lab.md](docs/validation-lab.md).
## Quickstart
-### 1. Configure Required Secrets
-
-ARES does not ship deployment secrets. The operator or organization deploying
-ARES must generate these values and provide them through environment variables
-or a private `.env` file.
-
-The required values are:
-
-| Variable | Who creates it? | Purpose |
-| --- | --- | --- |
-| `ARES_SECRET_KEY` | The deployer/client | Signs JWT/session security data. Generate a random high-entropy string. |
-| `ARES_ENCRYPTION_KEY` | The deployer/client | Encrypts sensitive stored data such as vault/checkpoint material. Generate a Fernet key and keep it stable. |
-| `ARES_DEFAULT_ADMIN_PASSWORD` | The deployer/client | Bootstrap password for the first `admin` account only when the user table is empty. Change it after first login. |
-
-PowerShell:
-
-```powershell
-$bytes = [byte[]]::new(32)
-[System.Security.Cryptography.RandomNumberGenerator]::Fill($bytes)
-$env:ARES_SECRET_KEY = -join ($bytes | ForEach-Object { $_.ToString("x2") })
-
-$env:ARES_ENCRYPTION_KEY = .\.venv\Scripts\python.exe -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
-$env:ARES_DEFAULT_ADMIN_PASSWORD = "replace-with-your-own-strong-admin-password"
-```
-
-Bash:
-
-```bash
-export ARES_SECRET_KEY="$(openssl rand -hex 32)"
-export ARES_ENCRYPTION_KEY="$(python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
-export ARES_DEFAULT_ADMIN_PASSWORD="replace-with-your-own-strong-admin-password"
-```
-
-Do not commit these values. Do not reuse the example password. Keep
-`ARES_ENCRYPTION_KEY` backed up securely; changing it after data has been
-encrypted can make existing encrypted records unreadable.
-
-Dashboard API keys are separate from these startup secrets. Create API keys
-from the Security page only after login when you need scripts, integrations, or
-automation to call the API with `X-API-Key` instead of an interactive session.
-The dashboard shows a new API key secret once in the `Save your key` modal and
-then lists only key metadata and a prefix.
-
-Optional AI planner provider keys:
-
-| Variable | Used by | Notes |
-| --- | --- | --- |
-| `ANTHROPIC_API_KEY` | `ai.autonomous_planner` with `llm_backend=claude`; Strategy default path. | Required when using Claude-backed planning. |
-| `OPENAI_API_KEY` | `ai.autonomous_planner` with `llm_backend=openai`. | Required when using OpenAI-backed planning. |
-| Local Ollama at `http://localhost:11434` | `ai.autonomous_planner` with `llm_backend=local`. | No cloud key required, but Ollama and the selected model must already be running. |
-
-Example:
-
-```powershell
-$env:OPENAI_API_KEY="sk-..."
-```
-
-or:
-
-```powershell
-$env:ANTHROPIC_API_KEY="sk-ant-..."
-```
-
-### 2. Start the API and Dashboard
-
-Recommended local dashboard startup from the repository root:
-
-```bash
-ares dashboard dev
-```
-
-Windows virtualenv example:
-
-```powershell
-.\.venv\Scripts\ares.exe dashboard dev
-```
-
-The launcher starts both services in one terminal:
-
-- Backend API: `http://127.0.0.1:8080`
-- Dashboard dev server: `http://127.0.0.1:5173/dashboard/`
-
-It prints both URLs, opens the dashboard by default, prefixes backend/frontend
-logs, and shuts both child processes down when you press `Ctrl+C`. Login with:
-
-- Username: `admin`
-- Password: the value of `ARES_DEFAULT_ADMIN_PASSWORD` in the current
- environment or `.env` file
-
-The command does not print the password value. If `frontend/node_modules` is
-missing, run `npm ci` in `frontend/` or start with:
-
-```bash
-ares dashboard dev --install
-```
-
-Useful launcher options:
-
-- `--no-open`: print the URL without opening a browser.
-- `--no-reload`: start uvicorn without reload.
-- `--api-host` / `--api-port`: change the backend bind address.
-- `--ui-host` / `--ui-port`: change the Vite bind address.
-- `--install`: run `npm ci` in `frontend/` if `node_modules` is missing.
-
-Manual fallback for troubleshooting:
-
-Terminal 1:
-
-```powershell
-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:
-
-```powershell
-Set-Location "<ARES repo root>\frontend"
-& "C:\Program Files\nodejs\npm.cmd" run dev -- --host 127.0.0.1 --port 5173
-```
-
-Open:
-
-```text
-http://127.0.0.1:5173/dashboard/
-```
-
-### 3. Check Health
-
-```powershell
-Invoke-RestMethod http://127.0.0.1:8080/health
-```
-
-Expected:
-
-```text
-status version db
------- ------- --
-ok 6.0.0 connected
-```
-
-### 4. Run the Local Validation Lab
-
-```powershell
-$env:ARES_LAB_PASSWORD="replace-with-your-current-admin-password"
-.\scripts\run_validation_lab.ps1
-```
-
-Expected ending:
-
-```text
-Validation lab passed.
-```
-
-### 5. Check Prerequisites With Doctor
-
-`ares doctor` checks the runtime you are about to operate: Python, required
-packages, optional module dependencies, PDF export capability, common service
-sockets, environment configuration, settings loading, and database connectivity.
-
-```bash
-ares doctor
-```
-
-Windows virtualenv example:
-
-```powershell
-.\.venv\Scripts\ares.exe doctor
-```
-
-A green check means the dependency is available. A yellow warning usually means
-an optional module family or external OS tool is not installed. It does not
-block the base dashboard, API, validation lab, or unit suite. A red failure
-means a required runtime check should be fixed before running that workflow.
-
-Optional module families can be installed only when you need them:
-
-```bash
-pip install -e ".[ad]"
-pip install -e ".[cloud]"
-pip install -e ".[container]"
-pip install -e ".[windows]"
-pip install -e ".[pdf]"
-pip install -e ".[full]"
-```
-
-External tools such as `hashcat` and `john` are operating-system packages, not
-Python extras. Install them with your platform package manager if you want the
-related modules to use them.
+Use [QUICKSTART.md](QUICKSTART.md) as the complete source of truth for the
+first-run path from clone to report. The universal order is:
+
+1. Clone the repo.
+2. Create `.venv`.
+3. Install `.[dev,pdf]`.
+4. Run `npm ci` in `frontend/`.
+5. Configure `ARES_SECRET_KEY`, `ARES_ENCRYPTION_KEY`, and
+ `ARES_DEFAULT_ADMIN_PASSWORD`.
+6. Set `$env:ARES_PDF_BROWSER = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"`
+ on Windows when using Edge PDF fallback.
+7. Run `.\.venv\Scripts\ares.exe doctor --pdf-smoke`.
+8. Start `.\.venv\Scripts\ares.exe dashboard dev --no-reload`.
+9. Log in, create a campaign/scope, run a module, review findings, and manage
+ reports from the Report Library.
+
+Optional module families are installed only when needed, for example `.[ad]`,
+`.[cloud]`, `.[windows]`, or `.[full]`.
---
@@ -543,15 +410,17 @@ related modules to use them.
Backend:
```bash
-python -m venv .venv
+python3.12 -m venv .venv
source .venv/bin/activate
-pip install -e ".[dev,pdf]"
-pytest tests/unit -q
+python -m pip install -e ".[dev,pdf]"
+python -m pytest tests/unit -q
```
Windows PowerShell:
```powershell
+py -3.12 -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev,pdf]"
.\.venv\Scripts\python.exe -m pytest tests/unit -q --tb=short --timeout=60 --timeout-method=thread
```
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 5a689d5..5d8e7b7 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -1,6 +1,6 @@
# ARES API Reference
-> **Base URL:** `http://localhost:8080`
+> **Base URL:** `http://127.0.0.1:8080`
> API endpoints require authentication unless noted otherwise. Automation
> endpoints may accept `X-API-Key`; account/security management endpoints use
> JWT/browser sessions only. `POST /auth/token` and `GET /health` are
@@ -56,6 +56,17 @@ Revoke current access token (adds JTI to blacklist).
Return current authenticated user info.
+This endpoint accepts either a JWT bearer token or an ARES API key with a
+compatible read scope. Example:
+
+```powershell
+$headers = @{ "X-API-Key" = "YOUR_ARES_API_KEY" }
+
+Invoke-RestMethod `
+ -Uri "http://127.0.0.1:8080/auth/me" `
+ -Headers $headers
+```
+
---
### `POST /auth/register`
@@ -112,7 +123,7 @@ created.
Change password for the authenticated user.
```json
-{ "current_password": "old", "new_password": "NewPass1!" }
+{ "current_password": "old-password", "new_password": "NewStrongPass1!" }
```
---
@@ -182,9 +193,9 @@ Create a new campaign. Requires `operator` role or higher.
{
"name": "Corp Red Team Q1",
"client": "ACME Corp",
- "scope": ["10.0.0.0/8", "192.168.1.0/24"],
- "noise_profile": "normal",
- "operator": "alice"
+ "targets": ["10.0.0.10"],
+ "scope_cidrs": ["10.0.0.0/8", "192.168.1.0/24"],
+ "noise_profile": "normal"
}
```
@@ -586,9 +597,11 @@ dashboard at `GET /dashboard/`, with SPA fallback for routes like
screen works; all sensitive data is fetched from the main authenticated API
routes above.
-For local development, run `ares dashboard dev` from the repository root 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.
+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 uses `POST /auth/token`, `POST /auth/refresh`, the main REST API,
and `WS /ws/campaigns/{campaign_id}/events?token=<token>`. Legacy
diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md
index 8e0daa3..84fe333 100644
--- a/docs/dashboard-guide.md
+++ b/docs/dashboard-guide.md
@@ -14,13 +14,13 @@ Production/static route after frontend assets are built:
Recommended local dashboard startup from the repository root:
```bash
-ares dashboard dev
+ares dashboard dev --no-reload
```
Windows virtualenv example:
```powershell
-.\.venv\Scripts\ares.exe dashboard dev
+.\.venv\Scripts\ares.exe dashboard dev --no-reload
```
This one-terminal launcher starts:
@@ -34,7 +34,7 @@ the value of `ARES_DEFAULT_ADMIN_PASSWORD` from the current environment or
`.env` file; the launcher does not print that password. Use
`ares dashboard dev --no-open` to skip browser open, or
`ares dashboard dev --install` to run `npm ci` if `frontend/node_modules` is
-missing.
+missing. Use `--no-reload` for stable demos and recording.
Options: `--api-host`, `--api-port`, `--ui-host`, `--ui-port`, `--no-open`,
`--no-reload`, and `--install`.
@@ -303,7 +303,13 @@ Formats:
fallback for local environments that do not have WeasyPrint native libraries.
- On Windows, run the dashboard from normal non-Administrator PowerShell with
Python 3.12.x. If browser auto-detection needs help, set
- `ARES_PDF_BROWSER=C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`.
+ the session fallback before running doctor or starting the dashboard:
+
+ ```powershell
+ $env:ARES_PDF_BROWSER = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
+ .\.venv\Scripts\ares.exe doctor --pdf-smoke
+ ```
+
- WeasyPrint on Windows requires native GTK/Pango libraries in addition to the
pip package; use `ares doctor --pdf-smoke` to validate the active backend.
diff --git a/docs/frontend.md b/docs/frontend.md
index ce3d802..05e32c7 100644
--- a/docs/frontend.md
+++ b/docs/frontend.md
@@ -5,10 +5,10 @@ for the FastAPI backend.
## Runtime
-- Development: run `ares dashboard dev` from the repository root. It starts
- the FastAPI API on `http://127.0.0.1:8080` and the Vite dashboard on
- `http://127.0.0.1:5173/dashboard/` in one terminal.
-- Windows virtualenv: `.\.venv\Scripts\ares.exe dashboard dev`.
+- Development: run `ares dashboard dev --no-reload` from the repository root.
+ It starts the FastAPI API on `http://127.0.0.1:8080` and the Vite dashboard
+ on `http://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`.
diff --git a/docs/modules.md b/docs/modules.md
index 4eb9477..2fa5ebe 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -5,6 +5,13 @@ buttons. They are building blocks for an authorized engagement: create a
campaign, define scope, run safe validation first, collect findings, then
generate a report.
+The core workflow is universal across module families: create a campaign,
+define targets and scope CIDRs, select a module from the backend catalog, fill
+the generated parameters, dry-run where supported, execute only inside
+authorized scope, review findings, and generate a report. AD/Kerberos, cloud,
+network, credential, Windows, Linux, and other modules differ only in optional
+extras/tools and parameter values.
+
## Safety Model
Only run ARES in systems you own or have written permission to test.
@@ -25,10 +32,11 @@ layer; the backend remains the enforcement boundary.
### Dashboard Flow
-1. For local development, run `ares dashboard dev` from the repository root
- and open `http://127.0.0.1:5173/dashboard/`. In production/static mode,
- FastAPI serves the built dashboard at `/dashboard` after frontend assets are
- built.
+1. For local development, run `ares dashboard dev --no-reload` from the
+ repository root and open `http://127.0.0.1:5173/dashboard/`. On Windows,
+ use `.\.venv\Scripts\ares.exe dashboard dev --no-reload`. In
+ production/static mode, FastAPI serves the built dashboard at `/dashboard`
+ after frontend assets are built.
2. Log in as an authorized operator.
3. Go to `Campaigns`.
4. Create or select a campaign.
@@ -61,7 +69,7 @@ $headers = @{ Authorization = "Bearer $token" }
Invoke-RestMethod `
-Method Get `
- -Uri http://localhost:8080/modules `
+ -Uri http://127.0.0.1:8080/modules `
-Headers $headers
```
@@ -70,16 +78,21 @@ Run a module in dry-run mode:
```powershell
Invoke-RestMethod `
-Method Post `
- -Uri http://localhost:8080/modules/recon.fingerprint/run `
+ -Uri http://127.0.0.1:8080/modules/recon.fingerprint/run `
-Headers $headers `
-ContentType "application/json" `
-Body '{
"campaign_id": "CAMPAIGN_ID",
- "params": { "target": "127.0.0.1" },
+ "target": "127.0.0.1",
+ "params": {},
"dry_run": true
}'
```
+Optional extras and native tools depend on the module family. The base
+dashboard/reporting workflow uses the `dev,pdf` baseline; install `.[ad]`,
+`.[cloud]`, `.[windows]`, or `.[full]` only when those modules are needed.
+
## Module Categories
| Category | Purpose | Typical Use |
diff --git a/docs/security-model.md b/docs/security-model.md
index ff493a2..2682e7b 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -118,6 +118,12 @@ and `Done` closes the modal and clears the in-memory new-key state. The key
list shows metadata and a prefix only; the full secret cannot be retrieved
later.
+API-key scopes are `read`, `write`, and `admin`. They are an additional
+restriction on API-key-compatible automation routes and do not replace RBAC.
+Use `X-API-Key` for automation endpoints such as `GET /auth/me`; account
+credential management, user registration, and API-key lifecycle operations are
+performed from an authenticated browser/JWT session.
+
**Unauthenticated endpoints** (by design):
- `POST /auth/token` — login (takes credentials, returns token)
- `GET /health` — health check (no sensitive data)
diff --git a/docs/validation-lab.md b/docs/validation-lab.md
index e564a59..64aecfc 100644
--- a/docs/validation-lab.md
+++ b/docs/validation-lab.md
@@ -1,7 +1,8 @@
# ARES Local Validation Lab
This lab is a safe local harness for checking ARES after UI or backend changes.
-It does not attack external systems. By default it only talks to `localhost:8080`.
+It does not attack external systems. By default it only talks to
+`127.0.0.1:8080`.
## What It Checks
@@ -46,13 +47,13 @@ lab.
```powershell
$env:ARES_LAB_PASSWORD="your-current-admin-password"
-.\.venv\Scripts\python.exe .\scripts\validation_lab.py --base-url http://localhost:8080 --username admin
+.\.venv\Scripts\python.exe .\scripts\validation_lab.py --base-url http://127.0.0.1:8080 --username admin
```
## Safety Guard
-The script refuses non-localhost URLs by default. For an explicitly authorized
-lab host only:
+The script refuses non-local URLs by default. For an explicitly authorized lab
+host only:
```powershell
.\.venv\Scripts\python.exe .\scripts\validation_lab.py --base-url http://127.0.0.1:8080