platform-codebase/features/threat-intelligence/docs/admin-guide.md

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.