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: fix port inconsistency and add 5 missing endpoint docs (AUD-010, AUD-011)

Mafifrizi8255f6b90d84
diff --git a/README.md b/README.md
index 6e5542b..f6001e6 100644
--- a/README.md
+++ b/README.md
@@ -694,7 +694,7 @@ Automate engagements, dispatch modules, and stream real-time WebSocket telemetry
```python
from ares.sdk import AresClient
-async with AresClient(base_url="http://127.0.0.1:8000", api_key="ares_key_...") as ares:
+async with AresClient(base_url="http://127.0.0.1:8080", api_key="ares_key_...") as ares:
campaign = await ares.campaigns.create(name="Op-Titan", scope=["10.0.0.0/24"])
job = await ares.modules.run("ad.kerberoast", target="dc01.corp.local", campaign_id=campaign["id"])
findings = await ares.campaigns.findings(campaign["id"])
diff --git a/docs/api-reference.md b/docs/api-reference.md
index c4d09c2..0463927 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -362,27 +362,119 @@ cleanup or removing test campaigns from the dashboard.
### `GET /campaigns/{id}/findings`
-Get confirmed findings for a campaign.
-Optional filters: `?severity=critical&page=1&per_page=50`
+Get confirmed findings for a campaign with pagination and filtering.
-Campaign finding metadata remains available, but `evidence_json` is redacted for
-every caller and contains the JSON-encoded string `{"redacted":true}`. This
-endpoint does not provide raw evidence access. The policy applies only to the
-API response; it does not delete or rewrite evidence stored for authorized
-internal forensic consumers.
+**Authentication:** JWT Bearer token or `X-API-Key` with `read` scope. Requires campaign access.
+
+**Parameters:**
+- `page` (query, integer, default `1`, minimum `1`): Page number.
+- `per_page` (query, integer, default `50`, range `1-500`): Items per page.
+- `severity` (query, string, optional): Filter by severity (`critical`, `high`, `medium`, `low`, `info`).
+- `false_positive` (query, boolean, optional): Filter false positives (`true` or `false`).
+
+**Response Headers:**
+- `X-Total-Count`: Total number of matching findings.
+- `X-Page`: Current page number.
+- `X-Per-Page`: Current per-page limit.
+
+**Response:** `200 OK`
+```json
+[
+ {
+ "id": "fnd_12345",
+ "campaign_id": "abc12345",
+ "module_id": "ad.kerberoast",
+ "title": "Kerberoastable Service Account Found",
+ "severity": "high",
+ "confidence": "confirmed",
+ "mitre_technique": "T1558.003",
+ "evidence_json": "{\"redacted\":true}",
+ "cvss_score": 7.5,
+ "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N",
+ "false_positive": false,
+ "discovered_at": "2026-09-30T00:00:00Z"
+ }
+]
+```
+
+> **Forensic Redaction Policy:** Campaign finding metadata remains available, but `evidence_json` is redacted for every caller and contains `{"redacted":true}`. This endpoint does not provide raw evidence access over HTTP; raw evidence is stored for authorized internal consumers only.
---
### `GET /campaigns/{id}/cvss`
-Get CVSS score distribution for a campaign.
+Get CVSS v3.1 score distribution and summary for a campaign, suitable for compliance reports (PCI-DSS, ISO 27001).
+
+**Authentication:** JWT Bearer token or `X-API-Key` with `read` scope. Requires campaign access.
+
+**Response:** `200 OK`
+```json
+{
+ "campaign_id": "abc12345",
+ "cvss_summary": {
+ "total_findings": 10,
+ "mean_score": 6.8,
+ "max_score": 9.8,
+ "critical_count": 2,
+ "high_count": 4,
+ "medium_count": 3,
+ "low_count": 1
+ },
+ "findings_with_scores": [
+ {
+ "id": "fnd_12345",
+ "title": "Kerberoastable Service Account Found",
+ "cvss_score": 7.5,
+ "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N",
+ "severity": "high",
+ "mitre": "T1558.003"
+ }
+ ]
+}
+```
---
### `GET /campaigns/{id}/diff/{other_id}`
-Compare two campaigns - shows new findings, fixed findings, and severity changes.
-Useful for verifying remediation between assessments.
+Generate a delta report comparing two campaigns (`campaign_id` vs `other_id`). Compares findings matched by normalized title (case-insensitive) to verify remediation progress between assessments.
+
+**Authentication:** JWT Bearer token or `X-API-Key`. Caller must have authorized access to both campaigns.
+
+**Response:** `200 OK`
+```json
+{
+ "new_findings": [
+ {
+ "id": "fnd_67890",
+ "title": "Unquoted Service Path",
+ "severity": "medium",
+ "cvss_score": 6.5,
+ "cvss_vector": "CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H",
+ "mitre": "T1574.009"
+ }
+ ],
+ "fixed_findings": [
+ {
+ "id": "fnd_12345",
+ "title": "Kerberoastable Service Account Found",
+ "severity": "high",
+ "cvss_score": 7.5,
+ "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:L/UI:N/S:U/C:H/I:N/A:N",
+ "mitre": "T1558.003"
+ }
+ ],
+ "severity_changed": [],
+ "summary": {
+ "current_campaign_id": "abc12345",
+ "base_campaign_id": "prev67890",
+ "new_count": 1,
+ "fixed_count": 1,
+ "net_change": 0,
+ "risk_improved": true
+ }
+}
+```
---
@@ -416,11 +508,17 @@ durably terminal:
### `POST /campaigns/{id}/restore-vault`
-Re-hydrate the campaign's `CredentialVault` from persisted database records. Loads encrypted credentials at rest (`AES-256-GCM` v2 / transparent legacy Fernet fallback) into the active campaign memory session.
+Re-hydrate the campaign's `CredentialVault` from persisted database records into the active runtime engine state. Loads encrypted credentials at rest (`AES-256-GCM` AEAD or transparent legacy fallback) into the active campaign memory session after a server restart.
+
+**Authentication:** Requires `operator` or `team_lead` role. Rate-limited per IP (`vault_restore` limit).
**Response:** `200 OK`
```json
-{ "status": "restored", "credentials_loaded": 5 }
+{
+ "restored": 5,
+ "campaign_id": "abc12345",
+ "message": "Vault restored into the active campaign runtime state"
+}
```
---
@@ -760,6 +858,33 @@ does not add bypass logic.
---
+## Telemetry & Statistics
+
+### `GET /stats/monthly`
+
+Return confirmed findings aggregated by day for the current calendar month (UTC). Used for dashboard metric cards, burn-down charts, and velocity tracking.
+
+**Authentication:** JWT Bearer token or `X-API-Key` with `read` scope.
+
+**Parameters:**
+- `campaign_id` (query, string, optional): Filter aggregation to a specific campaign. If omitted, aggregates across all campaigns accessible to the caller.
+
+**Response:** `200 OK`
+```json
+{
+ "period": "2026-09",
+ "label": "Security signals this cycle",
+ "total": 12,
+ "confirmed_findings": 12,
+ "series": [
+ { "date": "2026-09-01", "count": 3 },
+ { "date": "2026-09-02", "count": 9 }
+ ]
+}
+```
+
+---
+
## Templates
### `GET /templates`
diff --git a/docs/module-development.md b/docs/module-development.md
index 2debc68..05dc15c 100644
--- a/docs/module-development.md
+++ b/docs/module-development.md
@@ -453,7 +453,7 @@ Automate engagements, module runs, and telemetry streams from Python scripts or
from ares.sdk import AresClient
async def main():
- async with AresClient(base_url="http://127.0.0.1:8000", api_key="ares_key_...") as ares:
+ async with AresClient(base_url="http://127.0.0.1:8080", api_key="ares_key_...") as ares:
# Create campaign with approved scope
campaign = await ares.campaigns.create(
name="Op-Nightshade",
diff --git a/docs/module_sdk.md b/docs/module_sdk.md
index b15c7f5..0fa6582 100644
--- a/docs/module_sdk.md
+++ b/docs/module_sdk.md
@@ -152,7 +152,7 @@ Control and automate ARES from external Python scripts, SOAR playbooks, or CI/CD
```python
from ares.sdk import AresClient
-async with AresClient(base_url="http://127.0.0.1:8000", api_key="ares_pat_...") as client:
+async with AresClient(base_url="http://127.0.0.1:8080", api_key="ares_pat_...") as client:
campaign = await client.campaigns.create(name="Op-Titan", scope=["10.10.0.0/24"])
print(f"Created Campaign: {campaign['id']}")