Version: 0.3.0 Last Updated: 2025-11-16

1. Overview
2. Security Model
3. Authentication & Authorization
4. Data Security
5. Daemon Security
6. IPC Security
7. Privacy Considerations
8. Threat Model
9. Security Best Practices
10. Vulnerability Reporting

Time Audit is designed as a local-first, privacy-focused time tracking application. All data processing occurs on the user's machine, and no data is transmitted to external servers without explicit user configuration.

1. Local Data Storage: All time tracking data stays on the user's machine
2. Minimal Permissions: Request only necessary system permissions
3. Process Isolation: Daemon runs with user-level privileges (no root/admin required)
4. Secure IPC: Inter-process communication uses secure Unix sockets/named pipes
5. Transparent Operation: All operations are logged and auditable
6. Privacy by Default: Sensitive data collection is opt-in only

┌─────────────────────────────────────────────────┐
│              User's Machine                      │
│  ┌───────────────────────────────────────────┐  │
│  │         Time Audit Process Space          │  │
│  │  ┌────────┐  ┌────────┐  ┌────────┐      │  │
│  │  │  CLI   │◄─┤  IPC   │─►│ Daemon │      │  │
│  │  └────────┘  └────────┘  └────────┘      │  │
│  │       │           │            │          │  │
│  │       ▼           ▼            ▼          │  │
│  │  ┌────────────────────────────────┐      │  │
│  │  │     Data Directory (~/.)       │      │  │
│  │  │   - entries.csv (600)          │      │  │
│  │  │   - config.yml (600)           │      │  │
│  │  │   - daemon.sock (600)          │      │  │
│  │  └────────────────────────────────┘      │  │
│  └───────────────────────────────────────────┘  │
│                      ▲                           │
│                      │ OS APIs                   │
│                      ▼                           │
│  ┌───────────────────────────────────────────┐  │
│  │       Operating System                    │  │
│  │  - Process info (psutil)                  │  │
│  │  - Idle detection (input events)          │  │
│  │  - Desktop notifications                  │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘

Authentication Method: File System Permissions

• IPC socket is created with mode 0600 (owner read/write only)
• Only the user who started the daemon can communicate with it
• No password or token required (protected by OS file permissions)

Why no password authentication?

• Daemon runs as the user, for the user
• File system permissions provide sufficient protection
• Simpler UX - no password management
• Appropriate for single-user desktop application

• Config file: ~/.time-audit/config.yml (mode 600)
• Data directory: ~/.time-audit/data/ (mode 700)
• Only the owner can read or modify configuration

Storage Format: CSV and JSON files

File Permissions:

~/.time-audit/                    # 700 (drwx------)
├── data/
│   ├── entries.csv               # 600 (-rw-------)
│   ├── projects.csv              # 600 (-rw-------)
│   └── categories.csv            # 600 (-rw-------)
├── config.yml                    # 600 (-rw-------)
├── state/
│   ├── current.json              # 600 (-rw-------)
│   └── daemon.json               # 600 (-rw-------)
└── runtime/
    └── daemon.sock               # 600 (srw-------)

Data Integrity:

• Atomic file writes (write to temp file, then rename)
• File locking during write operations (prevents concurrent corruption)
• Automatic backups before destructive operations
• Validation on read to detect corruption

At Rest: Optional

Time Audit does not encrypt data at rest by default, because:

1. Data is already protected by OS file permissions (mode 600)
2. Full-disk encryption (FileVault, LUKS, BitLocker) provides system-wide protection
3. Encryption adds complexity and potential data loss risk

Optional Encryption: Users who need additional protection can:

1. Enable full-disk encryption at the OS level (recommended)
2. Store ~/.time-audit/ in an encrypted volume
3. Use third-party encryption tools (EncFS, VeraCrypt) to encrypt the data directory

In Transit: N/A

Data never leaves the local machine in default configuration. Future cloud sync features will use TLS 1.3.

• Backups inherit permissions from original files (mode 600)
• Backup files stored in ~/.time-audit/backups/
• Automatic cleanup of old backups (configurable retention)

Privilege Level: User (non-root)

The daemon:

• Runs with the same privileges as the user who started it
• Does NOT require root/administrator privileges
• Cannot access other users' data
• Cannot modify system-wide settings

Sandboxing: OS-dependent

• Linux: Optionally use systemd hardening directives
• macOS: Runs within user's security context
• Windows: Runs as user service, not system service

The daemon handles termination signals gracefully:

• SIGTERM: Graceful shutdown (save state, close files, exit)
• SIGINT: Same as SIGTERM (Ctrl+C)
• SIGKILL: Immediate termination (state may be lost)

Best Practice: Always use time-audit daemon stop rather than kill -9

To prevent resource exhaustion:

• CPU: Target <1% CPU usage during monitoring
• Memory: Target <50MB memory footprint
• Disk: Log rotation to prevent unbounded growth
• Network: None (daemon makes no network connections)

Required OS Permissions:

Privacy Controls:

• Process detection is opt-in (disabled by default)
• User controls which processes are monitored
• Option to exclude sensitive applications
• Window titles can be hashed instead of stored plaintext

Protocol: JSON-RPC 2.0 over Unix domain sockets (Linux/macOS) or named pipes (Windows)

Why Unix sockets?

• Inherit file system permissions (mode 600)
• Faster than TCP sockets
• Immune to network-based attacks
• Only accessible to local user

Linux/macOS:

# Socket file created with restrictive permissions
~/.time-audit/runtime/daemon.sock  # mode 600 (srw-------)

# Only owner can read/write
$ ls -l ~/.time-audit/runtime/daemon.sock
srw------- 1 user user 0 Nov 16 10:00 daemon.sock

Windows:

• Named pipe: \\.\pipe\time-audit-daemon
• Access controlled by Windows ACLs
• Only the creating user has access

All IPC messages are validated:

# Request validation
{
    "jsonrpc": "2.0",           # Must be "2.0"
    "id": <int|string|null>,    # Required
    "method": <string>,         # Required, must match known methods
    "params": <object>          # Validated by handler
}

Validation Rules:

1. JSON syntax must be valid
2. jsonrpc must be "2.0"
3. method must be a registered handler
4. params validated by specific handler
5. Reject oversized messages (>64KB)

Rate Limiting: None currently implemented

Rationale:

• IPC socket only accessible to owner
• Owner unlikely to DoS themselves
• If needed, implement connection limits per second

Message Size Limits:

• Maximum message size: 64KB
• Prevents memory exhaustion attacks
• Sufficient for all current use cases

Time Audit collects:

Window Title Filtering:

Users can exclude sensitive applications:

# config.yml
privacy:
  exclude_processes:
    - "keepass"
    - "1password"
    - "*bank*"
    - "*password*"
  exclude_window_patterns:
    - ".*incognito.*"
    - ".*private.*"

Window Title Hashing (Optional):

Instead of storing window titles plaintext:

privacy:
  hash_window_titles: true

Stores SHA256 hash of window title, allowing:

• Pattern matching (same hash = same window)
• No plaintext sensitive data in storage
• Privacy-preserving analytics

Default Configuration: Minimal data collection

• Process detection: OFF
• Idle detection: OFF
• Notifications: OFF

User Control: All data collection is opt-in

• Default: Unlimited retention
• Configurable: Auto-delete entries older than N days
• Manual: time-audit batch delete --filter "date<2024-01-01"

1. Trusted User: User running Time Audit is not malicious
2. Secure OS: Operating system is not compromised
3. Physical Security: Machine has physical security
4. No Shared Accounts: One user per system account (typical desktop use)

1. Keep Time Audit Updated: Apply security updates promptly
2. Use Full-Disk Encryption: Enable FileVault/LUKS/BitLocker
3. Lock Your Screen: When away from computer
4. Review Process Exclusions: Exclude sensitive apps from monitoring
5. Backup Regularly: Use time-audit export to back up data
6. Strong OS Password: Protect your user account

1. Input Validation: Validate all user input and IPC messages
2. Least Privilege: Run with minimal required permissions
3. Fail Secure: On error, fail to a safe state (stop tracking)
4. Audit Logging: Log all daemon operations for debugging
5. Dependency Scanning: Regularly scan dependencies for vulnerabilities
6. Code Review: Review all PRs for security issues

Minimal Privacy Impact:

process_detection:
  enabled: false
idle_detection:
  enabled: true
  threshold: 300
notifications:
  enabled: false

Balanced:

process_detection:
  enabled: true
  auto_switch: false  # Require confirmation
privacy:
  exclude_processes:
    - "*password*"
    - "*bank*"
idle_detection:
  enabled: true
notifications:
  enabled: true

Maximum Automation:

process_detection:
  enabled: true
  auto_switch: true  # Auto-switch for learned rules
idle_detection:
  enabled: true
notifications:
  enabled: true
# Note: Understand privacy tradeoffs

If you discover a security vulnerability in Time Audit:

1. DO NOT open a public GitHub issue
2. Email: security@time-audit.example.com (placeholder - update with real contact)
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

• Acknowledgment: Within 48 hours
• Initial Assessment: Within 1 week
• Fix Development: Depends on severity
• Public Disclosure: After fix is available

Security updates are released as:

• Critical: Immediate release, notify all users
• High: Release within 1 week
• Medium/Low: Include in next regular release

Time Audit is designed for personal use and does not typically fall under GDPR as no data is transferred to a data controller. However:

If Used in an Organization:

• Time tracking data may be personal data
• Employer is the data controller
• Users must be informed about tracking
• Data must be retained according to policy
• Users have right to access/delete their data

Built-in GDPR Support:

• Export all data: time-audit export json
• Delete all data: rm -rf ~/.time-audit/
• Transparency: All data stored locally in readable formats

• Downloaded from official source (PyPI/GitHub releases)
• Verified package signature (if available)
• Installed in user directory (not system-wide)

• Reviewed default configuration
• Configured process exclusions for sensitive apps
• Set appropriate data retention policy
• Enabled full-disk encryption (OS level)

• Daemon runs as user (not root)
• IPC socket has mode 600
• Data files have mode 600
• Regular backups configured
• Logs reviewed for errors

• Keep Time Audit updated
• Review and prune old data
• Audit process detection rules
• Check file permissions periodically

• OWASP Top 10
• CWE/SANS Top 25 Most Dangerous Software Errors
• Unix Security Best Practices

Document Version: 1.0 Last Review: 2025-11-16 Next Review: 2026-01-16