sultree

(noun) : a wary oak

what is this?

A SELinux-aware variant of the tree command that filters directory trees based on SELinux security contexts.

Features

• Full tree compatibility: Supports all standard tree command options
• SELinux filtering: Filter files and directories by SELinux security contexts using the -S flag
• Pattern matching: Support for wildcard patterns in SELinux context matching
• Security focused: Designed with security best practices and safe defaults
• Memory efficient: Uses iterative traversal for large directory trees
• Safe error handling: Gracefully handles permission denied and broken symlinks

Requirements

• Python 3.8+
• Linux system with SELinux enabled (optional for basic tree functionality)
• getfattr utility (part of attr package)

Installation

Quick Start (No Installation)

You can run sultree directly from the source directory:

cd sultree
./sultree /path/to/directory

Development Installation (Editable)

cd sultree
pip install -e .[dev]

This installs sultree in editable mode, so changes to the source code are immediately available.

Regular Installation

cd sultree  
pip install .

Usage

Basic Tree Functionality

# Basic directory tree (like standard tree)
sultree /etc

# Show hidden files
sultree -a /home/user

# Directories only, depth limited
sultree -d -L 2 /usr

# Show full paths
sultree -f -L 1 /var/log

# Follow symbolic links
sultree -l /usr/local

SELinux Filtering

# Show only files with specific SELinux type
sultree -S passwd_file_t /etc

# Wildcard patterns in any part of context
sultree -S "*admin*" /var/log
sultree -S "httpd_*" /var/www
sultree -S "*_exec_t" /usr/bin

# Multiple SELinux patterns (OR logic)
sultree -S passwd_file_t -S shadow_t /etc

# Full context pattern matching
sultree -S "system_u:object_r:*:s0" /etc

# Combine SELinux filtering with tree options
sultree -d -S httpd_exec_t -L 1 /usr/sbin
sultree -a -S "*_config_t" /etc

Pattern Matching

# Include only certain file patterns
sultree -P "*.conf" /etc

# Exclude backup files
sultree -I "*.bak" -I "*~" /home/user

# Case-insensitive matching
sultree --ignore-case -P "*.TXT" /tmp

# Apply patterns to directories too
sultree --match-dirs -P "*ssl*" /etc

Advanced Options

# Limit files per directory (performance)
sultree --filelimit 100 /usr

# Stay on one filesystem
sultree -x /

# Suppress file/directory count
sultree --no-report /etc

SELinux Context Display

When using SELinux filtering (-S option), sultree automatically displays the SELinux security contexts:

$ sultree -S passwd_file_t /etc
etc
group  [system_u:object_r:passwd_file_t:s0]
group-  [system_u:object_r:passwd_file_t:s0]
passwd  [system_u:object_r:passwd_file_t:s0]
passwd-  [system_u:object_r:passwd_file_t:s0]

4 files

Security Considerations

• Input validation: All paths and patterns are validated to prevent injection attacks
• Safe system calls: Uses getfattr directly, no shell command execution
• Path canonicalization: Prevents directory traversal attacks
• Symlink loop detection: Safely handles circular symlink references
• Permission handling: Gracefully handles permission denied errors
• Memory safety: Iterative processing prevents memory exhaustion on large trees
• Error information: Careful not to leak sensitive information in error messages

Error Handling

sultree handles various error conditions gracefully:

• Permission denied: Warns and continues with accessible files
• Broken symlinks: Logs and skips broken symbolic links
• SELinux unavailable: Clear error message if SELinux filtering requested but not available
• Invalid patterns: Validates and sanitizes all user input
• Large directories: File limit option prevents overwhelming output

Development

Project Structure

sultree/
├── src/sultree/
│   ├── __init__.py       # Package initialization
│   ├── __main__.py       # CLI entry point
│   ├── cli.py           # Main CLI orchestration
│   ├── args.py          # Argument parsing
│   ├── selinux.py       # SELinux functionality  
│   ├── traversal.py     # Directory traversal
│   └── formatting.py    # Tree output formatting
├── tests/               # Test suite
├── pyproject.toml       # Modern Python packaging
├── sultree              # Standalone script
└── README.md           # This file

Running Tests

# Using unittest (no external dependencies)
PYTHONPATH=src python3 -m unittest discover tests -v

# Or with pytest (if available)
pytest tests/ -v

Security Scanning

# Security linting with bandit
bandit -r src/

# Dependency scanning with safety (if available)  
safety check

Code Quality

# Type checking with mypy
mypy src/

# Code formatting with black
black src/ tests/

# Linting with flake8
flake8 src/

License

MIT License - see pyproject.toml for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Compatibility

sultree aims for compatibility with the standard tree command while adding SELinux functionality. Most tree options are supported with the same behavior.

Supported tree Options

• -a, --all: Show all files including hidden
• -d, --dirs-only: List directories only
• -l, --follow-links: Follow symbolic links
• -f, --full-path: Print full path prefix
• -x, --one-file-system: Stay on current filesystem
• -L level: Descend only level directories deep
• -P pattern: List only files matching pattern
• -I pattern: Ignore files matching pattern
• --match-dirs: Include directory names in pattern matching
• --ignore-case: Case insensitive pattern matching
• --filelimit N: Don't descend dirs with more than N files
• --no-report: Turn off file/directory count

SELinux Extensions

• -S pattern, --selinux pattern: Show only files matching SELinux pattern

Examples

System Administration

# Find all executable files in /usr/bin
sultree -S "*_exec_t" -L 1 /usr/bin

# Audit configuration files with specific contexts
sultree -S "*_config_t" /etc

# Check for files with admin contexts
sultree -S "*admin*" /var/log

Security Analysis

# Find files with user contexts in system directories
sultree -S "user_*" /etc /var

# Look for temporary file contexts
sultree -S "*tmp*" /var /tmp

# Audit files accessible to specific domains
sultree -S "httpd_*" /var/www /etc/httpd