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.

docs: clarify AI planner usage

Mafifrizi63433b269df1
diff --git a/README.md b/README.md
index 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 keys
from the Security page only after login when you need scripts, integrations, or
automation 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 Dashboard
From an installed package:
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 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 module
authorization.
+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.
+
---
## Health
diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md
index 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.
+
### Strategy
Purpose: 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 sensitive
flows.
+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.
+
### Security
Purpose: account and security administration.
diff --git a/docs/modules.md b/docs/modules.md
index 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.
-