docs/security/pentest_scope.md

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 POST /api/v1/predict/score POST /api/v1/transactions/score	HTTP REST	Real-time transaction risk scoring engine (realtime_inference.py, predict.py)	Authenticated Bank API Key / JWT	Input validation fuzzing, payload injection, rate limit evasion, circuit breaker tripping
POST /api/v1/cases GET /api/v1/cases	HTTP REST	Case management workbench API (cases.py, 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 POST /api/v1/cases/generate-sar	HTTP REST	FinCEN BSA SAR 2.0 XML generator (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)	Authenticated Lead Analyst JWT	Prompt injection, unauthorized data exfiltration, LLM hallucination boundary testing
POST /api/v1/psi/run POST /api/v1/entities/fuzzy-resolve	HTTP REST	Diffie-Hellman Private Set Intersection & MinHash LSH (psi_service.py, entity_resolution.py)	Authenticated Bank Client mTLS / JWT	Cryptographic parameter tampering, membership inference, set exhaustion
GET /v1/compliance/soc2-evidence POST /v1/compliance/soc2-evidence	HTTP REST	Automated SOC 2 evidence collection API (compliance.py)	Authenticated Security Auditor JWT	Evidence manipulation, false compliance injection
POST /api/v1/onboarding/request GET /api/v1/banks	HTTP REST	Self-service bank onboarding & consortium node registry (onboarding.py)	Authenticated Node Operator / Admin	Sybil identity injection, unauthorized node registration, CSRF
WS /ws/alerts WS /ws/scenarios 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.
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.
• 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.
• 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.

---

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/:

Test Suite	Targeted Attack Surface	Verified Defensive Invariant	Test Count	Status
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	API Gateway & Routing	Route prefix enforcement, unauthenticated request rejection, rate limiting	14	✅ 100% Pass
test_auth_security.py	Authentication & Tokens	JWT cryptographic signatures, expiration handling, role authorization, tenant claims	9	✅ 100% Pass
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	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