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: explain user roles and registration

Mafifrizi392409bb6539
diff --git a/README.md b/README.md
index 243b54e..8968581 100644
--- a/README.md
+++ b/README.md
@@ -183,6 +183,51 @@ See [docs/modules.md](docs/modules.md).
See [docs/security-model.md](docs/security-model.md).
+### User Roles And Accounts
+
+ARES creates the first `admin` account automatically when the user table is
+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.
+
+Roles are assigned when a `team_lead` creates a user:
+
+| Role | Intended use | Practical access |
+| --- | --- | --- |
+| `team_lead` | Engagement lead or local administrator. | Full API access, user registration, security audit, campaign deletion, high-noise authorization, and normal operator work. |
+| `operator` | Day-to-day operator account. | Campaign workflows, module execution, reports, graph, artifacts, and standard validation flows. Cannot register users. |
+| `recon` | Low-risk review/recon identity. | Read-heavy access. The internal module permission matrix marks enumeration, fingerprint, and network modules as recon-safe, but the main dashboard execution endpoints are still operator-gated. |
+| `reporter` | Report reviewer or stakeholder account. | Read-only access to campaign/report/graph-style data. No module execution and no user administration. |
+
+Create additional users through the API while logged in as `team_lead`:
+
+```powershell
+$token = (Invoke-RestMethod `
+ -Method Post `
+ -Uri http://localhost: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://localhost:8080/auth/register `
+ -Headers $headers `
+ -ContentType "application/json" `
+ -Body (@{
+ username = "alice"
+ password = "StrongPass1!"
+ role = "operator"
+ } | ConvertTo-Json)
+```
+
+Valid role values are exactly `team_lead`, `operator`, `recon`, and `reporter`.
+Passwords must be at least 12 characters and include uppercase, lowercase,
+number, and special-character content. The current dashboard lists users in the
+Security page, but role assignment is done at account creation time through
+`POST /auth/register`.
+
### Reporting
- HTML, Markdown, and JSON report output.
diff --git a/docs/api-reference.md b/docs/api-reference.md
index e9826c8..32b8076 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -64,6 +64,45 @@ Create a new user. Requires `team_lead` role.
{ "username": "bob", "password": "StrongPass1!", "role": "operator" }
```
+Valid roles:
+
+| Role | Intended use |
+| --- | --- |
+| `team_lead` | Engagement lead/admin. Full API access, user registration, security audit, restricted authorization, campaign deletion, and normal operator work. |
+| `operator` | Day-to-day operator. Campaign/module/report workflows. Cannot register users. |
+| `recon` | Read-heavy recon identity. Internal module permissions mark enumeration, fingerprint, and network modules as recon-safe; main dashboard execution remains operator-gated. |
+| `reporter` | Read-only reporting/review account. No module execution or user administration. |
+
+Password requirements: minimum 12 characters with uppercase, lowercase, digit,
+and special-character content.
+
+PowerShell example:
+
+```powershell
+$token = (Invoke-RestMethod `
+ -Method Post `
+ -Uri http://localhost: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://localhost:8080/auth/register `
+ -Headers $headers `
+ -ContentType "application/json" `
+ -Body (@{
+ username = "bob"
+ password = "StrongPass1!"
+ role = "operator"
+ } | ConvertTo-Json)
+```
+
+The current dashboard lists users on the Security page, but user role
+assignment is done through this registration endpoint when the account is
+created.
+
---
### `POST /auth/change-password`
diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md
index c063455..55935b5 100644
--- a/docs/dashboard-guide.md
+++ b/docs/dashboard-guide.md
@@ -19,10 +19,62 @@ Roles:
| Role | Meaning |
| --- | --- |
-| `Team Lead` | Admin/operator lead. Can manage users, API keys, high-risk actions, and campaign deletion. |
-| `Operator` | Runs normal modules and campaign workflows. |
-| `Recon` | Lower-risk read and recon workflows. |
-| `Reporter` | Read-only reporting and review. |
+| `Team Lead` | Admin/operator lead. Full API access, user registration, security audit, campaign deletion, high-noise authorization, and normal operator work. |
+| `Operator` | Day-to-day operator. Can run normal campaign/module/report workflows but cannot register users. |
+| `Recon` | Read-heavy recon identity. The backend module permission matrix marks enumeration, fingerprint, and network modules as recon-safe; main dashboard execution paths are still operator-gated. |
+| `Reporter` | Read-only reporting and review. No module execution or user administration. |
+
+Role names in API requests must use lowercase values: `team_lead`,
+`operator`, `recon`, or `reporter`.
+
+### Creating Users And Assigning Roles
+
+The first account is created automatically:
+
+- Username: `admin`.
+- Role: `team_lead`.
+- Password source: `ARES_DEFAULT_ADMIN_PASSWORD`.
+
+Change the bootstrap password from the `Security` page after first login.
+
+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
+include a role editor. In the current release, the role is assigned when the
+account is created.
+
+PowerShell example:
+
+```powershell
+$token = (Invoke-RestMethod `
+ -Method Post `
+ -Uri http://localhost: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://localhost:8080/auth/register `
+ -Headers $headers `
+ -ContentType "application/json" `
+ -Body (@{
+ username = "bob"
+ password = "StrongPass1!"
+ role = "operator"
+ } | ConvertTo-Json)
+```
+
+Password rules:
+
+- Minimum 12 characters.
+- At least one uppercase letter.
+- At least one lowercase letter.
+- At least one digit.
+- At least one special character.
+
+To review users, open `Security` as a `team_lead` or call
+`GET /security/users` with a team-lead token.
## Pages
@@ -211,6 +263,14 @@ Use it for:
- Review security audit output.
- Review users.
+User management notes:
+
+- Only `team_lead` can create users.
+- The Security page lists users for review.
+- Assign a role by passing `role` to `POST /auth/register`.
+- The current release does not expose dashboard role editing for existing
+ users.
+
API key behavior:
- API keys are created after login; they are not the same thing as
diff --git a/docs/security-model.md b/docs/security-model.md
index ae03c3c..18f9e95 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -126,12 +126,42 @@ Tokens are issued by `POST /auth/token` with valid operator credentials (bcrypt-
### Authorization
-| Role | Endpoints |
-|------|-----------|
-| `team_lead` | All endpoints |
-| `operator` | `/campaign`, `/module`, `/artifacts`, `/report` |
-| `recon` | Read-only + enumeration module endpoints |
-| `reporter` | Read-only: `/campaign/{id}`, `/report` |
+ARES uses four account roles. Role values are lowercase in API requests:
+`team_lead`, `operator`, `recon`, and `reporter`.
+
+| Role | Intended use | Access model |
+|------|--------------|--------------|
+| `team_lead` | Engagement lead or local administrator. | Full API access, user registration, security audit, campaign deletion, restricted authorization, and normal operator work. |
+| `operator` | Day-to-day operator. | Campaign workflows, module execution, reports, graph, artifacts, and standard validation flows. Cannot register users. |
+| `recon` | Low-risk review/recon identity. | Read-heavy access. The module permission matrix marks enumeration, fingerprint, and network modules as recon-safe, but the main dashboard execution endpoints are still operator-gated in this release. |
+| `reporter` | Reviewer or stakeholder. | Read-only campaign/report/graph-style access. No module execution and no user administration. |
+
+The first account is bootstrapped as:
+
+| Username | Role | Password source |
+|----------|------|-----------------|
+| `admin` | `team_lead` | `ARES_DEFAULT_ADMIN_PASSWORD` |
+
+Additional accounts are created by a `team_lead` through `POST /auth/register`.
+The role is assigned at creation time:
+
+```http
+POST /auth/register
+Authorization: Bearer <team-lead-token>
+Content-Type: application/json
+
+{
+ "username": "alice",
+ "password": "StrongPass1!",
+ "role": "operator"
+}
+```
+
+Valid role values are `team_lead`, `operator`, `recon`, and `reporter`.
+Passwords must be at least 12 characters and include uppercase, lowercase,
+numeric, and special-character content. The Security dashboard can list users,
+but the current release does not expose a dashboard role editor for changing
+an existing account's role.
### Rate limiting