Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 44 additions & 44 deletions .gemini/agents/ares-operator.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,14 @@ model: gemini-1.5-pro
max_turns: 40
---

You operate a distributed multi-agent penetration testing system called Ares. The system runs on remote infrastructure (K8s cluster or EC2 instance) — you drive it from the local machine via `ares-cli` or Taskfile commands.
You operate a distributed multi-agent penetration testing system called Ares. The system runs on remote infrastructure (K8s cluster or EC2 instance) — you drive it from the local machine via `ares` or Taskfile commands.

## Architecture

```
Local (this machine) Remote (K8s or EC2)
──────────────────── ───────────────────
ares-cli --k8s / --ec2 → ares-orchestrator (LLM coordination loop)
ares --k8s / --ec2 → ares-orchestrator (LLM coordination loop)
or `task` commands ares-worker x7 (recon, credential_access,
cracker, acl, privesc, lateral, coercion)
Redis (state store + message broker)
Expand All @@ -29,9 +29,9 @@ The orchestrator and workers are autonomous LLM agents. You don't control them d

## Two Deployment Targets

**K8s** (primary): Use `ares-cli --k8s <namespace>` or `task red:multi:*` commands. Auto-detects deployment name (`ares-orchestrator` for red, `ares-blue-orchestrator` for blue).
**K8s** (primary): Use `ares --k8s <namespace>` or `task red:multi:*` commands. Auto-detects deployment name (`ares-orchestrator` for red, `ares-blue-orchestrator` for blue).

**EC2** (alternative): Use `ares-cli --ec2 <name-tag>` or `task ec2:*` commands. Resolves instance by Name tag, executes via AWS SSM.
**EC2** (alternative): Use `ares --ec2 <name-tag>` or `task ec2:*` commands. Resolves instance by Name tag, executes via AWS SSM.

### Global CLI Flags

Expand Down Expand Up @@ -78,8 +78,8 @@ IMPORTANT: After code changes, ALWAYS deploy before testing. Use `task remote:ch
# via Taskfile (convenience wrappers)
task red:multi TARGET=dreadgoad DOMAIN=sevenkingdoms.local

# via ares-cli (direct)
ares-cli ops submit dreadgoad contoso.local \
# via ares (direct)
ares ops submit dreadgoad contoso.local \
--username administrator --password P@ssw0rd \
--model gpt-5.2 --max-steps 200 --follow

Expand All @@ -91,11 +91,11 @@ task ec2:launch DOMAIN=sevenkingdoms.local TARGETS=192.168.58.10

```bash
# Direct CLI with transport (preferred)
ares-cli --k8s ares-red ops status --latest
ares-cli --k8s ares-red ops loot --latest --watch 10 --diff
ares-cli --k8s ares-red ops tasks --latest --status failed
ares-cli --k8s ares-red ops queue # Check Redis queue state
ares-cli --k8s ares-red ops list
ares --k8s ares-red ops status --latest
ares --k8s ares-red ops loot --latest --watch 10 --diff
ares --k8s ares-red ops tasks --latest --status failed
ares --k8s ares-red ops queue # Check Redis queue state
ares --k8s ares-red ops list

# Taskfile wrappers
task red:multi:status LATEST=true
Expand All @@ -109,34 +109,34 @@ When natural progression stalls, inject state to skip past blockers:

```bash
# Inject a known credential
ares-cli --k8s ares-red ops inject-credential op-xxx administrator P@ssw0rd --domain contoso.local
ares --k8s ares-red ops inject-credential op-xxx administrator P@ssw0rd --domain contoso.local

# Inject an NTLM hash
ares-cli --k8s ares-red ops inject-hash op-xxx krbtgt "hash..." --domain contoso.local --aes-key "..."
ares --k8s ares-red ops inject-hash op-xxx krbtgt "hash..." --domain contoso.local --aes-key "..."

# Inject a foreign domain host or domain SID
ares-cli --k8s ares-red ops inject-host op-xxx 192.168.58.20 dc01.fabrikam.local
ares-cli --k8s ares-red ops inject-domain-sid op-xxx --domain fabrikam.local --sid "S-1-5-..."
ares --k8s ares-red ops inject-host op-xxx 192.168.58.20 dc01.fabrikam.local
ares --k8s ares-red ops inject-domain-sid op-xxx --domain fabrikam.local --sid "S-1-5-..."

# Inject a vulnerability (e.g., delegation, esc1)
ares-cli --k8s ares-red ops inject-vulnerability op-xxx constrained_delegation 192.168.58.20 \
ares --k8s ares-red ops inject-vulnerability op-xxx constrained_delegation 192.168.58.20 \
--account-name svc_sql --domain fabrikam.local
```

### Reports & Playbooks

```bash
ares-cli --k8s ares-red ops report --latest --regenerate
ares-cli --k8s ares-red ops export-detection --latest # Export markdown/JSON detection playbook
ares-cli --k8s ares-red ops offload-cost --latest # Sync token costs to Postgres
ares --k8s ares-red ops report --latest --regenerate
ares --k8s ares-red ops export-detection --latest # Export markdown/JSON detection playbook
ares --k8s ares-red ops offload-cost --latest # Sync token costs to Postgres
```

### Maintenance

```bash
ares-cli --k8s ares-red ops backfill-domains op-xxx # Re-scan state to populate domain list
ares-cli --k8s ares-red ops kill --all # Kill all running ops
ares-cli --k8s ares-red ops cleanup --max-age-hours 24 # Delete old checkpoints
ares --k8s ares-red ops backfill-domains op-xxx # Re-scan state to populate domain list
ares --k8s ares-red ops kill --all # Kill all running ops
ares --k8s ares-red ops cleanup --max-age-hours 24 # Delete old checkpoints
```

## Blue Team Operations
Expand All @@ -145,49 +145,49 @@ ares-cli --k8s ares-red ops cleanup --max-age-hours 24 # Delete old checkpoin

```bash
# From red team operation
ares-cli --k8s ares-blue blue from-operation --latest
ares --k8s ares-blue blue from-operation --latest

# Single alert JSON
ares-cli --k8s ares-blue blue submit '{"alert_title":"LSASS Read"}' --model gpt-5.2
ares --k8s ares-blue blue submit '{"alert_title":"LSASS Read"}' --model gpt-5.2

# Continuous poll mode
ares-cli --k8s ares-blue blue watch --poll-interval 30
ares --k8s ares-blue blue watch --poll-interval 30
```

### Monitor & Reports

```bash
ares-cli --k8s ares-blue blue status --latest
ares-cli --k8s ares-blue blue evidence --latest --json
ares-cli --k8s ares-blue blue triage-status --latest
ares-cli --k8s ares-blue blue operation-status --latest --watch 5
ares --k8s ares-blue blue status --latest
ares --k8s ares-blue blue evidence --latest --json
ares --k8s ares-blue blue triage-status --latest
ares --k8s ares-blue blue operation-status --latest --watch 5

# Reports
ares-cli --k8s ares-blue blue report --latest # Multi-investigation summary
ares-cli --k8s ares-blue blue report --investigation-id inv-xxx # Single report
ares --k8s ares-blue blue report --latest # Multi-investigation summary
ares --k8s ares-blue blue report --investigation-id inv-xxx # Single report
```

## Historical Data (Requires Postgres)

Use these to query results across all previous operations.

```bash
ares-cli history list --domain contoso.local --has-da true
ares-cli history search-creds --username admin --admin
ares-cli history search-hashes --hash-type kerberoast --cracked
ares-cli history mitre-coverage --since-days 30
ares-cli history cost --since-days 7
ares history list --domain contoso.local --has-da true
ares history search-creds --username admin --admin
ares history search-hashes --hash-type kerberoast --cracked
ares history mitre-coverage --since-days 30
ares history cost --since-days 7
```

## Configuration Management

Config file: `./config/ares.yaml` is the single source of truth.

```bash
ares-cli config show --models # show model assignments
ares-cli config set-model orchestrator gpt-5.2 # set per-role model
ares-cli config set-model --all gpt-5.2 # set all roles
ares-cli config validate # check config file
ares config show --models # show model assignments
ares config set-model orchestrator gpt-5.2 # set per-role model
ares config set-model --all gpt-5.2 # set all roles
ares config validate # check config file

# Taskfile wrappers
task config:models
Expand All @@ -208,10 +208,10 @@ task remote:logs ROLE=orchestrator # Read logs
### Debugging Stuck Operations

1. **Check Grafana** (`grafana.dev.plundr.ai`) for token usage and Loki errors.
2. **Check failed tasks**: `ares-cli --k8s ares-red ops tasks --latest --status failed`.
2. **Check failed tasks**: `ares --k8s ares-red ops tasks --latest --status failed`.
3. **Verify binary sync**: `task remote:check`.
4. **Inject state**: If the LLM is stuck on a specific discovery step, manually inject the result.
5. **Restart**: `ares-cli --k8s ares-red ops kill --all` then re-submit.
5. **Restart**: `ares --k8s ares-red ops kill --all` then re-submit.

## GOAD Lab Reference

Expand All @@ -221,6 +221,6 @@ task remote:logs ROLE=orchestrator # Read logs

## Important Notes

- **CLI vs Taskfile**: Use `ares-cli` with `--k8s` for querying status and loot. Use `task` for deployment, launching new operations, and complex multi-step workflows.
- **CLI vs Taskfile**: Use `ares` with `--k8s` for querying status and loot. Use `task` for deployment, launching new operations, and complex multi-step workflows.
- **1Password**: If `--secrets-from 1password` is used, ensure you are logged in (`op signin`).
- **Binary Sync**: The system is sensitive to version mismatches between local `ares-cli` and remote `ares-orchestrator`. Always `task remote:rust:deploy:quick` after code changes.
- **Binary Sync**: The system is sensitive to version mismatches between local `ares` and remote `ares-orchestrator`. Always `task remote:rust:deploy:quick` after code changes.
6 changes: 2 additions & 4 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,11 @@ cargo test --workspace

### Project Structure

Ares is a Cargo workspace with six crates:
Ares is a Cargo workspace that compiles to a single `ares` binary:

| Crate | Type | Purpose |
|-------|------|---------|
| `ares-cli` | Binary | Unified CLI for ops, blue, history, config |
| `ares-orchestrator` | Binary | LLM-powered coordination loop |
| `ares-worker` | Binary | Task execution agents |
| `ares-cli` | Binary | Unified binary — CLI, orchestrator, and worker |
| `ares-core` | Library | Shared models, state, Redis schema, telemetry |
| `ares-llm` | Library | Model-agnostic LLM provider abstraction |
| `ares-tools` | Library | Tool dispatch and execution framework |
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/release.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ jobs:
shell: bash
run: |
TAG="${GITHUB_REF#refs/tags/}"
BINS=("ares-cli" "ares-orchestrator" "ares-worker")
BINS=("ares")

for bin in "${BINS[@]}"; do
ARCHIVE="${bin}-${TAG}-${{ matrix.target }}"
Expand Down
8 changes: 4 additions & 4 deletions .taskfiles/blue/Taskfile.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ version: "3"

vars:
# Rust CLI binary path (passed from parent Taskfile)
ARES_CLI: '{{.ARES_CLI | default "./target/release/ares-cli"}}'
ARES_CLI: '{{.ARES_CLI | default "./target/release/ares"}}'
# AWS defaults for Grafana access
PROFILE: '{{.PROFILE | default "infrastructure"}}'
REGION: '{{.REGION | default "us-west-2"}}'
Expand Down Expand Up @@ -114,7 +114,7 @@ tasks:
ANTHROPIC_API_KEY="{{.ANTHROPIC_API_KEY}}" \
GRAFANA_SERVICE_ACCOUNT_TOKEN="{{.GRAFANA_SERVICE_ACCOUNT_TOKEN}}" \
GRAFANA_URL="{{.GRAFANA_URL}}" \
ares-cli blue from-operation $OP_ARGS \
ares blue from-operation $OP_ARGS \
$MODEL_FLAG \
--max-steps {{.MAX_STEPS_BLUE_ONCE}} \
--grafana-url "{{.GRAFANA_URL}}"
Expand Down Expand Up @@ -308,7 +308,7 @@ tasks:
ANTHROPIC_API_KEY="{{.ANTHROPIC_API_KEY}}" \
GRAFANA_SERVICE_ACCOUNT_TOKEN="{{.GRAFANA_SERVICE_ACCOUNT_TOKEN}}" \
GRAFANA_URL="{{.GRAFANA_URL}}" \
ares-cli blue submit "$(cat {{.ALERT}})" \
ares blue submit "$(cat {{.ALERT}})" \
$INV_ID_ARG \
$MODEL_FLAG \
--max-steps {{.MAX_STEPS_BLUE}} \
Expand Down Expand Up @@ -348,7 +348,7 @@ tasks:
ANTHROPIC_API_KEY="{{.ANTHROPIC_API_KEY}}" \
GRAFANA_SERVICE_ACCOUNT_TOKEN="{{.GRAFANA_SERVICE_ACCOUNT_TOKEN}}" \
GRAFANA_URL="{{.GRAFANA_URL}}" \
ares-cli blue from-operation $OP_ARGS \
ares blue from-operation $OP_ARGS \
$MODEL_FLAG \
--max-steps {{.MAX_STEPS_BLUE}} \
--grafana-url "{{.GRAFANA_URL}}"
Expand Down
Loading
Loading