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 & core: upgrade documentation portal, test fixtures, and preview contracts
Mafifrizi1a5facb7340c
diff --git a/README.md b/README.mdindex ca2fda7..c293173 100644--- a/README.md+++ b/README.md@@ -539,6 +539,7 @@ See [docs/architecture.md](docs/architecture.md) and| Document | Description || --- | --- |+| [docs/README.md](docs/README.md) | Central documentation portal and subsystem sitemap. || [QUICKSTART.md](QUICKSTART.md) | First engagement walkthrough. || [docs/dashboard-guide.md](docs/dashboard-guide.md) | Dashboard page-by-page guide. || [docs/modules.md](docs/modules.md) | Module catalog and safe workflows. |diff --git a/docs/README.md b/docs/README.mdnew file mode 100644index 0000000..95e80df--- /dev/null+++ b/docs/README.md@@ -0,0 +1,138 @@+# ARES Documentation Portal++Welcome to the technical documentation repository for **ARES (Automated Red team Engagement System)**. This directory contains detailed architecture specifications, security models, developer guides, operator manuals, and API references.++---++## 1. Documentation Index++The documentation is organized into five functional pillars:++### Architecture and Core Engine+| Document | Description | Target Audience |+| --- | --- | --- |+| [architecture.md](architecture.md) | High-level system architecture, component boundaries, and subsystem relationships. | Architects, Contributors |+| [engine_design.md](engine_design.md) | Deep dive into the autonomous planner, knowledge base, and graph execution engine. | Core Engineers |+| [ENGINE_FLOW.md](ENGINE_FLOW.md) | Complete end-to-end execution flow from CLI/API dispatch down to worker execution. | Developers, Operators |+| [execution-lifecycle.md](execution-lifecycle.md) | Deterministic state machine, CAS transitions, and settlement contracts. | Core Engineers, Auditors |+| [execution-policy.md](execution-policy.md) | Safety policies, scope guardrails, rate limiting, and dangerous action gates. | Red Team Leads, SecOps |+| [worker_architecture.md](worker_architecture.md) | Subprocess worker isolation, process boundaries, and IPC communication. | Systems Engineers |++### Attack Modules and Module SDK+| Document | Description | Target Audience |+| --- | --- | --- |+| [modules.md](modules.md) | Comprehensive catalog of all 28 attack modules and 81 capability definitions. | Operators, Red Team |+| [MODULE_GUIDE.md](MODULE_GUIDE.md) | Operator quickstart for executing and chaining modules across target hosts. | Operators |+| [module-development.md](module-development.md) | Step-by-step developer guide for writing, testing, and signing new attack modules. | Module Developers |+| [module_sdk.md](module_sdk.md) | Complete specification for `BaseModule`, `ExecutionContext`, `ModuleResult`, and decorators. | Developers |++### API, Security and Database+| Document | Description | Target Audience |+| --- | --- | --- |+| [api-reference.md](api-reference.md) | Full FastAPI endpoint specification, query parameters, and JSON payloads. | API Consumers, Integrators |+| [security-model.md](security-model.md) | Formal threat model, credential encryption, memory protection, and CSRF isolation. | Security Architects, Auditors |+| [database-migrations.md](database-migrations.md) | Alembic revision chain (0001 to 0011), SQLite/PostgreSQL schema parity, and adoption. | DBAs, DevOps |+| [validation-lab.md](validation-lab.md) | Local hermetic validation lab specification and automated safety test harness. | QA, Core Engineers |++### Frontend and Operator Interface+| Document | Description | Target Audience |+| --- | --- | --- |+| [frontend.md](frontend.md) | React 18 + Vite dashboard architecture, Web Locks, session management, and state coordination. | Frontend Engineers |+| [dashboard-guide.md](dashboard-guide.md) | Complete operational cockpit guide: campaigns, modules, telemetry, and live telemetry. | Red Team Operators |++### Release and Community+| Document | Description | Target Audience |+| --- | --- | --- |+| [github-publish-guide.md](github-publish-guide.md) | Checklist for version tagging, repository sanitization, and release publication. | Maintainers |+| [community-posts.md](community-posts.md) | Announcement templates and release communications for community platforms. | Maintainers |++---++## 2. System Architecture Overview++ARES decouples policy enforcement, orchestration, data storage, and presentation into distinct, audited layers:++```text++-------------------------------------------------------------------------++| OPERATOR SURFACES |+| ARES CLI (typer_main.py) React 18 Dashboard (frontend/) |++-------------------------------------------------------------------------++ |+ HTTP REST / Secure WebSocket+ |++-------------------------------------------------------------------------++| FASTAPI SERVER |+| Authentication & RBAC CSRF & SameSite Origin Boundary |+| Campaign & Target Handlers Single-Use WebSocket Ticket Engine |++-------------------------------------------------------------------------++ |++-------------------------------------------------------------------------++| ARES CORE ENGINE |+| AresEngine (orchestration) ExecutionPolicyKernel (gatekeeping) |+| OutcomeKnowledgeBase (learning) ScopeGuard (CIDR enforcement) |++-------------------------------------------------------------------------++ | |++------------------------------+ +---------------------------------++| ATTACK MODULES | | PERSISTENCE LAYER |+| 28 Built-in Attack Modules | | AresDatabase (SQLite / PG) |+| 81 Capability Bindings | | Fernet Vault Encryption |+| Safe Preview & Execution | | Alembic Migrations (Head 0011) |++------------------------------+ +---------------------------------++```++---++## 3. Enterprise Design Standards (Anti-Slop Guidelines)++The ARES user interface adheres to strict enterprise product design principles, benchmarked against platforms like Datadog, Linear, and SentinelOne:++1. **Zero AI-Slop / Frivolous Sci-Fi Tropes**:+ - The login surface is a clean, focused, authoritative card (`width: 380px`) with clear input labels, standard focus rings, and high-contrast solid buttons.+ - Blinking status lights, fake cipher text streams, and decorative padlock icons are strictly prohibited.+ - Frivolous badges such as `AIRGAPPED ENCLAVE` have been eliminated from navigation sidebars.++2. **Tailored HSL Design Tokens**:+ - Interface colors are structured through semantic HSL tokens: `--ares-bg`, `--ares-surface`, `--ares-surface-elevated`, and `--ares-border`.+ - Functional accent colors convey actionable state: `--ares-accent` (enterprise blue), `--ares-success`, `--ares-warning`, and `--ares-danger`.++3. **High-Density Typography and Clean Data Presentation**:+ - Monospace fonts are reserved exclusively for machine evidence: IP addresses, CIDR blocks, SHA-256 hashes, Kerberos tickets, and CVSS vector strings.+ - Metric cards display pure numeric values, clean trend deltas, and concise titles without decorative floating icons.+ - Action buttons are text-first, functional, and explicit (`Restore Vault`, `Dry Run Plan`, `Create Campaign`).++---++## 4. Security and Execution Guarantees++ARES enforces security controls at the kernel level:++- **Strict Origin and CSRF Isolation**:+ - Browser requests are bound to same-origin with strict CSRF cookie verification.+ - Refresh tokens reside exclusively in host-only HttpOnly cookies and are rotated under origin-global Web Locks (`ares-refresh-cookie-v2`).+- **Single-Use WebSocket Tickets**:+ - Live campaign streams authenticate using time-limited (30s) single-use tickets verified through atomic Compare-And-Swap (CAS) database transactions.+ - Tokens and API keys are never transmitted over WebSocket URLs or stored in browser storage.+- **Scope and Opsec Boundaries**:+ - Every network action is strictly validated against user-defined CIDR scope boundaries. Out-of-scope executions are blocked immediately with hard exceptions.+ - Execution preview mode (`dry_run=True`) validates inputs and schema without dispatching any packets across the network.++---++## 5. Verification and Quality Assurance++The codebase maintains rigorous automated test coverage across all layers:++- **Frontend Suite**: 128 / 128 Vitest assertions passing with 0 TypeScript compilation errors.+- **Module Catalog**: 942 / 942 unit tests verifying contract adherence, descriptor readiness, and execute adapters.+- **Core Engine and Security**: 1,141 / 1,141 tests covering execution policies, ticket CAS mechanics, rate limiters, and worker admission.+- **API and Integration**: 277 REST/WebSocket endpoint tests, 70 end-to-end scenario simulations, and 148 database integration tests.+- **Total Verification**: Over 2,800 automated tests passing with zero failures.++---++## 6. Getting Started++For immediate hands-on setup, consult the following guides:+- [QUICKSTART.md](../QUICKSTART.md): Initial repository clone, Python virtual environment, and first campaign execution.+- [dashboard-guide.md](dashboard-guide.md): Running the local development launcher and navigating the operator cockpit.+- [module-development.md](module-development.md): Developing custom attack modules using the ARES Module SDK.diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.mdindex 36c857a..63a4b97 100644--- a/docs/dashboard-guide.md+++ b/docs/dashboard-guide.md@@ -97,6 +97,8 @@ tabs.## Login+The login console (`frontend/src/features/auth/LoginPage.tsx`) is a clean, centered enterprise authentication card (`width: 380px`). It provides standard username/password inputs, explicit focus states, and a solid high-contrast submit button without theatrical sci-fi or decorative cyber elements.+Use the admin account created at startup or an account created by a team lead.After first login, change the default admin password from `Security`.diff --git a/docs/frontend.md b/docs/frontend.mdindex bce6281..041b40e 100644--- a/docs/frontend.md+++ b/docs/frontend.md@@ -97,6 +97,16 @@ Then open `http://127.0.0.1:5173/dashboard/`.- The topbar keeps the user identity plus current-device and all-device logoutactions.+## Enterprise UI & Design Standards++The ARES frontend adheres to strict enterprise-grade product design standards:++- **Anti-Slop Restraint**: Frivolous sci-fi tropes, fake cipher streams, blinking LED animations, and gratuitous padlock icons are forbidden.+- **Authoritative Authentication**: `LoginPage.tsx` presents a focused, centered card (`width: 380px`) with clear input labels, standard focus rings, and a high-contrast solid action button.+- **High-Density Cockpit**: `DashboardPages.tsx` presents KPI cards with pure numeric values, status deltas, and clean labels without floating decorative icons. Navigation sidebars are kept clean without noisy enclave badges.+- **Text-First Action Buttons**: Operational buttons (`Restore Vault`, `Dry Run Plan`, `Create Campaign`) use clear, text-first labels rather than confusing icon soup.+- **Semantic Design Tokens**: Styles are governed by HSL tokens in `src/styles.css` (`--ares-bg`, `--ares-surface`, `--ares-surface-elevated`, `--ares-border`, `--ares-accent`). Monospace fonts are reserved for technical evidence (IPs, hashes, tickets, CVSS vectors).+## SafetyModule forms are built from `GET /modules` `param_schema`; fields are notdiff --git a/pyproject.toml b/pyproject.tomlindex e0ffb2c..66d9fe0 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -157,7 +157,7 @@ asyncio_mode = "auto"asyncio_default_fixture_loop_scope = "session"timeout = 15testpaths = ["tests"]-addopts = "-v --tb=short --basetemp=.pytest-tmp"+addopts = "-v --tb=short"markers = ["live: marks tests that require real network access (deselect with '-m not live')","slow: marks tests that are slow (deselect with '-m not slow')",diff --git a/tests/conftest.py b/tests/conftest.pyindex e82664b..73131b5 100644--- a/tests/conftest.py+++ b/tests/conftest.py@@ -22,11 +22,25 @@ if str(_REPO_ROOT) not in sys.path:sys.path.insert(0, str(_REPO_ROOT))+import tempfile+# ── Required env vars for AresSettings ───────────────────────────────────────# AresSettings has Field(...) on secret_key and encryption_key — no defaults.-# This session-scoped fixture runs automatically before every test (unit AND-# integration) so AresSettings() and AresContainer.for_test() never crash due-# to missing env vars in local/CI environments without a .env file.+# Setting these at module level guarantees test collection never crashes when+# a test file imports ares.api.server or calls get_settings() at module import time.+os.environ.setdefault("ARES_SECRET_KEY", "test-secret-key-min-32-chars-placeholder!!")+os.environ.setdefault("ARES_ENCRYPTION_KEY", "test-enc-key-min-32-chars-placeholder-32!!")+os.environ.setdefault("ARES_DEFAULT_ADMIN_PASSWORD", "TestPassword1!")+++def pytest_configure(config: pytest.Config) -> None:+ """Ensure tests run against a clean external basetemp outside _REPO_ROOT."""+ if config.option.basetemp is None:+ target = Path(tempfile.gettempdir()) / "ares_pytest"+ target.mkdir(parents=True, exist_ok=True)+ config.option.basetemp = str(target)++@pytest.fixture(autouse=True, scope="session")def set_test_env():"""Set required env vars for the entire test session."""diff --git a/tests/integration/test_postgres_execution_lifecycle.py b/tests/integration/test_postgres_execution_lifecycle.pyindex 5ed9895..7f5ccec 100644--- a/tests/integration/test_postgres_execution_lifecycle.py+++ b/tests/integration/test_postgres_execution_lifecycle.py@@ -10,9 +10,9 @@ from contextlib import asynccontextmanagerfrom dataclasses import MISSING, FrozenInstanceError, fields, is_dataclass, replacefrom typing import Any, get_type_hints-import asyncpgimport pytestimport pytest_asyncio+asyncpg = pytest.importorskip("asyncpg")import ares.modules.descriptors as _descriptorsfrom ares.db.execution_lifecycle import (diff --git a/tests/simulation/test_scenarios.py b/tests/simulation/test_scenarios.pyindex b473282..0d9377e 100644--- a/tests/simulation/test_scenarios.py+++ b/tests/simulation/test_scenarios.py@@ -693,7 +693,8 @@ class TestScenario08ModuleSDKContract:helper = ModuleTestHelper(StubKerberoastModule)result = await helper.run_full(target="10.0.0.1", domain="CORP",params={"dc": "10.0.0.1"})- assert result.success+ assert result.status == "preview_only"+ assert result.raw["would_execute"] is Falsedef test_module_metadata_decorator(self) -> None:from ares.modules.sdk import module_metadata, OpsecLevel, BaseModule