mizcausevic-dev/shadow-ai-detector

Shadow AI Detector is a deterministic TypeScript/Express API for identifying enterprise traffic to known LLM endpoints, scanning request payload snippets for sensitive material, scoring event and fleet risk, and reporting department exposure and incidents. The documented main workflow is initiated by an enterprise proxy/firewall traffic source sending captured events to the API; the sampled implementation analyzes events supplied by API callers and also exposes reports calculated from a built-in demo dataset. Live proxy ingestion and automated enforcement are not established.

Components

HTTP application

• API server — src/index.ts: Creates the Express app, installs middleware, serves health status, and mounts endpoint, analysis, incident, and dashboard routers. It listens on the configured port when run as the main module.

• API request handlers — src/routes/index.ts: Implements the documented REST routes, validates analysis requests, calls governance functions, and returns catalog, assessment, incident, and dashboard responses.

• Request schemas — src/schemas/validation-schemas.ts: Defines Zod validation for endpoint classification, payload scans, and single or bulk traffic assessments.

Detection and exposure analysis

• Endpoint classifier — src/governance/endpoint-classifier.ts: Matches URL hosts and paths against a catalog of LLM endpoints and returns provider, capability, risk, and country metadata; also supports listing endpoints and determining sanction status.

• Payload scanner — src/governance/payload-scanner.ts: Applies regex patterns for credentials, PII, payment data, health data, internal markers, and source-code secrets; returns severity and redacted match snippets.

• Event and fleet risk scorer — src/governance/risk-scorer.ts: Combines endpoint classification, sanction status, payload hits, and upload volume into per-event risk verdicts, then aggregates fleet summaries and top-risk users.

• Department exposure rollup — src/governance/department-rollup.ts: Aggregates aligned events and assessments by department into usage, tier, provider, sanction-rate, exposure-score, and recommended-action metrics.

Catalog and report data

• Endpoint and sanction catalog — src/data/endpoints.ts: Holds the demo organization’s sanctioned endpoint IDs and provider metadata used in catalog and dashboard responses.

• Demo traffic dataset — src/data/traffic.ts: Supplies representative proxy-style events used by dashboard summaries and exposure reports; this is sample data, not evidence of a connected traffic feed.

• Incident register — src/data/incidents.ts: Defines the in-memory incident records and their status, severity, ownership, and recommended actions; sampled routes read and filter these records.

Relationships

• Enterprise proxy/firewall traffic source (external; repository path: null) -> API server: documented as the traffic origin; live source integration is not shown.

• API server -> API request handlers: mounts routers for endpoint, analysis, incident, and dashboard routes.

• API request handlers -> Request schemas: validates request bodies with safeParse before analysis calls.

• API request handlers -> Endpoint classifier: classifies submitted URLs and lists catalog entries.

• API request handlers -> Payload scanner: scans submitted payloads directly on the payload-analysis route.

• API request handlers -> Event and fleet risk scorer: assesses a single submitted event or a submitted event batch; dashboard handlers also score demo events.

• Event and fleet risk scorer -> Endpoint classifier: classifies each event URL and resolves sanction status.

• Event and fleet risk scorer -> Payload scanner: scans each event’s payload snippet and incorporates findings into its verdict.

• API request handlers -> Department exposure rollup: passes submitted events and fleet assessments for bulk analysis; dashboard handlers pass demo events and assessments.

• API request handlers -> Endpoint and sanction catalog: reads sanctioned IDs and provider metadata for catalog and dashboard responses.

• API request handlers -> Demo traffic dataset: reads events for dashboard summary and exposure calculations.

• API request handlers -> Incident register: reads and filters incidents for incident and dashboard routes.

• Enterprise API consumer (external; repository path: null) -> API server: calls the documented HTTP endpoints; this is the implemented interface for supplying events and retrieving results.

• API server -> Enterprise API consumer: returns JSON responses, including event verdicts, fleet summaries, department exposure, catalog, and incident data.

Coverage limits

The source excerpts establish route wiring and core analysis flow, but do not show the full endpoint catalog or all classifier logic. The README documents a 30+ endpoint catalog and additional reporting behavior; sampled data is in-memory, and no persistence, live proxy/firewall connector, or egress-blocking integration is shown. The dashboard preview file is present, but its behavior is not established by the sampled source.