opnsense-admin

通过 API 和 SSH 管理 OPNsense 防火墙、DNS、IDS/IPS 和网络配置。在管理 OPNsense 防火墙、配置 Suricata IDS/IPS、管理未绑定 DNS、创建防火墙规则、备份配置、监控流量或排除网络问题时使用。支持 OPNsense 26.1+ 基于 API 的自动化和 SSH 命令执行。

## 概述（中文）

通过 API 和 SSH 管理 OPNsense 防火墙、DNS、IDS/IPS 和网络配置。在管理 OPNsense 防火墙、配置 Suricata IDS/IPS、管理未绑定 DNS、创建防火墙规则、备份配置、监控流量或排除网络问题时使用。支持 OPNsense 26.1+ 基于 API 的自动化和 SSH 命令执行。

## 原文

# OPNsense Admin

> ⚠️ **DISCLAIMER**
>
> This tool grants **HIGH PRIVILEGE** access to your firewall and network.
> It can modify firewall rules, block traffic, and restart critical services.
>
> **By using this skill, you declare that:**
> - You are a responsible adult
> - You have authorization to administer this firewall
> - You understand that a mistake can render your network inoperable
> - You will use this tool ethically and legally
>
> **The author is not responsible** for misconfigurations, access lockouts,
> or damages resulting from the use of this skill.

Complete OPNsense firewall administration via API and SSH. Automate backups, monitor security, manage services, and troubleshoot network issues.

## Features

- 🔥 **Firewall Management** - Rules, NAT, aliases, and diagnostics
- 🛡️ **IDS/IPS (Suricata)** - Monitor and manage intrusion detection/prevention
- 🌐 **DNS (Unbound)** - DNS resolver, blocklists, forwarding, DNS over TLS
- 📊 **Monitoring** - Service status, traffic analysis, system health
- 💾 **Automated Backups** - Scheduled configuration backups with retention
- 🔧 **Service Control** - Start/stop/restart services via SSH
- 🔌 **API Integration** - RESTful API wrapper for automation

## Installation

### Prerequisites

- OPNsense 26.1 or later
- API key with appropriate permissions
- SSH access (optional, for service management)

### Quick Setup

1. Generate API credentials in OPNsense:
   ```
   System → Access → Users → API
   ```

2. Configure credentials (choose one method):

   **Option A: Environment variables**
   ```bash
   export OPNSENSE_HOST="192.168.1.1"
   export OPNSENSE_KEY="your_api_key"
   export OPNSENSE_SECRET="your_api_secret"
   ```

   **Option B: Credentials file** (recommended)
   ```bash
   mkdir -p ~/.opnsense
   cat > ~/.opnsense/credentials << EOF
   OPNSENSE_HOST=192.168.1.1
   OPNSENSE_PORT=443
   OPNSENSE_KEY=your_api_key
   OPNSENSE_SECRET=your_api_secret
   EOF
   chmod 600 ~/.opnsense/credentials
   ```

## Usage

### API Helper Script

```bash
# Check system status
./scripts/opnsense-api.sh status

# Get firmware information
./scripts/opnsense-api.sh firmware-status

# Check Suricata status
./scripts/opnsense-api.sh suricata-status

# Custom API request
./scripts/opnsense-api.sh get /api/core/system/status
./scripts/opnsense-api.sh post /api/core/firmware/update '{"upgrade":true}'
```

### Configuration Backup

```bash
# Full backup (with RRD data)
./scripts/backup-config.sh

# Config-only backup (smaller)
./scripts/backup-config.sh --config-only

# Custom directory and retention
./scripts/backup-config.sh --dir /mnt/backups --keep 90
```

### Service Control

```bash
# Restart DNS resolver
./scripts/service-control.sh unbound restart

# Check Suricata status
./scripts/service-control.sh suricata status

# Reload DHCP configuration
./scripts/service-control.sh dhcpd reload

# Check all services
./scripts/service-control.sh all status
```

## Configuration Reference

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `OPNSENSE_HOST` | `192.168.1.1` | OPNsense IP or hostname |
| `OPNSENSE_PORT` | `443` | HTTPS port |
| `OPNSENSE_KEY` | - | API key |
| `OPNSENSE_SECRET` | - | API secret |
| `SSH_PORT` | `22` | SSH port for service control |
| `BACKUP_DIR` | `./backups` | Default backup directory |
| `KEEP_DAYS` | `30` | Backup retention period |

### Common API Endpoints

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/core/system/status` | GET | System health |
| `/api/core/firmware/status` | GET | Firmware info |
| `/api/ids/service/status` | GET | Suricata status |
| `/api/unbound/diagnostics/stats` | GET | DNS statistics |
| `/api/diagnostics/interface/getInterfaceConfig` | GET | Interface config |
| `/api/diagnostics/firewall/pfstatists` | GET | Firewall stats |
| `/api/core/backup/backup` | GET | Download backup |

## Security Best Practices

1. **SSL Certificate Validation** - Enabled by default. Use `--insecure` or `OPNSENSE_INSECURE=true` ONLY for development or self-signed certificates in internal networks
2. **Restrict API permissions** - Create dedicated API users with minimal required permissions
3. **Secure credential storage** - Use file permissions (600) and environment variables
4. **Backup before changes** - Always backup configuration before making changes
5. **Test IDS rules first** - Run Suricata in IDS mode before enabling IPS blocking

### SSL/TLS Configuration

By default, all API calls validate SSL certificates. For production deployments with valid certificates, no changes needed.

For development or self-signed certificates:
```bash
# Option 1: Command line flag
./scripts/opnsense-api.sh --insecure status

# Option 2: Environment variable
export OPNSENSE_INSECURE=true
./scripts/opnsense-api.sh status
```

## Key Concepts

### Firewall Rules

- **Stateful filtering** - Connection tracking enabled by default
- **Processing order**: Floating → Interface Groups → Interface Rules
- **Actions**: Pass (allow), Block (drop silently), Reject (drop with notice)
- **NAT**: Processed BEFORE filter rules

### Suricata IDS/IPS

- **IDS Mode**: Detection only (alerts, no blocking)
- **IPS Mode**: Detection + blocking (requires inline setup)
- **Best Practice**: Monitor on LAN interface to see real client IPs
- **Rules**: Emerging Threats, Abuse.ch feeds, app detection

### Unbound DNS

- **Recursive resolver** - Queries root servers directly by default
- **DNSSEC validation** - Enabled by default for security
- **Blocklists** - DNS-based ad/tracker blocking via plugin
- **DNS over TLS** - Encrypted upstream queries

## Troubleshooting

### API Connection Issues

```bash
# Test connectivity
curl -k -u "key:secret" https://opnsense/api/core/system/status

# Check API is enabled in OPNsense
# System → Access → Settings → Enable API
```

### SSH Connection Issues

```bash
# Test SSH connectivity
ssh -p 22 root@opnsense "echo OK"

# Check SSH is enabled
# System → Administration → Secure Shell
```

### Permission Denied

- Verify API key has required permissions
- Check user is member of appropriate groups
- Ensure API is enabled in System → Access → Settings

## Version Compatibility

| OPNsense Version | Skill Version | Status |
|------------------|---------------|--------|
| 26.1+ | 1.x | ✅ Supported |
| 25.x | 1.x | ⚠️ May work |
| 24.x | 1.x | ❌ Not tested |

## Reference Documentation

- [API Guide](references/api-guide.md) - Complete API authentication guide
- [Firewall Rules](references/firewall-rules.md) - Rule structure and examples
- [Suricata IPS](references/suricata-ips.md) - IDS/IPS configuration
- [Unbound DNS](references/unbound-dns.md) - DNS resolver setup
- [Quick Reference](references/quick-ref.md) - Commands and file locations

## License

MIT - See LICENSE file for details.

## Contributing

Issues and pull requests welcome at the GitHub repository.

---

**Disclaimer**: This is an unofficial skill. Not affiliated with Deciso B.V. or the OPNsense project.

---

## 中文说明

# OPNsense Admin

> ⚠️ **免责声明**
>
> 此工具授予对你的防火墙和网络的**高权限**访问。
> 它可以修改防火墙规则、阻止流量并重启关键服务。
>
> **使用此技能即表示你声明：**
> - 你是一名负责任的成年人
> - 你已获得管理此防火墙的授权
> - 你理解一个错误可能导致你的网络无法运行
> - 你将以合乎道德和合法的方式使用此工具
>
> **作者不对**因使用此技能造成的配置错误、访问锁定或损害**承担责任**。

通过 API 和 SSH 完整管理 OPNsense 防火墙。自动化备份、监控安全、管理服务并排除网络问题。

## 功能特性

- 🔥 **防火墙管理** - 规则、NAT、别名和诊断
- 🛡️ **IDS/IPS（Suricata）** - 监控和管理入侵检测/防御
- 🌐 **DNS（Unbound）** - DNS 解析器、屏蔽列表、转发、DNS over TLS
- 📊 **监控** - 服务状态、流量分析、系统健康
- 💾 **自动备份** - 带保留策略的定时配置备份
- 🔧 **服务控制** - 通过 SSH 启动/停止/重启服务
- 🔌 **API 集成** - 用于自动化的 RESTful API 封装

## 安装

### 前置条件

- OPNsense 26.1 或更高版本
- 具有适当权限的 API 密钥
- SSH 访问（可选，用于服务管理）

### 快速设置

1. 在 OPNsense 中生成 API 凭据：
   ```
   System → Access → Users → API
   ```

2. 配置凭据（选择一种方式）：

   **方式 A：环境变量**