agentseal 0.5.1 → 0.6.0

package/dist/index.d.cts

@@ -405,7 +405,12 @@ declare function stripBidiControls(text: string): string;
 declare function stripHtmlComments(text: string): string;
 /** Check if text contains any invisible/obfuscation characters. */
 declare function hasInvisibleChars(text: string): boolean;
-/** Apply NFKC unicode normalization (homoglyphs → ASCII). */
+/**
+ * Apply NFKC unicode normalization then TR39 confusable mapping.
+ * NFKC handles compatibility decompositions (fullwidth, ligatures).
+ * The confusable map catches cross-script homoglyphs that NFKC misses
+ * (Cyrillic, Greek, Cherokee, etc.).
+ */
 declare function normalizeUnicode(text: string): string;
 /**
  * Find and decode inline base64 strings.
@@ -426,19 +431,16 @@ declare function unescapeSequences(text: string): string;
  */
 declare function expandStringConcat(text: string): string;
 /**
- * Apply all deobfuscation transforms to text.
+ * Decode HTML character references (numeric, hex, and named).
+ * Handles c (decimal), c (hex), and & (named) forms.
+ */
+declare function decodeHtmlEntities(text: string): string;
+/**
+ * Apply all deobfuscation transforms to text (2-pass pipeline).
  *
- * Returns cleaned text for regex pattern matching.
- * Transforms applied in order (same as Python):
- * 1. stripZeroWidth
- * 2. stripTagChars
- * 3. stripVariationSelectors
- * 4. stripBidiControls
- * 5. stripHtmlComments
- * 6. normalizeUnicode (NFKC)
- * 7. decodeBase64Blocks
- * 8. unescapeSequences
- * 9. expandStringConcat
+ * Two passes catch nested obfuscation where the first pass reveals
+ * content that a second pass can further decode (e.g. base64 hidden
+ * inside zero-width splits, or escape sequences inside HTML entities).
  */
 declare function deobfuscate(text: string): string;
 
@@ -486,6 +488,9 @@ interface MCPServerResult {
     source_file: string;
     verdict: GuardVerdict;
     findings: MCPFinding[];
+    registry_score?: number;
+    registry_level?: string;
+    registry_findings_count?: number;
 }
 /** Return the highest-severity finding from an MCPServerResult, or undefined. */
 declare function topMCPFinding(result: MCPServerResult): MCPFinding | undefined;
@@ -530,6 +535,47 @@ interface BaselineChangeResult {
     change_type: string;
     detail: string;
 }
+interface UnlistedFinding {
+    code: string;
+    title: string;
+    description: string;
+    severity: string;
+    item_name: string;
+    item_type: string;
+}
+declare function unlistedFindingToDict(f: UnlistedFinding): Record<string, any>;
+interface CustomFinding {
+    code: string;
+    title: string;
+    severity: string;
+    verdict: string;
+    remediation: string;
+    rule_file: string;
+    entity_type: string;
+    entity_name: string;
+}
+declare function customFindingFromDict(d: Record<string, any>): CustomFinding;
+declare function customFindingToDict(f: CustomFinding): Record<string, any>;
+interface DeltaEntry {
+    change_type: string;
+    entity_type: string;
+    entity_name: string;
+    code?: string;
+    title?: string;
+    old_verdict?: string;
+    new_verdict?: string;
+    severity?: string;
+}
+declare function deltaEntryToDict(e: DeltaEntry): Record<string, any>;
+declare class DeltaResult {
+    previous_timestamp: string;
+    entries: DeltaEntry[];
+    constructor(previous_timestamp: string, entries?: DeltaEntry[]);
+    get total_new(): number;
+    get total_resolved(): number;
+    get total_changed(): number;
+    toDict(): Record<string, any>;
+}
 interface GuardReport {
     timestamp: string;
     duration_seconds: number;
@@ -540,6 +586,9 @@ interface GuardReport {
     toxic_flows: ToxicFlowResult[];
     baseline_changes: BaselineChangeResult[];
     llm_tokens_used: number;
+    unlisted_findings?: UnlistedFinding[];
+    custom_findings?: CustomFinding[];
+    config_path?: string;
 }
 declare function totalDangers(report: GuardReport): number;
 declare function totalWarnings(report: GuardReport): number;
@@ -547,6 +596,8 @@ declare function totalSafe(report: GuardReport): number;
 declare function hasCritical(report: GuardReport): boolean;
 /** Collect all remediation actions, sorted by severity. */
 declare function allActions(report: GuardReport): string[];
+/** Build a GuardReport from a plain dict (e.g. parsed JSON). */
+declare function guardReportFromDict(d: Record<string, any>): GuardReport;
 
 /**
  * Skill threat detection — layered analysis for skill/rules files.
@@ -707,11 +758,81 @@ declare class MCPConfigChecker {
     private _checkHighEntropySecrets;
 }
 
+/**
+ * .agentseal.yaml project config loader, resolution, and filtering.
+ *
+ * Port of Python agentseal/project_config.py — same structure, TypeScript implementation.
+ */
+
+interface IgnoreFindingEntry {
+    id: string;
+    reason?: string;
+}
+interface ProjectConfig {
+    fail_on: string;
+    allowed_agents: string[];
+    allowed_mcp_servers: string[];
+    ignore_paths: string[];
+    ignore_findings: IgnoreFindingEntry[];
+    rules_paths: string[];
+    config_path: string;
+}
+/**
+ * Parse a .agentseal.yaml file and return a validated ProjectConfig.
+ * Throws on invalid YAML, invalid fail_on, or non-dict root.
+ */
+declare function loadProjectConfig(configPath: string): ProjectConfig;
+/**
+ * Resolve project config by explicit path or by walking up from searchDir.
+ * Returns null if no config found.
+ */
+declare function resolveProjectConfig(opts?: {
+    configPath?: string;
+    searchDir?: string;
+}): ProjectConfig | null;
+/**
+ * Check if a file path should be ignored based on config.ignore_paths.
+ * Splits path on "/" and checks if ANY segment exactly matches an ignore entry.
+ */
+declare function shouldIgnorePath(config: ProjectConfig, path: string): boolean;
+/**
+ * Check if a finding should be ignored based on config.ignore_findings.
+ * Entry id can be bare code ("SKILL-001") or code:path ("SKILL-001:./file.md").
+ */
+declare function shouldIgnoreFinding(config: ProjectConfig, code: string, path?: string): boolean;
+/**
+ * Determine if the scan should fail based on fail_on level and verdicts.
+ */
+declare function shouldFail(failOn: string, verdicts: {
+    hasDanger: boolean;
+    hasWarning: boolean;
+    hasSafe?: boolean;
+}): boolean;
+/**
+ * Generate GUARD-001 (unlisted agent) and GUARD-002 (unlisted MCP server) findings.
+ * Only checks if the respective allowlist is non-empty.
+ */
+declare function generateUnlistedFindings(config: ProjectConfig, agents: AgentConfigResult[], mcpServers: Record<string, any>[]): UnlistedFinding[];
+/**
+ * Generate a .agentseal.yaml config string from discovered agents and MCP servers.
+ */
+declare function generateConfigYaml(agents: AgentConfigResult[], mcpServers: Record<string, any>[]): string;
+/**
+ * Initialize a .agentseal.yaml config in the target directory.
+ * Returns true if written, false if file exists and not force.
+ */
+declare function runGuardInit(opts?: {
+    targetDir?: string;
+    force?: boolean;
+    interactive?: boolean;
+}): boolean;
+
 /**
  * Guard — one-command machine security scan.
  *
- * Chains machine discovery, skill scanning, blocklist, and deobfuscation
- * into a single zero-config experience.
+ * Chains machine discovery, skill scanning, blocklist, deobfuscation,
+ * project config, custom rules, registry enrichment, history/delta,
+ * and unlisted findings into a single zero-config experience.
  *
  * Port of Python agentseal/guard.py + agentseal/skill_scanner.py.
  */
@@ -728,6 +849,18 @@ interface GuardOptions {
     embedFn?: (texts: string[]) => Promise<number[][]>;
     /** Scan a specific directory instead of the whole machine. */
     scanPath?: string;
+    /** Pre-loaded project config. If not provided, resolved from scanPath. */
+    config?: ProjectConfig;
+    /** Skip registry enrichment. Default: false */
+    noRegistry?: boolean;
+    /** Skip history save and delta computation. Default: false */
+    noDiff?: boolean;
+    /** Paths to custom rule files/directories. */
+    rulesPaths?: string[];
+    /** Load a previously saved JSON report instead of scanning. */
+    fromJson?: string;
+    /** Fail threshold: "danger" (default), "warning", or "safe". */
+    failOn?: string;
 }
 /** Extract a human-readable name from a skill file path. */
 declare function extractSkillName(filePath: string): string;
@@ -736,10 +869,10 @@ declare function computeVerdict(findings: SkillFinding[]): GuardVerdict;
 /** Scan a single skill file through all detection layers. */
 declare function scanSkillFile(filePath: string, scanner: SkillScanner, blocklist: Blocklist): SkillResult;
 declare class Guard {
-    private readonly _options;
+    private readonly options;
     constructor(options?: GuardOptions);
     /** Execute full guard scan. Returns a GuardReport with all findings. */
-    run(): GuardReport;
+    run(): Promise<GuardReport>;
 }
 
 /**
@@ -952,6 +1085,177 @@ declare class Notifier {
     private _notifyFallback;
 }
 
+/**
+ * Client for agentseal.org MCP trust score enrichment API.
+ *
+ * Enriches local MCP scan results with registry intelligence
+ * (trust score, risk level, finding counts) via bulk lookup.
+ */
+
+/** Convert a name to a URL-safe slug. */
+declare function slugify(name: string): string;
+/**
+ * Extract a package name from a command string and slugify it.
+ *
+ * Recognises: npx, bunx, uvx, pip/pip3 install, docker run.
+ * Strips @version suffixes. Returns null for bare binaries or
+ * unparseable commands.
+ */
+declare function extractPackageSlug(command: string): string | null;
+/**
+ * POST a list of slugs to the bulk-check endpoint.
+ *
+ * Returns the parsed JSON on success, or {} on any error (timeout,
+ * network failure, non-ok status).
+ */
+declare function bulkCheck(slugs: string[], apiKey?: string): Promise<Record<string, any>>;
+/**
+ * Enrich MCP scan results with registry intelligence (in-place).
+ *
+ * For each result, derives a name slug and a command slug, queries the
+ * registry, then writes registry_score / registry_level /
+ * registry_findings_count onto matching results.
+ *
+ * Results that already have registry_score set are skipped to prevent
+ * double-enrichment.
+ */
+declare function enrichMcpResults(results: MCPServerResult[], apiKey?: string): Promise<void>;
+
+/**
+ * YAML community rule engine with glob matching.
+ *
+ * Port of Python agentseal/rules.py — same structure, TypeScript classes.
+ */
+
+/**
+ * Match a value against a glob pattern (case-insensitive).
+ *
+ * Supports `*` (any chars), `?` (single char), `[abc]` and `[!abc]` character classes.
+ * All regex special characters are escaped except glob operators.
+ */
+declare function fnmatchCase(value: string, pattern: string): boolean;
+interface RuleTest {
+    name: string;
+    input: Record<string, string>;
+    expect: string;
+}
+interface Rule {
+    id: string;
+    title: string;
+    description: string;
+    severity: string;
+    verdict: string;
+    remediation: string;
+    match: Record<string, string | string[]>;
+    tests: RuleTest[];
+    source_file: string;
+}
+interface RuleTestResult {
+    rule_id: string;
+    test_name: string;
+    passed: boolean;
+    expected: string;
+    actual: string;
+}
+declare class RuleEngine {
+    private rules;
+    constructor(rules: Rule[]);
+    /**
+     * Load rules from file paths and/or directory paths.
+     *
+     * - Files are loaded directly.
+     * - Directories are globbed for *.yaml and *.yml files.
+     * - Files without a top-level "rules" key are silently skipped.
+     * - Validates required fields, severity, verdict, match.type.
+     * - Throws on duplicate IDs across files.
+     */
+    static fromPaths(paths: string[]): RuleEngine;
+    /**
+     * Check if a rule matches an entity's data.
+     *
+     * - AND logic across fields (all fields must match).
+     * - OR logic within a field (any pattern in the array matches).
+     * - The "type" field in match is skipped (used for routing only).
+     */
+    private _matchEntity;
+    /**
+     * Evaluate MCP rules against a server result.
+     */
+    evaluateMcp(server: MCPServerResult | Record<string, any>, rawConfig: Record<string, any>): CustomFinding[];
+    /**
+     * Evaluate skill rules against a skill result.
+     */
+    evaluateSkill(skill: SkillResult | Record<string, any>, content: string): CustomFinding[];
+    /**
+     * Evaluate agent rules against an agent config result.
+     */
+    evaluateAgent(agent: AgentConfigResult | Record<string, any>): CustomFinding[];
+    /**
+     * Run embedded tests for all rules.
+     */
+    runTests(): RuleTestResult[];
+}
+
+/**
+ * SQLite history store with delta computation for guard scans.
+ *
+ * Uses better-sqlite3 (optional dependency) for persistence.
+ * If better-sqlite3 is not installed, all history features degrade gracefully.
+ */
+
+/**
+ * Normalize a skill/file path for use as a stable key in delta comparison.
+ *
+ * - Replaces `\` with `/` (Windows compat)
+ * - If path starts with HOME directory, replaces HOME prefix with `~/`
+ * - Else if scanPath provided and path starts with it, makes it relative
+ * - Else fallback: last 2 path segments (or last 1 if only 1)
+ */
+declare function normalizeSkillPath(skillPath: string, scanPath?: string): string;
+/**
+ * SQLite-backed store for guard scan history. Enables delta computation
+ * between consecutive scans.
+ *
+ * If better-sqlite3 is not available, all methods degrade gracefully
+ * (save is a no-op, loadPrevious returns null, etc.).
+ */
+declare class HistoryStore {
+    private db;
+    private maxRows;
+    private retentionDays;
+    constructor(dbPath?: string, maxRows?: number, retentionDays?: number);
+    /**
+     * Save a guard report to the history store.
+     */
+    save(report: GuardReport, scanPath?: string): void;
+    /**
+     * Load the previous report (second-most-recent) for a given scan path.
+     * Returns null if fewer than 2 entries exist or on any error.
+     */
+    loadPrevious(scanPath?: string): GuardReport | null;
+    /**
+     * Remove stale entries: older than retentionDays, or exceeding maxRows.
+     */
+    prune(): void;
+    /**
+     * Return the total number of rows in the store. For test assertions.
+     */
+    _count(): number;
+    /**
+     * Close the database connection.
+     */
+    close(): void;
+}
+/**
+ * Compute a delta between the current and previous guard reports.
+ *
+ * Tracks:
+ * - Skills: new/resolved findings, changed verdicts, new/removed entities
+ * - MCP servers: new/resolved findings, changed verdicts, new/removed entities
+ * - Agents: new/removed entities (no findings on agents)
+ */
+declare function computeDelta(current: GuardReport, previous: GuardReport, scanPath?: string): DeltaResult;
+
 /**
  * Shield — continuous filesystem monitoring for AI agent security.
  *
@@ -1033,4 +1337,4 @@ declare class Shield {
     stop(): void;
 }
 
-export { type AffectedProbe, type AgentConfigResult, AgentSealError, AgentValidator, type AttackChain, BACKUPS_DIR, BOUNDARY_CATEGORIES, BOUNDARY_WEIGHT, type BaselineChange, type BaselineChangeResult, type BaselineEntry, BaselineStore, Blocklist, COMMON_WORDS, CONSISTENCY_WEIGHT, type ChainStep, type ChatFn, type CompareResult, DANGER_CONCEPTS, DATA_EXTRACTION_WEIGHT, DebouncedHandler, type DefenseProfile, type DiscoveryResult, EXTRACTION_WEIGHT, type EmbedFn, type FixResult, Guard, type GuardOptions, type GuardProgressFn, type GuardReport, GuardVerdict, INJECTION_WEIGHT, KNOWN_SERVER_LABELS, LABEL_DESTRUCTIVE, LABEL_PRIVATE, LABEL_PUBLIC_SINK, LABEL_UNTRUSTED, LLMJudge, type LLMJudgeFinding, type LLMJudgeOptions, type LLMJudgeResult, MAX_CONTENT_BYTES, MCPConfigChecker, type MCPFinding, type MCPRuntimeFinding, type MCPRuntimeResult, type MCPServerResult, Notifier, PROFILES, PROJECT_MCP_CONFIGS, PROJECT_SKILL_DIRS, PROJECT_SKILL_FILES, type Probe, type ProbeResult, ProbeTimeoutError, type ProfileConfig, type ProgressFn, ProviderError, QUARANTINE_DIR, type QuarantineEntry, REFUSAL_PHRASES, REPORTS_DIR, type RemediationItem, type RemediationReport, SEMANTIC_HIGH_THRESHOLD, SEMANTIC_MODERATE_THRESHOLD, SEVERITY_ORDER, SYSTEM_PROMPT, type ScanReport, type ScoreBreakdown, Severity, Shield, type ShieldCallback, type ShieldOptions, type SkillFinding, type SkillResult, SkillScanner, TRANSFORMS, type ToxicFlowResult, TrustLevel, ValidationError, type ValidatorOptions, Verdict, allActions, analyzeToxicFlows, applyProfile, base64Wrap, buildExtractionProbes, buildInjectionProbes, buildProbe, caseScramble, classifyPath, classifyServer, collectWatchPaths, compareReports, computeScores, computeSemanticSimilarity, computeVerdict, decodeBase64Blocks, deobfuscate, detectCanary, detectChains, detectExtraction, detectExtractionWithSemantic, detectProvider, expandStringConcat, extractSkillName, extractUniquePhrases, fingerprintDefense, fromAnthropic, fromEndpoint, fromLangChain, fromOllama, fromOpenAI, fromVercelAI, fuseVerdicts, generateCanary, generateMutations, generateRemediation, getFixableSkills, getWellKnownConfigs, hasCritical, hasInvisibleChars, isRefusal, leetspeak, listProfiles, listQuarantine, loadAllCustomProbes, loadCustomProbes, loadGuardReport, loadScanReport, normalizeUnicode, parseProbeFile, parseResponse, prefixPadding, quarantineSkill, resolveProfile, restoreSkill, reverseEmbed, rot13Wrap, saveReport, scanDirectory, scanMachine, scanSkillFile, sha256, shannonEntropy, stripBidiControls, stripHtmlComments, stripJsonComments, stripModelPrefix, stripTagChars, stripVariationSelectors, stripZeroWidth, topMCPFinding, topSkillFinding, totalDangers, totalSafe, totalWarnings, truncateContent, trustLevelFromScore, unescapeSequences, unicodeHomoglyphs, validateProbe, verdictFromFindings, verdictScore, zeroWidthInject };
+export { type AffectedProbe, type AgentConfigResult, AgentSealError, AgentValidator, type AttackChain, BACKUPS_DIR, BOUNDARY_CATEGORIES, BOUNDARY_WEIGHT, type BaselineChange, type BaselineChangeResult, type BaselineEntry, BaselineStore, Blocklist, COMMON_WORDS, CONSISTENCY_WEIGHT, type ChainStep, type ChatFn, type CompareResult, type CustomFinding, DANGER_CONCEPTS, DATA_EXTRACTION_WEIGHT, DebouncedHandler, type DefenseProfile, type DeltaEntry, DeltaResult, type DiscoveryResult, EXTRACTION_WEIGHT, type EmbedFn, type FixResult, Guard, type GuardOptions, type GuardProgressFn, type GuardReport, GuardVerdict, HistoryStore, INJECTION_WEIGHT, type IgnoreFindingEntry, KNOWN_SERVER_LABELS, LABEL_DESTRUCTIVE, LABEL_PRIVATE, LABEL_PUBLIC_SINK, LABEL_UNTRUSTED, LLMJudge, type LLMJudgeFinding, type LLMJudgeOptions, type LLMJudgeResult, MAX_CONTENT_BYTES, MCPConfigChecker, type MCPFinding, type MCPRuntimeFinding, type MCPRuntimeResult, type MCPServerResult, Notifier, PROFILES, PROJECT_MCP_CONFIGS, PROJECT_SKILL_DIRS, PROJECT_SKILL_FILES, type Probe, type ProbeResult, ProbeTimeoutError, type ProfileConfig, type ProgressFn, type ProjectConfig, ProviderError, QUARANTINE_DIR, type QuarantineEntry, REFUSAL_PHRASES, REPORTS_DIR, type RemediationItem, type RemediationReport, type Rule, RuleEngine, type RuleTest, type RuleTestResult, SEMANTIC_HIGH_THRESHOLD, SEMANTIC_MODERATE_THRESHOLD, SEVERITY_ORDER, SYSTEM_PROMPT, type ScanReport, type ScoreBreakdown, Severity, Shield, type ShieldCallback, type ShieldOptions, type SkillFinding, type SkillResult, SkillScanner, TRANSFORMS, type ToxicFlowResult, TrustLevel, type UnlistedFinding, ValidationError, type ValidatorOptions, Verdict, allActions, analyzeToxicFlows, applyProfile, base64Wrap, buildExtractionProbes, buildInjectionProbes, buildProbe, bulkCheck, caseScramble, classifyPath, classifyServer, collectWatchPaths, compareReports, computeDelta, computeScores, computeSemanticSimilarity, computeVerdict, customFindingFromDict, customFindingToDict, decodeBase64Blocks, decodeHtmlEntities, deltaEntryToDict, deobfuscate, detectCanary, detectChains, detectExtraction, detectExtractionWithSemantic, detectProvider, enrichMcpResults, expandStringConcat, extractPackageSlug, extractSkillName, extractUniquePhrases, fingerprintDefense, fnmatchCase, fromAnthropic, fromEndpoint, fromLangChain, fromOllama, fromOpenAI, fromVercelAI, fuseVerdicts, generateCanary, generateConfigYaml, generateMutations, generateRemediation, generateUnlistedFindings, getFixableSkills, getWellKnownConfigs, guardReportFromDict, hasCritical, hasInvisibleChars, isRefusal, leetspeak, listProfiles, listQuarantine, loadAllCustomProbes, loadCustomProbes, loadGuardReport, loadProjectConfig, loadScanReport, normalizeSkillPath, normalizeUnicode, parseProbeFile, parseResponse, prefixPadding, quarantineSkill, resolveProfile, resolveProjectConfig, restoreSkill, reverseEmbed, rot13Wrap, runGuardInit, saveReport, scanDirectory, scanMachine, scanSkillFile, sha256, shannonEntropy, shouldFail, shouldIgnoreFinding, shouldIgnorePath, slugify, stripBidiControls, stripHtmlComments, stripJsonComments, stripModelPrefix, stripTagChars, stripVariationSelectors, stripZeroWidth, topMCPFinding, topSkillFinding, totalDangers, totalSafe, totalWarnings, truncateContent, trustLevelFromScore, unescapeSequences, unicodeHomoglyphs, unlistedFindingToDict, validateProbe, verdictFromFindings, verdictScore, zeroWidthInject };