Skip to content

CLAUDE.md

Latest commit

 

History

History
138 lines (99 loc) · 5.5 KB

CLAUDE.md

File metadata and controls

138 lines (99 loc) · 5.5 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

SecVF (Security Virtualization Framework) is a native macOS app for security research, malware analysis, and incident response. Built with Swift using Apple's Virtualization framework.

Primary use case: Running malware samples in isolated VMs while capturing and analyzing network traffic.

Build Commands

# Build the project
xcodebuild -scheme SecVF -configuration Debug -destination 'platform=macOS,arch=arm64' build

# Run tests
xcodebuild test -scheme SecVF -destination 'platform=macOS'

# Run specific test class
xcodebuild test -scheme SecVF -destination 'platform=macOS' -only-testing:SecVFTests/VMConfigurationTests

# Open in Xcode
open SecVF.xcodeproj

Architecture

Core Components

VM Management Layer

  • AppDelegate.swift - Application lifecycle, menu bar, multi-window VM management, NotificationCenter handlers
  • VMManager.swift - VM CRUD operations, bundle management, async initialization on background threads
  • VMConfiguration.swift - Codable data model for VM settings (CPU, memory, disk, network mode)
  • VMLibraryWindowController.swift - Main window UI: VM table, packet log panel, Active VMs sidebar (~2600 LOC)

Network Stack

  • VirtualNetworkSwitch.swift - L2/L3 software switch for isolated VM-to-VM communication, MAC learning, packet forwarding
  • PacketCaptureManager.swift - tshark integration, Combine PassthroughSubject/CurrentValueSubject publishers for real-time packet events
  • PacketAnalysisWindowController.swift - Full packet analysis UI with Wireshark-style display filters

Supporting Components

  • ISOCacheManager.swift - Linux ISO download/caching with checksum validation (~1000 LOC)
  • DistroVersionFetcher.swift - Dynamic version discovery from official distro mirrors; distro metadata in Resources/distros.json
  • MacOSVMInstaller.swift - IPSW download from Apple CDN with security validation
  • VMSecurityMonitor.swift - Real-time filesystem/resource monitoring, security event logging
  • ScriptsUSBManager.swift - Scripts USB disk creation and management for guest VMs
  • SecVFError.swift - Typed error enum (11 categories) with LocalizedError recovery suggestions; audit trail at ~/.avf/logs/error-audit.log

Protocols (SecVF/Protocols/) - Protocol abstraction for dependency injection and testing:

  • VMManagerProtocol.swift, NetworkSwitchProtocol.swift, PacketCaptureProtocol.swift

Key Architectural Patterns

  • Singletons: VMManager.shared, VirtualNetworkSwitch.shared, PacketCaptureManager.shared
  • Combine: Reactive updates for packet events and protocol statistics
  • @MainActor: Applied to all UI/window controller classes for thread safety; background work on DispatchQueue
  • NotificationCenter: VM lifecycle coordination across the app

Key Notification Names

Notification.Name.startVM         // Start a VM
Notification.Name.stopVM          // Stop a VM
Notification.Name.pauseVM         // Pause/Resume a VM
Notification.Name.packetCaptured  // New packet captured

VM Storage Structure

~/.avf/
   Linux/<VMName>.bundle/
      Disk.img, NVRAM, MachineIdentifier, metadata.json
   MacOS/<VMName>.bundle/
      (same structure + .ipsw)
   logs/
      security-YYYY-MM-DD.log
      error-audit.log

Network Modes

  • NAT Mode (NetworkMode.nat) - Default, internet access through host
  • Virtual Network (NetworkMode.virtual) - Isolated VM-to-VM via VirtualNetworkSwitch
  • Router VM pattern: Kali Linux acts as gateway for traffic inspection

Testing

Test files in SecVF/Tests/:

  • TestHelpers.swift - Mock VM bundle creation, async helpers, XCTest extensions
  • VMConfigurationTests.swift, VMManagerTests.swift, VirtualNetworkSwitchTests.swift
  • ISOCacheManagerTests.swift, VMLibraryUITests.swift, IntegrationTests.swift

Use Given/When/Then pattern for tests.

CLI Tool

The command-line interface is at SecVF/cli/ (Swift package, secvf-cli binary):

# Build the CLI
cd SecVF/cli && swift build

# Run CLI commands
.build/debug/secvf-cli vm list
.build/debug/secvf-cli tui  # Launch Terminal UI (Python/Textual)

The TUI (SecVF/cli/tui/) is implemented in Python using the Textual framework. CLI commands: vm, usb, switch, capture, tui.

Key Dependencies

  • Apple Virtualization Framework - VM hypervisor (requires macOS 14.0+, Apple Silicon for macOS VMs)
  • tshark (optional) - Packet capture, install via brew install wireshark
  • swift-argument-parser 1.3.0+ - CLI argument parsing

Router VM Scripts

scripts/kali-router-setup.sh - Configures Kali Linux as router with:

  • Static IP 10.0.100.1/24, IP forwarding, iptables rules, DHCP
  • Security analysis tools (tcpdump, tshark, nmap)
  • Helper commands: secvf-status, secvf-monitor, secvf-capture

scripts/kali-fakenet-setup.sh - FakeNet honeypot environment:

  • All DNS resolves to router, fake HTTP/HTTPS responses
  • Captures malware network behavior

Security Considerations

This app handles potentially hostile guest VMs:

  • Apple Virtualization Framework provides hardware-enforced isolation
  • No shared folders by default
  • IPSW downloads validated against Apple CDN whitelist
  • VMSecurityMonitor watches for suspicious activity with severity levels (INFO, WARNING, CRITICAL, EMERGENCY)
  • Security logs at ~/.avf/logs/security-*.log

When modifying network or VM code, maintain the isolation guarantees.