# Penetration Testing Scope & Rules of Engagement

This document defines the authorized penetration testing scope, target systems, out-of-scope infrastructure, attack surface architecture, test scenarios, and rules of engagement for security assessments of the Collaborative Fraud Intelligence (CFI) Platform.

---

## 1. Authorized Testing Scope

The following application interfaces, REST endpoints, and WebSocket channels are **IN SCOPE** for authorized white-box, gray-box, and black-box security penetration testing:

| Endpoint Path | Protocol | Target System / Function | Required Authorization Level | Permitted Test Types |
| :--- | :---: | :--- | :--- | :--- |
| `POST /v1/inference/score`<br>`POST /api/v1/predict/score`<br>`POST /api/v1/transactions/score` | HTTP REST | Real-time transaction risk scoring engine ([realtime_inference.py](../../backend/app/presentation/routers/realtime_inference.py), [predict.py](../../backend/app/presentation/routers/predict.py)) | Authenticated Bank API Key / JWT | Input validation fuzzing, payload injection, rate limit evasion, circuit breaker tripping |
| `POST /api/v1/cases`<br>`GET /api/v1/cases` | HTTP REST | Case management workbench API ([cases.py](../../backend/app/presentation/routers/cases.py), [case_workbench.py](../../backend/app/application/services/case_workbench.py)) | Authenticated Analyst JWT (`role: investigator`) | BOLA / IDOR, cross-tenant case leakage, privilege escalation |
| `POST /api/v1/cases/{case_id}/transition` | HTTP REST | Case lifecycle state machine & Four-Eyes dual control gating | Authenticated Supervisor JWT (`role: supervisor`) | State bypass attacks, anti-collusion single-supervisor signoff attempts |
| `POST /api/v1/cases/{case_id}/file-sar`<br>`POST /api/v1/cases/generate-sar` | HTTP REST | FinCEN BSA SAR 2.0 XML generator ([regulatory_reporter.py](../../backend/app/application/services/regulatory_reporter.py)) | Authenticated Compliance Officer JWT | XML External Entity (XXE) injection, schema poisoning, unapproved filing bypass |
| `POST /api/v1/cases/{case_id}/copilot-narrative` | HTTP REST | Agentic AML Copilot narrative generator ([aml_agentic_copilot.py](../../backend/app/application/services/aml_agentic_copilot.py)) | Authenticated Lead Analyst JWT | Prompt injection, unauthorized data exfiltration, LLM hallucination boundary testing |
| `POST /api/v1/psi/run`<br>`POST /api/v1/entities/fuzzy-resolve` | HTTP REST | Diffie-Hellman Private Set Intersection & MinHash LSH ([psi_service.py](../../backend/app/application/services/psi_service.py), [entity_resolution.py](../../backend/app/application/services/entity_resolution.py)) | Authenticated Bank Client mTLS / JWT | Cryptographic parameter tampering, membership inference, set exhaustion |
| `GET /v1/compliance/soc2-evidence`<br>`POST /v1/compliance/soc2-evidence` | HTTP REST | Automated SOC 2 evidence collection API ([compliance.py](../../backend/app/presentation/routers/compliance.py)) | Authenticated Security Auditor JWT | Evidence manipulation, false compliance injection |
| `POST /api/v1/onboarding/request`<br>`GET /api/v1/banks` | HTTP REST | Self-service bank onboarding & consortium node registry ([onboarding.py](../../backend/app/presentation/routers/onboarding.py)) | Authenticated Node Operator / Admin | Sybil identity injection, unauthorized node registration, CSRF |
| `WS /ws/alerts`<br>`WS /ws/scenarios`<br>`WS /ws/training` | WebSocket | Real-time fraud alert, scenario replay, and training telemetry streams | Authenticated WebSocket Bearer Token | Connection hijacking, unauthenticated subscription, cross-tenant frame injection |

---

## 2. Out-of-Scope Components

The following infrastructure components, internal network channels, and administrative control planes are strictly **OUT OF SCOPE** for penetration testing:

1. **Internal Microservice Mesh & Inter-Node Transport**:
   - `grpcs://coordinator:50051` and internal docker bridge network channels (`net-bank-a`, `net-bank-b`, `net-bank-c`, `net-coordinator`).
2. **Key Management Systems (KMS) & Vault Administrative Interfaces**:
   - HashiCorp Vault root management port (`:8200`), AWS KMS API keys, and unsealed Vault master keys.
3. **Database Engine Management Interfaces**:
   - Direct PostgreSQL port `5432` and Redis port `6379` direct network socket access (must only be accessed via application endpoints).
4. **Cloud Infrastructure & Managed Kubernetes Control Planes**:
   - AWS EKS control plane APIs, AWS IAM administrative credentials, and cloud provider hypervisors.
5. **Physical Enclave Hardware**:
   - Physical extraction of Intel SGX / AWS Nitro memory chips or CPU side-channel timing analysis requiring laboratory hardware access.
6. **Denial of Service (DoS / DDoS)**:
   - Volumetric network flood attacks (SYN flood, UDP flood) or resource exhaustion attacks targeting shared cloud transit gateways.

---

## 3. Known Attack Surface & Trust Boundaries

```
[ External Client / Bank IT / Auditor ]
             │
             ▼  (HTTPS / TLS 1.3 + OAuth2 JWT / mTLS)
   ┌───────────────────┐
   │   Perimeter WAF   │ (OWASP Top 10 Guard: SQLi, XSS, Null Byte, Sensitive Path, Auth Lockout)
   └─────────┬─────────┘
             │ (Inspected Requests)
             ▼
   ┌───────────────────┐
   │  FastAPI Gateway  │ (Dynamic ABAC, Tenant Isolation: tenant_{bank_id}, Rate Limiting)
   └─────────┬─────────┘
             │
             ├──► [ Application Layer Services ] (RiskEngine, PSI, Workbench, RegulatoryReporter)
             │
             ▼
   ┌───────────────────┐
   │ Persistence Layer │ (PostgreSQL schema-per-tenant, Redis Cache, Vault PKI / KMS)
   └───────────────────┘
```

### Core Trust Boundaries
1. **Multi-Tenant Isolation**: Each participant bank institution is strictly schema-isolated at the database engine level (`tenant_{bank_id}`). Cross-tenant data access is blocked by tenant context dependencies in [dependencies.py](../../backend/app/dependencies.py).
2. **Zero-PII Transmission**: All customer and transaction identifiers are normalized and hashed locally via type-salted HMAC-SHA256. Raw PII never traverses network boundaries.
3. **Differential Privacy Budgeting**: Local model training executes Opacus DP-SGD ($\epsilon \le 2.0, \delta = 10^{-5}$), mathematically bounding membership inference risk.
4. **Four-Eyes Dual-Control Governance**: High-risk case resolutions (`RESOLVED_TRUE_POSITIVE`, `RESOLVED_FALSE_POSITIVE`) and FinCEN SAR filings mandate two distinct supervisor cryptographic signatures (`SIG_SUPERVISOR_<ID>`).
5. **Cryptographic Payload Signing**: Coordinator-to-client federation REST traffic mandates HMAC-SHA256 signature verification (`X-Payload-Signature`, `X-Payload-Timestamp`) within a $\pm 300\text{s}$ tolerance window.

---

## 4. Permitted Attack Scenarios & Exploit Objectives

Penetration testers are authorized to execute the following threat scenarios against in-scope endpoints:

### Scenario A — Authentication & Authorization Bypass
* **JWT Claim Tampering**: Modifying `bank_id`, `roles`, or `clearance_level` claims within bearer tokens to evaluate signature validation robustness.
* **Horizontal Privilege Escalation (BOLA/IDOR)**: Attempting to retrieve, modify, or delete cases belonging to peer banks (e.g. Bank Alpha accessing `case_bank_beta_102`).
* **Broken Object Property Level Authorization (BOPLA)**: Submitting administrative fields during case updates (e.g., attempting to self-sign supervisor signatures).

### Scenario B — Injection & Input Validation Fuzzing
* **SQL Injection (SQLi)**: Injecting stacked SQL queries, UNION statements, and blind boolean vectors into transaction scoring and case search fields to test [perimeter_waf.py](../../backend/app/infrastructure/security/perimeter_waf.py).
* **Cross-Site Scripting (XSS)**: Injecting DOM payloads (`<script>`, `javascript:`) into case notes and investigator narrative fields.
* **Null Byte & Path Traversal**: Supplying `\x00` null bytes and directory traversal patterns (`../`) to test sensitive path blocking.

### Scenario C — Business Logic & Anti-Collusion Verification
* **Four-Eyes Gating Bypass**: Attempting to resolve a fraud case or generate FinCEN SAR XML using a single supervisor signature or identical dual signatures (`first == second`).
* **State Machine Invariant Violation**: Attempting illegal state transitions (e.g., transitioning directly from `NEW` to `RESOLVED_TRUE_POSITIVE` without `UNDER_INVESTIGATION`).

### Scenario D — Adversarial Machine Learning & Privacy Auditing
* **Membership Inference Attacks (MIA)**: Submitting transaction feature vectors to measure loss distribution anomalies and evaluate membership exposure via [privacy_audit_service.py](../../backend/app/application/services/privacy_audit_service.py).
* **Model Inversion**: Testing gradient norm variance to verify reconstruction resistance.
* **Deep Leakage from Gradients (DLG)**: Evaluating Pearson correlation leakage between candidate feature vectors and model updates.

---

## 5. Rules of Engagement & Emergency Procedures

### Pre-Testing Coordination
* Security assessment teams must provide **72 hours advance written notification** prior to beginning active testing.
* Testing must be conducted within agreed operational testing windows (typically 01:00 UTC – 05:00 UTC) to minimize potential impact on production simulation runs.

### Prohibited Activities
* **Destructive Data Modification**: Altering or deleting production audit chains, baseline model checkpoints, or regulatory archive filings.
* **Social Engineering & Phishing**: Physical access attempts, spear-phishing bank personnel, or credential harvesting targeting administrative staff.
* **Denial of Service**: Exceeding testing traffic thresholds or launching volumetric DDoS attacks.

### Critical Escalation & Emergency Stop
If an assessor identifies a critical vulnerability (CVSS v3.1 $\ge 9.0$, such as unauthenticated Remote Code Execution, full database compromise, or cross-tenant private key exposure) or causes unintended platform instability:
1. **Immediately Halt Testing**: Stop all active automated scanners and manual exploit execution.
2. **Contact Incident Response**: Notify the Security Operations Center at `secops@cfi-platform.org` with the subject line `[CRITICAL-PENTEST-FINDING]`.
3. **Execute Emergency Protocols**: Follow the formal containment and triage workflows defined in the [Incident Response Playbook](../incident_response_playbook.md).

---

## 6. Automated Security & Attack Surface Test Matrix

The platform's attack surface defenses, authentication invariants, WAF filters, and gateway boundaries are continuously verified through unit tests under [backend/tests/unit/](../../backend/tests/unit):

| Test Suite | Targeted Attack Surface | Verified Defensive Invariant | Test Count | Status |
| :--- | :--- | :--- | :---: | :---: |
| [test_security_controls_audit.py](../../backend/tests/unit/test_security_controls_audit.py) | **WAF & Perimeter Defense** | SQLi rejection, sensitive path protection, auth lockout (5 attempts), CORS origin whitelisting | 10 | ✅ 100% Pass |
| [test_security_gateway.py](../../backend/tests/unit/test_security_gateway.py) | **API Gateway & Routing** | Route prefix enforcement, unauthenticated request rejection, rate limiting | 14 | ✅ 100% Pass |
| [test_auth_security.py](../../backend/tests/unit/test_auth_security.py) | **Authentication & Tokens** | JWT cryptographic signatures, expiration handling, role authorization, tenant claims | 9 | ✅ 100% Pass |
| [test_auth_routes.py](../../backend/tests/unit/test_auth_routes.py) | **Auth Routes & ABAC Isolation** | Endpoint discovery, Bearer token lifecycle, tenant boundary isolation, /me profile, lockout status | 12 | ✅ 100% Pass |
| [test_security_headers.py](../../backend/tests/unit/test_security_headers.py) | **HTTP Header Hardening** | OWASP A02 headers (`X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `X-XSS-Protection`) | 2 | ✅ 100% Pass |
| **Total Verified** | **5 Dedicated Security Suites** | **Penetration Testing Attack Surface Parity** | **47 Tests** | **100% Pass** |