ARES - authorized red-team engagement automation with dashboard, campaign scope, module orchestration, OPSEC controls, encrypted vault, and reporting.
Python active-directorycloud-securitydefensive-validationfastapigood-first-issuemitre-attackopsecreactred-teamreportingsecurity
docs: align report workflow and support guidance
Mafifrizi28a65136152c
diff --git a/.env.example b/.env.exampleindex 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 defaultsARES_DEFAULT_NOISE_PROFILE=stealthdiff --git a/QUICKSTART.md b/QUICKSTART.mdindex 5de9e33..af7dac8 100644--- a/QUICKSTART.md+++ b/QUICKSTART.md@@ -236,12 +236,21 @@ Port behavior is module-specific. Some modules require explicit ports because thOpen `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 TemplatesOpen `Templates` when you want a repeatable plan.diff --git a/README.md b/README.mdindex 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 whenyou choose the HTML format. Report evidence is rendered as readable tablesand 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 andintegrations; the Security Audit panel reports dependency-audit status forthe 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, andremediation-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.mdindex 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 fallback to a local Chromium-compatible browser in local environments whereWeasyPrint native libraries are not installed. On Windows, use Python 3.12.xfrom normal non-Administrator PowerShell; WeasyPrint needs native GTK/Pangolibraries in addition to the pip package. Use `ares doctor --pdf-smoke` tovalidate 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, encodedtraversal, 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 }+```+---## Telemetrydiff --git a/docs/dashboard-guide.md b/docs/dashboard-guide.mdindex 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.@@ -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 addressbar 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.`+### GraphPurpose: understand relationships and attack paths.diff --git a/docs/frontend.md b/docs/frontend.mdindex 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 startdiff --git a/docs/module-development.md b/docs/module-development.mdindex 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.mdindex 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