@aspect-guard/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aspect Guard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,395 @@
+type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+type RiskLevel = 'critical' | 'high' | 'medium' | 'low' | 'safe';
+declare const SEVERITY_ORDER: Record<Severity, number>;
+declare function compareSeverity(a: Severity, b: Severity): number;
+declare function isAtLeastSeverity(severity: Severity, minimum: Severity): boolean;
+
+interface ExtensionInfo {
+    id: string;
+    displayName: string;
+    version: string;
+    publisher: {
+        name: string;
+        verified: boolean;
+    };
+    description: string;
+    categories: string[];
+    activationEvents: string[];
+    extensionDependencies: string[];
+    installPath: string;
+    engines: {
+        vscode: string;
+    };
+    repository?: string;
+    license?: string;
+    fileCount: number;
+    totalSize: number;
+}
+interface ExtensionManifest {
+    name: string;
+    publisher: string;
+    version: string;
+    displayName?: string;
+    description?: string;
+    categories?: string[];
+    activationEvents?: string[];
+    contributes?: Record<string, unknown>;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    extensionDependencies?: string[];
+    main?: string;
+    browser?: string;
+    engines?: {
+        vscode?: string;
+    };
+    repository?: string | {
+        url: string;
+    };
+    license?: string;
+    [key: string]: unknown;
+}
+
+type FindingCategory = 'data-exfiltration' | 'remote-code-execution' | 'credential-theft' | 'keylogger' | 'code-obfuscation' | 'suspicious-network' | 'excessive-permission' | 'known-malicious' | 'hardcoded-secret' | 'vulnerable-dependency' | 'persistence' | 'supply-chain' | 'crypto-mining';
+interface Evidence {
+    filePath: string;
+    lineNumber?: number;
+    columnNumber?: number;
+    lineContent?: string;
+    contextBefore?: string[];
+    contextAfter?: string[];
+    matchedPattern?: string;
+    snippet?: string;
+}
+interface Finding {
+    id: string;
+    ruleId: string;
+    severity: Severity;
+    category: FindingCategory;
+    title: string;
+    description: string;
+    evidence: Evidence;
+    mitreAttackId?: string;
+    remediation?: string;
+}
+
+interface ScanResult {
+    extensionId: string;
+    displayName: string;
+    version: string;
+    trustScore: number;
+    riskLevel: RiskLevel;
+    findings: Finding[];
+    metadata: ExtensionInfo;
+    analyzedFiles: number;
+    scanDurationMs: number;
+}
+interface ScanSummary {
+    byRiskLevel: Record<RiskLevel, number>;
+    bySeverity: Record<Severity, number>;
+    byCategory: Partial<Record<FindingCategory, number>>;
+    topFindings: Finding[];
+    overallHealthScore: number;
+}
+interface DetectedIDE {
+    name: string;
+    path: string;
+    extensionCount: number;
+}
+interface FullScanReport {
+    scanId: string;
+    version: string;
+    timestamp: string;
+    environment: {
+        os: string;
+        ides: DetectedIDE[];
+    };
+    totalExtensions: number;
+    uniqueExtensions: number;
+    results: ScanResult[];
+    summary: ScanSummary;
+    scanDurationMs: number;
+}
+interface PolicyViolation {
+    extensionId: string;
+    rule: string;
+    message: string;
+    action: 'block' | 'warn' | 'info';
+}
+interface AuditReport extends FullScanReport {
+    policyPath: string;
+    policyViolations: PolicyViolation[];
+    auditPassed: boolean;
+}
+
+interface ScanOptions {
+    idePaths?: string[];
+    autoDetect?: boolean;
+    severity?: Severity;
+    rules?: string[];
+    skipRules?: string[];
+    concurrency?: number;
+    timeout?: number;
+}
+interface InspectOptions {
+    vsixPath: string;
+    severity?: Severity;
+    rules?: string[];
+}
+
+declare class ExtensionGuardScanner {
+    private options;
+    private ruleEngine;
+    constructor(options?: Partial<ScanOptions>);
+    scan(options?: Partial<ScanOptions>): Promise<FullScanReport>;
+    private scanExtension;
+    private calculateTrustScore;
+    private calculateRiskLevel;
+    private calculateSummary;
+}
+
+declare const IDE_PATHS: Record<string, string[]>;
+declare function expandPath(inputPath: string): string;
+declare function detectIDEPaths(): DetectedIDE[];
+
+declare function readExtension(extensionPath: string): Promise<ExtensionInfo | null>;
+declare function readExtensionsFromDirectory(directoryPath: string): Promise<ExtensionInfo[]>;
+
+declare function shouldCollectFile(filePath: string): boolean;
+declare function collectFiles(extensionPath: string): Promise<Map<string, string>>;
+
+interface DetectionRule {
+    id: string;
+    name: string;
+    description: string;
+    severity: Severity;
+    category: FindingCategory;
+    mitreAttackId?: string;
+    enabled: boolean;
+    detect(files: Map<string, string>, manifest: ExtensionManifest): Evidence[];
+}
+
+interface RuleEngineOptions {
+    rules?: string[];
+    skipRules?: string[];
+    minSeverity?: Severity;
+}
+declare class RuleEngine {
+    private options;
+    constructor(options?: RuleEngineOptions);
+    run(files: Map<string, string>, manifest: ExtensionManifest): Finding[];
+    private getApplicableRules;
+    private createFinding;
+}
+
+declare class RuleRegistry {
+    private rules;
+    register(rule: DetectionRule): void;
+    get(id: string): DetectionRule | undefined;
+    getAll(): DetectionRule[];
+    getEnabled(): DetectionRule[];
+    getByCategory(category: string): DetectionRule[];
+    getBySeverity(severity: string): DetectionRule[];
+    clear(): void;
+}
+declare const ruleRegistry: RuleRegistry;
+
+declare function registerBuiltInRules(): void;
+
+interface ReporterOptions {
+    includeEvidence?: boolean;
+    includeSafe?: boolean;
+    minSeverity?: Severity;
+}
+interface Reporter {
+    readonly format: string;
+    generate(report: FullScanReport, options?: ReporterOptions): string;
+}
+
+declare class JsonReporter implements Reporter {
+    readonly format = "json";
+    generate(report: FullScanReport, options?: ReporterOptions): string;
+    private filterResults;
+}
+
+declare class SarifReporter implements Reporter {
+    readonly format = "sarif";
+    generate(report: FullScanReport, _options?: ReporterOptions): string;
+    private extractRules;
+    private extractResults;
+}
+
+declare class MarkdownReporter implements Reporter {
+    readonly format = "markdown";
+    generate(report: FullScanReport, options?: ReporterOptions): string;
+    private formatExtensionResult;
+    private formatFinding;
+}
+
+/**
+ * Policy Engine Types
+ *
+ * Defines the structure for Extension Guard policy configurations.
+ * Policies allow organizations to enforce security standards for VSCode extensions.
+ */
+
+/**
+ * Root policy configuration structure.
+ * Supports both scanning configuration and policy enforcement rules.
+ */
+interface PolicyConfig {
+    /** Schema version for the policy file (e.g., "1") */
+    version: string;
+    /** Scanning behavior configuration */
+    scanning?: {
+        /** Minimum severity level to report (findings below this are ignored) */
+        minSeverity?: Severity;
+        /** Rule IDs to skip during scanning */
+        skipRules?: string[];
+        /** Scan timeout in milliseconds */
+        timeout?: number;
+    };
+    /** Policy enforcement configuration */
+    policy?: {
+        /** Extension IDs that are always allowed (bypass policy checks) */
+        allowlist?: string[];
+        /** Extension IDs that are always blocked */
+        blocklist?: string[];
+        /** Configurable policy rules */
+        rules?: PolicyRules;
+    };
+}
+/**
+ * Configurable policy rules for extension evaluation.
+ * Each rule can specify its own action when violated.
+ */
+interface PolicyRules {
+    /** Minimum trust score requirement */
+    minTrustScore?: {
+        /** Score threshold (0-100) */
+        threshold: number;
+        /** Action to take when score is below threshold */
+        action: PolicyAction;
+    };
+    /** Require extensions to have a verified publisher */
+    requireVerifiedPublisher?: {
+        /** Whether this rule is enabled */
+        enabled: boolean;
+        /** Action to take when publisher is not verified */
+        action: PolicyAction;
+        /** Extension IDs exempt from this rule */
+        exceptions?: string[];
+    };
+    /** Maximum days since last extension update */
+    maxDaysSinceUpdate?: {
+        /** Maximum allowed days since last update */
+        days: number;
+        /** Action to take when extension is too old */
+        action: PolicyAction;
+    };
+    /** Block extensions with obfuscated code */
+    blockObfuscated?: {
+        /** Whether this rule is enabled */
+        enabled: boolean;
+        /** Action to take when obfuscated code is detected */
+        action: PolicyAction;
+    };
+}
+/**
+ * Action to take when a policy rule is violated.
+ * - 'block': Prevent extension usage (fail the check)
+ * - 'warn': Allow but generate a warning
+ * - 'info': Log for informational purposes only
+ */
+type PolicyAction = 'block' | 'warn' | 'info';
+
+/**
+ * Policy Loader
+ *
+ * Loads and validates Extension Guard policy configuration files.
+ */
+
+/**
+ * Load and validate a policy configuration file.
+ *
+ * @param configPath - Optional path to the config file. If not provided,
+ *                     searches for .extension-guard.json in the current directory.
+ * @returns The parsed PolicyConfig or null if not found.
+ * @throws Error if the file exists but is invalid JSON or fails validation.
+ */
+declare function loadPolicyConfig(configPath?: string): Promise<PolicyConfig | null>;
+
+/**
+ * Policy Engine
+ *
+ * Evaluates extension scan results against policy rules to determine compliance.
+ */
+
+/**
+ * PolicyEngine evaluates scan results against configured policy rules.
+ *
+ * @example
+ * ```typescript
+ * const config = await loadPolicyConfig();
+ * const engine = new PolicyEngine(config);
+ * const violations = engine.evaluate(scanResults);
+ *
+ * if (engine.hasBlockingViolations()) {
+ *   console.error('Policy check failed');
+ *   process.exit(1);
+ * }
+ * ```
+ */
+declare class PolicyEngine {
+    private config;
+    private violations;
+    /**
+     * Create a new PolicyEngine instance.
+     *
+     * @param config - The policy configuration to evaluate against
+     */
+    constructor(config: PolicyConfig);
+    /**
+     * Evaluate scan results against the configured policy.
+     *
+     * Checks are applied in this order for each extension:
+     * 1. Blocklist - if matched, block immediately and skip other checks
+     * 2. Allowlist - if matched, skip all other checks
+     * 3. Individual rules (minTrustScore, blockObfuscated, etc.)
+     *
+     * @param results - Array of scan results to evaluate
+     * @returns Array of policy violations found
+     */
+    evaluate(results: ScanResult[]): PolicyViolation[];
+    /**
+     * Check if there are any violations with 'block' action.
+     *
+     * @returns true if any blocking violations exist
+     */
+    hasBlockingViolations(): boolean;
+    /**
+     * Get all violations from the last evaluation.
+     *
+     * @returns Array of all policy violations
+     */
+    getViolations(): PolicyViolation[];
+    /**
+     * Check minTrustScore rule.
+     */
+    private checkMinTrustScore;
+    /**
+     * Check blockObfuscated rule.
+     */
+    private checkBlockObfuscated;
+    /**
+     * Check requireVerifiedPublisher rule.
+     */
+    private checkRequireVerifiedPublisher;
+    /**
+     * Check maxDaysSinceUpdate rule.
+     */
+    private checkMaxDaysSinceUpdate;
+}
+
+declare const VERSION = "0.1.0";
+
+export { type AuditReport, type DetectedIDE, type DetectionRule, type Evidence, ExtensionGuardScanner, type ExtensionInfo, type ExtensionManifest, type Finding, type FindingCategory, type FullScanReport, IDE_PATHS, type InspectOptions, JsonReporter, MarkdownReporter, type PolicyAction, type PolicyConfig, PolicyEngine, type PolicyRules, type PolicyViolation, type Reporter, type ReporterOptions, type RiskLevel, RuleEngine, type RuleEngineOptions, SEVERITY_ORDER, SarifReporter, type ScanOptions, type ScanResult, type ScanSummary, type Severity, VERSION, collectFiles, compareSeverity, detectIDEPaths, expandPath, isAtLeastSeverity, loadPolicyConfig, readExtension, readExtensionsFromDirectory, registerBuiltInRules, ruleRegistry, shouldCollectFile };