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.

9.8 KB
Raw Blame

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 six functional pillars:

Architecture and Core Engine

Document Description Target Audience
architecture.md High-level system architecture, component boundaries, and subsystem relationships. Architects, Contributors
engine_design.md Deep dive into the autonomous planner, knowledge base, and graph execution engine. Core Engineers
ENGINE_FLOW.md Complete end-to-end execution flow from CLI/API dispatch down to worker execution. Developers, Operators
execution-lifecycle.md Deterministic state machine, CAS transitions, and settlement contracts. Core Engineers, Auditors
execution-policy.md Safety policies, scope guardrails, rate limiting, and dangerous action gates. Red Team Leads, SecOps
worker_architecture.md Subprocess worker isolation, process boundaries, and IPC communication. Systems Engineers

Attack Modules and Module SDK

Document Description Target Audience
modules.md Comprehensive catalog of all 66 active attack modules (70 total) and capability definitions. Operators, Red Team
MODULE_GUIDE.md Operator quickstart for executing and chaining modules across target hosts. Operators
module-development.md Step-by-step developer guide for writing, testing with ModuleTestHarness, and signing attack modules. Module Developers
module_sdk.md Modern v2 SDK specification (BaseModule[P, R], Pydantic v2 params, testing harness, and AresClient). Developers, Integrators
mcp-server.md Universal Model Context Protocol (MCP) server architecture, 7 security guarantees, and multi-client setup. AI Engineers, Operators

API, Security and Database

Document Description Target Audience
api-reference.md Full FastAPI endpoint specification, query parameters, and JSON payloads. API Consumers, Integrators
security-model.md Formal threat model, credential encryption, memory protection, and CSRF isolation. Security Architects, Auditors
sso-setup.md Enterprise Multi-Tenant Single Sign-On (SAML 2.0 / OIDC), IdP federation, and setup. IAM Engineers, Admins
database-migrations.md Alembic revision chain (0001 to 0011), SQLite/PostgreSQL schema parity, and adoption. DBAs, DevOps
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 React 18 + Vite dashboard architecture, Web Locks, session management, and state coordination. Frontend Engineers
dashboard-guide.md Complete operational cockpit guide: campaigns, modules, tactical pivot graph & beacon console, and live telemetry. Red Team Operators

Release and Community

Document Description Target Audience
github-publish-guide.md Checklist for version tagging, repository sanitization, and release publication. Maintainers

Research Tracks and Architecture RFCs

Document Description Target Audience
linux-active-directory-tradecraft.md RFC 001 (Implemented): Cross-platform Linux Active Directory post-exploitation suite (SSSD cache harvesting, Kerberos ccache extraction, keytab abuse, Samba secrets, ticket converter). Offensive Researchers, Red Team

2. System Architecture Overview

ARES decouples policy enforcement, orchestration, data storage, and presentation into distinct, audited layers:

+-------------------------------------------------------------------------+
|                         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)   ScopeFirewall (Egress Scope Wall)   |
+-------------------------------------------------------------------------+
        |                                                 |
+------------------------------+        +---------------------------------+
|      ATTACK MODULES          |        |        PERSISTENCE LAYER        |
|  66 Active Attack Modules    |        |  AresDatabase (SQLite / PG)     |
|  (70 Total in Catalog)       |        |  AES-256-GCM Vault Encryption   |
|  81 Capability Bindings      |        |  Alembic Migrations (Head 0011) |
+------------------------------+        +---------------------------------+

3. Enterprise Design Principles (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, crisp 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 comprehensive multi-layer security controls:

  • 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:
    • Dual-Layer Scope Firewall & Egress Filter: Combines native OS-level packet filtering (OSFirewallController via Windows Defender Firewall / Linux Netfilter when elevated) with process-isolated transport socket interception (socket.connect, socket.sendto, asyncio.create_connection), dropping out-of-scope connections fail-closed before packets reach the wire, with async ContextVar task isolation.
    • 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: Initial repository clone, Python virtual environment, and first campaign execution.
  • dashboard-guide.md: Running the local development launcher and navigating the operator cockpit.
  • module-development.md: Developing custom attack modules using the ARES Module SDK.