PatchCTL Agent

The PatchCTL agent is a lightweight daemon that runs on your managed servers, enabling secure communication with the PatchCTL platform.

Architecture

The agent follows a pull-based security model:

┌──────────────────┐                    ┌──────────────────┐
│   Your Server    │                    │   PatchCTL API   │
│                  │                    │                  │
│  ┌────────────┐  │     HTTPS/443      │  ┌────────────┐  │
│  │  PatchCTL  │  │  ───────────────►  │  │  Command   │  │
│  │   Agent    │  │    (outbound)      │  │   Queue    │  │
│  └────────────┘  │                    │  └────────────┘  │
│                  │                    │                  │
└──────────────────┘                    └──────────────────┘

Key security features:

• Agent only makes outbound connections
• No inbound ports required
• All traffic encrypted with TLS 1.3
• Commands validated against whitelist

What the Agent Does

Heartbeat (every 5 minutes)

• Reports server online status
• Sends basic system metrics (CPU, RAM, disk)
• Pulls any queued commands
• Reports command execution results

Package Scan (every 6 hours)

• Inventories all installed packages
• Checks for available updates
• Identifies security-related updates
• Correlates packages with CVE data

Command Execution

The agent only executes whitelisted operations:

• check_updates - Refresh package list
• install_updates - Apply selected updates
• get_package_info - Query specific packages
• health_check - System health verification

No Arbitrary Execution

The agent cannot execute arbitrary commands. All operations are validated against a strict whitelist for security.

Directory Structure

/opt/patchctl/
├── bin/
│   └── patchctl-agent      # Agent binary
└── log/                    # Optional local log directory

/etc/patchctl/
└── config.json             # Agent configuration

Quick Reference

Topic	Description
Installation	Install the agent on various distributions
Configuration	Configure agent behavior
Updates	Agent self-update mechanism
Troubleshooting	Diagnose common issues
Uninstall	Remove the agent

System Service

The agent runs as a systemd service:

# Check status
sudo systemctl status patchctl

# View logs
sudo journalctl -u patchctl -f

# Restart agent
sudo systemctl restart patchctl