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: align report workflow and support guidance

Mafifrizi28a65136152c
diff --git a/.env.example b/.env.example
index c53b0f6..a5c611e 100644
--- a/.env.example
+++ b/.env.example
@@ -55,6 +55,14 @@ ARES_LOG_FILE=logs/ares.log
# Rate limiting (requests per minute per IP)
ARES_RATE_LIMIT_RPM=60
+# Optional Redis URL for multi-pod/distributed rate limiting.
+# Leave unset for the in-process local fallback.
+# ARES_REDIS_URL=redis://redis:6379/0
+
+# PDF export browser fallback (optional)
+# Set only if browser auto-detection cannot find a working Edge/Chrome/Chromium.
+# Windows Edge example:
+# ARES_PDF_BROWSER=C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe
# Noise defaults
ARES_DEFAULT_NOISE_PROFILE=stealth
diff --git a/QUICKSTART.md b/QUICKSTART.md
index 5de9e33..af7dac8 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -236,12 +236,21 @@ Port behavior is module-specific. Some modules require explicit ports because th
Open `Reports`:
1. Select a campaign.
-2. Choose HTML, PDF, Markdown, or JSON.
+2. Choose `json`.
3. Click `Generate`.
-4. Use the dashboard `Download` button.
+4. Switch to `Library` and use `Download` to save/open the JSON artifact.
+5. Return to `Generate`, choose `pdf`, and click `Generate`.
+6. Switch to `Library` and use `Download` to save/open the PDF artifact.
+7. Use a row's `Delete` action to remove one artifact after confirming.
+8. Use `Delete all` / Clear library to remove the campaign's generated report
+ artifacts after confirming.
Do not open report file URLs directly in the browser address bar. Report downloads are authenticated, so direct unauthenticated URLs return `401`.
+Report evidence is redacted by default. Do not expose raw Kerberoast,
+ASREPRoast, password, token, or other secret material in demos or public
+reports; include sensitive evidence only for authorized internal review.
+
## 8. Use Templates
Open `Templates` when you want a repeatable plan.
diff --git a/README.md b/README.md
index 2c0531f..95d3b72 100644
--- a/README.md
+++ b/README.md
@@ -128,7 +128,7 @@ Dashboard areas:
| Overview | Health, operator telemetry metrics, and campaign summary. Overview has no variation tabs. |
| Campaigns | `List`, `Scope`, and `Findings` tabs for campaign creation, inspection, compare/restore/dry-run actions, and cleanup. |
| Modules | `Catalog`, `Run Panel`, and `Results` tabs for browsing modules, filling backend-generated parameter forms, and reviewing execution output. |
-| Reports | `Generate` and `Library` tabs for authenticated campaign report creation, listing, and download. |
+| Reports | `Generate` and `Library` tabs for authenticated campaign report creation, listing, download, per-report delete, and Delete all / Clear library cleanup. |
| Graph | `Entities`, `Attack Paths`, and `Ingest` tabs for graph review and BloodHound/SharpHound import. |
| Templates | `Templates` and `Plan Builder` tabs for selecting built-in plans and generating reviewable execution stages. |
| Strategy | `Objective`, `Active`, and `Result` tabs for authorized goal-based planning and state review. |
@@ -157,6 +157,11 @@ Recommended dashboard workflow:
PDF generation writes the PDF artifact directly; HTML is generated only when
you choose the HTML format. Report evidence is rendered as readable tables
and key-value rows where possible instead of unformatted report objects.
+ Report evidence is redacted by default; include sensitive evidence only
+ intentionally and only with authorized access. The Library tab supports
+ Download, per-report Delete, and Delete all / Clear library cleanup.
+ Successful deletes remove rows and update the artifact count without a page
+ reload.
7. Use `Security` for account administration. API keys are for scripts and
integrations; the Security Audit panel reports dependency-audit status for
the ARES environment, not findings from a target network.
@@ -315,6 +320,11 @@ Security page, but role assignment is done at account creation time through
- Findings, readable evidence tables, severity, timeline, MITRE, and
remediation-oriented sections.
- Authenticated report download through the dashboard.
+- Report Library cleanup through per-report Delete and Delete all / Clear
+ library actions.
+- Sensitive report evidence is redacted by default. Include raw hashes,
+ secrets, or other sensitive evidence only for authorized internal review,
+ never in public demos or shared reports.
### Validation Lab
@@ -642,6 +652,8 @@ Important design boundaries:
- Module forms are generated from backend metadata.
- Sensitive data stays behind authentication.
- Reports require authenticated download through the dashboard or API.
+- Report Library delete actions are authenticated and update visible rows and
+ artifact counts after success.
- Local validation flows use localhost by default.
See [docs/architecture.md](docs/architecture.md) and
@@ -684,7 +696,8 @@ Runtime features confirmed locally:
assets are built; local Vite dev mode uses `http://127.0.0.1:5173/dashboard/`.
- Health endpoint returns connected DB.
- Login, password change, API key lifecycle, and campaign cleanup work.
-- Report generation and authenticated download work.
+- Report generation, authenticated download, and Report Library delete/Delete
+ all cleanup work.
- PDF report layout, footer branding, and evidence rendering work.
- Overview telemetry records API-triggered module runs in the current process.
- Campaign delete removes stored child data and updates the UI immediately.
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 11892b2..5a689d5 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -329,25 +329,34 @@ Run a single module directly.
Generate a campaign report.
-```json
-{
- "format": "html",
- "include_timeline": true,
- "include_mitre_heatmap": true
-}
-```
+Query parameters:
-Supported formats: `html` | `pdf` | `json` | `markdown`
+| Parameter | Values | Default | Notes |
+| --- | --- | --- | --- |
+| `fmt` | `html`, `pdf`, `markdown`, `json` | `html` | Report artifact format. |
+| `include_sensitive_evidence` | `true`, `false` | `false` | Includes raw sensitive evidence only when the caller is authorized as `team_lead`. |
+
+Example:
+
+```text
+POST /reports/{campaign_id}?fmt=json&include_sensitive_evidence=false
+```
PDF generation uses the report renderer internally and returns a PDF artifact
-for `format: "pdf"`. The server uses WeasyPrint when available and can fall
+for `fmt=pdf`. The server uses WeasyPrint when available and can fall
back to a local Chromium-compatible browser in local environments where
WeasyPrint native libraries are not installed. On Windows, use Python 3.12.x
from normal non-Administrator PowerShell; WeasyPrint needs native GTK/Pango
libraries in addition to the pip package. Use `ares doctor --pdf-smoke` to
validate the active PDF backend. HTML and PDF reports render finding evidence
-as readable tables and key-value rows where possible. Use `json` output when
-you need raw machine-readable report data.
+as readable tables and key-value rows where possible.
+
+Report evidence is redacted by default. Do not include raw Kerberoast,
+ASREPRoast, password, token, or other secret material in public demos or shared
+reports. Use `include_sensitive_evidence=true` only for intentional,
+authorized internal review; non-`team_lead` callers receive `403`.
+
+Use `fmt=json` when you need machine-readable report data.
**Response:** `200 OK`
```json
@@ -364,6 +373,37 @@ that belong to the campaign and resolve inside the report directory.
Download a generated report file. Filename traversal, absolute paths, encoded
traversal, and symlink escapes are rejected.
+### `DELETE /reports/{campaign_id}/files/{filename}`
+
+Delete one generated report artifact for the campaign.
+
+- Requires report/campaign authorization.
+- Rejects unsafe filenames: traversal, absolute paths, nested paths, path
+ separators, empty filenames, and symlink escapes outside the report
+ directory.
+- Returns `404` when the report artifact is missing.
+
+**Response:** `200 OK`
+
+```json
+{ "status": "deleted", "campaign_id": "abc12345", "filename": "abc12345_Corp_20260714_1200.pdf" }
+```
+
+### `DELETE /reports/{campaign_id}`
+
+Clear generated report artifacts for the campaign.
+
+- Requires report/campaign authorization.
+- Deletes only generated report artifact extensions: `.pdf`, `.json`, `.html`,
+ and `.md`.
+- Ignores directories and unrelated files.
+
+**Response:** `200 OK`
+
+```json
+{ "status": "deleted", "campaign_id": "abc12345", "deleted": 3 }
+```
+
---
## Telemetry
diff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.md
index f085009..8e0daa3 100644
--- a/docs/dashboard-guide.md
+++ b/docs/dashboard-guide.md
@@ -290,7 +290,7 @@ Scope behavior:
### Reports
-Purpose: generate and download campaign reports.
+Purpose: generate, download, and manage campaign report artifacts.
![Report generation workflow](assets/screenshots/dashboard-reports.png)
@@ -313,6 +313,14 @@ rows where possible. Use JSON output when you need raw machine-readable data.
Use the dashboard Download button. Directly opening the file URL in the address
bar will return `401` because report files require an authenticated request.
+The Library tab lists generated artifacts for the selected campaign. Each row
+supports authenticated Download and per-report Delete. The Library header also
+offers Delete all / Clear library when artifacts exist. Delete actions require
+confirmation, remove the row or clear the table after success, and update the
+artifact count without a full page reload. If deletion fails, the page keeps
+the row and shows an error notice. When no reports remain, the Library shows
+the clean empty state: `No reports generated for this campaign yet.`
+
### Graph
Purpose: understand relationships and attack paths.
diff --git a/docs/frontend.md b/docs/frontend.md
index 367f79e..ce3d802 100644
--- a/docs/frontend.md
+++ b/docs/frontend.md
@@ -48,7 +48,7 @@ Then open `http://127.0.0.1:5173/dashboard/`.
- `/` overview: health, telemetry, campaign summary
- `/campaigns`: `List`, `Scope`, and `Findings` tabs for list/create/detail/delete, findings, CVSS, diff, restore, and dry-run plan actions
- `/modules`: `Catalog`, `Run Panel`, and `Results` tabs for catalog filters, backend-derived dynamic params, dry-run default, and execution output
-- `/reports`: `Generate` and `Library` tabs for report creation, listing, and authenticated download
+- `/reports`: `Generate` tab for report creation; `Library` tab for listing artifacts, authenticated download, per-report delete, and Delete all/Clear library cleanup. Successful delete actions update rows and artifact counts without a full page reload.
- `/graph`: `Entities`, `Attack Paths`, and `Ingest` tabs for graph review, attack paths, and BloodHound ingest
- `/templates`: `Templates` and `Plan Builder` tabs for listing templates and generating plans
- `/strategy`: `Objective`, `Active`, and `Result` tabs for active engagements and role-gated engagement start
diff --git a/docs/module-development.md b/docs/module-development.md
index 28fc2ad..bb7d0a1 100644
--- a/docs/module-development.md
+++ b/docs/module-development.md
@@ -321,7 +321,7 @@ def test_module_metadata():
"author": "Your Name",
"description": "Enumerate MSSQL instances",
"requires": ["pymssql"],
- "ares_min": "0.9.0",
+ "ares_min": "6.0.0",
"signature": "sha256:abc123..."
}
```
diff --git a/docs/security-model.md b/docs/security-model.md
index 3dd14a8..ff493a2 100644
--- a/docs/security-model.md
+++ b/docs/security-model.md
@@ -233,7 +233,8 @@ All sensitive operations are written to the NDJSON audit log:
{"event": "operator_joined", "actor": "bob", "role": "recon", "campaign_id": "..."}
```
-Log location: `~/.ares/audit.ndjson` (configurable via `ARES_AUDIT_LOG`).
+Audit log location follows the supported logging configuration: ARES writes
+`audit.ndjson` next to `ARES_LOG_FILE` (default: `logs/audit.ndjson`).
### Sensitive field masking