Protection Tools
Local safety controls for permissions, process isolation, and damage-resistant operation. Use these pages to protect the local system itself: file permissions, helper runtimes, containment boundaries, and safer operational defaults.
System Protection and Isolation Layer
Kodachi protection tooling combines native permission enforcement with hardened third-party isolation and tunneling runtimes to reduce attack surface and contain process behavior at runtime.
Permission Enforcement Plane
Guard
permission-guard continuously monitors policy-defined paths and can auto-remediate unauthorized permission drift with full audit visibility.
Isolation and Tunneling Plane
Isolate
Bundled oniux and tun2socks provide process namespace isolation and proxy-based traffic containment, integrated into higher-level network workflows.
Documentation Navigation
Navigate the documentation:
- Quick Start - Installation guide and getting started
- CLI Reference - Complete command-line reference
Enterprise-Grade System Protection and Process Isolation
The protection tools in Kodachi OS provide comprehensive system hardening through real-time permission monitoring, process isolation, and security policy enforcement. These production-ready binaries ensure system integrity by preventing unauthorized changes and maintaining strict access controls.
Core Architecture Principles - Verified
Real-Time Monitoring: Continuous surveillance of file permissions and system changes
Process Isolation: Advanced namespace separation for secure process execution
Policy Enforcement: Automatic remediation of unauthorized modifications
Defense in Depth: Multiple layers of protection from file-level to process-level
Binary Categories and Requirements
Core Protection Tools
| Binary | Primary Function | Commands | Requires Auth | Requires Sudo | Auto-Start |
|---|---|---|---|---|---|
| permission-guard | Real-time permission monitoring and enforcement | 8 | No | Yes (fixes) | Called by online-auth |
| oniux | Third-party open source Tor isolation tool | Variable | No | Yes (namespaces) | No |
| tun2socks | Third-party open source TUN/TAP to SOCKS5 proxy tool | Variable | No | Yes (network) | No |
| kodachi-session-helper | Session lifecycle helper shared across the Kodachi service suite (17th signed service) | 3 | No | No | Session-driven |
Inter-Binary Dependencies Matrix
Binary Communication Flow
| Service | Calls These Binaries | Called By These Binaries |
|---|---|---|
| permission-guard | logs-hook | online-auth |
| oniux | logs-hook | tor-switch (for Tor isolation) |
Critical Service Dependencies
| Dependency Type | Description | Affected Services |
|---|---|---|
| Authentication Integration | Started and managed by online-auth | permission-guard |
| Logging Infrastructure | All services use logs-hook | Both protection binaries |
| Process Isolation | tor-switch uses oniux for Tor instance isolation | tor-switch |
| System Monitoring | Continuous file system surveillance | permission-guard daemon |
System Requirements and Permissions
Privilege Escalation Requirements
| Operation Type | Required Permissions | Affected Binaries |
|---|---|---|
| Permission Fixes | sudo/root | permission-guard (auto-fix mode) |
| Namespace Creation | sudo/root | oniux (process isolation) |
| File Monitoring | Read access | permission-guard (scan mode) |
| Policy Updates | sudo/root | permission-guard config |
System Integration
| Component | Integration Method | Services |
|---|---|---|
| inotify | Kernel file monitoring | permission-guard |
| Namespaces | Linux namespaces API | oniux |
| Capabilities | Linux capabilities system | Both services |
| SELinux/AppArmor | MAC integration | Optional enhancement |
Key Capabilities Overview
Permission Monitoring (permission-guard - 8 commands)
| Category | Command/Feature | Description |
|---|---|---|
| Monitoring Modes | watch |
Continuous daemon monitoring with auto-fix |
| Monitoring Modes | scan |
One-time comprehensive permission scan |
| Monitoring Modes | status |
Current monitoring status and statistics |
| Monitoring Modes | config |
Configuration management interface |
| Configuration Commands | config show |
Display current embedded configuration |
| Security Features | Real-time monitoring | inotify-based file system monitoring |
| Security Features | Automatic correction | Permission fixes applied automatically |
| Security Features | Pattern exclusions | Rule-based exclusion system |
| Security Features | Audit logging | Comprehensive security audit trail |
| Security Features | Field filtering | Advanced filtering and pagination |
Process Isolation (oniux - third-party open source tool)
Third-Party Integration
Oniux is an open source tool developed by the Tor Project (https://gitlab.torproject.org/tpo/core/oniux) that has been integrated into Kodachi OS specifically for its powerful Tor process isolation capabilities. It is primarily used in conjunction with tor-switch to provide advanced namespace separation and security features for Tor instances.
| Feature Category | Capability | Description |
|---|---|---|
| Isolation Features | Mount namespace separation | Isolates filesystem mounts from host system |
| Isolation Features | User namespace mapping | Maps user/group IDs for privilege separation |
| Isolation Features | Network namespace isolation | Separates network stack and interfaces |
| Isolation Features | PID namespace containment | Process ID isolation and containment |
| Isolation Features | IPC namespace separation | Inter-process communication isolation |
| Security Capabilities | Capability dropping | Removes unnecessary Linux capabilities |
| Security Capabilities | Seccomp filtering | System call filtering and restriction |
| Security Capabilities | Resource limits (cgroups) | CPU, memory, and I/O resource constraints |
| Security Capabilities | Filesystem restrictions | Access control and path restrictions |
| Security Capabilities | Network filtering | Network traffic filtering and blocking |
| Use Cases | Tor process isolation | Secure Tor instance separation |
| Use Cases | Untrusted application sandboxing | Safe execution of untrusted code |
| Use Cases | Service compartmentalization | Service-level security boundaries |
| Use Cases | Testing environments | Isolated testing and development |
Network Tunneling (tun2socks - third-party open source tool)
Third-Party Integration
tun2socks is an open source tool (https://github.com/xjasonlyu/tun2socks) that has been integrated into Kodachi OS for its powerful TUN/TAP to SOCKS5 proxy capabilities. It is bundled alongside oniux in the Kodachi package and is used by various binaries to route traffic through SOCKS5 proxies. This tool is not developed by Kodachi but is an essential third-party component.
| Feature Category | Capability | Description |
|---|---|---|
| Network Features | TUN device support | Creates and manages TUN virtual network interfaces |
| Network Features | TAP device support | Handles TAP layer 2 network interfaces |
| Network Features | SOCKS5 proxy integration | Routes traffic through SOCKS5 proxy servers |
| Network Features | TCP/UDP support | Full support for both TCP and UDP protocols |
| Routing Capabilities | Transparent proxying | Seamless traffic redirection without app changes |
| Routing Capabilities | Split tunneling | Selective routing based on rules |
| Routing Capabilities | DNS handling | Proper DNS query routing through proxy |
| Performance | High-speed forwarding | Optimized packet forwarding engine |
| Use Cases | Proxy routing | Route system traffic through SOCKS5 proxies |
| Use Cases | VPN alternatives | Lightweight proxy-based routing solution |
| Use Cases | Network isolation | Isolate application traffic through proxies |
Common Workflows
Initial System Protection Setup
# Perform initial permission scan
sudo permission-guard scan
# Start monitoring with auto-fix
sudo permission-guard watch /home --auto-fix --scan-interval 60
Continuous Protection Monitoring
# Check current status
permission-guard status --json
# View detailed status
permission-guard status --detailed
Process Isolation Operations
# Run process in isolated namespace
sudo oniux isolate --net --pid --mount /usr/bin/application
# Create Tor-specific isolation
sudo oniux tor-isolate --instance tor1
# Sandbox untrusted application
sudo oniux sandbox --strict /path/to/untrusted/app
Configuration Management
# View current configuration
permission-guard config show
# View configuration in JSON format
permission-guard config show --json
Performance Metrics
| Metric | Value | Description |
|---|---|---|
| File Monitoring | 10,000+ files | Concurrent monitoring capacity |
| Scan Speed | 50,000 files/sec | Permission checking rate |
| Response Time | < 10ms | Change detection latency |
| Memory Usage | < 30MB | Combined services |
| CPU Usage | < 2% | During active monitoring |
Protection Architecture
Multi-Layer Defense Model
Application Layer
↓
Permission Guard (File System)
↓
Oniux (Process Isolation)
↓
Kernel Security Modules
↓
Hardware Security
Permission Enforcement Flow
File Change Event → inotify → Permission Guard
↓
Policy Evaluation
↓
[Allowed] or [Fix Required]
↓
Auto-Remediation
↓
Audit Logging
Isolation Architecture
Process Request → Oniux → Namespace Creation
↓
Capability Restriction
↓
Resource Limitation
↓
Isolated Execution
Security Policies
Default Protection Levels
Permission-guard operates on a single model: all detected ownership mismatches are either automatically fixed (when --auto-fix is enabled) or logged for review (default behavior).
Advanced Features
Forensic Capabilities
| Feature | Description |
|---|---|
| Change History | In-memory change log (per session only) |
Integration with Security Stack
# Integration with health-control
sudo health-control system-audit
permission-guard scan
# Integration with integrity-check
integrity-check check-all
permission-guard status --detailed
# Integration with logs-hook
permission-guard watch --verbose
tail -f <hooks-dir>/logs/permission-guard-log.log
Compliance Reporting
Output is available in JSON format via --json flag and text console output.
Use Cases
System Administrators
| Use Case | Description |
|---|---|
| Configuration Management | Prevent configuration drift |
| Security Enforcement | Enforce security baselines |
| Access Monitoring | Monitor privileged file access |
| Intrusion Detection | Detect intrusion attempts |
Security Operations
| Use Case | Description |
|---|---|
| Threat Detection | Real-time threat detection |
| Compliance | Compliance enforcement |
| Incident Response | Incident investigation |
| Security Monitoring | Security posture monitoring |
DevSecOps
| Use Case | Description |
|---|---|
| Pipeline Security | CI/CD pipeline security |
| Container Management | Container permission management |
| Deployment | Deployment verification |
| IaC Validation | Infrastructure as Code validation |
Privacy Protection
| Use Case | Description |
|---|---|
| Data Control | Personal data access control |
| Key Protection | Encryption key protection |
| Browser Isolation | Browser profile isolation |
| App Sandboxing | Communication app sandboxing |
Integration Points
The protection tools integrate with:
| Integration Type | Components |
|---|---|
| Security Services | health-control, integrity-check, online-auth |
| Logging System | Centralized logs-hook integration |
| Kernel Subsystems | inotify, namespaces, capabilities |
| File Systems | ext4, btrfs, xfs attributes |
| Container Runtimes | Docker, Podman isolation |
Troubleshooting
Common Issues
| Issue | Solution | Prevention |
|---|---|---|
| High CPU usage | Reduce scan frequency | Optimize path selection |
| Permission fix fails | Check file system | Verify root access |
| False positives | Add exclusions | Refine policies |
| Monitoring stops | Check daemon status | Enable auto-restart |
Diagnostic Commands
# Check service health
permission-guard --daemon-status
# Test inotify limits
cat /proc/sys/fs/inotify/max_user_watches
# Verify namespace support
unshare --help
# Check audit logs
tail -f <hooks-dir>/logs/permission-guard-log.log
Performance Tuning
# Increase inotify watches
echo "fs.inotify.max_user_watches=524288" >> /etc/sysctl.conf
sysctl -p
# Adjust scan intervals (set via --scan-interval on watch command)
# Note: The interval is set via --scan-interval 120 on the watch command
# Note: Exclusions are embedded in the binary configuration
Security Considerations
Important Security Notice
Protection tools modify system permissions and isolate processes. Incorrect configuration can lock out users or break applications. Always test policies in non-production environments first.
Best Practices
| Practice | Description |
|---|---|
| Baseline First | Create initial permission baseline before monitoring |
| Test Policies | Verify policies don't break legitimate operations |
| Regular Audits | Review change logs weekly |
| Backup Configs | Maintain configuration backups |
| Monitor Performance | Watch for resource exhaustion |
Operational Security
| Security Measure | Implementation |
|---|---|
| Immutable Files | Use chattr +i for critical files |
| MAC Integration | Enable SELinux/AppArmor policies |
| Audit Subsystem | Configure auditd rules |
| File Integrity | Combine with integrity-check |
| Access Logging | Enable detailed access logs |
System Information
| Component | Version | Build Date | License |
|---|---|---|---|
| permission-guard | 9.8.4 (build 319) | 2026-07-02 | Proprietary |
| oniux | Third-party | Open Source | Open Source |
| tun2socks | Third-party | Open Source | Open Source |
| Documentation | 9.8.4 (build 319) | 2026-07-02 | © 2026 Linux Kodachi |