Linux Patch API

Version: 1.0.0
Status: Production Ready
License: Internal Use Only

Secure REST API for remote package and patch management on Linux systems.

---

Table of Contents

• Overview
• Features
• Quick Start
• Installation
• Configuration
• API Usage
• Security
• Performance
• Contributing
• Support

---

Overview

Linux Patch API provides a secure, production-ready interface for managing software packages and system patches on Linux servers. Designed for internal network deployment with enterprise-grade security controls.

Key Design Principles:

• Zero-trust security architecture (mTLS + IP whitelist)
• Pure REST API with async job handling
• Real-time status via WebSocket streaming
• Multi-distro support (Debian, RHEL, Alpine, Arch)
• Comprehensive audit logging

---

Features

Package Management

• Install, update, and remove packages remotely
• Batch operations with dependency resolution
• Support for apt, dnf, yum, apk, pacman backends
• Version pinning and force options

Patch Management

• List available security patches
• Apply patches with optional auto-reboot
• Patch scheduling and delay options
• Rollback capabilities

Job Management

• Async operation tracking with job IDs
• Real-time status via WebSocket
• Job history and audit trail
• Configurable concurrency limits

System Management

• System information retrieval
• Health check endpoints
• Remote reboot capabilities
• Service status monitoring

Security Features

• mTLS certificate authentication (TLS 1.3 only)
• IP whitelist enforcement (deny by default)
• Comprehensive audit logging (systemd journal)
• Systemd hardening and process isolation
• File permission enforcement

---

Quick Start

Prerequisites

• Linux server (Debian/Ubuntu, RHEL/CentOS/Fedora, Alpine, or Arch)
• systemd init system
• Root or sudo access
• Internal CA infrastructure for certificates

1. Install Package

Debian/Ubuntu:

dpkg -i linux-patch-api_1.0.0-1_amd64.deb

RHEL/CentOS/Fedora:

rpm -ivh linux-patch-api-1.0.0-1.x86_64.rpm

Manual Installation:

./install.sh

2. Configure Certificates

# Copy CA certificate
cp ca.pem /etc/linux_patch_api/certs/

# Copy server certificate and key
cp server.pem /etc/linux_patch_api/certs/
cp server.key.pem /etc/linux_patch_api/certs/
chmod 600 /etc/linux_patch_api/certs/server.key.pem

3. Configure IP Whitelist

Edit /etc/linux_patch_api/whitelist.yaml:

entries:
  - "192.168.1.0/24"      # Management network
  - "10.0.0.50"           # Admin workstation

4. Start Service

systemctl enable linux-patch-api
systemctl start linux-patch-api
systemctl status linux-patch-api

5. Test Connection

curl --cacert ca.pem \
     --cert client.pem \
     --key client.key.pem \
     https://localhost:12443/api/v1/health

---

Installation

Package Installation

Debian/Ubuntu (.deb)

# Install the package
dpkg -i linux-patch-api_1.0.0-1_amd64.deb

# Fix any dependency issues
apt-get install -f -y

# Verify installation
systemctl status linux-patch-api
linux-patch-api --version

RHEL/CentOS/Fedora (.rpm)

# Install the package
rpm -ivh linux-patch-api-1.0.0-1.x86_64.rpm

# Verify installation
systemctl status linux-patch-api
linux-patch-api --version

Manual Installation

For systems without package manager support:

# Run interactive installer (requires root)
./install.sh

The installer will:

• Detect operating system
• Create system user and group
• Set up directory structure
• Install binary and configuration files
• Configure systemd service

Building from Source

# Clone repository
git clone https://gitea.internal/linux-patch-api.git
cd linux-patch-api

# Build release binary
cargo build --release --target x86_64-unknown-linux-gnu

# Build Debian package
dpkg-buildpackage -us -uc -b

# Or build RPM package
rpmbuild -ba linux-patch-api.spec

See BUILD_PACKAGES.md for detailed build instructions.

---

Configuration

Configuration File

Location: /etc/linux_patch_api/config.yaml

# Server Configuration
server:
  port: 12443
  bind: "0.0.0.0"
  timeout_seconds: 30

# TLS/mTLS Configuration
tls:
  enabled: true
  port: 12443
  ca_cert: "/etc/linux_patch_api/certs/ca.pem"
  server_cert: "/etc/linux_patch_api/certs/server.pem"
  server_key: "/etc/linux_patch_api/certs/server.key"
  min_tls_version: "1.3"

# Job Configuration
jobs:
  max_concurrent: 5
  timeout_minutes: 30
  storage_path: "/var/lib/linux_patch_api/jobs"

# Logging Configuration
logging:
  level: "info"
  journal_enabled: true
  syslog_enabled: false
  file_path: "/var/log/linux_patch_api/audit.log"
  retention_days: 30

# IP Whitelist Configuration
whitelist:
  path: "/etc/linux_patch_api/whitelist.yaml"

# Package Manager Backend
package_manager:
  backend: "auto"  # auto, apt, dnf, yum, apk, pacman

IP Whitelist

Location: /etc/linux_patch_api/whitelist.yaml

entries:
  - "192.168.1.0/24"      # Management network
  - "10.0.0.50"           # Specific admin workstation
  - "admin-server.internal"  # Hostname (resolved at startup)

Supported Entry Types:

• Individual IPs: 192.168.1.100
• CIDR subnets: 192.168.1.0/24
• Hostnames: admin-server.internal

Note: Changes to whitelist are applied automatically (no restart required).

Certificate Requirements

File	Location	Permissions	Description
CA Certificate	/etc/linux_patch_api/certs/ca.pem	644	Internal CA public cert
Server Cert	/etc/linux_patch_api/certs/server.pem	644	Server public certificate
Server Key	/etc/linux_patch_api/certs/server.key	600	Server private key
Client Cert	/etc/linux_patch_api/certs/client.pem	644	Client public certificate
Client Key	/etc/linux_patch_api/certs/client.key	600	Client private key

See DEPLOYMENT_SECURITY_GUIDE.md for certificate setup instructions.

---

API Usage

Base URL

https://<server-ip>:12443/api/v1/

Authentication

All requests require:

1. Valid client certificate (signed by internal CA)
2. Source IP in whitelist

curl --cacert ca.pem \
     --cert client.pem \
     --key client.key.pem \
     https://localhost:12443/api/v1/health

Standard Response Format

{
  "success": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-04-09T13:04:02Z",
  "data": {},
  "error": null
}

Example: List Packages

curl --cacert ca.pem \
     --cert client.pem \
     --key client.key.pem \
     "https://localhost:12443/api/v1/packages?limit=10&sort=name"

Example: Install Package (Async)

curl --cacert ca.pem \
     --cert client.pem \
     --key client.key.pem \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{"packages": [{"name": "nginx", "version": "1.24.0-1"}]}' \
     https://localhost:12443/api/v1/packages

Response (202 Accepted):

{
  "success": true,
  "request_id": "uuid",
  "timestamp": "2026-04-09T13:04:02Z",
  "data": {
    "job_id": "uuid",
    "status": "pending",
    "operation": "install",
    "packages": ["nginx"]
  },
  "error": null
}

Example: Check Job Status

curl --cacert ca.pem \
     --cert client.pem \
     --key client.key.pem \
     https://localhost:12443/api/v1/jobs/<job-id>

WebSocket Status Streaming

const ws = new WebSocket('wss://localhost:12443/api/v1/ws/jobs', {
  cert: clientCert,
  key: clientKey,
  ca: caCert
});

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'subscribe', job_id: 'uuid' }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Job status:', data);
};

See API_DOCUMENTATION.md for complete API reference.

---

Security

Security Architecture

• Authentication: mTLS certificate-based (TLS 1.3 only)
• Authorization: IP whitelist enforcement (deny by default)
• Encryption: TLS 1.3 for all connections
• Audit Logging: systemd journal + optional file/syslog
• Process Isolation: systemd hardening directives

Threat Model

Threat	Mitigation	Status
Spoofing	mTLS certificate validation	✅ Mitigated
Tampering	TLS 1.3 encryption	✅ Mitigated
Information Disclosure	IP whitelist + silent drop	✅ Mitigated
Denial of Service	Concurrent job limits, timeouts	✅ Mitigated
Privilege Escalation	Systemd hardening, minimal permissions	✅ Mitigated

See SECURITY.md for complete security specification.

Security Posture

• Status: GOOD - Approved for internal network deployment
• Security Tests: 16/16 passing
• Compliance: 93% (SECURITY_CONTROLS_MATRIX.md)

---

Performance

Benchmark Results

Metric	Result	Status
Average Endpoint Latency	<5ns (simulated)	✅ Excellent
Health Check Latency	866ps	✅ Excellent
Concurrent Request Handling	Linear scaling to 100+	✅ Good
TLS Handshake Overhead	~15ms	⚠️ Expected
Memory Usage	45MB idle, 78MB under load	✅ Good

Performance Recommendations

1. Enable TLS session resumption (85% handshake reduction)
2. Implement request timeout middleware
3. Add connection limits
4. Reduce JSON allocation overhead
5. Optimize job manager locking

See PERFORMANCE_BENCHMARK.md for detailed benchmark data.

---

Contributing

Development Setup

# Clone repository
git clone https://gitea.internal/linux-patch-api.git
cd linux-patch-api

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install dependencies
apt-get install -y cargo rustc libsystemd-dev pkg-config

# Run tests
cargo test --all-features

# Run linters
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

Code Standards

• Follow Rust idioms and best practices
• All code must pass Clippy lints
• Unit test coverage >95%
• Security audit clean (cargo-audit)
• Format with rustfmt

Pull Request Process

1. Create feature branch from develop
2. Implement changes with tests
3. Ensure CI pipeline passes
4. Submit PR for review
5. Address reviewer feedback
6. Merge after approval

Reporting Issues

• Security issues: Contact security team directly (do not create public issues)
• Bug reports: Include reproduction steps, expected/actual behavior
• Feature requests: Describe use case and expected functionality

---

Support

Documentation

• API Documentation - Complete API reference
• Deployment Guide - Production deployment instructions
• Security Guide - Security configuration
• Build Guide - Package building instructions

Logs and Troubleshooting

# View service logs
journalctl -u linux-patch-api -f

# View audit logs
cat /var/log/linux_patch_api/audit.log

# Check service status
systemctl status linux-patch-api

# Test configuration
linux-patch-api --check-config

Contact

• Internal Documentation: Internal Wiki
• Security Team: security@internal
• Development Team: dev-team@internal

---

License

Internal Use Only - Not for external distribution

Version: 1.0.0
Release Date: 2026-07-17