ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Python active-directorycloud-securitydefensive-validationfastapigood-first-issuemitre-attackopsecreactred-teamreportingsecurity
docs: add universal first-run workflow
Mafifrizif4b85325e1a2
diff --git a/QUICKSTART.md b/QUICKSTART.mdindex 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:```bashgit clone https://github.com/Mafifrizi/ARES.gitcd 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 .venvsource .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 LibraryOpen `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 reportartifacts 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 SDKUse 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 labRun 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.mdindex 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 ExistsOffensive 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 throughbrowser fallback for local environments that do not have WeasyPrint nativelibraries 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 pippackage; 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 .venvsource .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.mdindex 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 likescreen works; all sensitive data is fetched from the main authenticated APIroutes 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>`. Legacydiff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.mdindex 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 withPython 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 thepip package; use `ares doctor --pdf-smoke` to validate the active backend.diff --git a/docs/frontend.md b/docs/frontend.mdindex 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.mdindex 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 acampaign, define scope, run safe validation first, collect findings, thengenerate 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 ModelOnly 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:```powershellInvoke-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.mdindex 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 keylist shows metadata and a prefix only; the full secret cannot be retrievedlater.+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.mdindex e564a59..64aecfc 100644--- a/docs/validation-lab.md+++ b/docs/validation-lab.md@@ -1,7 +1,8 @@# ARES Local Validation LabThis 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