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.

fix: enforce API key scopes

Mafifrizi47852da2c3d4
diff --git a/ares/api/server.py b/ares/api/server.py
index f57b852..14aae1b 100644
--- a/ares/api/server.py
+++ b/ares/api/server.py
@@ -10,7 +10,7 @@ v6.0.0 changes vs v1.0.0:
✓ WebSocket /ws/campaigns/{id}/events — real-time module progress
✓ Pagination on /campaigns, /campaigns/{id}/findings
✓ X-RateLimit-Remaining + X-Total-Count response headers
- ✓ POST /auth/change-password, GET /auth/api-keys CRUD
+ ✓ JWT-only account management and API-key lifecycle endpoints
"""
from __future__ import annotations
@@ -455,11 +455,48 @@ async def get_current_user_or_apikey(
db = get_db(request)
data = await db.verify_api_key(api_key)
if data:
- return AuthenticatedUser(username=data["username"], role=data["role"])
+ return AuthenticatedUser(
+ username=data["username"],
+ role=data["role"],
+ auth_type="api_key",
+ api_key_id=data.get("key_id") or data.get("id"),
+ api_key_scopes=_normalize_api_key_scopes(data.get("scopes")),
+ )
raise HTTPException(401, "Not authenticated. Provide Bearer token or X-API-Key.")
-_current_user_or_apikey_dep = Depends(get_current_user_or_apikey)
+def _normalize_api_key_scopes(raw_scopes: Any) -> tuple[str, ...]:
+ if raw_scopes is None:
+ return ()
+ if isinstance(raw_scopes, str):
+ return tuple(
+ scope.strip()
+ for scope in raw_scopes.replace(",", " ").split()
+ if scope.strip()
+ )
+ if isinstance(raw_scopes, (list, tuple, set)):
+ return tuple(str(scope).strip() for scope in raw_scopes if str(scope).strip())
+ return ()
+
+
+def require_api_key_scope(*allowed_scopes: str) -> Any:
+ async def _check(
+ actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ ) -> AuthenticatedUser:
+ if actor.is_api_key and not actor.has_api_scope(*allowed_scopes):
+ raise HTTPException(
+ 403,
+ "API key scope insufficient. "
+ f"Required one of: {', '.join(allowed_scopes)}",
+ )
+ return actor
+
+ return _check
+
+
+_api_key_read_dep = Depends(require_api_key_scope("read", "write", "admin"))
+_api_key_write_dep = Depends(require_api_key_scope("write", "admin"))
+_current_user_or_apikey_dep = _api_key_read_dep
_db_dep = Depends(get_db)
@@ -597,7 +634,7 @@ async def refresh_access_token(
@app.post("/auth/logout", tags=["auth"])
async def logout(
request: Request,
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = Depends(require_any_auth()),
settings: AresSettings = Depends(get_settings),
db: AresDatabase = Depends(get_db),
) -> dict[str, str]:
@@ -704,7 +741,7 @@ class ChangePasswordRequest(BaseModel):
async def change_password(
request: Request,
body: ChangePasswordRequest,
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = Depends(require_any_auth()),
settings: AresSettings = Depends(get_settings),
db: AresDatabase = Depends(get_db),
) -> dict[str, str]:
@@ -744,7 +781,7 @@ async def change_password(
@app.get("/auth/me", tags=["auth"])
async def whoami(
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_read_dep,
) -> dict:
return {"username": actor.username, "role": actor.role}
@@ -761,7 +798,7 @@ class CreateAPIKeyRequest(BaseModel):
@app.post("/auth/api-keys", tags=["auth"])
async def create_api_key(
body: CreateAPIKeyRequest,
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = Depends(require_any_auth()),
db: AresDatabase = Depends(get_db),
) -> dict[str, str]:
"""Create API key for CI/CD automation. Key is shown ONCE — save it."""
@@ -782,7 +819,7 @@ async def create_api_key(
@app.get("/auth/api-keys", tags=["auth"])
async def list_api_keys(
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = Depends(require_any_auth()),
db: AresDatabase = Depends(get_db),
) -> list[dict]:
user = await db.get_user(actor.username)
@@ -794,7 +831,7 @@ async def list_api_keys(
@app.delete("/auth/api-keys/{key_id}", tags=["auth"])
async def revoke_api_key(
key_id: str,
- actor: AuthenticatedUser = Depends(get_current_user),
+ actor: AuthenticatedUser = Depends(require_any_auth()),
db: AresDatabase = Depends(get_db),
) -> dict[str, str]:
user = await db.get_user(actor.username)
@@ -935,7 +972,7 @@ async def create_campaign(
async def list_campaigns(
page: int = Query(1, ge=1),
per_page: int = Query(50, ge=1, le=200),
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_read_dep,
db: AresDatabase = Depends(get_db),
) -> JSONResponse:
"""List campaigns with pagination. Returns X-Total-Count header.
@@ -957,7 +994,7 @@ async def list_campaigns(
@app.get("/campaigns/{campaign_id}", tags=["campaigns"])
async def get_campaign(
campaign_id: str,
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_read_dep,
db: AresDatabase = Depends(get_db),
) -> dict[str, Any]:
c = await db.get_campaign(campaign_id)
@@ -1044,7 +1081,7 @@ async def list_findings(
per_page: int = Query(50, ge=1, le=500),
severity: str | None = Query(None, pattern="^(critical|high|medium|low|info)$"),
false_positive: bool | None = None,
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_read_dep,
db: AresDatabase = Depends(get_db),
) -> JSONResponse:
"""Paginated findings. Filters: severity, false_positive."""
@@ -1070,7 +1107,7 @@ async def list_findings(
@app.get("/modules", tags=["modules"])
async def list_modules(
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_read_dep,
engine: AresEngine = Depends(get_engine),
) -> list[dict]:
from ares.modules.params import MODULE_PARAMS
@@ -1636,7 +1673,7 @@ async def _broadcast_event(campaign_id: str, event: dict[str, Any]) -> None:
@app.get("/campaigns/{campaign_id}/cvss", tags=["campaigns"])
async def get_cvss_summary(
campaign_id: str,
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_read_dep,
db: AresDatabase = Depends(get_db),
) -> dict[str, Any]:
"""CVSS v3.1 score summary for a campaign — for compliance reports (PCI-DSS, ISO 27001)."""
@@ -1785,7 +1822,7 @@ def _delete_report_artifacts_for_campaign(campaign_id: str) -> int:
async def generate_report(
campaign_id: str,
fmt: str = Query("html", pattern="^(html|pdf|markdown|json)$"),
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_write_dep,
_rate: None = Depends(rate_limit("report")),
db: AresDatabase = Depends(get_db),
) -> dict[str, str]:
@@ -1876,7 +1913,7 @@ async def download_report(
@app.get("/telemetry", tags=["telemetry"])
async def get_telemetry(
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_read_dep,
) -> dict[str, Any]:
from ares.telemetry.collector import get_collector
@@ -1885,7 +1922,7 @@ async def get_telemetry(
@app.get("/telemetry/prometheus", tags=["telemetry"])
async def get_prometheus(
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_read_dep,
) -> Any:
from fastapi.responses import PlainTextResponse
@@ -1903,7 +1940,7 @@ async def get_prometheus(
@app.get("/graph/{campaign_id}", tags=["visualization"])
async def campaign_graph(
campaign_id: str,
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_read_dep,
db: AresDatabase = Depends(get_db),
) -> dict[str, Any]:
from ares.api.graph import build_campaign_graph
@@ -1924,7 +1961,7 @@ async def campaign_attack_paths(
top_n: int = 5,
source: str | None = None,
target: str | None = None,
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_read_dep,
db: AresDatabase = Depends(get_db),
) -> dict[str, Any]:
"""
@@ -2222,7 +2259,7 @@ def _diff_findings(
@app.get("/templates", tags=["campaigns"])
async def list_templates(
- actor: AuthenticatedUser = Depends(get_current_user_or_apikey),
+ actor: AuthenticatedUser = _api_key_read_dep,
) -> list[dict]:
"""List available campaign templates."""
from ares.core.engine import list_campaign_templates
diff --git a/tests/unit/test_api_endpoints.py b/tests/unit/test_api_endpoints.py
index 3e25506..c72cd56 100644
--- a/tests/unit/test_api_endpoints.py
+++ b/tests/unit/test_api_endpoints.py
@@ -18,6 +18,7 @@ from __future__ import annotations
import asyncio
import os
+from types import SimpleNamespace
from typing import Any
from unittest.mock import AsyncMock, MagicMock
@@ -55,6 +56,27 @@ def _auth(username: str, role: str) -> dict:
return {"Authorization": f"Bearer {_make_token(username, role)}"}
+def _api_key_headers(raw_key: str = "ares_test_api_key") -> dict:
+ return {"X-API-Key": raw_key}
+
+
+def _api_key_record(
+ scopes: str | list[str],
+ *,
+ username: str = "admin",
+ role: str = "team_lead",
+ key_id: str = "api-key-1",
+) -> dict[str, Any]:
+ scope_list = [scopes] if isinstance(scopes, str) else scopes
+ return {
+ "username": username,
+ "role": role,
+ "auth_type": "api_key",
+ "key_id": key_id,
+ "scopes": scope_list,
+ }
+
+
def _make_mock_db():
db = MagicMock()
db.verify_user = AsyncMock(return_value=None)
@@ -273,6 +295,203 @@ class TestAuthFlow:
# ── RBAC enforcement ──────────────────────────────────────────────────────────
+class TestAPIKeyScopeEnforcement:
+ def setup_method(self):
+ _reset_rate_limiter()
+
+ @pytest.mark.asyncio
+ async def test_api_key_identity_preserves_metadata(self, aclient):
+ _, db, _ = aclient
+ from ares.api.server import get_current_user_or_apikey
+
+ db.verify_api_key.return_value = _api_key_record(["read", "write"])
+ request = SimpleNamespace(
+ headers=_api_key_headers(),
+ app=SimpleNamespace(state=SimpleNamespace(db=db)),
+ )
+
+ actor = await get_current_user_or_apikey(request, bearer=None)
+
+ assert actor.username == "admin"
+ assert actor.role == "team_lead"
+ assert actor.auth_type == "api_key"
+ assert actor.is_api_key
+ assert actor.api_key_id == "api-key-1"
+ assert actor.api_key_scopes == ("read", "write")
+
+ @pytest.mark.asyncio
+ async def test_read_scoped_api_key_cannot_generate_report(self, aclient):
+ c, db, _ = aclient
+ db.verify_api_key.return_value = _api_key_record("read")
+ db.get_campaign.reset_mock()
+
+ r = await c.post("/reports/camp-api-key", headers=_api_key_headers())
+
+ assert r.status_code == 403
+ db.get_campaign.assert_not_called()
+
+ @pytest.mark.asyncio
+ async def test_write_scoped_api_key_can_generate_report_when_campaign_access_allows(
+ self, aclient, tmp_path, monkeypatch
+ ):
+ c, db, _ = aclient
+ import ares.modules.reporting.report_gen as report_gen
+
+ db.verify_api_key.return_value = _api_key_record("write")
+ db.audit.reset_mock()
+ db.get_campaign.return_value = {
+ "id": "camp-api-key",
+ "name": "API Key Campaign",
+ "client": "Internal",
+ "operator": "admin",
+ "targets": [],
+ "scope": [],
+ }
+
+ class FakeReportGenerator:
+ def generate(self, campaign, fmt="html"):
+ path = tmp_path / f"{campaign.id}_report.{fmt}"
+ path.write_text("report", encoding="utf-8")
+ return path
+
+ monkeypatch.setattr(report_gen, "ReportGenerator", FakeReportGenerator)
+
+ r = await c.post(
+ "/reports/camp-api-key?fmt=html",
+ headers=_api_key_headers(),
+ )
+
+ assert r.status_code == 200
+ assert r.json()["filename"] == "camp-api-key_report.html"
+ db.audit.assert_awaited()
+
+ @pytest.mark.asyncio
+ async def test_write_scoped_api_key_does_not_bypass_campaign_access(self, aclient):
+ c, db, _ = aclient
+ db.verify_api_key.return_value = _api_key_record(
+ "write", username="reporter_user", role="reporter"
+ )
+ db.get_campaign.return_value = {
+ "id": "camp-api-key",
+ "name": "API Key Campaign",
+ "operator": "admin",
+ }
+
+ r = await c.post(
+ "/reports/camp-api-key?fmt=html",
+ headers=_api_key_headers(),
+ )
+
+ assert r.status_code == 404
+
+ @pytest.mark.asyncio
+ async def test_jwt_auth_generate_report_unchanged(
+ self, aclient, tmp_path, monkeypatch
+ ):
+ c, db, _ = aclient
+ import ares.modules.reporting.report_gen as report_gen
+
+ db.is_access_token_revoked.return_value = False
+ db.get_campaign.return_value = {
+ "id": "camp-jwt",
+ "name": "JWT Campaign",
+ "client": "Internal",
+ "operator": "admin",
+ "targets": [],
+ "scope": [],
+ }
+
+ class FakeReportGenerator:
+ def generate(self, campaign, fmt="html"):
+ path = tmp_path / f"{campaign.id}_report.{fmt}"
+ path.write_text("report", encoding="utf-8")
+ return path
+
+ monkeypatch.setattr(report_gen, "ReportGenerator", FakeReportGenerator)
+
+ r = await c.post(
+ "/reports/camp-jwt?fmt=html",
+ headers=_auth("admin", "team_lead"),
+ )
+
+ assert r.status_code == 200
+ assert r.json()["filename"] == "camp-jwt_report.html"
+
+ @pytest.mark.parametrize(
+ ("method", "path", "kwargs"),
+ [
+ (
+ "post",
+ "/auth/change-password",
+ {
+ "json": {
+ "current_password": "CurrentPassword123!",
+ "new_password": "NewPassword123!",
+ }
+ },
+ ),
+ (
+ "post",
+ "/auth/api-keys",
+ {"json": {"name": "ci", "scopes": "admin"}},
+ ),
+ ("get", "/auth/api-keys", {}),
+ ("delete", "/auth/api-keys/api-key-1", {}),
+ ("post", "/auth/logout", {}),
+ ],
+ )
+ @pytest.mark.asyncio
+ async def test_api_key_cannot_manage_account_or_api_key_lifecycle(
+ self, aclient, method, path, kwargs
+ ):
+ c, db, _ = aclient
+ db.verify_api_key.return_value = _api_key_record("admin")
+
+ r = await getattr(c, method)(path, headers=_api_key_headers(), **kwargs)
+
+ assert r.status_code == 401
+
+ @pytest.mark.asyncio
+ async def test_jwt_auth_can_create_list_and_delete_api_keys(self, aclient):
+ c, db, _ = aclient
+ db.is_access_token_revoked.return_value = False
+ db.get_user.return_value = {"id": "user-1", "username": "admin"}
+ db.create_api_key = AsyncMock(
+ return_value=("api-key-1", "ares_created_secret_value")
+ )
+ db.list_api_keys = AsyncMock(
+ return_value=[
+ {
+ "id": "api-key-1",
+ "name": "ci",
+ "key_prefix": "ares_created",
+ "scopes": "read",
+ }
+ ]
+ )
+ db.revoke_api_key = AsyncMock(return_value=True)
+
+ headers = _auth("admin", "team_lead")
+ create = await c.post(
+ "/auth/api-keys",
+ headers=headers,
+ json={"name": "ci", "scopes": "read"},
+ )
+ listed = await c.get("/auth/api-keys", headers=headers)
+ deleted = await c.delete("/auth/api-keys/api-key-1", headers=headers)
+
+ assert create.status_code == 200
+ assert create.json()["key"] == "ares_created_secret_value"
+ assert listed.status_code == 200
+ item = listed.json()[0]
+ assert item["key_prefix"] == "ares_created"
+ assert "key" not in item
+ assert "raw_key" not in item
+ assert "key_hash" not in item
+ assert deleted.status_code == 200
+ assert deleted.json() == {"status": "revoked"}
+
+
class TestRBACEnforcement:
def setup_method(self):
_reset_rate_limiter()
diff --git a/tests/unit/test_core_infrastructure.py b/tests/unit/test_core_infrastructure.py
index 519bc3d..c1d13bd 100644
--- a/tests/unit/test_core_infrastructure.py
+++ b/tests/unit/test_core_infrastructure.py
@@ -288,6 +288,9 @@ class TestAresDatabase:
# List
keys = await db.list_api_keys(uid)
assert len(keys) >= 1
+ assert all("key_hash" not in key for key in keys)
+ assert all("key" not in key and "raw_key" not in key for key in keys)
+ assert raw_key not in repr(keys)
# Revoke
key_id = keys[0]["id"]
revoked = await db.revoke_api_key(key_id, uid)