src — security

Module: src-security Cohesion: 0.80 Members: 0

src — security

The src/security module is the cornerstone of Code Buddy's safety mechanisms, designed to protect the user's system and data from unintended or malicious actions by the AI agent. It implements a multi-layered defense strategy, combining explicit user approval, pattern-based allowlisting, static code analysis, and secure credential management.

This documentation provides a comprehensive overview for developers looking to understand, extend, or contribute to Code Buddy's security features.

Purpose and Core Principles

The primary goal of the src/security module is to ensure that the AI agent operates within defined boundaries and that any potentially dangerous operations are either automatically blocked, require explicit user confirmation, or are subject to rigorous validation.

Key principles guiding this module:

  1. Least Privilege: Agents should only have the minimum permissions necessary to perform their tasks.
  2. User Confirmation: Critical or ambiguous operations must be confirmed by the user.
  3. Auditability: All security-relevant decisions and actions are logged for review.
  4. Defense in Depth: Multiple layers of security (modes, allowlists, parsers, validators) are applied.
  5. Transparency: Users should understand why an action is blocked or requires confirmation.

Architectural Overview

The security module is composed of several interconnected components, each addressing a specific aspect of agent safety. At a high level, operational modes (ApprovalModeManager) define the general posture, while specific tools like the ApprovalFlowManager (for bash commands) and CodeValidator handle granular checks. All significant events are recorded by the AuditLogger. 

graph TD
    A[Agent Tool Execution] --> B{ApprovalModeManager};
    B -- "OperationType" --> C{ApprovalFlowManager};
    B -- "OperationType" --> D{CodeValidator};
    C -- "Bash Command" --> E[AllowlistStore];
    C -- "Prompt User" --> F[ConfirmationService];
    E -- "Patterns" --> G[PatternMatcher];
    D -- "Code Content" --> H[DangerousPatternsRegistry];
    B -- "Decision" --> I[AuditLogger];
    C -- "Decision" --> I;
    D -- "Decision" --> I;
    J[CredentialManager] -- "API Keys" --> K[External Services];
    L[CSRFProtection] -- "Web UI" --> M[HTTP Server];

    subgraph Bash Allowlist
        E -- "CRUD" --> G;
        C -- "Delegates" --> E;
    end

    subgraph Core Security
        B; C; D; I; J; L; H;
    end

Key Components

1. Approval Modes (src/security/approval-modes.ts)

This module defines a three-tier system for controlling the agent's operational permissions, inspired by common CLI permission models. It provides a high-level policy for various OperationTypes.

2. Bash Command Allowlist (src/security/bash-allowlist/)

This sub-module provides a granular, pattern-based system for approving or denying shell commands executed by the agent. It's a critical component for preventing arbitrary command execution.

2.1. Pattern Matching (src/security/bash-allowlist/pattern-matcher.ts)

2.2. Pattern Storage (src/security/bash-allowlist/allowlist-store.ts)

2.3. Approval Workflow (src/security/bash-allowlist/approval-flow.ts)

3. Bash Command Parser (src/security/bash-parser.ts)

4. Generated Code Validator (src/security/code-validator.ts)

5. Audit Logger (src/security/audit-logger.ts)

6. Credential Manager (src/security/credential-manager.ts)

7. CSRF Protection (src/security/csrf-protection.ts)

8. Dangerous Patterns Registry (src/security/dangerous-patterns.ts)

Integration and Execution Flow

The security components work in concert to enforce policies:

  1. Agent Action Request: When the agent attempts an operation (e.g., executing a bash command, writing a file), it first goes through the ApprovalModeManager.
  2. Mode-Based Check: ApprovalModeManager.checkApproval() classifies the operation and determines if it's auto-approved, blocked, or requires confirmation based on the current ApprovalMode.
  3. Bash Command Flow:

  1. Code Generation Flow:

  1. Credential Handling: CredentialManager ensures that API keys are loaded securely (preferring environment variables) and stored encrypted on disk.
  2. Audit Trail: Every significant decision and action (approvals, blocks, validations, confirmations) is recorded by the AuditLogger for transparency and post-mortem analysis.
  3. Web Security: CSRFProtection safeguards any web-facing components from common web vulnerabilities.

Example Execution Flow: Bash Command Approval

graph TD
    A[Agent requests: Execute 'npm install malicious-package'] --> B{ApprovalModeManager.checkApproval};
    B -- "OperationType: command-network" --> C{Mode Config: 'auto'};
    C -- "Requires Confirmation" --> D[ApprovalFlowManager.checkAndApprove];
    D --> E{AllowlistStore.checkCommand};
    E -- "No match, fallback: 'prompt'" --> F[ConfirmationService.requestConfirmation];
    F -- "User confirms & 'Always Allow'" --> G[ApprovalFlowManager.recordApproval];
    G --> H[AllowlistStore.addPattern];
    H -- "New pattern saved" --> I[AuditLogger.logConfirmation];
    I --> J[Command Approved];

Contributing to Security Features

Developers contributing to the src/security module should be mindful of the following:

Conclusion

The src/security module is a vital part of Code Buddy, providing the necessary safeguards for agent operations. By understanding its components and their interactions, developers can effectively contribute to building a more secure and trustworthy AI assistant.