Security & Permissions
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Security & Permissions system in the code-cli project provides a multi-layered defense architecture designed to protect the user's local environment, sensitive credentials, and workspace integrity from unauthorized or accidental AI-driven actions. The system ensures that all tool executions, particularly destructive ones or those accessing sensitive files, are subject to strictly defined security policies and user consent.
At its core, the system integrates workspace boundary enforcement, a comprehensive permission management framework, and a real-time security scanner for secret detection. These components work in tandem to validate every request processed by the agent, from the initial workspace verification on startup to the final commit of code changes.
Sources: src/core/agent.ts:100-150, tests/integration/securityIntegration.spec.ts:168-185
Workspace Safety & Boundary Enforcement
The first layer of defense is the workspaceSafety module, which validates the target directory before the agent initializes. This prevents the agent from operating in sensitive system areas or user root directories.
Validation Logic
The checkWorkspaceSafety function performs normalization and checks against a predefined list of prohibited paths across different operating systems (Linux, macOS, Windows). It blocks execution in filesystem roots, home directories, and system-critical folders like /etc, /usr, or C:\Windows.
Sources: src/startup/workspaceSafety.ts, tests/workspaceSafety.spec.ts:33-140
The diagram shows the sequential path validation process during application startup.
Sources: src/startup/workspaceSafety.ts, src/index.ts:178-183
Permission Management Framework
The PermissionManager acts as the primary orchestrator for tool authorization. It evaluates every requested action against a set of global and project-specific rules, including blacklists and whitelists.
Operating Modes
The system supports three distinct modes of operation that dictate how permissions are handled:
| Mode | Description |
|---|---|
interactive | Default mode. Prompts user for approval on non-whitelisted actions. |
unrestricted | Automatically allows non-blacklisted actions. Blacklisted items remain blocked. |
restricted | Automatically denies all dangerous or non-whitelisted operations. |
Sources: src/permissions/PermissionManager.ts, tests/integration/securityIntegration.spec.ts:102-120, src/core/toolManager.ts:25-30
Blacklist Enforcement
The system maintains a DEFAULT_SECURITY_BLACKLIST that is immutable across all modes. This ensures that even in unrestricted mode, the agent cannot access or modify high-risk items such as:
- Environment files (
.env,.env.local) - Git configuration (
.git/config) - SSH keys (
~/.ssh/id_rsa) - Cloud credentials (
~/.aws/credentials) - Dangerous shell commands (
sudo,rm -rf /,printenv)
Sources: tests/security/securityBlacklist.spec.ts:14-45, tests/integration/securityIntegration.spec.ts:122-135
The sequence diagram illustrates the decision flow when a tool requires permission.
Sources: src/core/actionExecutor.ts:114-140, src/permissions/PermissionManager.ts
Security Scanning & Secret Detection
The SecurityScanner provides a dedicated layer for detecting sensitive data within file contents and git diffs. It is primarily used during the git_commit and auto_commit workflows to prevent accidental leakage of secrets.
Detection Features
- Pattern Matching: Uses regex to identify AWS keys, GitHub tokens, OpenAI/Anthropic keys, Stripe live keys, and database connection strings.
- Severity Levels: Findings are categorized as
high,medium, orlow.highseverity findings (e.g., live private keys) trigger an automatic block of the commit. - False Positive Mitigation: Includes a
placeholderPatternslist to ignore common example strings likeyour-api-keyor***.
Sources: src/core/SecurityScanner.ts:40-115, src/core/actionExecutor.ts:600-625
Commit Scan Workflow
When a commit is initiated, the ActionExecutor invokes the SecurityScanner to analyze the staged changes. If high-severity secrets are detected, the commit is blocked with a detailed error message identifying the file and line number.
Sources: src/core/actionExecutor.ts:983-1015, tests/integration/agent-flow.spec.ts:220-245
Resource & Filesystem Limits
The FileActionManager enforces strict resource limits to protect against denial-of-service style operations and excessive memory consumption.
| Limit Constant | Value | Description |
|---|---|---|
MAX_READ_SIZE | 10 MB | Maximum file size allowed for reading. |
MAX_WRITE_SIZE | 50 MB | Maximum size for content being written to a file. |
MAX_UNDO_STACK | 100 | Maximum number of operations preserved for reversion. |
MAX_SEARCH_RESULTS | 1000 | Cap on the number of hits returned by a search operation. |
Sources: tests/security/resourceLimits.spec.ts:26-45, src/actions/filesystem.ts
Path Traversal Protection
Every filesystem operation is passed through a resolution utility that ensures the resulting path remains within the defined workspace root. Attempts to use ../ to escape the root or access absolute paths like /etc/passwd are caught and rejected by the FileActionManager.
Sources: tests/security/resourceLimits.spec.ts:111-130, src/core/actionExecutor.ts:1130-1135
Conclusion
Security and permissions in code-cli are implemented as a mandatory, multi-stage pipeline. By combining static workspace validation, dynamic permission management, and content-aware security scanning, the system creates a "walled garden" that allows the AI agent to be productive while significantly reducing the risk of environmental damage or data exfiltration. This architecture ensures that the user maintains ultimate control through explicit consent and immutable safety defaults.
Sources: src/core/agent.ts:152-180, tests/integration/securityIntegration.spec.ts:168-185