@surfinguard/core-engine

Heuristic scoring engine for the Surfinguard AI Security SDK. Analyzes AI agent actions against 5 risk primitives with 68 threat patterns — zero network calls, runs entirely in-process.

Installation

npm install @surfinguard/core-engine

Note: Most users should install @surfinguard/sdk instead, which provides a higher-level Guard class.

Analyzers

| Analyzer | Threats | Patterns | |----------|---------|----------| | UrlAnalyzer | U01-U14 | Data URIs, IP addresses, brand impersonation, shorteners, risky TLDs, cloud metadata, free hosting | | CommandAnalyzer | C01-C20 | Destructive ops, exfiltration, reverse shells, pipe-to-shell, privilege escalation, persistence, fork bombs, container escape | | TextAnalyzer | P01-P12 | Prompt injection, goal hijacking, tool manipulation, persona hijacking, encoding evasion, markup injection | | FileReadAnalyzer | FR01-FR10 | SSH keys, system credentials, cloud credentials, environment files, browser data | | FileWriteAnalyzer | FW01-FW12 | System config overwrite, SSH authorized_keys injection, startup persistence, git hook injection |

Usage

import { CoreEngine } from '@surfinguard/core-engine';

const engine = new CoreEngine();

const result = engine.check('url', 'https://paypa1.com/login');
// { score: 9, level: 'DANGER', primitive: 'MANIPULATION', reasons: ['Brand impersonation: paypal'], ... }

const cmd = engine.check('command', 'rm -rf /');
// { score: 10, level: 'DANGER', primitive: 'DESTRUCTION', ... }

Scoring Model

• Within each primitive: Scores are additive (sum), capped at 10
• Composite score: max(primitive_scores)
• Risk levels: SAFE (0-2), CAUTION (3-6), DANGER (7+)

Risk Primitives

| Primitive | Description | |-----------|-------------| | DESTRUCTION | Data loss, system damage | | EXFILTRATION | Data theft, credential access | | ESCALATION | Privilege escalation | | PERSISTENCE | Backdoor installation, startup modification | | MANIPULATION | Phishing, prompt injection, deception |

Pattern Databases

Versioned JSON files in patterns/:

• urls.json — URL threat patterns
• brands.json — Brand impersonation patterns
• commands.json — Command threat patterns
• text.json — Prompt injection patterns
• file-read.json — Sensitive file read patterns
• file-write.json — Sensitive file write patterns

License

MIT