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: clarify deployment secrets and API keys

Mafifrizi90fee683be7e
diff --git a/.env.example b/.env.example
index 3f27844..a759731 100644
--- a/.env.example
+++ b/.env.example
@@ -2,6 +2,9 @@
# Copy this to .env and fill in your values. NEVER commit .env to git.
# API Security
+# Generate this yourself per deployment. ARES does not provide a shared default.
+# Used to sign JWT/session security data. Keep private and never commit it.
+# Bash: openssl rand -hex 32
ARES_SECRET_KEY=CHANGE_ME_USE_openssl_rand_-hex_32
ARES_API_HOST=127.0.0.1
ARES_API_PORT=8080
@@ -28,7 +31,13 @@ ARES_DATABASE_URL=sqlite+aiosqlite:///./ares.db
# Run migrations first: alembic upgrade head
# ARES_DATABASE_URL=postgresql+asyncpg://ares_user:strong_password@db:5432/ares_db
-# Encryption key for stored campaign data
+# Encryption key for stored sensitive data
+# Generate this yourself per deployment. This must be a Fernet key.
+# Used for encrypted database/vault/checkpoint material.
+# Keep it stable and backed up securely; changing it after data exists can make
+# old encrypted records unreadable.
+# Generate:
+# python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
ARES_ENCRYPTION_KEY=CHANGE_ME_USE_Fernet_generate_key
# Legacy encryption salt — for DataEncryptor records written before v6
@@ -70,4 +79,6 @@ ARES_CORS_ORIGINS=http://localhost:3000,http://localhost:8080
ARES_TRUSTED_HOSTS=localhost,127.0.0.1
# ── Bootstrap Admin (change immediately after first startup) ──────────────────
+# You choose this password. It is only for creating the first admin account.
+# After first login, change it from the Security page.
ARES_DEFAULT_ADMIN_PASSWORD=YOUR_STRONG_ADMIN_PASSWORD_HERE
diff --git a/README.md b/README.md
index eaea9c0..18264e1 100644
--- a/README.md
+++ b/README.md
@@ -166,24 +166,44 @@ See [docs/validation-lab.md](docs/validation-lab.md).
### 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. Change it after first login. |
+
PowerShell:
```powershell
-$env:ARES_SECRET_KEY="local-dev-secret-key-32-chars-minimum!!"
-$env:ARES_ENCRYPTION_KEY="local-dev-encryption-key-32-chars!!"
-$env:ARES_DEFAULT_ADMIN_PASSWORD="ChangeMe123!Secure"
+$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 -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="local-dev-secret-key-32-chars-minimum!!"
-export ARES_ENCRYPTION_KEY="local-dev-encryption-key-32-chars!!"
-export ARES_DEFAULT_ADMIN_PASSWORD="ChangeMe123!Secure"
+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"
```
-For production, use generated high-entropy values and rotate the bootstrap
-admin password immediately after first login.
+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.
### 2. Start the API and Dashboard
@@ -230,7 +250,7 @@ ok 6.0.0 connected
### 4. Run the Local Validation Lab
```powershell
-$env:ARES_LAB_PASSWORD="ChangeMe123!Secure"
+$env:ARES_LAB_PASSWORD="replace-with-your-current-admin-password"
.\scripts\run_validation_lab.ps1
```
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 067e02b..e499070 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -80,6 +80,11 @@ Change password for the authenticated user.
Create an API key for the authenticated user.
+API keys are generated inside ARES after a user has authenticated. They are for
+automation and integrations that call API endpoints with `X-API-Key`. They are
+separate from deployment secrets such as `ARES_SECRET_KEY` and
+`ARES_ENCRYPTION_KEY`, which must be generated by the deployer before startup.
+
```json
{ "name": "CI pipeline key" }
```
diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md
index 8c91bfb..0cd51af 100644
--- a/docs/dashboard-guide.md
+++ b/docs/dashboard-guide.md
@@ -148,6 +148,10 @@ Use it for:
API key behavior:
+- API keys are created after login; they are not the same thing as
+ `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.
- After delete, revoked keys disappear from the list.
- Deleted keys cannot authenticate.
@@ -194,4 +198,3 @@ Use it for:
| `429 Global rate limit exceeded` | Too many rapid requests. | Wait a moment and retry. |
| Campaign remains after delete | Browser cache or old server process. | Restart ARES and press `Ctrl+F5`. |
| Report PDF returns HTML | PDF dependency is not installed. | Install optional PDF extra in a controlled environment. |
-
diff --git a/docs/security-model.md b/docs/security-model.md
index c0e9d87..ae03c3c 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -33,19 +33,26 @@ ARES is an offensive framework. This document explains how ARES protects the **o
| Data | Algorithm | Key Source |
|------|-----------|------------|
-| Credential vault | Fernet (AES-128-CBC + HMAC-SHA256) | `secret_key` in settings (SHA-256 derived) |
+| Credential vault | Fernet (AES-128-CBC + HMAC-SHA256) | `ARES_ENCRYPTION_KEY` |
| Campaign checkpoints | Fernet | Same key |
| Evidence files | Fernet | Same key |
| API tokens | bcrypt (cost=12) | N/A (one-way hash) |
-**Key management:** The `secret_key` is loaded from environment variable `ARES_SECRET_KEY`. Never store it in version control. Rotate it by re-encrypting all vault entries.
+**Key management:** ARES uses two separate deployment secrets. The deployer or
+client generates both; ARES does not ship a shared production key.
```bash
-# Generate a strong key
-python3 -c "import secrets; print(secrets.token_hex(32))"
-export ARES_SECRET_KEY=<output>
+# Token/session signing key
+export ARES_SECRET_KEY="$(openssl rand -hex 32)"
+
+# Encryption key for vault, checkpoint, and stored sensitive material
+export ARES_ENCRYPTION_KEY="$(python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
```
+Never store these values in version control. Keep `ARES_ENCRYPTION_KEY` stable
+and backed up securely; rotating it requires re-encrypting existing vault and
+stored sensitive records.
+
### In Transit
- REST API: HTTPS (TLS 1.2+) — use a reverse proxy (nginx/caddy)
@@ -100,6 +107,13 @@ or:
X-API-Key: ares_...
```
+API keys are created after login from the Security page or
+`POST /auth/api-keys`. They are not startup secrets. Use them for scripts,
+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.
+
**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 df465a2..b75cbff 100644
--- a/docs/validation-lab.md
+++ b/docs/validation-lab.md
@@ -19,16 +19,18 @@ It does not attack external systems. By default it only talks to `localhost:8080
Start ARES first:
```powershell
-$env:ARES_SECRET_KEY="local-dev-secret-key-32-chars-minimum!!"
-$env:ARES_ENCRYPTION_KEY="local-dev-encryption-key-32-chars!!"
-$env:ARES_DEFAULT_ADMIN_PASSWORD="ChangeMe123!Secure"
+$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 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+$env:ARES_DEFAULT_ADMIN_PASSWORD = "replace-with-your-own-strong-admin-password"
.\.venv\Scripts\ares-api.exe
```
In another PowerShell:
```powershell
-$env:ARES_LAB_PASSWORD="ChangeMe123!Secure"
+$env:ARES_LAB_PASSWORD="replace-with-your-own-strong-admin-password"
.\scripts\run_validation_lab.ps1
```