erkanrzgc/firewall

## 概述 Firewall 正在重建为一个原生、策略驱动的主机安全系统，具有明确的权限边界，且不依赖于逐包（packet-by-packet）的 userspace。 当前的基础提供： - **类型化策略** — 严格的 YAML/JSON 解析、稳定的规则 ID、capability 验证、确定性哈希、diff 和 shadow 分析。 - **可审计状态** — SQLite WAL 修订、compare-and-swap 更新、幂等键、确认期限和回滚状态。 - **网络可见性** — TCP/UDP socket 清单、有界 TCP connect 扫描，以及仅限元数据的 Linux packet 观察。 - **本地管理** — CLI 优先的工作流，以及带有一次性 bootstrap token 的可选仅限 loopback 的 Web 控制台。 - **真实的 capability 报告** — 不支持的平台语义将导致验证失败，而不是被静默削弱。 审计后端在原生的后端存在之前，会拒绝 `additive` 和 `authoritative` 强制模式。Packet 元数据尚未与策略规则相关联，也未自动转换为允许建议。 ## 功能 | 功能 | Linux | Windows | 备注 | |---|:---:|:---:|---| | YAML/JSON 策略验证 | 可用 | 可用 | 严格的 schema 和 capability 检查 | | 确定性计划和 shadow 分析 | 可用 | 可用 | 稳定的规范哈希和 diff | | 修订和审计存储 | 可用 | 可用 | 具有有限保留策略的 SQLite WAL | | 确认超时和回滚状态 | 可用 | 可用 | 修订状态；尚无内核强制执行 | | TCP/UDP socket 清单 | 可用 | — | Linux `/proc` 实现 | | Packet 元数据观察 | 可用 | — | 需要 root 或 `CAP_NET_RAW`；不捕获 payload | | 有界 TCP connect 扫描 | 可用 | 可用 | 一个目标，最多 1,024 个端口 | | 本地 Web 控制台 | 可用 | 可用 | 审计模式；仅限 loopback 且为可选 | | nftables 强制执行 | 计划中 | 不适用 | 原生 Linux 后端 | | WFP 强制执行 | 不适用 | 计划中 | 原生 Windows 后端 | | eBPF 和 Kubernetes 集成 | 计划中 | 计划中 | 基础工作完成后的任务 | ## 快速开始 ### 构建 需要受支持的 Go 1.25+ 工具链；推荐使用 Go 1.26.5。 ``` go test ./... go build -o bin/firewall-cli ./cmd/firewall-cli go build -o bin/firewall-agent ./cmd/firewall-agent go build -o bin/firewall-enforcer ./cmd/firewall-enforcer go build -o bin/firewall-web ./cmd/firewall-web ``` ### 创建和检查策略 从一个安全的审计策略开始： ``` bin/firewall-cli policy init \ --profile workstation \ --name my-host > policy.yaml bin/firewall-cli policy validate policy.yaml bin/firewall-cli policy plan policy.yaml ``` Apply 会创建一个待定的修订。请在期限之前使用返回的 token 进行确认： ``` bin/firewall-cli policy apply \ --expected-revision 0 \ --idempotency-key first-audit \ --confirm-timeout 120s \ policy.yaml bin/firewall-cli policy confirm CONFIRMATION_TOKEN ``` 针对同一个状态数据库运行 `firewall-agent`，以持续协调已过期的待定 apply。如果没有该 agent，下一次 `status` 命令将执行相同的协调。 ### CLI 指南 | 命令 | 用途 | |---|---| | `doctor` | 检查本地 runtime 和依赖项 | | `status` | 显示策略和修订状态 | | `capabilities` | 报告可用的平台功能 | | `policy init\|validate\|plan` | 创建和检查类型化策略 | | `policy apply\|confirm\|rollback\|export` | 安全地管理策略修订 | | `events tail` | 读取有限的审计事件 | | `inspect ports` | 清点本地 TCP/UDP socket | | `inspect packets` | 观察 Linux packet 元数据 | | `scan` | 运行有界 TCP connect 扫描 | | `ui` | 启动可选的本地控制台 | 读取命令支持 `--output table|json|yaml`。使用 `--state PATH` 选择 SQLite 数据库；否则将使用平台的本地状态目录。 ## 网络可见性 ### 本地端口 ``` bin/firewall-cli inspect ports --listening --processes ``` ### Packet 元数据 Linux packet 观察仅记录 headers 和元数据。不保留或打印 packet payload。 ``` sudo bin/firewall-cli inspect packets \ --interface eth0 \ --count 100 \ --duration 30s ``` ### 有界端口扫描 ``` bin/firewall-cli scan \ --target 192.0.2.10 \ --ports 22,80,443,8000-8010 ``` 扫描被刻意限制为一个主机名或 IP，1,024 个端口，128 个并发连接，以及每个端口最长五秒的超时时间。UDP socket 清单可用，但不支持主动 UDP 扫描。 ## 本地 Web 控制台 Web 控制台在显式启动之前处于禁用状态： ``` bin/firewall-cli ui --binary bin/firewall-web ``` 它绑定到一个随机的 `127.0.0.1` 端口，并生成一个一次性 bootstrap URL。 服务器使用 HttpOnly/SameSite cookie、CSRF 防护、严格的内容安全策略、有界的正文和请求，并且没有 CDN 资源或远程监听器。 ## 策略模型和 API | 资源 | 描述 | |---|---| | [`examples/workstation-audit.yaml`](examples/workstation-audit.yaml) | 安全的工作站审计示例 | | [`schema/policy-v1.schema.json`](schema/policy-v1.schema.json) | 策略 v1 JSON Schema | | [`api/v1/firewall.proto`](api/v1/firewall.proto) | 预期的本地 gRPC v1 合约 | | [`docs/threat-model.md`](docs/threat-model.md) | 信任边界和安全假设 | | [`docs/roadmap.md`](docs/roadmap.md) | 交付阶段和平台方向 | 规则涵盖方向、动作、IPv4/IPv6、TCP/UDP/ICMP、CIDR、端口范围、接口、conntrack 状态、日志记录、速率限制，以及声明的 Linux/Windows 工作负载身份。 Protobuf 合约记录了预期的本地 API。尚未提供生成的 stub、Unix socket/命名管道授权以及 gRPC 服务器。没有远程 TCP API。

稳定的 CLI 退出代码

| 代码 | 含义 | |---:|---| | 0 | 成功 | | 2 | 输入无效或命令使用不当 | | 3 | 策略验证失败 | | 4 | 修订冲突 | | 5 | Capability 或状态不可用 | | 6 | 权限被拒绝 | | 10 | 内部或 runtime 错误 |

## 安全模型 控制平面将策略文件、本地 API 请求、遥测生产者和内核状态视为不受信任的输入。其设计核心在于： - 严格的 schema 和明确的 capability 失败； - compare-and-swap 修订和幂等操作； - 默认 120 秒的确认期限； - 无 payload、有界的观察和审计通道； - 非特权的控制/Web 平面和狭窄的类型化执行器边界； - 仅拥有项目特定的内核对象。 Root 妥协、恶意内核模块、固件攻击、远程集群管理、TLS 拦截、网关/NAT 使用以及自定义 Windows 内核 callout 不在当前范围内。 请按照 [SECURITY.md](SECURITY.md) 中的说明私下报告漏洞。 ## 路线图 计划中的 Linux 后端将拥有一个专用的 `inet` nftables 表，应用原子批次，在内核中保留最后已知良好状态，并保持 firewalld/UFW 和外部的 nftables 对象不受影响。 计划中的 Windows 后端将使用专用的 WFP 提供程序和带有持久 ALE 过滤器的 sublayer。它不会禁用 Windows Defender Firewall。 可选的 eBPF 工作将侧重于 XDP 早期丢弃、tc 遥测和 cgroup 工作负载身份；它不会取代有状态防火墙。Kubernetes 适配器和可链接策略元插件工作将在原生主机后端之后进行。 有关分阶段计划，请参阅[项目路线图](docs/roadmap.md)。 ### 域名过滤限制 将域名解析为 IP 地址并不等同于可靠地阻止网站。DoH、DoQ、共享主机/CDN、不断变化的 DNS 答案和 ECH 使得这种声明不安全。未来可能会提供具有明确限制的基于 TTL 的 A/AAAA 集合模块；TLS 拦截不在范围内。 ## 贡献 在提交更改之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。本项目遵循 [Contributor Covenant](CODE_OF_CONDUCT.md)。 如果该项目对您有用，可以通过 [Ko-fi](https://ko-fi.com/erkanrzgc) 支持开发。 ## 许可证 [MIT](LICENSE) © erkanrzgc

标签：Docker镜像, EVTX分析, Golang, 主机防火墙, 子域名枚举, 安全编程, 日志审计, 系统安全, 网络访问控制