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: clarify deployment secrets and API keys
Mafifrizi90fee683be7e
diff --git a/.env.example b/.env.exampleindex 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 32ARES_SECRET_KEY=CHANGE_ME_USE_openssl_rand_-hex_32ARES_API_HOST=127.0.0.1ARES_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:8080ARES_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_HEREdiff --git a/README.md b/README.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdindex 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:8080Start 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```