aura-security 0.4.0

package/dist/agents/base.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Aura Protocol - Base Agent
+ *
+ * Abstract base class for all agents.
+ */
+import { Agent, AgentConfig, AgentCapabilities, AgentStatus, AgentResult } from './types.js';
+import { ZoneContext, ZoneFinding } from '../zones/types.js';
+export declare abstract class BaseAgent implements Agent {
+    readonly config: AgentConfig;
+    readonly capabilities: AgentCapabilities;
+    protected status: AgentStatus;
+    constructor(config: AgentConfig, capabilities: AgentCapabilities);
+    /**
+     * Check if external tool is installed
+     */
+    protected checkToolAvailable(toolName: string): Promise<boolean>;
+    /**
+     * Execute a command and return output
+     */
+    protected executeCommand(command: string, args: string[], options?: {
+        cwd?: string;
+        timeout?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    /**
+     * Check if agent is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get current status
+     */
+    getStatus(): AgentStatus;
+    /**
+     * Execute the agent
+     */
+    abstract execute(context: ZoneContext): Promise<AgentResult>;
+    /**
+     * Helper to create a finding
+     */
+    protected createFinding(agentId: string, partial: Omit<ZoneFinding, 'id' | 'agentId' | 'timestamp'>): ZoneFinding;
+}

package/dist/agents/base.js

@@ -0,0 +1,96 @@
+/**
+ * Aura Protocol - Base Agent
+ *
+ * Abstract base class for all agents.
+ */
+import { execSync, spawn } from 'child_process';
+export class BaseAgent {
+    config;
+    capabilities;
+    status = 'idle';
+    constructor(config, capabilities) {
+        this.config = config;
+        this.capabilities = capabilities;
+    }
+    /**
+     * Check if external tool is installed
+     */
+    async checkToolAvailable(toolName) {
+        try {
+            execSync(`which ${toolName}`, { stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            // Try Windows-style check
+            try {
+                execSync(`where ${toolName}`, { stdio: 'ignore' });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    /**
+     * Execute a command and return output
+     */
+    async executeCommand(command, args, options = {}) {
+        return new Promise((resolve) => {
+            const proc = spawn(command, args, {
+                cwd: options.cwd,
+                shell: true,
+                timeout: options.timeout || 300000, // 5 minute default
+            });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            proc.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            proc.on('close', (code) => {
+                resolve({
+                    stdout,
+                    stderr,
+                    exitCode: code || 0,
+                });
+            });
+            proc.on('error', (err) => {
+                resolve({
+                    stdout,
+                    stderr: err.message,
+                    exitCode: 1,
+                });
+            });
+        });
+    }
+    /**
+     * Check if agent is available
+     */
+    async isAvailable() {
+        if (!this.config.enabled)
+            return false;
+        if (this.config.externalTool) {
+            return this.checkToolAvailable(this.config.externalTool);
+        }
+        return true;
+    }
+    /**
+     * Get current status
+     */
+    getStatus() {
+        return this.status;
+    }
+    /**
+     * Helper to create a finding
+     */
+    createFinding(agentId, partial) {
+        return {
+            ...partial,
+            id: `${agentId}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+            agentId,
+            timestamp: Date.now(),
+        };
+    }
+}

package/dist/agents/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Aura Protocol - Agents
+ *
+ * Export all agents and agent utilities.
+ */
+export * from './types.js';
+export * from './base.js';
+export * from './scanners/index.js';
+export * from './policy/index.js';
+import { Agent } from './types.js';
+/**
+ * Create all default agents
+ */
+export declare function createAllAgents(): Agent[];

package/dist/agents/index.js

@@ -0,0 +1,17 @@
+/**
+ * Aura Protocol - Agents
+ *
+ * Export all agents and agent utilities.
+ */
+export * from './types.js';
+export * from './base.js';
+export * from './scanners/index.js';
+export * from './policy/index.js';
+import { createScannerAgents } from './scanners/index.js';
+import { createPolicyAgents } from './policy/index.js';
+/**
+ * Create all default agents
+ */
+export function createAllAgents() {
+    return [...createScannerAgents(), ...createPolicyAgents()];
+}

package/dist/agents/policy/evaluator.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Aura Protocol - Policy Evaluator Agent
+ *
+ * Evaluates findings against security policies.
+ * This agent provides context-aware analysis of findings.
+ */
+import { BaseAgent } from '../base.js';
+import { AgentResult } from '../types.js';
+import { ZoneContext } from '../../zones/types.js';
+export declare class PolicyEvaluatorAgent extends BaseAgent {
+    constructor();
+    execute(context: ZoneContext): Promise<AgentResult>;
+    private evaluateFinding;
+    private reduceSeverity;
+}

package/dist/agents/policy/evaluator.js

@@ -0,0 +1,183 @@
+/**
+ * Aura Protocol - Policy Evaluator Agent
+ *
+ * Evaluates findings against security policies.
+ * This agent provides context-aware analysis of findings.
+ */
+import { BaseAgent } from '../base.js';
+const CONFIG = {
+    id: 'policy-evaluator',
+    name: 'Policy Evaluator',
+    role: 'policy',
+    description: 'Evaluate findings against security policies',
+    enabled: true,
+};
+const CAPABILITIES = {
+    requiresExternalTool: false,
+    supportsParallel: false, // Policy evaluation should be sequential
+};
+// File patterns that indicate test/dev context
+const TEST_PATTERNS = [
+    /test[s]?\//i,
+    /spec[s]?\//i,
+    /__test__/i,
+    /\.test\./i,
+    /\.spec\./i,
+    /mock[s]?\//i,
+    /fixture[s]?\//i,
+    /example[s]?\//i,
+    /sample[s]?\//i,
+    /demo\//i,
+];
+// File patterns that indicate generated/vendored code
+const GENERATED_PATTERNS = [
+    /node_modules\//i,
+    /vendor\//i,
+    /dist\//i,
+    /build\//i,
+    /\.min\./i,
+    /bundle\./i,
+    /generated\//i,
+];
+// Packages known to have false positive vulnerabilities or low impact
+const LOW_PRIORITY_PACKAGES = [
+    'lodash', // Often has low-severity prototype pollution
+    'minimist', // Prototype pollution, but rarely exploitable
+    'qs', // Prototype pollution in old versions
+];
+export class PolicyEvaluatorAgent extends BaseAgent {
+    constructor() {
+        super(CONFIG, CAPABILITIES);
+    }
+    async execute(context) {
+        const startTime = Date.now();
+        this.status = 'running';
+        const processedFindings = [];
+        try {
+            context.log('info', 'Policy Evaluator analyzing findings');
+            // Get findings from scanner zone (passed via memory)
+            const scannerFindings = context.memory.data.get('scanner_findings') || [];
+            if (scannerFindings.length === 0) {
+                context.log('info', 'No findings to evaluate');
+                this.status = 'complete';
+                return {
+                    agentId: this.config.id,
+                    agentName: this.config.name,
+                    status: 'success',
+                    findings: [],
+                    duration: Date.now() - startTime,
+                };
+            }
+            context.log('info', `Evaluating ${scannerFindings.length} findings`);
+            for (const finding of scannerFindings) {
+                const evaluation = this.evaluateFinding(finding);
+                // Create annotated finding with policy metadata
+                const annotatedFinding = this.createFinding('policy-evaluator', {
+                    ...finding,
+                    metadata: {
+                        ...finding.metadata,
+                        policyEvaluation: evaluation,
+                        originalSeverity: finding.severity,
+                    },
+                    severity: evaluation.adjustedSeverity,
+                });
+                // Add context notes
+                if (evaluation.notes.length > 0) {
+                    annotatedFinding.description += `\n\nPolicy Notes:\n${evaluation.notes.map(n => `• ${n}`).join('\n')}`;
+                }
+                processedFindings.push(annotatedFinding);
+                context.addFinding(annotatedFinding);
+            }
+            // Store evaluated findings for validator
+            context.memory.data.set('evaluated_findings', processedFindings);
+            this.status = 'complete';
+            context.log('info', `Policy evaluation complete: ${processedFindings.length} findings processed`);
+            return {
+                agentId: this.config.id,
+                agentName: this.config.name,
+                status: 'success',
+                findings: processedFindings,
+                duration: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            this.status = 'error';
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            context.log('error', `Policy evaluation error: ${errorMsg}`);
+            return {
+                agentId: this.config.id,
+                agentName: this.config.name,
+                status: 'error',
+                findings: processedFindings,
+                duration: Date.now() - startTime,
+                error: errorMsg,
+            };
+        }
+    }
+    evaluateFinding(finding) {
+        const notes = [];
+        let adjustedSeverity = finding.severity;
+        let isTestContext = false;
+        let isGenerated = false;
+        let shouldSuppress = false;
+        const filePath = finding.file || '';
+        // Check if in test context
+        if (TEST_PATTERNS.some((p) => p.test(filePath))) {
+            isTestContext = true;
+            notes.push('Found in test/example context - lower priority');
+            adjustedSeverity = this.reduceSeverity(adjustedSeverity);
+        }
+        // Check if generated/vendored
+        if (GENERATED_PATTERNS.some((p) => p.test(filePath))) {
+            isGenerated = true;
+            notes.push('Found in generated/vendored code');
+            shouldSuppress = true;
+        }
+        // Check for low-priority packages
+        const pkgName = finding.metadata?.package || '';
+        if (LOW_PRIORITY_PACKAGES.some((p) => pkgName.toLowerCase().includes(p))) {
+            notes.push(`${pkgName} is known for low-impact vulnerabilities`);
+            adjustedSeverity = this.reduceSeverity(adjustedSeverity);
+        }
+        // Secrets in env.example or sample files are likely intentional
+        if (finding.type === 'secret' &&
+            /\.(example|sample|template)/i.test(filePath)) {
+            notes.push('Secret in example/template file - likely placeholder');
+            shouldSuppress = true;
+        }
+        // Check for fix availability
+        const fixAvailable = finding.metadata?.fixAvailable;
+        if (fixAvailable === false) {
+            notes.push('No fix available yet');
+        }
+        else if (typeof fixAvailable === 'object' && fixAvailable && 'version' in fixAvailable && fixAvailable.version) {
+            notes.push(`Fix available: upgrade to ${fixAvailable.version}`);
+        }
+        // Direct dependencies are higher priority
+        if (finding.metadata?.isDirect === true) {
+            notes.push('Direct dependency - higher priority');
+            if (finding.severity === 'medium') {
+                adjustedSeverity = 'high';
+            }
+        }
+        return {
+            adjustedSeverity,
+            notes,
+            isTestContext,
+            isGenerated,
+            shouldSuppress,
+        };
+    }
+    reduceSeverity(severity) {
+        switch (severity) {
+            case 'critical':
+                return 'high';
+            case 'high':
+                return 'medium';
+            case 'medium':
+                return 'low';
+            default:
+                return 'info';
+        }
+    }
+}

package/dist/agents/policy/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Aura Protocol - Policy Agents
+ *
+ * Export all policy agents.
+ */
+export { PolicyEvaluatorAgent } from './evaluator.js';
+export { ValidatorAgent } from './validator.js';
+import { Agent } from '../types.js';
+/**
+ * Create all policy agents
+ */
+export declare function createPolicyAgents(): Agent[];

package/dist/agents/policy/index.js

@@ -0,0 +1,15 @@
+/**
+ * Aura Protocol - Policy Agents
+ *
+ * Export all policy agents.
+ */
+export { PolicyEvaluatorAgent } from './evaluator.js';
+export { ValidatorAgent } from './validator.js';
+import { PolicyEvaluatorAgent } from './evaluator.js';
+import { ValidatorAgent } from './validator.js';
+/**
+ * Create all policy agents
+ */
+export function createPolicyAgents() {
+    return [new PolicyEvaluatorAgent(), new ValidatorAgent()];
+}

package/dist/agents/policy/validator.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Aura Protocol - Validator Agent
+ *
+ * Validates and deduplicates findings, removes false positives.
+ */
+import { BaseAgent } from '../base.js';
+import { AgentResult } from '../types.js';
+import { ZoneContext } from '../../zones/types.js';
+export declare class ValidatorAgent extends BaseAgent {
+    constructor();
+    execute(context: ZoneContext): Promise<AgentResult>;
+    private createFingerprint;
+    private isFalsePositive;
+    private calculateEntropy;
+}

package/dist/agents/policy/validator.js

@@ -0,0 +1,182 @@
+/**
+ * Aura Protocol - Validator Agent
+ *
+ * Validates and deduplicates findings, removes false positives.
+ */
+import { BaseAgent } from '../base.js';
+const CONFIG = {
+    id: 'validator',
+    name: 'Finding Validator',
+    role: 'validator',
+    description: 'Validate and deduplicate findings, remove false positives',
+    enabled: true,
+};
+const CAPABILITIES = {
+    requiresExternalTool: false,
+    supportsParallel: false,
+};
+// Patterns that indicate false positive secrets
+const FALSE_POSITIVE_PATTERNS = [
+    // SHA hashes (commit hashes, file hashes)
+    /^[a-f0-9]{40}$/i,
+    /^[a-f0-9]{64}$/i,
+    // UUIDs
+    /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i,
+    // NPM package integrity hashes
+    /^sha512-/i,
+    /^sha256-/i,
+    // Example/placeholder values
+    /^(xxx|aaa|test|example|sample|placeholder|dummy|fake)/i,
+    /^your[-_]?(api[-_]?key|secret|token|password)/i,
+    // Version strings
+    /^\d+\.\d+\.\d+$/,
+];
+// File paths that commonly have false positives
+const FALSE_POSITIVE_PATHS = [
+    /package-lock\.json$/i,
+    /yarn\.lock$/i,
+    /pnpm-lock\.yaml$/i,
+    /composer\.lock$/i,
+    /\.sum$/i,
+    /integrity.*\.txt$/i,
+];
+export class ValidatorAgent extends BaseAgent {
+    constructor() {
+        super(CONFIG, CAPABILITIES);
+    }
+    async execute(context) {
+        const startTime = Date.now();
+        this.status = 'running';
+        const validatedFindings = [];
+        try {
+            context.log('info', 'Validator analyzing findings');
+            // Get findings from policy zone
+            const evaluatedFindings = context.memory.data.get('evaluated_findings') ||
+                context.memory.data.get('scanner_findings') ||
+                [];
+            if (evaluatedFindings.length === 0) {
+                context.log('info', 'No findings to validate');
+                this.status = 'complete';
+                return {
+                    agentId: this.config.id,
+                    agentName: this.config.name,
+                    status: 'success',
+                    findings: [],
+                    duration: Date.now() - startTime,
+                };
+            }
+            context.log('info', `Validating ${evaluatedFindings.length} findings`);
+            const seenFindings = new Set();
+            let falsePositives = 0;
+            let duplicates = 0;
+            let suppressed = 0;
+            for (const finding of evaluatedFindings) {
+                // Check for duplicates
+                const fingerprint = this.createFingerprint(finding);
+                if (seenFindings.has(fingerprint)) {
+                    duplicates++;
+                    continue;
+                }
+                seenFindings.add(fingerprint);
+                // Check if suppressed by policy
+                if (finding.metadata?.policyEvaluation?.shouldSuppress) {
+                    suppressed++;
+                    continue;
+                }
+                // Check for false positives
+                if (this.isFalsePositive(finding)) {
+                    falsePositives++;
+                    continue;
+                }
+                // Valid finding
+                const validatedFinding = this.createFinding('validator', {
+                    ...finding,
+                    metadata: {
+                        ...finding.metadata,
+                        validated: true,
+                        fingerprint,
+                    },
+                });
+                validatedFindings.push(validatedFinding);
+                context.addFinding(validatedFinding);
+            }
+            // Store validated findings
+            context.memory.data.set('validated_findings', validatedFindings);
+            this.status = 'complete';
+            context.log('info', `Validation complete: ${validatedFindings.length} valid, ` +
+                `${falsePositives} false positives, ${duplicates} duplicates, ${suppressed} suppressed`);
+            return {
+                agentId: this.config.id,
+                agentName: this.config.name,
+                status: 'success',
+                findings: validatedFindings,
+                duration: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            this.status = 'error';
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            context.log('error', `Validation error: ${errorMsg}`);
+            return {
+                agentId: this.config.id,
+                agentName: this.config.name,
+                status: 'error',
+                findings: validatedFindings,
+                duration: Date.now() - startTime,
+                error: errorMsg,
+            };
+        }
+    }
+    createFingerprint(finding) {
+        // Create a unique fingerprint for deduplication
+        const parts = [
+            finding.type,
+            finding.file || '',
+            finding.line?.toString() || '',
+            finding.title,
+            finding.metadata?.vulnerabilityId || '',
+            finding.metadata?.package || '',
+        ];
+        return parts.join('::').toLowerCase();
+    }
+    isFalsePositive(finding) {
+        const filePath = finding.file || '';
+        // Check file path patterns
+        if (FALSE_POSITIVE_PATHS.some((p) => p.test(filePath))) {
+            return true;
+        }
+        // Check secret-specific false positives
+        if (finding.type === 'secret') {
+            const match = finding.metadata?.match || '';
+            // Check against false positive patterns
+            if (FALSE_POSITIVE_PATTERNS.some((p) => p.test(match))) {
+                return true;
+            }
+            // Very short matches are likely false positives
+            if (match.length < 16) {
+                return true;
+            }
+            // Check for low entropy (unlikely to be real secrets)
+            const entropy = this.calculateEntropy(match);
+            if (entropy < 2.5) {
+                return true;
+            }
+        }
+        return false;
+    }
+    calculateEntropy(str) {
+        const len = str.length;
+        if (len === 0)
+            return 0;
+        const freq = {};
+        for (const char of str) {
+            freq[char] = (freq[char] || 0) + 1;
+        }
+        let entropy = 0;
+        for (const count of Object.values(freq)) {
+            const p = count / len;
+            entropy -= p * Math.log2(p);
+        }
+        return entropy;
+    }
+}

package/dist/agents/scanners/gitleaks.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Aura Protocol - Gitleaks Agent
+ *
+ * Scans for secrets and API keys using gitleaks.
+ */
+import { BaseAgent } from '../base.js';
+import { AgentResult } from '../types.js';
+import { ZoneContext } from '../../zones/types.js';
+export declare class GitleaksAgent extends BaseAgent {
+    constructor();
+    execute(context: ZoneContext): Promise<AgentResult>;
+    private getSeverity;
+    private maskSecret;
+}