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
fix: enforce API key scopes
Mafifrizi47852da2c3d4
diff --git a/ares/api/server.py b/ares/api/server.pyindex 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_templatesdiff --git a/tests/unit/test_api_endpoints.py b/tests/unit/test_api_endpoints.pyindex 3e25506..c72cd56 100644--- a/tests/unit/test_api_endpoints.py+++ b/tests/unit/test_api_endpoints.py@@ -18,6 +18,7 @@ from __future__ import annotationsimport asyncioimport os+from types import SimpleNamespacefrom typing import Anyfrom 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.pyindex 519bc3d..c1d13bd 100644--- a/tests/unit/test_core_infrastructure.py+++ b/tests/unit/test_core_infrastructure.py@@ -288,6 +288,9 @@ class TestAresDatabase:# Listkeys = 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)# Revokekey_id = keys[0]["id"]revoked = await db.revoke_api_key(key_id, uid)