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: refresh setup and dashboard guidance

Mafifrizicdaf53ebc146
diff --git a/QUICKSTART.md b/QUICKSTART.md
index cde903b..508e67b 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -1,237 +1,275 @@
-# ARES — First Engagement in 30 Minutes
+# ARES Quickstart
-> Written authorization required before testing any system.
+ARES is an operator dashboard and automation framework for authorized red-team validation, lab workflows, campaign orchestration, module execution, telemetry, reporting, RBAC, and security checks.
----
+Use it only on systems you own or have written permission to assess.
-## Before you start
+## 1. Clone And Enter The Project
-You need three things:
-
-1. **Python 3.10+** on your attacker machine
-2. **A Windows domain** to test against — even a home lab works
-3. **Domain credentials** — a regular user account is enough to start
-
-No lab? → [Set one up in 20 minutes](#lab-setup) with GOAD.
+```bash
+git clone https://github.com/Mafifrizi/ARES.git
+cd ARES
+```
----
+## 2. Install The Local Environment
-## Step 1 — Install (3 min)
+Linux/macOS:
```bash
-pip install ares-redteam[ad]
-ares-setup # creates .env · generates random secrets
-ares doctor # verify everything is ready
+bash scripts/setup.sh
+source .venv/bin/activate
```
-What `ares doctor` should show:
-```
-✅ Python 3.11.x
-✅ impacket 0.12.x (AD/SMB modules)
-✅ ldap3 2.9.x (LDAP enumeration ready)
-✅ .env configured
+Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install -e ".[dev,pdf]"
```
-If anything is red, it prints the exact command to fix it.
+Notes:
-For a full install with all optional integrations:
+- The setup script installs the local project in editable mode.
+- Some offensive-security integrations are optional. `ares doctor` will tell you which optional packages or native tools are missing for AD, cloud, container, or password-cracking workflows.
+- PDF support uses WeasyPrint when available and has a local browser fallback in the API.
-```bash
-pip install ares-redteam[full]
-```
+## 3. Configure Secrets
-`[all]` remains available as a compatibility alias.
+ARES requires three local environment values before the API starts.
----
+These values are created by the operator or deployment owner. ARES does not provide shared public secrets.
-## Step 2 — Create a campaign (1 min)
+### Linux/macOS
```bash
-ares campaign create \
- --name "First Lab Test" \
- --client "Homelab" \
- --scope "192.168.56.0/24" \
- --noise normal
-
-# Save the campaign ID
-export C=$(ares campaign list --json | jq -r '.[0].id')
-echo "Campaign: $C"
+export ARES_SECRET_KEY="$(python - <<'PY'
+import secrets
+print(secrets.token_urlsafe(48))
+PY
+)"
+
+export ARES_ENCRYPTION_KEY="$(python - <<'PY'
+from cryptography.fernet import Fernet
+print(Fernet.generate_key().decode())
+PY
+)"
+
+export ARES_DEFAULT_ADMIN_PASSWORD="ChangeThisAdminPassword123!"
+```
+
+### Windows PowerShell
+
+```powershell
+$env:ARES_SECRET_KEY = python -c "import secrets; print(secrets.token_urlsafe(48))"
+$env:ARES_ENCRYPTION_KEY = python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+$env:ARES_DEFAULT_ADMIN_PASSWORD = "ChangeThisAdminPassword123!"
```
-The scope is a hard stop — ARES will refuse to run modules against IPs outside it.
+What each value does:
+
+| Variable | Purpose | Keep Stable? |
+| --- | --- | --- |
+| `ARES_SECRET_KEY` | Signs API sessions and tokens. | Yes, for a deployed instance. Rotating it invalidates sessions. |
+| `ARES_ENCRYPTION_KEY` | Encrypts sensitive local data such as credential vault material. | Yes. Losing or changing it can make existing encrypted data unreadable. |
+| `ARES_DEFAULT_ADMIN_PASSWORD` | Password for the first bootstrap `admin` account when the user table is empty. | Change after first login. |
+
+For repeated local use, copy `.env.example` to `.env`, fill these values once, and start ARES from the same project directory.
-### Dashboard login flow
+## 4. Start The API And Dashboard
```bash
ares-api
```
-Open `http://localhost:8080/dashboard`, sign in with the configured admin
-account, create a campaign, choose a module, keep `dry_run` enabled, and submit.
-The dashboard sends `POST /auth/token` as OAuth2 form data and calls only the
-main API routes documented in `docs/api-reference.md`.
+Open:
----
-
-## Step 3 — Enumerate (5 min, read-only)
+```text
+http://localhost:8080/dashboard
+```
-These modules only read from LDAP. No exploits, no alerts.
+Health check:
```bash
-DC="192.168.56.10"
-DOMAIN="corp.local"
-CREDS="--dc $DC --domain $DOMAIN --username jdoe --password Password123"
-
-ares module run ad.enum_users $CREDS # who's in the domain?
-ares module run ad.enum_spn $CREDS # which accounts are kerberoastable?
-ares module run ad.enum_computers $CREDS # what machines exist?
-ares module run recon.fingerprint --target $DC # what EDR is running?
+curl http://localhost:8080/health
```
-Check what was found:
-```bash
-ares findings list --campaign-id $C
+Expected result:
+
+```json
+{"status":"ok","version":"6.0.0","db":"connected"}
```
----
+Login with:
-## Step 4 — Harvest credentials (5 min)
+- Username: `admin`
+- Password: your `ARES_DEFAULT_ADMIN_PASSWORD`
-```bash
-# Request TGS tickets for all SPN accounts — save to vault
-ares module run ad.kerberoast $CREDS
+Then change the admin password from the `Security` page.
-# If any accounts don't require pre-auth (common misconfiguration)
-ares module run ad.asreproast --dc $DC --domain $DOMAIN \
- --userfile /tmp/users.txt # no creds needed for this one
+## 5. Create A Campaign
-# Crack offline — uses hashcat if available, john as fallback
-ares module run credential.crack
+Open `Campaigns` and create a scoped campaign.
-# See what got cracked
-ares vault list
-```
+Example local demo values:
----
+| Field | Example |
+| --- | --- |
+| Name | `ARES Local Finding Demo` |
+| Client | `Internal` |
+| Targets | `127.0.0.1` |
+| Scope CIDRs | `127.0.0.1/32` |
-## Step 5 — Escalate (if you have DA creds)
+Scope matters. Targeted modules will refuse to run if the target is outside the selected campaign scope.
-```bash
-# This requires team_lead authorization — protects against accidents
-ares module run ad.dcsync $CREDS
-# → dumps all NTLM hashes including krbtgt
-
-# Forge a golden ticket for persistent access
-ares module run credential.golden_ticket \
- --domain $DOMAIN \
- --domain-sid S-1-5-21-... \
- --krbtgt-hash <hash from dcsync>
-```
+## 6. Run A Module Safely
----
+Open `Modules`:
-## Step 6 — Generate the report (1 min)
+1. Select the campaign.
+2. Search for a module.
+3. Fill the generated parameter fields.
+4. Run with `Dry run` first when available.
+5. Run live only when the target and scope are authorized.
-```bash
-ares report generate \
- --campaign-id $C \
- --format html \
- --output lab_report.html
+Port behavior is module-specific. Some modules require explicit ports because they fingerprint a service. Broader discovery belongs in enumeration modules such as port scanning, then the discovered services can be used by more specific modules.
-open lab_report.html # macOS
-xdg-open lab_report.html # Linux
-```
+## 7. Generate Reports
+
+Open `Reports`:
+
+1. Select a campaign.
+2. Choose HTML, PDF, Markdown, or JSON.
+3. Click `Generate`.
+4. Use the dashboard `Download` button.
-The report includes:
-- MITRE ATT&CK heatmap of every technique used
-- Timeline of all actions with timestamps
-- Findings ranked by severity with evidence
-- Remediation steps per finding
+Do not open report file URLs directly in the browser address bar. Report downloads are authenticated, so direct unauthenticated URLs return `401`.
----
+## 8. Use Templates
-## What's next
+Open `Templates` when you want a repeatable plan.
-Once you're comfortable with the basics, try:
+Templates:
+
+- Generate deterministic plan stages.
+- Do not call an LLM.
+- Do not execute modules by themselves.
+- Are useful as a checklist before running campaign modules.
+
+Typical flow:
+
+1. Select a built-in template such as `internal_pentest`.
+2. Optionally provide JSON parameters.
+3. Click `Generate Plan`.
+4. Review the returned stages and module IDs.
+5. Execute approved modules manually from the campaign workflow.
+
+## 9. Use Strategy And AI Planning
+
+Strategy is for goal-based planning against an existing campaign.
+
+The default strategy path expects an LLM provider key unless you configure a local backend. ARES API keys from the `Security` page are not LLM keys.
+
+Common LLM environment variables:
-**Lateral movement:**
```bash
-ares module run lateral.psexec \
- --target 192.168.56.20 \
- --username Administrator \
- --password "CrackedPassword"
+export ANTHROPIC_API_KEY="..."
+export OPENAI_API_KEY="..."
```
-**Cloud attack paths (AWS):**
+Use Strategy only after:
+
+- A campaign exists.
+- Scope is correct.
+- Authorization notes are clear.
+- The required LLM provider key is configured, or a supported local backend is selected through the API.
+
+## 10. API Keys In The Security Page
+
+Dashboard API keys authenticate scripts and integrations to ARES itself.
+
+Use them as:
+
```bash
-pip install ares-redteam[cloud]
-ares module run cloud.aws --access-key AKIA... --secret-key ...
-ares module run cloud.aws_privesc --access-key AKIA...
+curl http://localhost:8080/campaigns \
+ -H "X-API-Key: ares_YOUR_KEY"
```
-**AI autonomous planning** — let ARES plan the whole engagement:
+They are not OpenAI, Anthropic, or Ollama keys.
+
+## 11. Roles
+
+The first user is `admin` with the `team_lead` role.
+
+| Role | Purpose |
+| --- | --- |
+| `team_lead` | Full local admin/operator lead. Can create users, delete campaigns, view security audit, and authorize higher-risk workflows. |
+| `operator` | Daily operator. Can run normal campaign/module/report workflows. |
+| `recon` | Read-heavy recon identity. Main dashboard execution endpoints remain operator-gated. |
+| `reporter` | Read-only reporting and review. |
+
+Create users through `POST /auth/register` with a team-lead token. See `docs/dashboard-guide.md` for a PowerShell example.
+
+## 12. Doctor And Optional Dependencies
+
+Run:
+
```bash
-# Start the API server first
-ares server start
-
-# Then trigger autonomous engagement
-curl -X POST http://localhost:8080/strategy/engage \
- -H "Authorization: Bearer $TOKEN" \
- -H "Content-Type: application/json" \
- -d '{
- "campaign_id": "'$C'",
- "goal": "domain_admin",
- "max_rounds": 3,
- "llm_backend": "claude",
- "authorizations": []
- }'
+ares doctor
```
-ARES will enumerate, select techniques, execute, check detection probability,
-and stop itself if anything looks too hot.
+`ares doctor` checks Python, key dependencies, optional module integrations, native tools, network socket support, environment configuration, and the local database.
----
+A yellow warning means an optional integration is missing. A red failure means a required dependency or configuration item needs attention.
-## Common issues
+Common examples:
-| Error | Fix |
-|-------|-----|
-| `No module named 'impacket'` | `pip install ares-redteam[ad]` |
-| `Connection refused :389` | Check DC IP — ARES needs ports 88, 389, 445 reachable |
-| `KDC_ERR_C_PRINCIPAL_UNKNOWN` | Username wrong — verify with `ares module run ad.enum_users` |
-| `STATUS_LOGON_FAILURE` | Wrong password |
-| `Scope violation: target not in scope` | Update `--scope` when creating campaign |
-| `ARES_SECRET_KEY not set` | Run `ares-setup` or `cp .env.example .env` |
-| `impacket version too old` | `pip install --upgrade impacket` |
+| Message | Meaning |
+| --- | --- |
+| `impacket` missing or old | AD/SMB modules need the optional impacket dependency. |
+| `pip-audit not installed` | Dependency audit is unavailable; core API can still start. |
+| `hashcat not in PATH` | Password-cracking helpers cannot use hashcat until installed. |
+| `.env configured` failed | Required environment values are missing. |
----
+## 13. Public SDK
-## Lab setup
+Use the public SDK import path for custom modules:
-Don't have a Windows domain? Two options:
+```python
+from ares.sdk import BaseModule, ExecutionContext, Finding, ModuleResult, register_module
+```
-**Option A — GOAD (recommended, 20 min)**
+`ares.modules.sdk` remains as a compatibility shim, but new code should use `ares.sdk`.
-[Game of Active Directory](https://github.com/Orange-Cyberdefense/GOAD) sets up
-a full 3-DC lab with pre-configured misconfigurations designed for testing.
+See:
-```bash
-git clone https://github.com/Orange-Cyberdefense/GOAD
-cd GOAD
-vagrant up # needs VirtualBox + Vagrant
-# → 3 DCs on 192.168.56.0/24, many vulns ready to test
+- `docs/module-development.md`
+- `docs/module_sdk.md`
+- `docs/examples/example_http_enum.py`
+
+## 14. Validation Lab
+
+Run the validation lab after changing API or dashboard behavior:
+
+```powershell
+$env:ARES_LAB_PASSWORD="YOUR_CURRENT_ADMIN_PASSWORD"
+.\scripts\run_validation_lab.ps1
```
-**Option B — Windows Server Eval (free, 180 days)**
+The lab checks login, profile, campaign validation, dry-run validation, reports, and API key lifecycle.
-1. Download [Windows Server 2022 Evaluation](https://www.microsoft.com/en-us/evalcenter/evaluate-windows-server-2022) (free, no account needed)
-2. Install in VirtualBox/VMware, promote to Domain Controller
-3. Create a regular user account
-4. Set scope to your VM's IP range in ARES
+## Troubleshooting
-→ You now have a target for all AD modules.
+| Symptom | Check |
+| --- | --- |
+| `ARES not configured` | Set `ARES_SECRET_KEY`, `ARES_ENCRYPTION_KEY`, and `ARES_DEFAULT_ADMIN_PASSWORD`. |
+| `Invalid credentials` | Use the current admin password, not the placeholder from docs. |
+| `Request failed with 422` | A required field is missing or a target/scope value is invalid. |
+| `Target is not in campaign scope` | Add the target CIDR to the campaign scope, for example `127.0.0.1/32`. |
+| `Global rate limit exceeded` | Wait briefly, then retry. Avoid repeatedly clicking actions while a request is pending. |
+| Report direct URL returns `401` | Use the authenticated dashboard Download button. |
+| Strategy does nothing useful | Confirm the campaign, authorization notes, and LLM provider key. |
----
+## Safety Reminder
-*ARES is for authorized red team engagements only.*
-*Get written permission before testing any real system.*
+ARES is intended for authorized security testing, lab use, and defensive validation only.
diff --git a/README.md b/README.md
index ca2a77f..61e9492 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ and professional report generation.
[![FastAPI](https://img.shields.io/badge/API-FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
[![React](https://img.shields.io/badge/Dashboard-React-61DAFB?style=for-the-badge&logo=react&logoColor=111111)](https://react.dev)
[![License](https://img.shields.io/badge/License-MIT-22C55E?style=for-the-badge)](LICENSE)
-[![Status](https://img.shields.io/badge/Unit%20Suite-1098%20passing-22C55E?style=for-the-badge)](tests/)
+[![Status](https://img.shields.io/badge/Unit%20Suite-1102%20passing-22C55E?style=for-the-badge)](tests/)
**Built for labs, internal security teams, and authorized engagements only.**
@@ -486,8 +486,12 @@ dry-run mode.
## ARES SDK Surface
-ARES exposes SDK-style contracts for module authors and dashboard integrations,
-but this release does not claim a separate stable public client SDK package.
+ARES exposes a public SDK import path for module authors and local
+integrations:
+
+```python
+from ares.sdk import BaseModule, ExecutionContext, ModuleResult
+```
Current SDK surface:
@@ -500,8 +504,9 @@ Current SDK surface:
[docs/module_sdk.md](docs/module_sdk.md) describe how to build and test ARES
modules without bypassing scope validation, RBAC, or audit controls.
-This keeps the public claim precise: ARES has module SDK contracts today. This
-README does not advertise a separate product SDK as a release feature.
+`ares.sdk` is the preferred import path for new code. The older
+`ares.modules.sdk` import path remains available so existing local modules keep
+working.
---
@@ -558,7 +563,7 @@ See [docs/architecture.md](docs/architecture.md) and
Current local verification:
```text
-1098 unit tests passed
+1102 unit tests passed
frontend build passed
validation lab passed
ares doctor dependency display and local-env isolation covered by tests
diff --git a/ares/cli/typer_main.py b/ares/cli/typer_main.py
index 0174f1e..12e112f 100644
--- a/ares/cli/typer_main.py
+++ b/ares/cli/typer_main.py
@@ -1593,7 +1593,7 @@ from __future__ import annotations
MITRE ATT&CK: Fill in technique ID (e.g. T1558.003 for Kerberoasting)
"""
from typing import Any
-from ares.modules.sdk import (
+from ares.sdk import (
BaseModule, ExecutionContext, ModuleResult,
OpsecLevel, Severity, module_metadata,
get_logger, ModuleValidationError, HostUnreachable,
diff --git a/ares/modules/sdk.py b/ares/modules/sdk.py
index 5db5d8d..aa73163 100644
--- a/ares/modules/sdk.py
+++ b/ares/modules/sdk.py
@@ -5,7 +5,7 @@ Provides all base classes, helpers, and type definitions needed
to write a compliant ARES module.
Quick start:
- from ares.modules.sdk import (
+ from ares.sdk import (
BaseModule, ExecutionContext, ModuleResult,
Finding, Severity, OpsecLevel,
module_metadata, requires_privilege, timeout,
diff --git a/ares/sdk/__init__.py b/ares/sdk/__init__.py
new file mode 100644
index 0000000..d3d1a9a
--- /dev/null
+++ b/ares/sdk/__init__.py
@@ -0,0 +1,97 @@
+"""Public ARES SDK import surface.
+
+Prefer this package for module authoring and local integrations:
+
+ from ares.sdk import BaseModule, ExecutionContext, ModuleResult
+
+The legacy ``ares.modules.sdk`` path remains available for existing modules.
+"""
+from __future__ import annotations
+
+from ares.modules.sdk import (
+ AccountLocked,
+ AresError,
+ ArtifactStore,
+ AuthenticationFailed,
+ BaseModule,
+ ConnectionRefused,
+ ConnectionTimeout,
+ CredentialArtifact,
+ CredentialError,
+ CredentialExpired,
+ DetectionSignal,
+ ExecutionContext,
+ ExecutionError,
+ Finding,
+ HashArtifact,
+ HoneypotDetected,
+ HostArtifact,
+ HostUnreachable,
+ InsufficientPrivilege,
+ InvalidContext,
+ ModuleError,
+ ModuleResult,
+ ModuleTestHelper,
+ ModuleTimeoutError,
+ ModuleValidationError,
+ NetworkError,
+ NoCredentialsAvailable,
+ OpsecError,
+ OpsecLevel,
+ PermissionArtifact,
+ SandboxError,
+ ScopeError,
+ Severity,
+ TechniqueLibrary,
+ TechniqueMapper,
+ UserArtifact,
+ get_logger,
+ module_metadata,
+ requires_privilege,
+ timeout,
+ validate_module_class,
+)
+
+__all__ = [
+ "BaseModule",
+ "ModuleResult",
+ "OpsecLevel",
+ "validate_module_class",
+ "ExecutionContext",
+ "AresError",
+ "ModuleError",
+ "ModuleValidationError",
+ "ModuleTimeoutError",
+ "NetworkError",
+ "ConnectionRefused",
+ "ConnectionTimeout",
+ "HostUnreachable",
+ "CredentialError",
+ "AuthenticationFailed",
+ "AccountLocked",
+ "CredentialExpired",
+ "NoCredentialsAvailable",
+ "ExecutionError",
+ "SandboxError",
+ "ScopeError",
+ "OpsecError",
+ "DetectionSignal",
+ "HoneypotDetected",
+ "InsufficientPrivilege",
+ "InvalidContext",
+ "Finding",
+ "Severity",
+ "get_logger",
+ "TechniqueLibrary",
+ "TechniqueMapper",
+ "ArtifactStore",
+ "HostArtifact",
+ "UserArtifact",
+ "CredentialArtifact",
+ "HashArtifact",
+ "PermissionArtifact",
+ "module_metadata",
+ "requires_privilege",
+ "timeout",
+ "ModuleTestHelper",
+]
diff --git a/docs/MODULE_GUIDE.md b/docs/MODULE_GUIDE.md
index 2fbb7dd..4bb393d 100644
--- a/docs/MODULE_GUIDE.md
+++ b/docs/MODULE_GUIDE.md
@@ -26,7 +26,7 @@ This creates two files:
Every ARES module is a Python class that inherits from `BaseModule`:
```python
-from ares.modules.sdk import (
+from ares.sdk import (
BaseModule, ExecutionContext, ModuleResult,
OpsecLevel, Severity, module_metadata,
)
@@ -130,7 +130,7 @@ Controls whether the planner includes your module in stealth profiles:
## Finding Severity
```python
-from ares.modules.sdk import Severity
+from ares.sdk import Severity
Severity.CRITICAL # CVSS 9.0–10.0
Severity.HIGH # CVSS 7.0–8.9
diff --git a/docs/architecture.md b/docs/architecture.md
index ef521f5..35b1672 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -109,7 +109,7 @@ class BaseModule(ABC):
MITRE_TECHNIQUES: list[str] # ["T1558.003"]
MODULE_AUTHOR: str
- # v0.9.0 SDK (preferred)
+ # Public SDK (preferred)
async def validate(self, ctx: ExecutionContext) -> None: ...
async def execute(self, ctx: ExecutionContext) -> ModuleResult: ...
def report(self, result: ModuleResult) -> dict: ...
@@ -132,7 +132,7 @@ ctx = ExecutionContext.build(
session = operator_session,
)
findings, raw = await module.run(**ctx.params) # legacy
-result = await module.execute(ctx) # v0.9.0
+result = await module.execute(ctx) # ARES SDK
```
### 4. Error Hierarchy
diff --git a/docs/community-posts.md b/docs/community-posts.md
index 60d240c..f4dbbd1 100644
--- a/docs/community-posts.md
+++ b/docs/community-posts.md
@@ -50,8 +50,8 @@ It is intended for labs, internal security teams, and authorized engagements.
Feedback is welcome, especially around UX, docs, module quality, and defensive
validation workflows.
-GitHub: YOUR_GITHUB_LINK
-Docs: YOUR_DOCS_LINK
+GitHub: https://github.com/Mafifrizi/ARES
+Docs: https://github.com/Mafifrizi/ARES#readme
```
## Facebook Post - More Professional Version
@@ -73,7 +73,7 @@ Core features:
- Encrypted vault and token revocation.
- Team lead/operator/recon/reporter roles.
- Local validation lab for safe smoke testing.
-- HTML report generation with ARES branding.
+- HTML, PDF, Markdown, and JSON report generation with ARES branding.
ARES is for authorized security testing only. It is not a C2 framework, not an
implant framework, and not intended for unauthorized access.
@@ -81,7 +81,7 @@ implant framework, and not intended for unauthorized access.
I would appreciate feedback from practitioners on the dashboard UX, module
coverage, documentation, and safe lab workflows.
-GitHub: YOUR_GITHUB_LINK
+GitHub: https://github.com/Mafifrizi/ARES
```
## Discord Announcement
@@ -97,7 +97,7 @@ ARES is an authorized red-team engagement framework with:
lateral, EDR/OPSEC, and AI planning
- Encrypted credential vault
- RBAC and API key management
-- Report generation
+- HTML, PDF, Markdown, and JSON report generation
- Local validation lab
Use case: labs, internal security teams, and authorized engagements where you
@@ -105,8 +105,8 @@ want structure, reporting, and OPSEC controls around module execution.
Not a C2, not an implant, not for unauthorized testing.
-GitHub: YOUR_GITHUB_LINK
-Docs: YOUR_DOCS_LINK
+GitHub: https://github.com/Mafifrizi/ARES
+Docs: https://github.com/Mafifrizi/ARES#readme
Feedback welcome, especially around UX and module docs.
```
@@ -120,7 +120,7 @@ vault, OPSEC controls, reports, API keys, and a local validation lab.
It is built for labs/internal teams/authorized engagements, not C2 or
unauthorized testing.
-GitHub: YOUR_GITHUB_LINK
+GitHub: https://github.com/Mafifrizi/ARES
```
## GitHub Release Body
@@ -139,7 +139,7 @@ Highlights:
- Encrypted credential vault.
- RBAC, JWT refresh, token revocation, and API key lifecycle.
- Local validation lab for safe smoke testing.
-- Branded HTML report generation.
+- Branded HTML, PDF, Markdown, and JSON report generation.
Safety:
ARES is for authorized security testing only. Do not use it against systems you
@@ -190,4 +190,3 @@ Before posting screenshots:
- Blur tokens.
- Blur real IPs/domains unless they are `localhost` or lab-only.
- Do not show `.env`.
-
diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md
index dcf28d3..fa42313 100644
--- a/docs/dashboard-guide.md
+++ b/docs/dashboard-guide.md
@@ -76,6 +76,13 @@ Password rules:
To review users, open `Security` as a `team_lead` or call
`GET /security/users` with a team-lead token.
+
+## State And Navigation Behavior
+
+The dashboard keeps the active campaign, selected module, and recent result panels aligned with the current page context. When you change campaign, module, report format, graph path, or template input, stale results from the previous context are hidden so the UI does not imply that old output belongs to the new action.
+
+The `Live` page uses a browser WebSocket session. Leaving the page closes that browser connection. When you return, select the campaign and reconnect to start listening again. The underlying campaign data remains in the backend; only the current browser stream session is temporary.
+
## Pages
### Overview
@@ -352,3 +359,6 @@ Use it for:
| Module says target is not in scope | Selected campaign has no matching scope CIDR. | Create or select a campaign whose scope includes the target, such as `127.0.0.1/32` for local testing. |
| Telemetry looks empty after restart | Telemetry is an in-memory runtime snapshot. | Run modules in the current API process, or use Reports/Campaigns for durable history. |
| PDF generation fails | No PDF backend or browser fallback is available. | Install the PDF extra/native libraries or run on a machine with an available Chromium-compatible browser; use HTML, Markdown, or JSON meanwhile. |
+## Cross-Platform Notes
+
+The core API, dashboard, database migrations, SDK imports, and unit suite are designed to run on Windows, Linux, and macOS. Optional module dependencies can vary by operating system. Use `ares doctor` on each host to see which optional integrations are available before running modules that need AD, cloud, container, PDF, or native password-cracking tooling.
diff --git a/docs/examples/example_http_enum.py b/docs/examples/example_http_enum.py
index 746373f..8604a42 100644
--- a/docs/examples/example_http_enum.py
+++ b/docs/examples/example_http_enum.py
@@ -1,6 +1,6 @@
"""
ARES Example Module — HTTP Service Enumeration
-A minimal, fully commented example of the v0.9.0 module SDK.
+A minimal, fully commented example of the ARES public module SDK.
Copy this file as a starting point for your own module.
Run the test at the bottom with: pytest docs/examples/example_http_enum.py -v
@@ -13,14 +13,12 @@ from __future__ import annotations
import asyncio
from typing import Any
-from ares.core.campaign import Finding, Severity
-from ares.core.context import ExecutionContext
from ares.core.errors import (
ConnectionRefused,
ConnectionTimeout,
ModuleValidationError,
)
-from ares.modules.base import BaseModule, ModuleResult, OpsecLevel
+from ares.sdk import BaseModule, ExecutionContext, Finding, ModuleResult, OpsecLevel, Severity
class HttpEnumModule(BaseModule):
@@ -294,7 +292,7 @@ def test_report_has_narrative(module) -> None:
def test_module_metadata_valid() -> None:
- from ares.modules.base import validate_module_class
+ from ares.sdk import validate_module_class
errors = validate_module_class(HttpEnumModule)
assert errors == [], f"Metadata errors: {errors}"
diff --git a/docs/frontend.md b/docs/frontend.md
index c36761d..3d1e871 100644
--- a/docs/frontend.md
+++ b/docs/frontend.md
@@ -38,3 +38,10 @@ Module forms are built from `GET /modules` `param_schema`; fields are not
hardcoded in the frontend. Module runs default to `dry_run=true`, and
high-noise or sensitive modules require explicit UI confirmation. Backend RBAC
remains the enforcement boundary.
+## Runtime UX State
+
+Dashboard result panels are context-aware. Modules, reports, graph ingest, templates, strategy, and EDR/OPSEC views keep their latest result only while the selected campaign/module/input still matches the action that produced it. Changing page context hides stale output instead of showing old JSON under a new selection.
+
+Long-running actions should show a loading state on the button or result area. Operators should be able to tell that ARES is processing a request without watching the terminal.
+
+The Live page owns a browser WebSocket connection. Navigating away closes that connection, so users reconnect when they return to the page.
diff --git a/docs/github-publish-guide.md b/docs/github-publish-guide.md
index 59e2c3e..12f11b0 100644
--- a/docs/github-publish-guide.md
+++ b/docs/github-publish-guide.md
@@ -122,7 +122,7 @@ Highlights:
- Encrypted vault and token revocation.
- RBAC for team lead, operator, recon, and reporter workflows.
- Local validation lab for safe smoke testing.
-- HTML report generation with ARES branding.
+- HTML, PDF, Markdown, and JSON report generation with ARES branding.
- Campaign delete flow for cleanup of lab/test campaigns.
Safety note:
diff --git a/docs/module-development.md b/docs/module-development.md
index dfcb047..28fc2ad 100644
--- a/docs/module-development.md
+++ b/docs/module-development.md
@@ -8,9 +8,7 @@ Writing your first ARES module in 10 minutes.
```python
# mymodule/mssql_enum.py
-from ares.modules.base import BaseModule, ModuleResult, OpsecLevel
-from ares.core.campaign import Finding, Severity
-from ares.core.context import ExecutionContext
+from ares.sdk import BaseModule, ExecutionContext, Finding, ModuleResult, OpsecLevel, Severity
from ares.core.errors import NetworkError, ConnectionRefused
@@ -30,7 +28,7 @@ class MssqlEnumModule(BaseModule):
MITRE_TECHNIQUES = ["T1505.001"]
MODULE_AUTHOR = "Your Name <[email protected]>"
- # ── v0.9.0 SDK contract ─────────────────────────────────────────────
+ # ── ARES SDK contract ─────────────────────────────────────────────
async def validate(self, ctx: ExecutionContext) -> None:
"""Check that context has everything we need before executing."""
@@ -127,7 +125,7 @@ class MssqlEnumModule(BaseModule):
---
-## The SDK Contract (v0.9.0)
+## The ARES SDK Contract
### `validate(ctx)` — Called before execution
@@ -277,7 +275,7 @@ result = ModuleResult(
```python
import pytest
-from ares.core.context import ExecutionContext
+from ares.sdk import ExecutionContext
from mymodule.mssql_enum import MssqlEnumModule
@pytest.mark.asyncio
@@ -304,7 +302,7 @@ async def test_mssql_enum_dry_run():
assert result.module_id == "db.mssql_enum"
def test_module_metadata():
- from ares.modules.base import validate_module_class
+ from ares.sdk import validate_module_class
errors = validate_module_class(MssqlEnumModule)
assert errors == [], f"Module metadata errors: {errors}"
```
diff --git a/docs/module_sdk.md b/docs/module_sdk.md
index 9d3b336..713bfdd 100644
--- a/docs/module_sdk.md
+++ b/docs/module_sdk.md
@@ -2,16 +2,19 @@
**Version:** 1.0.0 | **Status:** Active
-> Complete guide for community module authors.
+> Complete guide for ARES module authors.
> Everything needed to build, test, sign, and publish an ARES module.
+`ares.sdk` is the preferred public import path for new modules. The older
+`ares.modules.sdk` path remains available for existing modules.
+
---
## Quick Start
```python
# my_module.py
-from ares.modules.sdk import (
+from ares.sdk import (
BaseModule, ExecutionContext, ModuleResult,
OpsecLevel, Severity, Finding,
module_metadata, get_logger,
@@ -214,7 +217,7 @@ class MyModule(BaseModule):
Always raise typed SDK errors — engine uses the type to decide retry/fallback/abort:
```python
-from ares.modules.sdk import (
+from ares.sdk import (
AuthenticationFailed, # try next credential
AccountLocked, # ABORT all auth attempts
HostUnreachable, # skip this target
@@ -317,7 +320,7 @@ Use `ModuleTestHelper` from the SDK:
```python
# tests/test_my_module.py
import pytest
-from ares.modules.sdk import ModuleTestHelper
+from ares.sdk import ModuleTestHelper
from my_module import MyModule
class TestMyModule:
@@ -347,7 +350,7 @@ class TestMyModule:
await helper.validate(ctx)
def test_report_structure(self, helper):
- from ares.modules.base import ModuleResult
+ from ares.sdk import ModuleResult
result = ModuleResult(status="success", module_id="myorg.my_attack")
report = helper.report(result)
assert "module_id" in report
diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index d9b4a59..cd5717c 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -73,12 +73,14 @@ interface DashboardUiState {
}
interface ModuleRunRecord {
+ campaignId: string;
moduleId: string;
payload: unknown;
isError?: boolean;
}
interface PersistedResult {
+ key: string;
payload: unknown;
isError?: boolean;
}
@@ -597,8 +599,8 @@ function ModulesPage() {
});
const run = useMutation({
mutationFn: () => api.runModule(selectedId, buildModuleRunPayload(campaignId, params, dryRun)),
- onSuccess: (payload) => setLastRunRecord({ moduleId: selectedId, payload }),
- onError: (error) => setLastRunRecord({ moduleId: selectedId, payload: serializeError(error), isError: true })
+ onSuccess: (payload) => setLastRunRecord({ campaignId, moduleId: selectedId, payload }),
+ onError: (error) => setLastRunRecord({ campaignId, moduleId: selectedId, payload: serializeError(error), isError: true })
});
const list = modules.data ?? [];
const selected = list.find((item) => item.id === selectedId);
@@ -617,7 +619,7 @@ function ModulesPage() {
const canRun = Boolean(campaignId && selectedId) && (!sensitive || confirmed) && !run.isPending;
const runBlocked = !canRun || Boolean(scopeWarning);
const runHint = moduleRunHint(campaignId, selected, selectedCampaign, sensitive, confirmed, dryRun);
- const persistedRun = lastRunRecord?.moduleId === selectedId ? lastRunRecord : null;
+ const persistedRun = lastRunRecord?.campaignId === campaignId && lastRunRecord.moduleId === selectedId ? lastRunRecord : null;
const runResult = (run.data ?? (!persistedRun?.isError ? persistedRun?.payload : undefined)) as Record<string, unknown> | undefined;
const runError = run.error ?? (persistedRun?.isError ? persistedRun.payload : undefined);
@@ -752,14 +754,16 @@ function ReportsPage() {
queryFn: () => api.reports(campaignId),
enabled: Boolean(campaignId)
});
+ const reportResultKey = `${campaignId}:${format}`;
const generate = useMutation({
mutationFn: () => api.generateReport(campaignId, format),
onSuccess: (payload) => {
- setLastGenerateResult({ payload });
+ setLastGenerateResult({ key: reportResultKey, payload });
void queryClient.invalidateQueries({ queryKey: ["reports", campaignId] });
},
- onError: (error) => setLastGenerateResult({ payload: serializeError(error), isError: true })
+ onError: (error) => setLastGenerateResult({ key: reportResultKey, payload: serializeError(error), isError: true })
});
+ const persistedGenerateResult = lastGenerateResult?.key === reportResultKey ? lastGenerateResult : null;
const download = useMutation({
mutationFn: async (item: ReportItem) => {
const blob = await api.downloadReport(campaignId, item.filename);
@@ -806,8 +810,8 @@ function ReportsPage() {
</div>
{warning && <p className="mt-2 text-sm font-semibold text-red-700">{warning}</p>}
<DataPanel
- title={(generate.error ?? (lastGenerateResult?.isError ? lastGenerateResult.payload : undefined)) ? "Generate Error" : "Generate Result"}
- data={generate.error ?? generate.data ?? lastGenerateResult?.payload}
+ title={(generate.error ?? (persistedGenerateResult?.isError ? persistedGenerateResult.payload : undefined)) ? "Generate Error" : "Generate Result"}
+ data={generate.error ?? generate.data ?? persistedGenerateResult?.payload}
/>
</div>
<section className="panel mt-4 overflow-auto p-4">
@@ -844,11 +848,13 @@ function GraphPage() {
const [lastIngestResult, setLastIngestResult] = useSessionState<PersistedResult | null>("ares.dashboard.graph.lastIngest", null);
const graph = useQuery({ queryKey: ["graph", campaignId], queryFn: () => api.graph(campaignId), enabled: Boolean(campaignId) });
const paths = useQuery({ queryKey: ["attack-paths", campaignId], queryFn: () => api.attackPaths(campaignId), enabled: Boolean(campaignId) });
+ const ingestResultKey = `${campaignId}:${jsonPath.trim()}`;
const ingest = useMutation({
mutationFn: () => api.ingestBloodhound(campaignId, jsonPath),
- onSuccess: (payload) => setLastIngestResult({ payload }),
- onError: (error) => setLastIngestResult({ payload: serializeError(error), isError: true })
+ onSuccess: (payload) => setLastIngestResult({ key: ingestResultKey, payload }),
+ onError: (error) => setLastIngestResult({ key: ingestResultKey, payload: serializeError(error), isError: true })
});
+ const persistedIngestResult = lastIngestResult?.key === ingestResultKey ? lastIngestResult : null;
const nodes = Array.isArray(graph.data?.nodes) ? graph.data.nodes : [];
const links = Array.isArray(graph.data?.links) ? graph.data.links : [];
return (
@@ -913,8 +919,8 @@ function GraphPage() {
{warning && <p className="mt-2 text-sm font-semibold text-red-700">{warning}</p>}
<DataPanel title="Attack Paths" data={paths.data} />
<DataPanel
- title={(ingest.error ?? (lastIngestResult?.isError ? lastIngestResult.payload : undefined)) ? "Ingest Error" : "Ingest Result"}
- data={ingest.data ?? ingest.error ?? lastIngestResult?.payload}
+ title={(ingest.error ?? (persistedIngestResult?.isError ? persistedIngestResult.payload : undefined)) ? "Ingest Error" : "Ingest Result"}
+ data={ingest.data ?? ingest.error ?? persistedIngestResult?.payload}
/>
</section>
</div>
@@ -928,13 +934,15 @@ function TemplatesPage() {
const [params, setParams] = useSessionState("ares.dashboard.templates.params", "{}");
const [warning, setWarning] = useState("");
const [lastPlanResult, setLastPlanResult] = useSessionState<PersistedResult | null>("ares.dashboard.templates.lastPlan", null);
+ const templatePlanKey = `${name.trim()}:${params}`;
const plan = useMutation({
mutationFn: () => api.templatePlan(name, safeJson(params)),
- onSuccess: (payload) => setLastPlanResult({ payload }),
- onError: (error) => setLastPlanResult({ payload: serializeError(error), isError: true })
+ onSuccess: (payload) => setLastPlanResult({ key: templatePlanKey, payload }),
+ onError: (error) => setLastPlanResult({ key: templatePlanKey, payload: serializeError(error), isError: true })
});
const selected = (templates.data ?? []).find((item) => item.name === name);
- const generated = (plan.data ?? (!lastPlanResult?.isError ? lastPlanResult?.payload : undefined)) as TemplatePlanResponse | undefined;
+ const persistedPlanResult = lastPlanResult?.key === templatePlanKey ? lastPlanResult : null;
+ const generated = (plan.data ?? (!persistedPlanResult?.isError ? persistedPlanResult?.payload : undefined)) as TemplatePlanResponse | undefined;
const paramsValid = isJsonObject(params);
return (
<Page title="Templates">
@@ -1036,8 +1044,8 @@ function TemplatesPage() {
</button>
<TemplatePlanSummary plan={generated} />
<DataPanel
- title={(plan.error ?? (lastPlanResult?.isError ? lastPlanResult.payload : undefined)) ? "Plan Error" : "Plan Details"}
- data={plan.error ?? plan.data ?? lastPlanResult?.payload}
+ title={(plan.error ?? (persistedPlanResult?.isError ? persistedPlanResult.payload : undefined)) ? "Plan Error" : "Plan Details"}
+ data={plan.error ?? plan.data ?? persistedPlanResult?.payload}
/>
</section>
</div>
@@ -1054,6 +1062,7 @@ function StrategyPage() {
const [llmBackend, setLlmBackend] = useSessionState("ares.dashboard.strategy.llmBackend", "claude");
const [authorizations, setAuthorizations] = useSessionState("ares.dashboard.strategy.authorizations", "");
const [lastEngageResult, setLastEngageResult] = useSessionState<PersistedResult | null>("ares.dashboard.strategy.lastEngage", null);
+ const strategyResultKey = `${campaignId}:${goal}:${llmBackend}:${authorizations}`;
const engage = useMutation({
mutationFn: () =>
api.engageStrategy({
@@ -1063,9 +1072,10 @@ function StrategyPage() {
max_rounds: 5,
authorizations: splitLines(authorizations)
}),
- onSuccess: (payload) => setLastEngageResult({ payload }),
- onError: (error) => setLastEngageResult({ payload: serializeError(error), isError: true })
+ onSuccess: (payload) => setLastEngageResult({ key: strategyResultKey, payload }),
+ onError: (error) => setLastEngageResult({ key: strategyResultKey, payload: serializeError(error), isError: true })
});
+ const persistedEngageResult = lastEngageResult?.key === strategyResultKey ? lastEngageResult : null;
const allowed = user?.role === "team_lead" || user?.role === "operator";
return (
<Page title="Strategy">
@@ -1114,8 +1124,8 @@ function StrategyPage() {
<section>
<DataPanel title="Active" data={active.data} />
<DataPanel
- title={(engage.error ?? (lastEngageResult?.isError ? lastEngageResult.payload : undefined)) ? "Engagement Error" : "Engagement Result"}
- data={engage.data ?? engage.error ?? lastEngageResult?.payload}
+ title={(engage.error ?? (persistedEngageResult?.isError ? persistedEngageResult.payload : undefined)) ? "Engagement Error" : "Engagement Result"}
+ data={engage.data ?? engage.error ?? persistedEngageResult?.payload}
/>
</section>
</div>
@@ -1220,6 +1230,7 @@ function EdrPage() {
const [success, setSuccess] = useSessionState("ares.dashboard.edr.success", false);
const [notes, setNotes] = useSessionState("ares.dashboard.edr.notes", "");
const [lastReportResult, setLastReportResult] = useSessionState<PersistedResult | null>("ares.dashboard.edr.lastReport", null);
+ const edrReportKey = `${techniqueId.trim()}:${vendor.trim()}:${version.trim()}:${success}:${notes.trim()}`;
const report = useMutation({
mutationFn: () =>
api.reportBypass({
@@ -1229,9 +1240,10 @@ function EdrPage() {
success,
notes: notes.trim()
}),
- onSuccess: (payload) => setLastReportResult({ payload }),
- onError: (error) => setLastReportResult({ payload: serializeError(error), isError: true })
+ onSuccess: (payload) => setLastReportResult({ key: edrReportKey, payload }),
+ onError: (error) => setLastReportResult({ key: edrReportKey, payload: serializeError(error), isError: true })
});
+ const persistedReportResult = lastReportResult?.key === edrReportKey ? lastReportResult : null;
return (
<Page title="EDR/OPSEC">
<section className="panel p-4">
@@ -1301,8 +1313,8 @@ function EdrPage() {
</form>
</section>
<DataPanel
- title={(report.error ?? (lastReportResult?.isError ? lastReportResult.payload : undefined)) ? "Outcome Error" : "Outcome Result"}
- data={report.data ?? report.error ?? lastReportResult?.payload}
+ title={(report.error ?? (persistedReportResult?.isError ? persistedReportResult.payload : undefined)) ? "Outcome Error" : "Outcome Result"}
+ data={report.data ?? report.error ?? persistedReportResult?.payload}
/>
<DataPanel title="Raw Stats" data={stats.data} />
</Page>
diff --git a/pyproject.toml b/pyproject.toml
index d765063..e6e2157 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "ares-redteam"
version = "6.0.0"
-description = "ARES — Automated Red team Engagement System"
+description = "ARES - Automated Red Team Engagement System"
readme = "README.md"
license = { text = "MIT" }
requires-python = ">=3.10"
@@ -50,7 +50,7 @@ dependencies = [
"aiosqlite>=0.20",
"sqlalchemy>=2.0",
"aiofiles>=23.2",
- "alembic>=1.13", # DB migrations — required for revoked_access_tokens table
+ "alembic>=1.13", # DB migrations - required for revoked_access_tokens table
# CLI
"typer>=0.12",
@@ -133,7 +133,7 @@ line-length = 100
target-version = "py310"
select = ["E", "F", "W", "I", "N", "UP", "S", "B", "A", "C4", "PT"]
ignore = ["S101", "S104", "S108"]
-# Removed S603/S607 — subprocess shell injection must be audited, not silenced.
+# Removed S603/S607 - subprocess shell injection must be audited, not silenced.
# If a module intentionally calls subprocess, add inline: # noqa: S603
[tool.mypy]
diff --git a/scripts/setup.sh b/scripts/setup.sh
index f4636fa..6eaa136 100644
--- a/scripts/setup.sh
+++ b/scripts/setup.sh
@@ -3,12 +3,12 @@ set -e
echo "=== ARES Setup ==="
-# Cek Python 3.10+
+# Check Python 3.10+
python3 -c "import sys; assert sys.version_info >= (3,10), 'Python 3.10+ required'" 2>/dev/null \
|| { echo "ERROR: Python 3.10+ required"; exit 1; }
echo "[OK] Python $(python3 --version)"
-# Buat venv kalau belum ada
+# Create virtual environment kalau belum ada
if [ ! -d ".venv" ]; then
echo "[*] Creating virtual environment..."
python3 -m venv .venv
@@ -32,7 +32,7 @@ if [ ! -f ".env" ]; then
ENC=$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
sed -i "s|ARES_SECRET_KEY=CHANGE_ME.*|ARES_SECRET_KEY=$SECRET|" .env
sed -i "s|ARES_ENCRYPTION_KEY=CHANGE_ME.*|ARES_ENCRYPTION_KEY=$ENC|" .env
- echo "[!] .env created — set ARES_DEFAULT_ADMIN_PASSWORD before starting"
+ echo "[!] .env created - set ARES_DEFAULT_ADMIN_PASSWORD before starting"
fi
echo ""
diff --git a/tests/unit/test_sdk_public_api.py b/tests/unit/test_sdk_public_api.py
new file mode 100644
index 0000000..0fdec91
--- /dev/null
+++ b/tests/unit/test_sdk_public_api.py
@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import pytest
+
+import ares.sdk as sdk
+from ares.core.context import ExecutionContext
+from ares.modules.base import BaseModule, ModuleResult, OpsecLevel, validate_module_class
+
+
+def test_public_sdk_re_exports_core_contracts() -> None:
+ assert sdk.BaseModule is BaseModule
+ assert sdk.ExecutionContext is ExecutionContext
+ assert sdk.ModuleResult is ModuleResult
+ assert sdk.OpsecLevel is OpsecLevel
+ assert sdk.validate_module_class is validate_module_class
+
+
+def test_public_sdk_all_contains_author_symbols() -> None:
+ for symbol in (
+ "BaseModule",
+ "ExecutionContext",
+ "ModuleResult",
+ "ModuleTestHelper",
+ "Finding",
+ "Severity",
+ "module_metadata",
+ "requires_privilege",
+ "timeout",
+ "ModuleValidationError",
+ ):
+ assert symbol in sdk.__all__
+ assert hasattr(sdk, symbol)
+
+
+def test_module_metadata_decorator_available_from_public_sdk() -> None:
+ @sdk.module_metadata(
+ module_id="demo.example",
+ name="Demo Example",
+ category="network",
+ description="SDK import smoke test",
+ author="ARES",
+ opsec=sdk.OpsecLevel.LOW,
+ requires=["target"],
+ outputs=["finding"],
+ mitre=["T1592.002"],
+ )
+ class DemoModule(sdk.BaseModule):
+ async def run(self, **kwargs):
+ return [], {"ok": True}
+
+ assert DemoModule.MODULE_ID == "demo.example"
+ assert DemoModule.metadata()["id"] == "demo.example"
+ assert sdk.validate_module_class(DemoModule) == []
+
+
+async def test_module_test_helper_available_from_public_sdk() -> None:
+ @sdk.module_metadata(
+ module_id="demo.helper",
+ name="Demo Helper",
+ category="network",
+ description="SDK helper smoke test",
+ )
+ class DemoModule(sdk.BaseModule):
+ async def execute(self, ctx: sdk.ExecutionContext) -> sdk.ModuleResult:
+ return sdk.ModuleResult(
+ status="dry_run" if ctx.dry_run else "success",
+ module_id=self.MODULE_ID,
+ raw={"target": ctx.target},
+ )
+
+ async def run(self, **kwargs):
+ return [], {"ok": True}
+
+ helper = sdk.ModuleTestHelper(DemoModule, scope_cidrs=["127.0.0.1/32"])
+ result = await helper.run_full(target="127.0.0.1", dry_run=True)
+
+ assert result.status == "dry_run"
+ assert result.module_id == "demo.helper"
+ assert result.raw == {"target": "127.0.0.1"}