Protection Tools

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	4 (+8 config)	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

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 - 4 primary + 8 config 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	`add-path`	Add directories to monitor
Configuration Commands	`remove-path`	Remove from monitoring
Configuration Commands	`list-paths`	Show monitored directories
Configuration Commands	`set-interval`	Adjust check frequency
Configuration Commands	`set-fix-mode`	Enable/disable auto-fix
Configuration Commands	`add-exclusion`	Exclude patterns
Configuration Commands	`remove-exclusion`	Remove exclusions
Configuration Commands	`show-config`	Display full 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

# Configure monitoring paths
sudo ./permission-guard config add-path /etc
sudo ./permission-guard config add-path /usr/local/bin
sudo ./permission-guard config add-path /home/user/.ssh

# Set monitoring parameters
sudo ./permission-guard config set-interval 60
sudo ./permission-guard config set-fix-mode true

# Start monitoring daemon
sudo ./permission-guard watch

Continuous Protection Monitoring

# Check current status
./permission-guard status --json

# View recent changes
./permission-guard status --changes

# Generate compliance report
./permission-guard status --report > compliance.json

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

# Add exclusions for dynamic files
sudo ./permission-guard config add-exclusion "*.log"
sudo ./permission-guard config add-exclusion "*.tmp"

# View current configuration
./permission-guard config show-config

# Export configuration
./permission-guard config export > guard-config.json

# Import configuration
sudo ./permission-guard config import guard-config.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

Level	Description	Action	Examples
Critical	System files	Immediate fix + alert	/etc/passwd, /etc/shadow
High	Config files	Fix + log	/etc/ssh/*, service configs
Medium	User files	Alert only	~/.ssh/, ~/.gnupg/
Low	Data files	Log only	/var/log/, /tmp/

Custom Policy Framework

# Define custom policies
cat > custom-policy.json << EOF
{
  "paths": {
    "/custom/secure": {
      "level": "critical",
      "permissions": "0600",
      "owner": "root:root",
      "action": "fix"
    }
  }
}
EOF

# Apply custom policy
sudo ./permission-guard config import-policy custom-policy.json

Advanced Features

Forensic Capabilities

Feature	Description
Change History	Complete audit trail of all modifications
Timeline Analysis	Chronological view of system changes
Attribution	User and process identification
Rollback Points	Restore previous permissions

Integration with Security Stack

# Integration with health-control
sudo ./health-control security-audit
./permission-guard scan --deep

# Integration with integrity-check
./integrity-check check-all
./permission-guard status --verify

# Integration with logs-hook
./permission-guard watch --log-level debug
tail -f /dashboard/hooks/logs/permission-guard.log

Compliance Reporting

Report Type	Format	Use Case
Daily Summary	JSON/PDF	Management review
Change Log	CSV	Audit trail
Violation Report	HTML	Incident response
Compliance Status	JSON	Automated monitoring

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
systemctl status permission-guard

# Test inotify limits
cat /proc/sys/fs/inotify/max_user_watches

# Verify namespace support
unshare --help

# Check audit logs
journalctl -u permission-guard -f

Performance Tuning

# Increase inotify watches
echo "fs.inotify.max_user_watches=524288" >> /etc/sysctl.conf
sysctl -p

# Optimize scan intervals
sudo ./permission-guard config set-interval 120

# Limit monitored paths
sudo ./permission-guard config remove-path /var/cache

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.0.1	2025-09-18	Proprietary
oniux	Third-party	Open Source	Open Source
Documentation	9.0.1	2025-09-19	© 2025 Linux Kodachi