# Threat Intelligence — Admin Guide

> All admin operations require the `risk_assessment_admin` role, separate from regular admin.
> All admin actions are audited. Never log or share plaintext identifiers.

## Accessing the Admin Interface

The admin interface is available at `/risk-assessment` in the platform-admin dashboard (Phase 5). Until the frontend is built, all operations use the internal API at `POST/GET/PATCH /internal/risk-assessment/admin/...`.

## Core Concepts

### Threat Profiles

A threat profile represents a known dangerous individual. Profiles are identified by an admin-assigned **codename** (label) — never a real name.

**Fields:**
- **Label**: Admin codename (e.g., "FOXHOUND-7", "BRAVO-12")
- **Severity**: `low` | `medium` | `high` | `critical`
- **Source**: How the profile was created (`admin_flag`, `community_report`, `cross_reference`, `external_intel`)
- **Threat Score**: Computed from community reports (see Scoring below)
- **Active**: Whether identifiers on this profile trigger shadow onboarding

### Flagged Identifiers

SHA-256 hashed identifiers linked to threat profiles. When someone registers with a matching identifier, shadow onboarding activates.

**PII-based identifier types:** email, phone, legal_name, card_hash, device_fp, ip_address, username, payment_app_id

**Browser fingerprint types:** canvas_fp, webgl_fp, audio_fp, webrtc_local_ip, screen_geometry, timezone_locale, font_set, hardware_profile

**Behavioral biometric types:** typing_cadence, mouse_dynamics

**Confidence score** (0.00–1.00): Admin-entered identifiers default to 1.0. Shadow-collected identifiers default to 0.8. Browser fingerprint matches default to 0.8. Behavioral biometric matches may be lower (typically 0.6–0.7) due to natural variation in typing and movement patterns across sessions.

#### Browser Fingerprints

Browser fingerprints are collected passively during shadow onboarding steps. They provide VPN-resistant, identity-change-resistant signals that persist even when a user creates a new identity with different PII. Canvas, WebGL, and audio fingerprints are GPU/OS-bound. Font detection reveals installed software. Hardware profiles expose device characteristics. WebRTC can leak the true local IP behind a VPN.

#### Behavioral Biometrics

Typing cadence and mouse dynamics are unique to individuals. The system captures keystroke timing patterns (inter-key intervals, key dwell times) and mouse movement characteristics (speed, acceleration, path straightness, click precision). Values are quantized into bins before hashing so that similar behavioral samples across sessions produce the same fingerprint hash.

### Community Reports

Incident reports submitted by liveness-verified providers. Reports include severity, category, description, and evidence notes.

**Categories:** violence, assault, stealthing, non_payment, coercion, harassment, trafficking, other

## Common Operations

### Flagging a New Individual (Admin-Initiated)

1. Create a threat profile with a codename and severity:
   ```
   POST /internal/risk-assessment/admin/profiles
   { "label": "FOXHOUND-7", "severity": "high", "source": "admin_flag" }
   ```

2. Add known identifiers to the profile:
   ```
   POST /internal/risk-assessment/admin/profiles/{id}/identifiers
   { "type": "phone", "value": "+15551234567" }
   ```
   The server normalizes and hashes the value. The plaintext is never stored.

3. The profile is immediately active — any registration attempt using a matching identifier will trigger shadow onboarding.

### Reviewing Community Reports

Providers submit reports through the marketplace safety UI. Reports appear in the admin queue:

```
GET /internal/risk-assessment/admin/reports?page=1&limit=20
```

To verify a report (confirms legitimacy, influences severity):
```
PATCH /internal/risk-assessment/admin/reports/{id}/verify
{ "adminNotes": "Verified with reporter via secure channel. Consistent with other reports." }
```

### Monitoring Shadow Sessions

Active shadow sessions show flagged individuals currently progressing through the shadow onboarding flow:

```
GET /internal/risk-assessment/admin/sessions?status=active
```

View a session's collection events (what identifiers were captured at each step):
```
GET /internal/risk-assessment/admin/sessions/{id}
```

To close a session (stops collection):
```
PATCH /internal/risk-assessment/admin/sessions/{id}/close
```

### Merging Profiles

When two profiles are discovered to represent the same individual (e.g., identifier overlap detected during shadow collection):

```
POST /internal/risk-assessment/admin/profiles/{keepId}/merge/{mergeIntoId}
```

All identifiers, reports, sessions, and notes from the merged profile are transferred to the kept profile. The merged profile is deactivated.

### Viewing a Profile Timeline

```
GET /internal/risk-assessment/admin/profiles/{id}/timeline
```

Returns chronological events: profile creation, identifier additions, shadow sessions, community reports, admin actions.

### Dashboard Statistics

```
GET /internal/risk-assessment/admin/stats
```

Returns:
- Active profiles count
- Total/active shadow sessions
- Total/verified community reports
- Identifier type distribution (how many of each type)

## Threat Scoring

The threat score for a profile is computed from its community reports:

| Severity | Weight |
|----------|--------|
| Low | 1 |
| Medium | 3 |
| High | 7 |
| Critical | 15 |

**Score = SUM of all report severity weights**

Shadow onboarding triggers when the score crosses the configurable threshold (default: 7). This means:
- 1 CRITICAL report → triggers immediately (15 >= 7)
- 1 HIGH report → triggers immediately (7 >= 7)
- 3 MEDIUM reports → triggers (9 >= 7)
- 7 LOW reports → triggers (7 >= 7)

Admin-flagged identifiers **always** trigger shadow onboarding regardless of score.

## Security Protocols

### What Admins Must Never Do

- **Never log plaintext identifiers.** When discussing a profile, reference the codename or profile ID only.
- **Never share shadow session details outside the risk assessment team.** Shadow status is the most sensitive operational detail.
- **Never reveal to a shadow user that they are in shadow onboarding.** The "under review" message is permanent and intentional.
- **Never delete threat profiles without consensus.** Deactivate instead (`isActive: false`).

### What Admins Should Do

- **Verify community reports promptly.** Unverified reports still contribute to scoring, but verification adds credibility.
- **Monitor for profile overlaps.** When shadow collection discovers an identifier already linked to a different profile, investigate for potential merge.
- **Review shadow sessions periodically.** Check collection event timelines for behavioral anomalies.
- **Document decisions in profile notes.** Use structured notes with categories (`behavioral`, `intelligence`, `legal`, `safety`).

### Identifier Privacy

- Identifiers are stored as SHA-256 hashes with a platform-wide pepper
- The pepper is stored in `vault/threat-intelligence/pepper` — access requires vault credentials
- Admins can add identifiers (the plaintext is hashed server-side and discarded)
- Admins **cannot** retrieve the original value from a hash
- The `matchCount` and `lastMatchedAt` fields on identifiers show how many times an identifier has been matched, without revealing whose registration triggered the match

## Environment Configuration

| Variable | Purpose | Default |
|----------|---------|---------|
| `THREAT_INTEL_PEPPER` | **Required.** Pepper for identifier hashing. | — |
| `THREAT_SCORE_THRESHOLD` | Score at which shadow onboarding activates | `7` |

The pepper must be identical across all instances of the service. If rotated, existing hashes become unmatchable — do not rotate without migrating all existing hashes.