attach Command
Inject Peeka Agent into a target Python process and establish a diagnostic channel.
Table of Contents
- Overview
- TUI Usage
- Syntax
- Usage Examples
- Permission Requirements
- Output Format
- Troubleshooting
- Security Considerations
- Related Commands
- References
Overview
The attach command is the first step in using Peeka. It injects Peeka Agent code into the target process and starts a Unix Domain Socket server, establishing a communication channel for subsequent diagnostic commands.
How It Works
Python 3.14+:
- Uses PEP 768’s
sys.remote_exec()API - Secure, efficient, officially supported
Python 3.8.1-3.13:
- Uses GDB + ptrace on Linux
- Uses LLDB + dlopen on macOS
- Compatibility fallback solution
TUI Usage
TUI Auto-Attach on Launch: Running peeka command directly launches TUI and automatically shows process selector:
- Run
peeka(no arguments) - In process selector, choose target process
- Press Enter to auto-attach and enter main interface
TUI Features:
- Real-time process list refresh
- Display process PID, command line, CPU/memory usage
- Support search/filter (type keywords to filter)
- Auto-validate permissions (show PEP 768, GDB, or LLDB availability)
CLI Equivalent Commands: All examples below use CLI commands for demonstration. TUI provides the same functionality with a graphical interface.
Syntax
peeka-cli attach <pid> [options]
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
pid |
int | ✅ | PID of the target process |
Options
| Option | Description | Default |
|---|---|---|
--timeout |
Attachment timeout (seconds) | 30 |
--socket-dir |
Socket file directory | /tmp |
Usage Examples
Basic Attachment
# Attach to process 12345
peeka-cli attach 12345
Output:
{"type":"status","level":"info","message":"Attaching to process 12345"}
{"type":"status","level":"info","message":"Using PEP 768 remote_exec"}
{"type":"success","command":"attach","data":{"pid":12345,"socket":"/tmp/peeka_12345.sock"}}
Finding Process PID
# Using ps
ps aux | grep python
# Using pgrep
pgrep -f "my_app.py"
# Using pidof
pidof python3
Attach and Execute Command Immediately
# Attach then immediately observe
peeka-cli attach 12345 && peeka-cli watch "app.func"
Permission Requirements
Linux Systems
Same User
The simplest approach is to run Peeka as the same user:
# Both target process and Peeka run as user1
user1$ python my_app.py # PID: 12345
user1$ peeka-cli attach 12345 # ✅ Success
Different Users (Requires sudo)
# Target process runs as user1, need sudo
user1$ python my_app.py # PID: 12345
user2$ sudo peeka-cli attach 12345 # ✅ Success
ptrace_scope Configuration
Check current configuration:
cat /proc/sys/kernel/yama/ptrace_scope
| Value | Description | Peeka Availability |
|---|---|---|
| 0 | No restrictions (not recommended) | ✅ All users can attach |
| 1 | Only parent-child processes or CAP_SYS_PTRACE | ✅ Recommended setting |
| 2 | Only CAP_SYS_PTRACE | ✅ Requires sudo |
| 3 | Completely disabled | ❌ Cannot use |
Temporary modification (for testing):
echo 1 | sudo tee /proc/sys/kernel/yama/ptrace_scope
Permanent modification:
echo "kernel.yama.ptrace_scope = 1" | sudo tee /etc/sysctl.d/10-ptrace.conf
sudo sysctl -p /etc/sysctl.d/10-ptrace.conf
Docker Containers
Need to add SYS_PTRACE capability:
# Add when running container
docker run --cap-add=SYS_PTRACE your-image
# docker-compose.yml
services:
app:
cap_add:
- SYS_PTRACE
security_opt:
- seccomp=unconfined
SELinux Systems
Check SELinux status:
getenforce # Enforcing, Permissive, Disabled
Temporarily allow ptrace:
sudo setsebool -P deny_ptrace off
Output Format
Success Response
{
"type": "success",
"command": "attach",
"data": {
"pid": 12345,
"socket": "/tmp/peeka_12345.sock",
"python_version": "3.12.0",
"attach_method": "remote_exec"
}
}
Error Response
{
"type": "error",
"command": "attach",
"error": "Operation not permitted: ptrace access denied"
}
Troubleshooting
Error: Operation not permitted
Cause: Insufficient permissions
Solutions:
- Use same user or sudo
- Check ptrace_scope setting
- Check SELinux configuration
# Check process owner
ps -o user= -p 12345
# Use sudo
sudo peeka-cli attach 12345
# Relax ptrace restrictions (for testing)
echo 1 | sudo tee /proc/sys/kernel/yama/ptrace_scope
Error: Process not found
Cause: PID doesn’t exist or has exited
Solutions:
# Confirm process exists
ps -p 12345
# Re-find PID
pgrep -f "my_app.py"
Error: Python debugging symbols not found (Linux, Python < 3.14)
Cause: Missing Python debugging symbols (required for the Linux GDB fallback)
Solutions:
# Debian/Ubuntu
sudo apt-get install python3-dbg
# RHEL/CentOS
sudo yum install python3-debuginfo
Error: GDB not found (Linux, Python < 3.14)
Cause: GDB not installed
Solutions:
# Debian/Ubuntu
sudo apt-get install gdb
# RHEL/CentOS
sudo yum install gdb
Error: LLDB not found (macOS, Python < 3.14)
Cause: Xcode Command Line Tools are not installed
Solutions:
xcode-select --install
Error: Timeout attaching to process
Cause: Attachment timeout (target process may be hung)
Solutions:
# Increase timeout
peeka-cli attach 12345 --timeout 60
# Check target process status
ps -p 12345 -o stat=
Security Considerations
Process Isolation
- Peeka can only attach to local processes
- Remote attachment not supported
- Unix Domain Socket limited to local access only
Principle of Least Privilege
- Production environments should use same user
- Avoid using root privileges
- Detach promptly when diagnostics are no longer needed
Code Injection Security
- Agent code only performs diagnostic functions
- Does not modify business logic
- All injections can be reverted via reset command