@surfinguard/core-engine 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @surfinguard/core-engine
+
+Heuristic scoring engine for the [Surfinguard](https://surfinguard.com) AI Security SDK. Analyzes AI agent actions against 5 risk primitives with 68 threat patterns — zero network calls, runs entirely in-process.
+
+## Installation
+
+```bash
+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
+
+```typescript
+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

package/dist/analyzers/base.d.ts

@@ -0,0 +1,38 @@
+import type { ActionType, RiskPrimitive } from '@surfinguard/types';
+/**
+ * A single finding from an analyzer check.
+ */
+export interface AnalyzerFinding {
+    /** Which risk primitive this finding maps to */
+    primitive: RiskPrimitive;
+    /** Score contribution (positive integer) */
+    score: number;
+    /** Human-readable reason */
+    reason: string;
+    /** Threat ID (e.g., "U01") if applicable */
+    threatId?: string;
+}
+/**
+ * Complete result from an analyzer.
+ */
+export interface AnalyzerResult {
+    /** The action type this result is for */
+    actionType: ActionType;
+    /** All findings from the analysis */
+    findings: AnalyzerFinding[];
+    /** Whether the analysis short-circuited (e.g., known safe) */
+    shortCircuit?: {
+        safe: boolean;
+        reason: string;
+    };
+}
+/**
+ * Base interface for all action analyzers.
+ */
+export interface Analyzer {
+    /** The action type this analyzer handles */
+    readonly actionType: ActionType;
+    /** Analyze a value and return findings */
+    analyze(value: string): AnalyzerResult;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/analyzers/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/analyzers/base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,SAAS,EAAE,aAAa,CAAC;IACzB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,UAAU,EAAE,UAAU,CAAC;IACvB,qCAAqC;IACrC,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,8DAA8D;IAC9D,YAAY,CAAC,EAAE;QACb,IAAI,EAAE,OAAO,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,0CAA0C;IAC1C,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC;CACxC"}

package/dist/analyzers/base.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=base.js.map

package/dist/analyzers/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/analyzers/base.ts"],"names":[],"mappings":""}

package/dist/analyzers/command.d.ts

@@ -0,0 +1,44 @@
+import type { CommandPatternDatabase } from '@surfinguard/types';
+import type { Analyzer, AnalyzerResult } from './base.js';
+/**
+ * Command Analyzer — heuristic shell command threat detection.
+ *
+ * Analyzes shell commands against 20 threat patterns (C01-C20)
+ * mapped to 5 risk primitives.
+ */
+export declare class CommandAnalyzer implements Analyzer {
+    readonly actionType: "command";
+    private readonly db;
+    private readonly safeCommandsSet;
+    private readonly destructiveCommandsSet;
+    private readonly exfiltrationCommandsSet;
+    private readonly networkCommandsSet;
+    private readonly packageManagersSet;
+    private readonly encodingCommandsSet;
+    constructor(patterns: CommandPatternDatabase);
+    analyze(value: string): AnalyzerResult;
+    /**
+     * Split a command string into pipeline segments.
+     * Splits on |, &&, ||, ; respecting quotes.
+     */
+    private tokenize;
+    /**
+     * Split on |, &&, ||, ; while respecting quotes and subshells.
+     */
+    private splitPipeline;
+    /**
+     * Tokenize a single command segment into command + args.
+     * Handles single/double quotes.
+     */
+    private tokenizeSegment;
+    private isForkBomb;
+    private isEncodedCommand;
+    private hasVariableExpansionRisk;
+    private targetsCriticalPath;
+    /**
+     * Check if a command segment has arguments that elevate risk
+     * beyond what the safe command alone would imply.
+     */
+    private hasRiskyArgs;
+}
+//# sourceMappingURL=command.d.ts.map

package/dist/analyzers/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../src/analyzers/command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAmB,cAAc,EAAE,MAAM,WAAW,CAAC;AAc3E;;;;;GAKG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,QAAQ,CAAC,UAAU,EAAG,SAAS,CAAU;IAEzC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAyB;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAc;IAC9C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAc;IACrD,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAc;IACtD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAc;IACjD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAc;IACjD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAc;gBAEtC,QAAQ,EAAE,sBAAsB;IAU5C,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc;IAsUtC;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAqBhB;;OAEG;IACH,OAAO,CAAC,aAAa;IA0ErB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAuCvB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,wBAAwB;IAOhC,OAAO,CAAC,mBAAmB;IAe3B;;;OAGG;IACH,OAAO,CAAC,YAAY;CA6BrB"}