VSGuard

Proactive security auditing for VS Code. Monitors file system access, processes and module loading to detect malicious behavior from extensions.

Features

• File System Access Monitoring: Tracks various file system operations, including:
  • File reading and writing (readFile, writeFile, etc.)
  • File deletion and renaming (unlink, rename, etc.)
  • File metadata access (stat, exists, access, etc.)
  • Directory listing (readdir)
  • File copying (copyFile)
  • Async operations via fs/promises
• Module Loading Detection: Identifies and monitors module imports to detect potentially malicious activity.
• Process Monitoring: Monitors process-related events to track extension behavior.
• Real-time Monitoring: Provides live feedback on security-relevant events.
• Configurable Hooks: Allows customization of monitoring behavior through exclusions and sensitive patterns.

Requirements

None. VSGuard works out of the box with no additional dependencies.

Extension Settings

VSGuard contributes the following settings and commands:

Settings

• vsguard.block (boolean): Enable or disable blocking of sensitive file access from extensions.

  • true: Actively block access to sensitive paths when a match is detected.
  • false: Only log and warn without blocking.

• vsguard.exclusions (array of objects): File-access exclusions.

  • Objects contain:
    • extensionId (string): The ID of the extension to exclude.
    • filePath (string/regex): The file path pattern to exclude.
  • You can manage these via the VSGuard: Show Exclusions command.

• vsguard.processExclusions (array of objects): Process-access exclusions.

  • Objects contain:
    • extensionId (string): The ID of the extension to exclude.
    • command (string/regex): The command pattern to exclude.

• vsguard.sensitivePatterns (array of objects): Custom regular-expression patterns for sensitive files.

  • Objects contain:
    • pattern (string/regex): The regex pattern to match.
    • description (string): A description of why this pattern is sensitive.
  • Example: [{"pattern": "\\.myapp\\/secrets", "description": "App secrets"}]

• vsguard.processDetections (array of objects): Patterns to detect anomalous process behaviors.

  • Objects contain:
    • command (string/regex or null): The command pattern to monitor.
    • args (array of string/regex): An array of argument patterns.
    • extensionId (string or null): The extension ID to associate with this detection.
    • description (string): A description of the detection.

Exclusion Creation and Matching Behavior

When you click "Exclude This" in VSGuard's warning dialogs, exclusions are automatically created. Here's how they work:

Automatic Exclusion Creation

Exclusions can be created for two types of events:

1. File System Access (vsguard.exclusions):

   • Triggered when accessing sensitive files (e.g., .env, .ssh/, .aws/credentials)
   • Automatically creates an exclusion rule for the extension that triggered the access
   • Stored in vsguard.exclusions setting

2. Process Execution (vsguard.processExclusions):

   • Triggered when executing processes or commands
   • Automatically creates an exclusion rule for the extension that triggered the execution
   • Stored in vsguard.processExclusions setting

Extension ID Matching Logic

VSGuard uses a sophisticated matching system to handle extensions without proper IDs:

Three-tier matching behavior:

1. Specific Extension ID: When an exclusion has a specific extension ID (e.g., "mycompany.myextension"), it only matches that exact extension.

2. "unknown" Fallback: When an extension's ID cannot be determined (null or undefined), VSGuard uses the string "unknown" as a marker. This allows:

   • Multiple different extensions with null IDs to have distinct exclusion rules
   • Proper matching when checking if an extension should be excluded
   • The rule only applies when the current operation also has a null/undefined extension ID

3. Wildcard (null): When an exclusion has extensionId: null, it applies to any extension performing the operation. This is useful for:

   • Global exclusions that should apply regardless of which extension triggers them
   • Temporary or anonymous operations

Example Scenarios

// Scenario 1: Specific extension exclusion
{
  "extensionId": "vscode.typescript-language-features",
  "filePath": "/path/to/tsconfig.json"
}
// Matches ONLY when the TypeScript extension accesses this file

// Scenario 2: "unknown" fallback (for extensions without IDs)
{
  "extensionId": "unknown",
  "filePath": "/path/to/file.txt"
}
// Matches when ANY extension with null/undefined ID accesses this file
// Does NOT match extensions with specific IDs

// Scenario 3: Wildcard exclusion
{
  "extensionId": null,
  "filePath": "/path/to/file.txt"
}
// Matches ANY extension accessing this file (global exclusion)

Managing Exclusions

Use the VSGuard: Show Exclusions command to:

• View all current exclusions
• Add new exclusions manually
• Remove unwanted exclusions
• Toggle block mode on/off

Best Practices

1. Review automatic exclusions: Check that auto-created exclusions are intentional.
2. Use specific IDs when possible: Prefer exact extension IDs over wildcards for better control.
3. Monitor "unknown" entries: These indicate extensions that couldn't be properly identified.
4. Regular cleanup: Remove exclusions for extensions you no longer use.

Commands

• vsguard.showMonitoringLog: Display the monitoring log in the output panel.
• vsguard.clearMonitoringLog: Clear the monitoring log.
• vsguard.showExclusions: Open the exclusions settings page.
• vsguard.syncSettings: Synchronize VSGuard settings.
• vsguard.enableBlockMode: Enable blocking for sensitive file access.
• vsguard.disableBlockMode: Disable blocking for sensitive file access.
• vsguard.openHookFile: Open the hook configuration file.
• vsguard.fireFsAccess: Fire a fsRead against .bashrc (for testing).
• vsguard.fireSshAccess: Fire a fsRead against .ssh/config (for testing).
• vsguard.installHook: Install the VSGuard hook.
• vsguard.uninstallHook: Uninstall the VSGuard hook.
• vsguard.spawnPowerShellBase64: Start PowerShell Base64 (for testing).

Installing and Using the Hook

VSGuard uses a hook mechanism to intercept file system, process, and module loading operations. The hook needs to be installed after activating the extension.

Installation Steps

1. Activate VSGuard Extension: Install and activate the VSGuard extension from the VS Code Extensions marketplace.

2. Install the Hook: Run the VSGuard: Install Hook command:

   • Go to Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
   • Type "VSGuard: Install Hook"
   • Select and execute the command

3. Verify Installation: Check the Output panel for a message like VSGUARD installHooks() confirming successful installation.

Uninstallation

To uninstall the hook:

1. Run VSGuard: Uninstall Hook from the Command Palette
2. The hook will be removed, but your exclusion settings will be preserved
3. Re-install by running VSGuard: Install Hook when needed

How the Hook Works

The hook intercepts the following operations:

File System Operations:

• fs.readFile, fs.readFileSync
• fs.writeFile, fs.writeFileSync
• fs.unlink, fs.unlinkSync
• fs.rename, fs.renameSync
• fs.stat, fs.statSync
• fs.exists, fs.existsSync
• fs.access, fs.accessSync
• fs.readdir, fs.readdirSync
• fs.copyFile, fs.copyFileSync

Module Loading:

• require() calls
• Module _load events

Process Operations:

• child_process.spawn
• child_process.spawnSync
• child_process.exec
• child_process.execSync
• child_process.execFile

Hook Lifecycle

1. On Extension Activation: The hook is not automatically installed when the extension activates.
2. Manual Installation Required: You must run VSGuard: Install Hook to enable monitoring.
3. Persistent Across Sessions: Once installed, the hook remains active until explicitly uninstalled.
4. Automatic Re-installation: If the hook is lost (e.g., VS Code restart), you'll need to reinstall it.

Troubleshooting Hook Issues

If VSGuard doesn't detect file system or process operations:

1. Check if hook is installed: Run VSGuard: Show Monitoring Log and look for VSGUARD installHooks() message.
2. Reinstall the hook: Use VSGuard: Uninstall Hook followed by VSGuard: Install Hook.
3. Check Output Panel: Look for any error messages related to hook installation.
4. Verify extension activation: Ensure VSGuard is properly activated in VS Code.

Testing the Hook

To verify the hook is working:

1. Run VSGuard: Fire Fs Access to test file access monitoring
2. Run VSGuard: Fire Ssh Access to test sensitive file detection
3. Run VSGuard: Spawn PowerShell Base64 to test process monitoring

These commands will trigger test events and show you how VSGuard responds.

How to configure it

1. Open VS Code settings and search for VSGuard.
2. Set vsguard.block to true if you want sensitive-file access to be blocked.
3. Add custom patterns to vsguard.sensitivePatterns for any extra sensitive files you want to monitor.
4. Use VSGuard: Show Exclusions to review or update the vsguard.exclusions list when an extension should be allowed to access a path.

Syslog Integration

VSGuard supports optional syslog integration for centralized logging and security monitoring. When enabled, VSGuard will forward security events to a syslog server in RFC5424 format.

Syslog Settings

• vsguard.syslog.enabled (boolean): Enable or disable syslog forwarding.

  • true: Forward all VSGuard log messages to the configured syslog server.
  • false: Disable syslog forwarding (default).

• vsguard.syslog.host (string): The hostname or IP address of the syslog server.

  • Default: 'localhost'

• vsguard.syslog.port (number): The port to connect to on the syslog server.

  • Default: 514 (standard syslog port)

• vsguard.syslog.protocol ('tcp' | 'tls'): The protocol to use for the connection.

  • 'tcp': Use plain TCP connection (default).
  • 'tls': Use TLS/SSL encrypted connection.

Syslog Message Format

When enabled, VSGuard logs are sent in RFC5424 format with the following structure:

<PRI>VERSION TIMESTAMP HOSTNAME APP-NAME PROCID MSGID [STRUCTURED-DATA] MSG

Example message:

<31>1 2026-06-17T10:30:45.123Z vscode.vsguard VSGuard - - - {"type":"fsRead","message":"Attempted to read sensitive file","data":{"filePath":"/home/user/.bashrc","extensionId":"vscode.codelldb"}}

Syslog Use Cases

• Centralized Security Monitoring: Forward all security events to a SIEM (Security Information and Event Management) system.
• Compliance Requirements: Meet regulatory requirements for centralized log management.
• Extended Retention: Store logs on a dedicated server with longer retention periods.
• Multi-server Environments: Aggregate logs from multiple development machines.

Configuration Example

{
  "vsguard.syslog.enabled": true,
  "vsguard.syslog.host": "logs.company.com",
  "vsguard.syslog.port": 514,
  "vsguard.syslog.protocol": "tcp"
}

Known Issues

SUPPORT