shield360 1.1.0 → 1.2.1

package/dist/rasp/rule-expr.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Custom RASP rule expressions (sdk/rasp/README.md "Custom rules").
+ *
+ * A small, sandboxed, CEL-style expression language: a fixed set of fields,
+ * string literals, comparison, `in`, a handful of string methods, a safe
+ * regular-expression subset matched in linear time, and CIDR matching,
+ * joined by `&&`, `||` and `!`. No loops, no function definitions, no I/O,
+ * nothing outside the fields. Expressions are parsed and type-checked once
+ * and evaluated as data; nothing downloaded is ever run as code.
+ *
+ * This file is shared: `sdk/typescript/src/rasp/rule-expr.ts` and
+ * `src/client/src/lib/security/rasp/rule-expr.ts` are byte-identical (a test
+ * in each tree says so), so the platform accepts exactly what the SDK runs.
+ * It imports nothing.
+ */
+/** Hard limits, identical on the platform and in every SDK. */
+export declare const RULE_EXPR_LIMITS: Readonly<{
+    /** UTF-8 bytes of the whole expression. */
+    expressionBytes: 2048;
+    /** AST depth (a leaf is 1), and parenthesis nesting. */
+    depth: 12;
+    /** AST nodes. */
+    nodes: 128;
+    /** UTF-8 bytes of one string literal, after escapes. */
+    stringBytes: 1024;
+    /** Items in one `in [...]` list. */
+    listItems: 64;
+    /** `matches` calls in one expression. */
+    regexes: 8;
+    /** UTF-8 bytes of one pattern. */
+    regexBytes: 256;
+    /** Atoms of one pattern once counted repetitions are expanded. */
+    regexAtoms: 256;
+    /** The largest bound in `{n}`, `{n,}`, `{n,m}`. */
+    regexRepeat: 100;
+    /** `matches` reads at most this many code points of its subject. */
+    matchCodePoints: 4096;
+}>;
+export type RuleExprErrorCode = "empty" | "too_long" | "syntax" | "depth" | "nodes" | "string_too_long" | "list_too_long" | "unknown_field" | "unknown_method" | "type" | "regex" | "too_many_regexes" | "cidr"
+/** A context this parser does not know (README "Collector contexts"). */
+ | "context";
+export type RuleExprError = {
+    code: RuleExprErrorCode;
+    pos: number;
+};
+export type RuleFieldType = "string" | "map";
+/** The fields an expression may read (README "Custom rules: fields"). */
+export declare const RULE_FIELDS: Readonly<Record<string, RuleFieldType>>;
+/**
+ * Where an expression runs, which decides the fields it may read (README
+ * "Collector contexts"): an app's RASP (`app`, the fields above), a coding
+ * agent's tool call (`agent_tool`) or a request through the AI proxy
+ * (`ai_proxy`). The grammar, types and limits are the same everywhere.
+ */
+export type RuleContext = "app" | "agent_tool" | "ai_proxy";
+/** The fields of each collector context. None is a map. */
+export declare const COLLECTOR_RULE_FIELDS: Readonly<Record<Exclude<RuleContext, "app">, Readonly<Record<string, RuleFieldType>>>>;
+/** The fields an expression may read in a context, or null for one this parser does not know. */
+export declare function ruleContextFields(context: RuleContext): Readonly<Record<string, RuleFieldType>> | null;
+/** One untrusted input of the request (the SDK's input list). */
+export type RuleInput = {
+    value: string;
+    key: string;
+    source: string;
+};
+/** What an expression is evaluated against. Missing parts read as null. */
+export type RuleSubject = {
+    app?: string | null;
+    request?: {
+        method?: string | null;
+        path?: string | null;
+        route?: string | null;
+        ip?: string | null;
+        /** Lower-case header names. */
+        headers?: Record<string, string>;
+        /** Query parameter name -> first value. */
+        query?: Record<string, string>;
+        /** Flattened body path (`user.name`) -> string leaf. */
+        body?: Record<string, string>;
+    } | null;
+    inputs?: RuleInput[];
+    sink?: string | null;
+    attack?: {
+        type?: string | null;
+        rule?: string | null;
+    } | null;
+    /** The collector contexts' fields (README "Collector contexts"). */
+    collector?: {
+        tool?: {
+            name?: string | null;
+            command?: string | null;
+            path?: string | null;
+        } | null;
+        agent?: {
+            name?: string | null;
+        } | null;
+        ai?: {
+            provider?: string | null;
+            model?: string | null;
+            tokens?: string | null;
+        } | null;
+        user?: {
+            id?: string | null;
+        } | null;
+        device?: {
+            os?: string | null;
+        } | null;
+    } | null;
+};
+type CmpOp = "==" | "!=" | "<" | "<=" | ">" | ">=";
+type StrMethod = "startsWith" | "endsWith" | "contains";
+/** Regular-expression program (Pike VM). */
+type Inst = {
+    op: "char";
+    c: number;
+} | {
+    op: "any";
+} | {
+    op: "class";
+    r: number[];
+    neg: boolean;
+} | {
+    op: "split";
+    x: number;
+    y: number;
+} | {
+    op: "jmp";
+    x: number;
+} | {
+    op: "bol";
+} | {
+    op: "eol";
+} | {
+    op: "match";
+};
+type Net = {
+    bytes: number[];
+    prefix: number;
+};
+export type RuleNode = {
+    k: "str";
+    v: string;
+} | {
+    k: "bool";
+    v: boolean;
+} | {
+    k: "null";
+} | {
+    k: "field";
+    name: string;
+    key?: string;
+} | {
+    k: "not";
+    x: RuleNode;
+} | {
+    k: "and" | "or";
+    xs: RuleNode[];
+} | {
+    k: "cmp";
+    op: CmpOp;
+    l: RuleNode;
+    r: RuleNode;
+} | {
+    k: "in";
+    l: RuleNode;
+    items: string[];
+} | {
+    k: "str_method";
+    m: StrMethod;
+    t: RuleNode;
+    arg: string;
+} | {
+    k: "lower";
+    t: RuleNode;
+} | {
+    k: "matches";
+    t: RuleNode;
+    prog: Inst[];
+} | {
+    k: "cidr";
+    t: RuleNode;
+    net: Net;
+};
+export type CompiledRuleExpr = {
+    ast: RuleNode;
+    /** Field names read (without map keys). */
+    fields: string[];
+    /** `finding` when the expression reads `sink.*` or `attack.*`, else `request`. */
+    phase: "request" | "finding";
+    /** Reads `input.*`: evaluated once per input, true when any input makes it true. */
+    usesInput: boolean;
+    /** Reads `request.body[...]`. */
+    usesBody: boolean;
+    /** The context it was compiled for. */
+    context: RuleContext;
+};
+export type RuleExprResult = {
+    ok: true;
+    expr: CompiledRuleExpr;
+} | {
+    ok: false;
+    error: RuleExprError;
+};
+/** UTF-8 length of a JS string (a lone surrogate counts 3, as its U+FFFD replacement). */
+export declare function utf8Length(s: string): number;
+/**
+ * Parses and type-checks an expression. Every limit is checked here; an
+ * expression that compiles is safe to evaluate on any input.
+ */
+export declare function compileRuleExpr(src: unknown, context?: RuleContext): RuleExprResult;
+/** Work left for one evaluation (regex steps); exhausting it ends the evaluation as no match. */
+export type RuleBudget = {
+    steps: number;
+};
+export declare const DEFAULT_RULE_BUDGET = 4000000;
+export type RuleEvalResult = {
+    matched: boolean;
+    input?: RuleInput;
+    exhausted?: boolean;
+};
+/**
+ * Evaluates a compiled expression. An expression that reads `input.*` is
+ * evaluated once per input, in order, and matches when any input makes it
+ * true (with no inputs, once with the input fields null). Never throws: an
+ * evaluation that runs out of budget, or fails in any way, is no match.
+ */
+export declare function evaluateRuleExpr(expr: CompiledRuleExpr, subject: RuleSubject, budget?: RuleBudget): RuleEvalResult;
+/** Checks a pattern against the safe subset and compiles it; null when refused. */
+export declare function compileRegex(pattern: string): Inst[] | null;
+/** Whether a pattern is in the safe subset. */
+export declare function isSafeRegex(pattern: string): boolean;
+/** An IPv4 or IPv6 address as 16 bytes (IPv4 as `::ffff:a.b.c.d`); null when not an address. */
+export declare function parseIpBytes(s: string): number[] | null;
+/** `a.b.c.d/n`, `x:y::z/n`, or a bare address (all bits). Null when malformed. */
+export declare function parseCidr(s: string): Net | null;
+export {};