• Reporting Vulnerabilities
• Coordinated Disclosure
• Security Design Philosophy
• Input Validation Architecture
• Subprocess Security
• Log Sanitization
• File System Security
• Cryptographic Operations
• Process Security
• Compound Action Security
• CWE Coverage
• Threat Model
• Security Testing
• Supported Versions
• Known Limitations

DO NOT report security vulnerabilities through public GitHub issues.

To report a vulnerability, please email the maintainers directly or use GitHub's private vulnerability reporting feature. Include:

1. Description of the vulnerability
2. Steps to reproduce
3. Affected version(s)
4. Potential impact assessment
5. Suggested fix (if any)

We will acknowledge receipt within 48 hours and provide an initial assessment within 7 days.

We follow a coordinated disclosure process:

1. Reporter notifies maintainers privately
2. Maintainers assess severity and develop a fix
3. Fix is released with a security advisory
4. Public disclosure after patch availability (minimum 14-day embargo)

Contributors who discover vulnerabilities are expected to follow this process. Public disclosure before a fix is available may constitute a violation of the project License.

Apotropaios operates at the most sensitive layer of system infrastructure -- the network firewall. The framework runs as root, modifies kernel-level packet filtering rules, and manages configuration that determines what traffic enters and exits the system. Every design decision prioritizes security:

1. Defense-in-depth: Multiple independent security controls at every layer. Input is validated, then sanitized, then passed as list-form arguments. Even if one layer fails, the next catches the problem.
2. Whitelist over blacklist: All 27 validators define what IS allowed, not what isn't. A new attack vector doesn't bypass whitelist validation.
3. Fail-closed: Invalid input is rejected. Unknown backends are rejected. Unrecognized commands are rejected. The default is denial.
4. Least privilege in design: Files are 0o600, directories 0o700, umask 0o077. Even though the framework runs as root, it minimizes the accessibility of its own data.
5. Zero external dependencies: The runtime uses only the Python 3.12+ standard library. No pip packages, no supply chain risk.

Every parameter entering the framework passes through at least one validator in core/validation.py (1,256 lines). Validators are pure functions that raise ValidationError on invalid input -- they never return boolean.

sanitize_input() applies defense-in-depth to all user input:

1. Rejects None/non-string input (raises SanitizationError)
2. Strips whitespace with str.strip()
3. Removes HTML tags with regex: <[^>]*> → empty string (prevents stored XSS)
4. Applies whitelist regex [^a-zA-Z0-9 .,_:/+=@~%-] -- removes any character not in this set
5. Truncates to Security.MAX_INPUT_LENGTH (4096 chars)
6. Returns the cleaned string

_contains_shell_meta(value) tests input against SHELL_METACHARACTERS frozenset containing: ;|&$(){}\<>!#`. Uses frozenset intersection for O(1) per-character lookup.

All subprocess calls use list-form arguments -- never shell=True. This is the single most important security control in the framework.

# CORRECT -- list-form, no shell interpretation
subprocess.run(["iptables", "-A", "INPUT", "-p", "tcp", "--dport", port, "-j", "ACCEPT"],
               capture_output=True, text=True, timeout=30)

# FORBIDDEN -- shell=True enables injection
subprocess.run(f"iptables -A INPUT -p tcp --dport {port} -j ACCEPT", shell=True)

Every subprocess call also:

• Captures stderr with capture_output=True for error diagnosis
• Sets timeout=30 seconds to prevent hanging (configurable via Performance.SUBPROCESS_TIMEOUT)
• Uses text=True for string (not bytes) output

The make security-scan target verifies no shell=True, eval(), exec(), or pickle usage exists in the codebase on every build.

LogSanitizer in core/logging.py intercepts all log messages before they reach any handler. Four compiled regex patterns mask different credential formats:

Sensitive field names (11): password, passwd, secret, token, key, api_key, apikey, access_token, auth, authorization, credential, private_key, api_secret, client_secret.

Control character stripping: Bytes 0x00-0x08 and 0x0E-0x1F are removed from all log messages to prevent log injection attacks where binary control sequences could manipulate terminal display or corrupt log parsing (CWE-117).

Compound actions (e.g., log,drop) are parsed by validate_rule_action():

1. Action string is split on commas only
2. Each component validated against ALL_ACTIONS frozenset
3. Terminal/non-terminal classification applied
4. Double-terminal detection rejects invalid combinations (accept,drop)
5. Backend-specific translation: iptables creates separate rules, nftables uses single expression

Why this matters: If compound action parsing were insecure, an attacker could craft an action string that creates unintended rules or bypasses the intended terminal action.

The security test suite (tests/security/test_injection.py, 15 tests) covers:

The make security-scan target also performs 6 static pattern checks:

1. No shell=True in subprocess calls
2. No eval() usage
3. No exec() usage
4. No pickle/marshal usage (deserialization attacks)
5. No hardcoded credentials
6. No TODO/FIXME markers (incomplete code)

1. Firewall rules -- Kernel-level packet filtering determining network access
2. Rule index -- Persistent tracking of all managed rules
3. Backup archives -- Historical firewall configurations
4. Log files -- Audit trail of all operations

1. Untrusted input -- Malicious parameters passed via CLI or import files
2. Compromised import files -- Tampered rule configurations
3. Local privilege escalation -- Non-root user attempting to modify firewall rules
4. Log manipulation -- Injection of misleading log entries

# Run security test suite (15 CWE-mapped tests)
make test-security

# Run static security scan (6 pattern checks)
make security-scan

# Run individual security tests
make test-injection

# Run all quality gates (includes security)
make test-all

1. Python GC and sensitive memory: Python's garbage collector does not guarantee timely scrubbing of sensitive memory. scrub_sensitive_values() is best-effort -- the GC may have already copied string objects.

2. Log rotation: Built-in rotation triggers at 100MB per file with 10 retained. High-traffic environments should use external log rotation (logrotate).

3. Container environments: Kernel modules (ip_tables, nf_tables) are required for firewall operations. Containers may lack these. Use --cap-add=NET_ADMIN with Docker.

4. Cross-process locking: Rule index uses thread-safe threading.Lock but does not implement cross-process file locking for the index file itself. Concurrent processes modifying rules may race.

5. TTL precision: The ExpiryMonitor checks every 30 seconds. A temporary rule may remain active up to 30 seconds past its nominal TTL.

6. IPv6 validation: IPv6 validation uses a simplified regex pattern. Exotic edge cases (embedded IPv4, zone IDs) may not be fully validated.

7. No TLS/encryption: Log files and data files are protected by filesystem permissions only. No at-rest encryption is provided.