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: align dashboard guide with updated UI

Mafifrizi2e446180018b
diff --git a/QUICKSTART.md b/QUICKSTART.md
index fc0ad9d..f39feb0 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -73,7 +73,7 @@ What each value does:
| --- | --- | --- |
| `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. |
+| `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. |
For repeated local use, copy `.env.example` to `.env`, fill these values once, and start ARES from the same project directory.
@@ -108,6 +108,31 @@ Login with:
Then change the admin password from the `Security` page.
+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.
+
+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.
+
## 5. Create A Campaign
Open `Campaigns` and create a scoped campaign.
@@ -133,6 +158,13 @@ Open `Modules`:
4. Run with `Dry run` first when available.
5. Run live only when the target and scope are authorized.
+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.
+
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.
## 7. Generate Reports
@@ -198,6 +230,12 @@ curl http://localhost:8080/campaigns \
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.
@@ -264,7 +302,7 @@ The lab checks login, profile, campaign validation, dry-run validation, reports,
| 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 from docs. |
+| `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. |
diff --git a/README.md b/README.md
index 8b124a6..7d8f42c 100644
--- a/README.md
+++ b/README.md
@@ -89,20 +89,39 @@ Dashboard preview:
![ARES dashboard overview](docs/assets/screenshots/dashboard-overview.png)
+Dashboard shell:
+
+- The left sidebar routes between the major dashboard pages.
+- The topbar menu button collapses and expands the sidebar.
+- Topbar quick search is client-side navigation over the currently loaded
+ dashboard context: page names/routes, campaigns, modules, reports, and
+ templates. It is not a server-backed global search across unloaded historical
+ data.
+- The notification bell is the status surface. There is no separate topbar
+ status pill labeled `Offline` or `Live`.
+- The notification badge counts unread notifications only. Opening the drawer
+ marks visible notifications as read; individual dismiss and clear-all actions
+ remove notifications from the current session. The frontend stores only
+ notification state, not bodies, tokens, API keys, stack traces, or raw
+ payloads.
+- The topbar also shows the signed-in identity and logout action.
+- Page headers provide context, and page tabs switch the visible content for
+ the current section.
+
Dashboard areas:
| Page | Purpose |
| --- | --- |
-| Overview | Health, operator telemetry metrics, and campaign summary. |
-| Campaigns | Create, inspect, compare, restore, dry-run, and delete campaigns. |
-| Modules | Browse the module catalog and run backend-generated parameter forms. |
-| Reports | Generate, list, and download authenticated campaign reports with readable evidence tables. |
-| Graph | Review graph data, attack paths, and BloodHound ingest. |
-| Templates | Generate repeatable execution plans. |
-| Strategy | Start or review authorized goal-based planning. |
-| Security | Change password, manage API keys, review audit and users. |
-| EDR/OPSEC | Record bypass outcomes and review EDR/OPSEC telemetry. |
-| Live | Watch campaign WebSocket events. |
+| Overview | Health, operator telemetry metrics, and campaign summary. Overview has no variation tabs. |
+| Campaigns | `List`, `Scope`, and `Findings` tabs for campaign creation, inspection, compare/restore/dry-run actions, and cleanup. |
+| Modules | `Catalog`, `Run Panel`, and `Results` tabs for browsing modules, filling backend-generated parameter forms, and reviewing execution output. |
+| Reports | `Generate` and `Library` tabs for authenticated campaign report creation, listing, and download. |
+| Graph | `Entities`, `Attack Paths`, and `Ingest` tabs for graph review and BloodHound/SharpHound import. |
+| Templates | `Templates` and `Plan Builder` tabs for selecting built-in plans and generating reviewable execution stages. |
+| Strategy | `Objective`, `Active`, and `Result` tabs for authorized goal-based planning and state review. |
+| Security | `Account`, `API Keys`, and `Audit` tabs for password changes, API key lifecycle, audit output, and user review. |
+| EDR/OPSEC | `Knowledge Base` and `Report Outcome` tabs for defensive telemetry and controlled outcome records. |
+| Live | `Stream` and `Buffer` tabs for campaign WebSocket feedback and buffered event review. |
Recommended dashboard workflow:
@@ -124,7 +143,7 @@ Recommended dashboard workflow:
6. Use `Reports` to generate HTML, PDF, Markdown, or JSON output for a campaign.
PDF generation writes the PDF artifact directly; HTML is generated only when
you choose the HTML format. Report evidence is rendered as readable tables
- and key-value rows where possible instead of raw JSON blobs.
+ and key-value rows where possible instead of unformatted report objects.
7. Use `Security` for account administration. API keys are for scripts and
integrations; the Security Audit panel reports dependency-audit status for
the ARES environment, not findings from a target network.
@@ -163,6 +182,10 @@ Planning modes:
The ARES API key created in the `Security` page is not an OpenAI, Anthropic,
or Ollama key. It authenticates scripts and integrations to the ARES API.
LLM provider keys are configured separately in the ARES server environment.
+Creating an ARES API key opens the `Save your key` modal. The full secret is
+shown once, the `Copy` button changes to `Copied` after a successful copy, 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.
See [docs/dashboard-guide.md](docs/dashboard-guide.md).
@@ -182,6 +205,8 @@ See [docs/dashboard-guide.md](docs/dashboard-guide.md).
- Backend-driven module parameter schema.
- Dry-run default in the dashboard.
- OPSEC levels for module risk.
+- High-noise and sensitive modules remain guarded by authorization and
+ confirmation checks.
- MITRE ATT&CK metadata for reporting.
See [docs/modules.md](docs/modules.md).
@@ -206,6 +231,12 @@ empty. That bootstrap account is assigned the `team_lead` role and uses the
password provided in `ARES_DEFAULT_ADMIN_PASSWORD`. Change that password after
the first login.
+Bootstrap happens only when the user table is empty. Changing
+`ARES_DEFAULT_ADMIN_PASSWORD` after an `admin` user already exists does not
+reset that user's password. For local development, either change the password
+from the `Security` page after logging in or recreate the local database if you
+intend to discard existing local data.
+
Roles are assigned when a `team_lead` creates a user:
| Role | Intended use | Practical access |
@@ -288,7 +319,7 @@ The required values are:
| --- | --- | --- |
| `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. Change it after first login. |
+| `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:
@@ -316,6 +347,8 @@ 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:
diff --git a/docs/api-reference.md b/docs/api-reference.md
index bc10ee2..f995866 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -134,6 +134,8 @@ separate from deployment secrets such as `ARES_SECRET_KEY` and
```
> Store `raw_key` immediately — it is not recoverable after this response.
+> In the dashboard, the same one-time secret is shown in the `Save your key`
+> modal. The key list shows metadata and a prefix only.
---
@@ -524,6 +526,21 @@ and `WS /ws/campaigns/{campaign_id}/events?token=<token>`. Legacy
`/dashboard/api/*` and `/dashboard/ws/live` routes are not the primary data
source.
+Dashboard shell behavior:
+
+- The left sidebar routes between pages, and the topbar menu collapses or
+ expands it.
+- Topbar quick search is client-side navigation over currently loaded page
+ names/routes, campaigns, modules, reports, and templates. It is not a
+ server-backed global search over unloaded historical data.
+- The notification bell is the only topbar status surface. Its badge counts
+ unread notifications; opening the drawer marks visible items as read, and
+ dismiss/clear-all remove notifications from the current session.
+- Notification state does not store bodies, API keys, tokens, stack traces, or
+ raw payloads.
+- Overview has no variation tabs. Other pages use the tabs documented in
+ `docs/dashboard-guide.md`.
+
---
## Error Responses
diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md
index 8f2e2ae..ef437d5 100644
--- a/docs/dashboard-guide.md
+++ b/docs/dashboard-guide.md
@@ -22,6 +22,27 @@ keys, bearer tokens, or sensitive report URLs.
| Modules | `docs/assets/screenshots/dashboard-modules-catalog.png` | Module catalog filters, OPSEC labels, campaign selection, and parameter forms. |
| Reports | `docs/assets/screenshots/dashboard-reports.png` | Campaign report generation and artifact list. |
+## Dashboard Shell
+
+The dashboard shell has a left sidebar, a topbar, page headers, and page-level
+tabs.
+
+- Use the left sidebar to move between Overview, Campaigns, Modules, Reports,
+ Graph, Templates, Strategy, Security, EDR/OPSEC, and Live.
+- Use the topbar menu button to collapse or expand the sidebar.
+- Topbar quick search is client-side quick navigation over the currently
+ loaded dashboard context: page names/routes, campaigns, modules, reports, and
+ templates. It is not a server-backed global search across unloaded historical
+ data.
+- The notification bell is the status surface. The topbar no longer has a
+ separate status pill labeled `Offline` or `Live`.
+- The bell badge counts unread notifications only. Opening the drawer marks
+ visible notifications as read. Individual dismiss and clear-all remove
+ notifications from the current session.
+- Notification read/deleted state is frontend session state. The UI does not
+ store notification bodies, API keys, tokens, stack traces, or raw payloads.
+- The topbar also shows the signed-in identity and logout action.
+
## Login
Use the admin account created at startup or an account created by a team lead.
@@ -48,7 +69,12 @@ The first account is created automatically:
- Role: `team_lead`.
- Password source: `ARES_DEFAULT_ADMIN_PASSWORD`.
-Change the bootstrap password from the `Security` page after first login.
+This bootstrap account is created only when the user table is empty. Changing
+`ARES_DEFAULT_ADMIN_PASSWORD` after `admin` already exists does not reset the
+existing password. Change the bootstrap password from the `Security` page after
+first login. For disposable local development data, recreate the local
+database only when you intentionally want to discard existing users and
+campaign data.
Additional users are created by a `team_lead` through `POST /auth/register`.
The dashboard currently shows users in the `Security` page, but it does not
@@ -96,6 +122,21 @@ The dashboard keeps the active campaign, selected module, and recent result pane
The `Live` page uses a browser WebSocket session. Leaving the page closes that browser connection. When you return, select the campaign and reconnect to start listening again. The underlying campaign data remains in the backend; only the current browser stream session is temporary.
+Current page tabs:
+
+| Page | Tabs |
+| --- | --- |
+| Overview | No variation tabs; the page shows its current telemetry and campaign summary directly. |
+| 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` |
+| Live | `Stream`, `Buffer` |
+
## Pages
### Overview
@@ -114,6 +155,9 @@ Shows:
- Expandable raw telemetry snapshot for debugging.
- Campaign summary table.
+Overview does not have variation tabs; the accepted dashboard view is shown
+directly.
+
Use it to confirm the server is alive before running modules and to see whether
the current API process is actively recording module activity. Telemetry is
in-memory operational monitoring, not permanent campaign history. It resets
@@ -153,6 +197,8 @@ Purpose: run individual modules safely.
Use it for:
- Browse the loaded module catalog.
+- Render built-in module IDs, names, categories, OPSEC labels, and parameter
+ schemas from backend metadata.
- Filter by category and OPSEC level.
- Select a campaign.
- Fill module parameters generated by the backend schema.
@@ -326,7 +372,12 @@ API key behavior:
`ARES_SECRET_KEY` or `ARES_ENCRYPTION_KEY`.
- Use API keys for scripts, CI jobs, integrations, or validation labs that need
to call ARES with `X-API-Key` instead of a browser login.
-- The full key is shown only once at creation time.
+- Creating a key opens the `Save your key` modal.
+- The full secret is shown only once at creation time.
+- The `Copy` button changes to `Copied` after a successful copy.
+- `Done` closes the modal and clears the in-memory new-key state.
+- The list shows metadata and a prefix only; the full secret cannot be
+ retrieved later.
- After delete, revoked keys disappear from the list.
- Deleted keys cannot authenticate.
diff --git a/docs/frontend.md b/docs/frontend.md
index 3d1e871..b5be7c0 100644
--- a/docs/frontend.md
+++ b/docs/frontend.md
@@ -22,15 +22,31 @@ for the FastAPI backend.
## Routes
- `/` overview: health, telemetry, campaign summary
-- `/campaigns`: list, create, detail, delete, findings, CVSS, diff, restore, dry-run plan
-- `/modules`: catalog filters, backend-derived dynamic params, dry-run default
-- `/reports`: generate, list, and authenticated download for campaign reports
-- `/graph`: graph, attack paths, BloodHound ingest
-- `/templates`: list templates and generate plans
-- `/strategy`: active engagements and role-gated engagement start
-- `/security`: profile, password change, API keys, audit, users
-- `/edr`: bypass telemetry and outcome reporting
-- `/live`: `WS /ws/campaigns/{campaign_id}/events?token=<token>`
+- `/campaigns`: `List`, `Scope`, and `Findings` tabs for list/create/detail/delete, findings, CVSS, diff, restore, and dry-run plan actions
+- `/modules`: `Catalog`, `Run Panel`, and `Results` tabs for catalog filters, backend-derived dynamic params, dry-run default, and execution output
+- `/reports`: `Generate` and `Library` tabs for report creation, listing, and authenticated download
+- `/graph`: `Entities`, `Attack Paths`, and `Ingest` tabs for graph review, attack paths, and BloodHound ingest
+- `/templates`: `Templates` and `Plan Builder` tabs for listing templates and generating plans
+- `/strategy`: `Objective`, `Active`, and `Result` tabs for active engagements and role-gated engagement start
+- `/security`: `Account`, `API Keys`, and `Audit` tabs for profile, password change, API keys, audit, and users
+- `/edr`: `Knowledge Base` and `Report Outcome` tabs for bypass telemetry and outcome reporting
+- `/live`: `Stream` and `Buffer` tabs backed by `WS /ws/campaigns/{campaign_id}/events?token=<token>`
+
+## Shell Controls
+
+- The left sidebar handles route navigation.
+- The topbar menu button collapses and expands the sidebar.
+- Topbar quick search is client-side navigation over currently loaded page
+ names/routes, campaigns, modules, reports, and templates. It is not a
+ server-backed search across unloaded historical data.
+- The notification bell is the health/status surface. There is no separate
+ topbar status pill for online/offline state.
+- The bell badge counts unread notifications only. Opening the drawer marks
+ visible notifications as read; individual dismiss and clear-all remove
+ notifications from the current session.
+- Notification state must not persist bodies, API keys, tokens, stack traces,
+ or raw payloads.
+- The topbar keeps the user identity and logout action.
## Safety
diff --git a/docs/modules.md b/docs/modules.md
index c8c6f59..98a69d0 100644
--- a/docs/modules.md
+++ b/docs/modules.md
@@ -38,6 +38,12 @@ layer; the backend remains the enforcement boundary.
The module form is generated from backend metadata. That means new or updated
modules can expose their own parameters without hardcoding fields in React.
+The dashboard catalog uses the backend loader output for built-in module IDs,
+names, categories, OPSEC labels, and parameter schemas. High-noise or sensitive
+modules remain guarded by RBAC, scope checks, and explicit confirmation. Do not
+run destructive, credential theft, lateral movement, exfiltration,
+persistence, EDR bypass, or other noisy workflows without written
+authorization and a scoped campaign.
### API Flow
diff --git a/docs/security-model.md b/docs/security-model.md
index 18f9e95..372caa8 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -112,7 +112,11 @@ API keys are created after login from the Security page or
CI jobs, internal integrations, or repeatable local validation where an
interactive browser session is not practical. The raw API key is shown only
once at creation time, is stored hashed, and can be revoked from the Security
-page.
+page. In the dashboard, key creation opens the `Save your key` modal. The full
+secret appears there once, `Copy` changes to `Copied` after a successful copy,
+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.
**Unauthenticated endpoints** (by design):
- `POST /auth/token` — login (takes credentials, returns token)
@@ -142,6 +146,11 @@ The first account is bootstrapped as:
|----------|------|-----------------|
| `admin` | `team_lead` | `ARES_DEFAULT_ADMIN_PASSWORD` |
+ARES creates that account only when the user table is empty. Changing
+`ARES_DEFAULT_ADMIN_PASSWORD` after the `admin` account exists does not reset
+the password. Use the Security page after login for normal password changes,
+or recreate the local database only when disposable local data can be lost.
+
Additional accounts are created by a `team_lead` through `POST /auth/register`.
The role is assigned at creation time:
diff --git a/docs/validation-lab.md b/docs/validation-lab.md
index b75cbff..0a05147 100644
--- a/docs/validation-lab.md
+++ b/docs/validation-lab.md
@@ -37,6 +37,11 @@ $env:ARES_LAB_PASSWORD="replace-with-your-own-strong-admin-password"
If the admin password has been changed, put the current password in
`ARES_LAB_PASSWORD`.
+`ARES_DEFAULT_ADMIN_PASSWORD` is used only when ARES creates the first
+`admin` account in an empty user table. Changing that environment variable
+after a local admin already exists does not reset the password used by this
+lab.
+
## Direct Python
```powershell