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: synchronize API reference, frontend auth, and anti-overclaim terminology

Mafifriziefe7b2b48a20
diff --git a/README.md b/README.md
index 5cc3559..aea0462 100644
--- a/README.md
+++ b/README.md
@@ -73,7 +73,7 @@ Traditional penetration testing is fundamentally flawed: it is expensive, episod
| **Testing Frequency** | Annual / Semi-Annual | Scheduled Daily / Weekly | **Continuous / On-Demand** |
| **Exploitability Validation** | Manual & Labor Intensive | Theoretical CVE Matching (No Validation) | **Deterministic Multi-Stage Proof** |
| **Multi-Hop Attack Paths** | Manual Drawing | None | **Real-Time Interactive DAG** |
-| **Scope Enclave & Egress Guard** | Operator Discipline Only | Network Firewalls Only | **Fail-Closed App-Layer ScopeGuard & Kernel Socket Firewall** |
+| **Scope Enclave & Egress Guard** | Operator Discipline Only | Network Firewalls Only | **Fail-Closed Dual-Layer ScopeGuard & OS/Transport Firewall** |
| **Active Directory Lateral Paths** | Slow Script Execution | No Active Paths | **Native BloodHound & Kerberos Suite** |
| **Credential Security & Storage** | Loose Flat Files / Cleartext | Vulnerability Logs | **AES-256-GCM Authenticated Vault** |
| **OPSEC & Telemetry Throttling** | Manual Jitter Scripts | High Network Noise | **Adaptive Noise Profiles & Governor** |
diff --git a/docs/README.md b/docs/README.md
index 73084d2..a82674b 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -32,6 +32,7 @@ The documentation is organized into five functional pillars:
| --- | --- | --- |
| [api-reference.md](api-reference.md) | Full FastAPI endpoint specification, query parameters, and JSON payloads. | API Consumers, Integrators |
| [security-model.md](security-model.md) | Formal threat model, credential encryption, memory protection, and CSRF isolation. | Security Architects, Auditors |
+| [sso-setup.md](sso-setup.md) | Enterprise Multi-Tenant Single Sign-On (SAML 2.0 / OIDC), IdP federation, and setup. | IAM Engineers, Admins |
| [database-migrations.md](database-migrations.md) | Alembic revision chain (0001 to 0011), SQLite/PostgreSQL schema parity, and adoption. | DBAs, DevOps |
| [validation-lab.md](validation-lab.md) | Local hermetic validation lab specification and automated safety test harness. | QA, Core Engineers |
diff --git a/docs/api-reference.md b/docs/api-reference.md
index eb4b961..85cfe03 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -156,6 +156,93 @@ created.
---
+### `GET /auth/sso/init`
+
+Initiate an SP-initiated Single Sign-On (SAML 2.0 or OIDC) flow for a specific organization. Returns the authorization redirect URL and registers an ephemeral single-use state token in the database for CSRF and replay protection.
+
+**Query Parameters:**
+- `org`: Organization slug (defaults to `"default"`).
+
+**Response:** `200 OK`
+```json
+{
+ "configured": true,
+ "protocol": "saml",
+ "redirect_url": "https://idp.example.com/sso/endpoint?...",
+ "flow_id": "c1f7b8c2-..."
+}
+```
+
+---
+
+### `POST /auth/sso/saml/acs`
+
+SAML 2.0 Assertion Consumer Service (ACS) endpoint (HTTP-POST binding). Receives signed base64-encoded XML assertions from Identity Providers (Okta, Microsoft Entra ID, Ping), verifies digital signatures with the stored IdP x.509 certificate, validates the `InResponseTo` correlation identifier against active state tokens, JIT-provisions the user, and sets secure browser session cookies (`ares-dev-refresh` and `ares-dev-csrf`).
+
+**Request:** `application/x-www-form-urlencoded`
+```
+SAMLResponse=PHNhbWxwOlJlc3BvbnNlLi4u&RelayState=%2Fdashboard%2F
+```
+
+**Response:** HTTP `303 See Other` redirecting to the target dashboard route with active session cookies.
+
+---
+
+### `GET /auth/sso/oidc/callback`
+
+OpenID Connect (OIDC) Authorization Code callback endpoint. Exchanges the one-time authorization code with the provider token endpoint, cryptographically verifies ID Token claims (`iss`, `aud`, `nonce`), maps user claims and roles, JIT-provisions the user account, and issues browser session cookies.
+
+**Query Parameters:**
+- `code`: Authorization code issued by the IdP.
+- `state`: Single-use state parameter generated during initiation.
+
+**Response:** HTTP `303 See Other` redirecting to `/dashboard/` with active session cookies.
+
+---
+
+### `GET /auth/sso/config/{org_slug}`
+
+Retrieve SSO status and metadata for an organization. Requires the `team_lead` administrative role.
+
+**Response:** `200 OK`
+```json
+{
+ "configured": true,
+ "organization": { "id": "org-1", "slug": "default", "name": "Default Organization" },
+ "protocol": "saml",
+ "is_enabled": true,
+ "issuer_or_entity_id": "https://idp.example.com/entityid",
+ "sso_url": "https://idp.example.com/sso",
+ "default_role": "reporter",
+ "has_certificate": true,
+ "has_client_secret": false
+}
+```
+
+---
+
+### `POST /auth/sso/config/{org_slug}`
+
+Register or update SSO federation settings for an organization. Requires the `team_lead` administrative role. All certificates and client secrets are encrypted before persistence via `AES-256-GCM` AEAD.
+
+**Request:** `application/json`
+```json
+{
+ "protocol": "saml",
+ "issuer_or_entity_id": "https://idp.example.com/entityid",
+ "sso_url": "https://idp.example.com/sso",
+ "idp_certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
+ "default_role": "reporter",
+ "role_mapping": {
+ "SecAdmins": "team_lead",
+ "RedTeam": "operator"
+ },
+ "is_enabled": true
+}
+```
+
+---
+
### `POST /auth/change-password`
Change password for the authenticated user.
@@ -327,6 +414,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.
+
+**Response:** `200 OK`
+```json
+{ "status": "restored", "credentials_loaded": 5 }
+```
+
+---
+
## Modules
### `GET /modules`
@@ -392,6 +490,67 @@ returns a local preview without module execution.
---
+### `POST /modules/{module_id}/feasibility`
+
+Pre-flight defense feasibility assessment before module execution. Evaluates target defense posture (EDR, Credential Guard, PPL, MDI, Sysmon), calculates risk score, and recommends stealthy alternatives.
+
+**Request:** `application/json`
+```json
+{
+ "campaign_id": "abc12345",
+ "target": "10.0.0.5",
+ "params": { "share": "C$" }
+}
+```
+
+**Response:** `200 OK`
+```json
+{
+ "module_id": "lateral.smb_exec",
+ "campaign_id": "abc12345",
+ "report": {
+ "feasible": true,
+ "risk_score": 45,
+ "target": "10.0.0.5",
+ "stealth_recommendations": []
+ }
+}
+```
+
+---
+
+### `GET /modules/execution-chains`
+
+Return read-only attack execution-chain guidance, capability paths, and multi-stage execution chain templates for the Modules catalog.
+
+**Response:** `200 OK`
+```json
+[
+ {
+ "id": "ad-kerberoast-to-privesc",
+ "name": "Active Directory Kerberoast to Local Privilege Escalation",
+ "steps": ["ad.spn_scan", "ad.kerberoast", "windows.privesc"]
+ }
+]
+```
+
+---
+
+### `POST /modules/reload`
+
+Hot-reload attack modules in-memory from builtin and external module sources. Strictly permitted for loopback origins (`127.0.0.1`, `::1`, `localhost`) or authenticated operators with administrative privileges.
+
+**Response:** `200 OK`
+```json
+{
+ "status": "ok",
+ "reloaded": true,
+ "module_count": 64
+}
+```
+
+---
+
## Reports
### `POST /reports/{campaign_id}`
diff --git a/docs/frontend.md b/docs/frontend.md
index 6398714..3a62c92 100644
--- a/docs/frontend.md
+++ b/docs/frontend.md
@@ -39,6 +39,12 @@ Then open `http://127.0.0.1:5173/dashboard/`.
- Browser authentication is same-origin only. Login first obtains a pre-login
CSRF cookie from `GET /auth/csrf`, then calls `POST /auth/token` with the
existing form body and `X-ARES-CSRF`.
+- Enterprise Single Sign-On (SAML 2.0 / OIDC): The login surface supports SP-initiated
+ SSO via **"Or continue with SSO"**. Clicking initiates `GET /auth/sso/init?org=default`,
+ redirecting to the configured IdP. Upon assertion verification at `/auth/sso/saml/acs`
+ or `/auth/sso/oidc/callback`, the backend issues secure session cookies and redirects
+ back to `/dashboard/`, where `AuthProvider` performs a locked startup refresh and loads
+ the operator profile.
- Access tokens are held in module memory only. Refresh tokens exist only in a
host-only HttpOnly cookie and never enter JSON, browser-readable storage,
React state, messages, logs, or request bodies/headers/queries.