Frequently Asked Questions (FAQ)

Frequently Asked Questions

General

Q: What does "Apotropaios" mean? A: From Greek ἀποτρόπαιος -- "averting evil." Ancient Greek apotropaic objects warded off evil spirits. The name reflects defending systems against malicious network traffic.

Q: What firewalls are supported? A: Five backends: iptables, nftables, firewalld, UFW, and ipset. Each has a full implementation with 12 operations.

Q: What Linux distributions are supported? A: Ubuntu 22.04/24.04, Debian 11/12, Kali Linux 2024+, Rocky Linux 8/9, AlmaLinux 8/9, Arch Linux (rolling). Derivatives supported via ID_LIKE.

Q: Does it require external packages? A: No. Runtime is stdlib-only -- zero pip dependencies. pytest and mypy are optional for development.

Q: Does it replace my firewall? A: No. Apotropaios is a management layer on top of native firewall tools. It creates and tracks rules through iptables/nft/firewall-cmd/ufw/ipset.

Q: What is the difference between bash and Python variants? A: The bash variant is the reference implementation at v1.1.10. The Python variant targets 100% feature parity with strict typing (mypy --strict), a 5-layer architecture, and 322 tests. Same features, same rule format, same CLI commands.

Installation

Q: Do I need to install it? A: No. Run directly: sudo python3 apotropaios.py detect. No pip install or venv required.

Q: pip or pip3? A: Always pip3 for Python 3.x projects (Lesson PY-005).

Q: Can I run in Docker? A: Yes, with --cap-add=NET_ADMIN --privileged and netfilter kernel modules loaded.

Q: Why Python 3.12+? A: Uses X | None union syntax, dict[str, str] generics, StrEnum, and other features requiring 3.12+.

Usage

Q: How do I see verbose output? A: --log-level info for informational, --log-level debug for diagnostic, --log-level trace for maximum. Default is warning.

Q: What is "status" vs "system-rules" vs "list-rules"? A: status = service state (running/enabled/version). system-rules = ALL native rules. list-rules = only Apotropaios-tracked rules.

Q: Can --log-level go after the command? A: Yes. Global options are position-independent: detect --log-level info works.

Rules

Q: What are compound actions? A: log,drop combines non-terminal (LOG) with terminal (DROP). Backend-specific: iptables = 2 rules, nftables = 1 expression, firewalld = rich rule.

Q: Can I combine accept and drop? A: No. Double-terminal combinations are rejected. Use log,drop or log,accept.

Q: What are temporary rules? A: Rules with TTL (60s to 30 days) that auto-expire. ExpiryMonitor daemon runs in interactive mode.

Q: How are rules tracked across reboots? A: UUID + pipe-delimited index file persists on disk. Backend persistence depends on native mechanisms.

Q: What connection tracking states exist? A: new, established, related, invalid, untracked. Comma-separated: --conn-state new,established.

Security

Q: Is it safe for production? A: 322 tests + mypy --strict and multiple internal audit passes, but no independent third-party audit.

Q: How does it prevent injection? A: Three layers: (1) 27 whitelist validators, (2) sanitize_input() defense-in-depth, (3) list-form subprocess (never shell=True).

Q: Are passwords logged? A: No. 4-family LogSanitizer masks passwords/tokens/keys/auth headers in all formats.

Backup

Q: What does a backup contain? A: tar.gz with per-backend config exports, rule index, rule state, JSON manifest, SHA-256 sidecar.

Q: What are immutable snapshots? A: Backups protected with chattr +i -- cannot be modified even by root without chattr -i.

Q: How many backups are retained? A: 20 by default. Oldest pruned automatically.

Development

Q: How do I run tests? A: make check (mypy + 322 tests), make test-quick (unit only), make test-report (per-file).

Q: What is mypy --strict? A: Most rigorous static type checking: no Any, no untyped signatures, no missing return types. Zero errors required.

Q: How do I add a new backend? A: Subclass FirewallBackend, implement 12 methods, register, add detection, import in cli.py, add tests. See Development Guide.

Q: What does Ctrl+C do?

A: In the menu, it aborts the current operation or prompt and returns to the menu (Install & Update recovers in place); it never exits the application. Headless CLI: cleanup, exit 130. Package operations cannot block on hidden prompts and time out at 300 seconds.