linux_patch_api/SECURITY.md

Linux_Patch_API - Security Specification Document

Security Overview

Philosophy: Defense in depth with zero-trust principles for internal network.

Approach:

• mTLS certificate-based authentication (required for all connections)
• IP whitelist enforcement (deny by default, allow only listed)
• Comprehensive audit logging for all operations
• Systemd hardening and process isolation
• Minimal attack surface (internal network only)

---

Threat Model

Threat Actor Profile

Attribute	Description
Origin	Internal network only
Skill Level	Moderate to High
Resources	Limited (not nation-state)
Motivation	Unauthorized system access, privilege escalation
Access	Must bypass mTLS + IP whitelist

STRIDE Threat Analysis

Threat Category	Potential Threat	Mitigation	Status
Spoofing	Attacker impersonates valid client	mTLS certificate validation, unique certs per client	✅ Mitigated
Spoofing	Attacker uses expired/revoked cert	Certificate expiry validation (1-year max)	✅ Mitigated
Tampering	API requests modified in transit	TLS 1.3 encryption	✅ Mitigated
Tampering	Config files modified unauthorized	File permissions (600/644), config validation before reload	✅ Mitigated
Repudiation	Client denies making request	Audit logging with request_id, client cert ID	✅ Mitigated
Repudiation	Server denies response	Comprehensive audit trail (systemd journal)	✅ Mitigated
Information Disclosure	Package/data info leaked to unauthorized	Silent drop for non-mTLS, IP whitelist	✅ Mitigated
Information Disclosure	Error messages leak system info	Detailed errors only for authenticated clients	✅ Mitigated
Denial of Service	Resource exhaustion via many requests	Internal network only, IP whitelist limits exposure	⚠️ Partial
Denial of Service	Job queue flooding	Configurable concurrent job limit (default: 5)	✅ Mitigated
Denial of Service	Long-running job starvation	30-minute job timeout enforcement	✅ Mitigated
Elevation of Privilege	Unauthorized package installation	Root required, but mTLS + IP whitelist required	✅ Mitigated
Elevation of Privilege	Subprocess escape	SystemCallFilter, ProtectSystem=strict	✅ Mitigated

Attack Vectors & Mitigations

Attack Vector	Likelihood	Impact	Mitigation
Network interception	Low	Critical	TLS 1.3 only, mTLS required
Certificate theft	Medium	Critical	Cert permissions (600), internal CA only
IP spoofing	Low	High	IP whitelist + mTLS (both required)
Config file tampering	Medium	High	File permissions, validation before reload
Package manager injection	Low	Critical	Pluggable backend with input validation
Job manipulation	Low	High	Job storage isolation, exclusive rollback mode
Log tampering	Medium	High	systemd journal (immutable), optional remote syslog

---

Authentication & Authorization

Authentication Requirements

• Method: mTLS certificate-based authentication
• Certificate Type: Unique client certificate per client (1-year validity)
• CA: Internal self-hosted Certificate Authority
• TLS Version: TLS 1.3 only
• Multi-factor: Certificate + IP whitelist (dual requirement)
• Session Management: Stateless (no sessions)

Authorization Model

• Model: Binary authorization (all-or-nothing)
• Permission Levels: Single level (full access if authenticated)
• Requirements:
  • Valid mTLS certificate (not expired, signed by internal CA)
  • Source IP in whitelist (YAML config, instant apply)
• No RBAC: All authenticated clients have full API access

---

Data Security

Encryption at Rest

• Certificates: File permissions 600 for private keys
• Job Storage: /var/lib/linux_patch_api/jobs/ (cleared on restart)
• Config Files: /etc/linux_patch_api/ (644 for config, 600 for keys)
• Audit Logs: systemd journal (immutable by default)

Encryption in Transit

• Protocol: TLS 1.3 only
• Port: 12443
• Cipher Suites: TLS 1.3 default (no legacy cipher support)
• Certificate Validation: Mutual TLS (server + client cert required)

Key Management

• CA Private Key: Stored securely on CA host only
• Server Certificates: /etc/linux_patch_api/certs/server.key (600)
• Client Certificates: Distributed manually to authorized clients
• Rotation: 1-year certificate expiry, manual renewal process
• Revocation: Not implemented (rely on expiry + physical cert retrieval)

---

API Security

Input Validation

• Package Names: Alphanumeric + standard package chars only
• Versions: Semantic versioning validation
• IP Addresses: IPv4 + CIDR validation for whitelist
• JSON Schema: Strict schema validation for all request bodies
• Path Traversal: Blocked (no .. in paths)

Rate Limiting

• Not Required: Internal network only with strict IP whitelist
• Job Concurrency: Configurable limit (default: 5 concurrent jobs)
• Job Timeout: 30-minute maximum per job

CORS Policy

• Not Applicable: API is not browser-accessible
• Origin: mTLS clients only (no browser CORS concerns)

---

Audit & Logging

Security Events to Log

• All API requests (endpoint, method, timestamp, client cert ID, source IP)
• Authentication events (success/failure, cert validation result)
• Authorization events (IP whitelist match/failure)
• Package operations (package name, version, action, result)
• Configuration changes (config reload, whitelist updates)
• Job lifecycle events (create, start, complete, fail, timeout, rollback)
• Service events (start, stop, restart, config validation failures)

Log Protection

• Primary Storage: systemd journal (immutable, access-controlled)
• Secondary Storage: Optional remote syslog
• Fallback: Local file /var/log/linux_patch_api/audit.log (640)
• Retention: 30 days with daily rotation and compression
• Access: Root only, audit group read access
• Integrity: systemd journal provides tamper evidence

---

Compliance Requirements

• Internal Standards: Follows organizational security policies
• No External Compliance: Not designed for PCI-DSS, HIPAA, SOC2 (can be extended)
• Audit Trail: Comprehensive logging supports internal audit requirements
• Access Control: mTLS + IP whitelist provides strong access control

---

Security Testing

Penetration Testing

• Schedule: Required before production deployment
• Scope:
  • mTLS authentication bypass attempts
  • IP whitelist enforcement testing
  • API endpoint fuzzing
  • Certificate validation testing
  • Config file tampering attempts
  • Privilege escalation attempts
• Tester: Internal security team or external contractor
• Frequency: Annual or after major changes

Vulnerability Management

• Dependency Scanning: Rust crate security advisories monitored
• System Patches: Host system patched via API itself (dogfooding)
• Certificate Updates: Annual renewal process
• Config Audits: Quarterly review of whitelist and security settings
• Incident Response: Log analysis for security event investigation

---

Following kiro spec-driven development standards Following kiro spec-driven development standards