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 AI planner usage
Mafifrizi63433b269df1
diff --git a/README.md b/README.mdindex 0eb3ac1..243b54e 100644--- a/README.md+++ b/README.md@@ -135,6 +135,19 @@ Common page inputs and outputs:| EDR/OPSEC | Technique ID, EDR vendor, version, outcome, campaign, and notes. | Historical success-rate telemetry and outcome records. | You want to track defensive visibility and tune OPSEC decisions from controlled tests. || Graph Ingest | Campaign plus local BloodHound/SharpHound JSON path. | Campaign graph nodes, links, and attack-path candidates. | You already collected BloodHound-style data and want it mapped into ARES. |+Planning modes:++| Mode | Where to use it | Requires LLM key? | What it does |+| --- | --- | --- | --- |+| Template plan | `Templates` page | No | Builds a deterministic plan from a named template such as `internal_pentest`. It is for review and does not execute modules by itself. |+| AI planner module | `Modules` page, module `ai.autonomous_planner` | Yes, unless using local Ollama | Reads campaign context and asks Claude, OpenAI, or a local Ollama model to produce a proposed execution plan with reasoning, confidence, and OPSEC warnings. |+| Strategy engagement | `Strategy` page | Usually yes | Starts a background goal-based strategy loop for an existing campaign. It uses AI planning and OPSEC checks, then sends progress events to the `Live` page. |+| Internal scorer | CLI / engine internals | No | Ranks possible next modules from local campaign/session state. This is AI-style scoring, not an external LLM call. |++The ARES API key created in the `Security` page is not an OpenAI, Anthropic,+or Ollama key. It authenticates scripts and integrations to the ARES API.+LLM provider keys are configured separately in the ARES server environment.+See [docs/dashboard-guide.md](docs/dashboard-guide.md).### Campaign System@@ -240,6 +253,26 @@ Dashboard API keys are separate from these startup secrets. Create API keysfrom the Security page only after login when you need scripts, integrations, orautomation to call the API with `X-API-Key` instead of an interactive session.+Optional AI planner provider keys:++| Variable | Used by | Notes |+| --- | --- | --- |+| `ANTHROPIC_API_KEY` | `ai.autonomous_planner` with `llm_backend=claude`; Strategy default path. | Required when using Claude-backed planning. |+| `OPENAI_API_KEY` | `ai.autonomous_planner` with `llm_backend=openai`. | Required when using OpenAI-backed planning. |+| Local Ollama at `http://localhost:11434` | `ai.autonomous_planner` with `llm_backend=local`. | No cloud key required, but Ollama and the selected model must already be running. |++Example:++```powershell+$env:OPENAI_API_KEY="sk-..."+```++or:++```powershell+$env:ANTHROPIC_API_KEY="sk-ant-..."+```+### 2. Start the API and DashboardFrom an installed package:diff --git a/docs/api-reference.md b/docs/api-reference.mdindex e499070..e9826c8 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -362,6 +362,36 @@ List active autonomous engagements.Start an autonomous engagement. Backend RBAC still enforces restricted moduleauthorization.+Request body:++```json+{+ "campaign_id": "CAMPAIGN_ID",+ "goal": "domain_admin",+ "max_rounds": 5,+ "llm_backend": "claude",+ "secondary_backend": "",+ "authorizations": [],+ "forbidden_modules": [],+ "allow_persistence": false+}+```++Notes:++- `goal` can be `domain_admin`, `enterprise_admin`, `cloud_admin`,+ `data_exfil`, `persistence`, or `full_compromise`.+- `llm_backend` can be `claude`, `openai`, or `local`.+- The dashboard Strategy page uses the backend defaults. By default that means+ Claude-backed planning, so `ANTHROPIC_API_KEY` must be present in the ARES+ server environment.+- `llm_backend=openai` requires `OPENAI_API_KEY`.+- `llm_backend=local` expects Ollama at `http://localhost:11434`.+- ARES dashboard API keys authenticate callers to ARES. They are not LLM+ provider keys.+- The endpoint returns immediately. Monitor progress through campaign events+ or the dashboard `Live` page.+---## EDR/OPSEC@@ -387,6 +417,12 @@ List campaign templates.Generate an execution plan from a template.+Template plans are deterministic and do not call an LLM. They return a plan for+operator review and do not execute modules automatically.++For LLM-backed planning, run module `ai.autonomous_planner` through the+`/modules/{module_id}/run` endpoint or the dashboard Modules page.+---## Healthdiff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.mdindex 0cd51af..c063455 100644--- a/docs/dashboard-guide.md+++ b/docs/dashboard-guide.md@@ -121,6 +121,19 @@ Use it for:- Generating a plan from template parameters.- Keeping campaign execution consistent.+Templates are deterministic. They do not call an LLM and they do not execute+modules automatically. Use them when you want a predictable checklist-style+plan for a common engagement type, then review the returned stages before+running anything against a campaign.++Typical flow:++1. Select a built-in template such as `internal_pentest`.+2. Optionally provide JSON parameters such as domain, DC, or usernames.+3. Click `Generate Plan`.+4. Review the returned stages and module IDs.+5. Run the plan manually through campaign execution only after authorization.+### StrategyPurpose: start or monitor goal-based engagement planning.@@ -134,6 +147,58 @@ Use it for:Backend RBAC still controls whether a user can start or execute sensitiveflows.+Strategy starts a background engagement loop for an existing campaign. It is+not the same as the Templates page. The backend default LLM backend is Claude,+so set `ANTHROPIC_API_KEY` before using the default Strategy path, or call the+API directly with another `llm_backend`.++Strategy emits progress events to the campaign WebSocket. Use the `Live` page+to watch those events while the engagement is running.++Safe usage:++1. Create a scoped campaign first.+2. Confirm the campaign has the context needed for planning.+3. Set the required LLM provider key in the ARES server environment.+4. Select a goal such as `domain_admin`.+5. Add authorization notes for sensitive actions.+6. Click `Engage` and monitor `Live`.++### AI Planner Module++Purpose: generate an LLM-backed execution plan from campaign context.++Use it from:++- `Modules` page.+- Module ID: `ai.autonomous_planner`.++Inputs:++- `goal`: `domain_admin`, `enterprise_admin`, `cloud_admin`, `data_exfil`,+ `persistence`, or `full_compromise`.+- `llm_backend`: `claude`, `openai`, or `local`.+- `llm_model`: optional model override.+- `auto_approve`: keep this disabled unless you have an explicit review process.++Provider setup:++- `llm_backend=claude` requires `ANTHROPIC_API_KEY`.+- `llm_backend=openai` requires `OPENAI_API_KEY`.+- `llm_backend=local` expects Ollama at `http://localhost:11434`.++Output:++- Proposed execution stages.+- AI reasoning.+- Confidence score.+- OPSEC warnings.+- Alternative plan data when available.++The AI planner module performs a local planning/LLM call only. It does not+contact the target network by itself. Review its plan before running any+generated modules.+### SecurityPurpose: account and security administration.diff --git a/docs/modules.md b/docs/modules.mdindex 6daa4f8..c8c6f59 100644--- a/docs/modules.md+++ b/docs/modules.md@@ -191,6 +191,44 @@ optional dependencies such as AD, cloud, container, Windows, and PDF extras.| `opsec.coverage_predictor` | Predict detection probability and recommended wait windows. || `ai.autonomous_planner` | Plan an engagement chain from campaign state and goals. |+### AI Planner Module++`ai.autonomous_planner` is the LLM-backed planning module. It is different from+template planning and from the internal module scorer:++| Planner surface | LLM required? | Primary use |+| --- | --- | --- |+| `Templates` dashboard page | No | Produce predictable template-based plans for review. |+| `ai.autonomous_planner` module | Yes, unless using local Ollama | Ask Claude, OpenAI, or Ollama to propose a plan from campaign context. |+| `Strategy` dashboard page | Usually yes | Start a background goal-based engagement loop with strategy events. |+| Internal `AttackPlanner` scorer | No | Rank possible next modules using local state and scoring weights. |++Parameters:++| Parameter | Values | Meaning |+| --- | --- | --- |+| `goal` | `domain_admin`, `enterprise_admin`, `cloud_admin`, `data_exfil`, `persistence`, `full_compromise` | The desired high-level outcome for the proposed plan. |+| `llm_backend` | `claude`, `openai`, `local` | Which planner backend to use. |+| `llm_model` | Optional string | Overrides the backend default model. |+| `auto_approve` | `false` recommended | When `false`, ARES returns a proposed plan for operator review. |++Provider setup:++- `llm_backend=claude` requires `ANTHROPIC_API_KEY`.+- `llm_backend=openai` requires `OPENAI_API_KEY`.+- `llm_backend=local` expects Ollama at `http://localhost:11434`.++Expected output:++- `execution_plan`: proposed stages and module IDs.+- `ai_reasoning`: why the planner selected the path.+- `confidence_score`: confidence from the planner response.+- `warnings`: OPSEC or safety notes to review before execution.++The module is OPSEC `LOCAL`: the planning call goes to the selected LLM backend+and does not contact the target network by itself. Treat the result as a plan+proposal, not as automatic authorization to execute it.+## Recommended Workflows### Local Validation@@ -229,4 +267,3 @@ temporary campaign when done.2. Use `edr.bypass_adaptive` to understand defensive product assumptions.3. Use `opsec.coverage_predictor` before noisy chains.4. Prefer low-noise enumeration when uncertainty is high.-