docs: update Netgrimoire/Network/Security/OPnSense_IDS

Netgrimoire/Network/Security/OPnSense_IDS.md

@@ -0,0 +1,212 @@
+---
+title: OpnSense-IDS/IPS
+description: IDS
+published: true
+date: 2026-02-23T21:51:41.041Z
+tags: 
+editor: markdown
+dateCreated: 2026-02-23T21:49:16.861Z
+---
+
+# Suricata IDS/IPS
+
+**Service:** Suricata Intrusion Detection & Prevention System
+**Host:** OPNsense firewall
+**Interfaces:** ATT (opt1) — add WAN (igc0) while still active
+**Mode:** IPS (inline blocking)
+**Rulesets:** ET Open, Feodo Tracker, Abuse.ch SSL
+
+---
+
+## Overview
+
+Suricata is OPNsense's built-in deep packet inspection engine. Unlike CrowdSec (which blocks based on IP reputation) and GeoIP (which blocks by country), Suricata inspects the **content** of traffic — detecting exploit patterns, malware C2 communication, vulnerability scans, and known CVE exploitation attempts in real time.
+
+The two systems complement each other and do not overlap:
+
+| Layer | Tool | What It Stops |
+|---|---|---|
+| IP reputation | CrowdSec | Known bad IPs from community threat intel |
+| Geography | GeoIP | Traffic from blocked countries |
+| Content inspection | Suricata | Malicious payloads, exploit patterns, C2 traffic |
+
+Suricata uses **Netmap** for high-performance inline packet processing with minimal CPU overhead.
+
+> ⚠ **Before enabling IPS mode:** Disable hardware offloading on your interfaces or Netmap will not function correctly. This is done in **Interfaces → Settings**.
+
+---
+
+## Pre-requisite: Disable Hardware Offloading
+
+1. Go to **Interfaces → Settings**
+2. Disable the following options:
+   - Hardware CRC
+   - Hardware TSO
+   - Hardware LRO
+   - VLAN Hardware Filtering
+3. Click **Save**
+4. Reboot the firewall
+
+> ✓ This is a one-time change. It has no meaningful impact on performance for home/small business use and is required for Suricata IPS mode to function.
+
+---
+
+## Installation
+
+Suricata is built into OPNsense — no plugin install required. Navigate directly to:
+
+**Services → Intrusion Detection → Administration**
+
+---
+
+## Configuration
+
+### Step 1 — General Settings
+
+Navigate to **Services → Intrusion Detection → Administration**
+
+| Setting | Value | Notes |
+|---|---|---|
+| Enabled | ✓ | Turns on the IDS/IPS engine |
+| IPS Mode | ✓ | Enables inline blocking (not just alerting) |
+| Promiscuous Mode | Leave default | Only needed for mirrored traffic setups |
+| Default Packet Size | Leave default | Auto-detected |
+| Interfaces | ATT, WAN | Add both while dual-WAN is active; remove WAN after migration |
+| Home Networks | 192.168.3.0/24, 192.168.5.0/24, 192.168.32.0/24 | Your internal subnets — critical for rule accuracy |
+| Log Level | Info | |
+| Log Retention | 7 days | Adjust based on disk space |
+
+> ⚠ **Home Networks is critical.** Suricata rules use `$HOME_NET` and `$EXTERNAL_NET` to determine direction. If your internal subnets are not listed here, many rules will fail to trigger correctly or will produce false positives.
+
+Click **Apply** after setting these values.
+
+### Step 2 — Download Rulesets
+
+Navigate to **Services → Intrusion Detection → Download**
+
+Enable the following rulesets:
+
+| Ruleset | Provider | Priority | Notes |
+|---|---|---|---|
+| ET Open | Proofpoint Emerging Threats | 🔴 Essential | Comprehensive free ruleset — 40,000+ rules covering exploits, malware, scanning, C2 |
+| Abuse.ch SSL Blacklist | Abuse.ch | 🔴 Essential | Blocks connections to malicious SSL certificates used by malware |
+| Feodo Tracker Botnet | Abuse.ch | 🔴 Essential | Blocks botnet C2 IP communication |
+| OSIF | OPNsense | 🟡 Recommended | OPNsense internal feed |
+| PT Research | Positive Technologies | 🟡 Recommended | Additional threat intelligence |
+
+To enable each ruleset:
+1. Find it in the list
+2. Toggle the **Enabled** switch
+3. Click **Download & Update Rules** at the top of the page
+
+> ✓ ET Open is the most important ruleset. It is maintained by Proofpoint, updated daily, and covers the vast majority of common attack patterns you will encounter.
+
+### Step 3 — Configure Policies
+
+Policies control what Suricata does when a rule matches — alert only, or drop the packet.
+
+Navigate to **Services → Intrusion Detection → Policy**
+
+**Recommended policy setup:**
+
+Add the following policies in order:
+
+**Policy 1 — Drop high-severity ET threats**
+| Field | Value |
+|---|---|
+| Description | Drop ET High Severity |
+| Priority | 1 |
+| Rulesets | ET Open |
+| Action | Drop |
+| Severity | ≥ High |
+
+**Policy 2 — Alert on medium-severity (tuning period)**
+| Field | Value |
+|---|---|
+| Description | Alert ET Medium |
+| Priority | 2 |
+| Rulesets | ET Open |
+| Action | Alert |
+| Severity | Medium |
+
+**Policy 3 — Drop all Feodo/Abuse.ch matches**
+| Field | Value |
+|---|---|
+| Description | Drop Botnet C2 and SSL Blacklist |
+| Priority | 1 |
+| Rulesets | Feodo Tracker, Abuse.ch SSL |
+| Action | Drop |
+| Severity | Any |
+
+> ✓ Start with medium-severity rules in **alert** mode for the first 1–2 weeks. Review alerts in the log for false positives before switching to drop. High-severity rules and the abuse.ch lists are safe to drop immediately.
+
+### Step 4 — Apply and Verify
+
+1. Click **Apply** on the Administration tab
+2. Navigate to **Services → Intrusion Detection → Alerts**
+3. Wait a few minutes — alerts should begin populating
+4. Check **Services → Intrusion Detection → Stats** to confirm traffic is being processed
+
+---
+
+## Tuning & False Positives
+
+After running in alert mode for a week, review the Alerts tab. Common false positives from home lab environments include:
+
+- **Nextcloud sync traffic** — may trigger file transfer rules
+- **Torrents/P2P** — will trigger multiple ET rules by design
+- **Internal port scanning tools** — Nmap from internal hosts triggers scan rules
+
+To suppress a false positive rule without disabling it entirely:
+
+1. Note the rule SID from the alert
+2. Go to **Services → Intrusion Detection → Rules**
+3. Search for the SID
+4. Change the rule action to **Alert** (instead of Drop) for that specific rule
+
+Alternatively, add a suppression in **Services → Intrusion Detection → Suppressions**:
+- Enter the SID
+- Set the direction (source or destination)
+- Enter the IP to suppress for that rule
+
+---
+
+## Monitoring
+
+### Alert Dashboard
+
+**Services → Intrusion Detection → Alerts** — real-time view of matched rules.
+
+Useful filters:
+- Filter by `severity: high` to see the most critical events
+- Filter by `action: drop` to see what is being actively blocked
+- Filter by source IP to investigate a specific host
+
+### Graylog Integration
+
+Forward Suricata alerts to Graylog for centralized analysis:
+
+1. Suricata logs to `/var/log/suricata/eve.json` in EVE JSON format
+2. In Graylog, add a **Beats input** or **Syslog UDP input**
+3. In OPNsense **System → Settings → Logging → Remote**, add Graylog as syslog target
+4. Create a Graylog stream filtering on `application_name: suricata`
+
+---
+
+## Key Files & Paths
+
+| Path | Purpose |
+|---|---|
+| `/var/log/suricata/eve.json` | EVE JSON alert log — used by Graylog |
+| `/var/log/suricata/stats.log` | Performance statistics |
+| `/usr/local/etc/suricata/suricata.yaml` | Main config (managed by OPNsense UI) |
+| `/usr/local/share/suricata/rules/` | Downloaded rulesets |
+
+---
+
+## Related Documentation
+
+- [OPNsense Firewall](./opnsense-firewall) — parent firewall documentation
+- [CrowdSec](./crowdsec) — complementary IP reputation layer
+- [Additional Blocklists](./opnsense-blocklists) — Feodo, Abuse.ch, ET IP blocklists at firewall level
+- [Graylog](./graylog) — centralized log target for Suricata alerts

Netgrimoire/Network/Security/OpnSense_AppInspection.md

@@ -0,0 +1,159 @@
+---
+title: OpnSense
+description: App Inspection
+published: true
+date: 2026-02-23T21:50:37.324Z
+tags: 
+editor: markdown
+dateCreated: 2026-02-23T21:50:37.324Z
+---
+
+# Zenarmor (NGFW)
+
+**Service:** Zenarmor Next-Generation Firewall
+**Plugin:** os-sunnyvalley
+**Tier:** Free Edition
+**Host:** OPNsense firewall
+
+---
+
+## Overview
+
+Zenarmor adds application-layer awareness and web filtering to OPNsense that the base firewall does not provide. Where Suricata inspects packet content for known threat signatures, Zenarmor identifies **what application or service** is generating traffic and can block or allow based on that — regardless of port.
+
+| Feature | Free Tier | Paid Tier |
+|---|---|---|
+| Layer-7 app identification | ✓ | ✓ |
+| Web category filtering | Default policy only | Custom policies |
+| Malware/phishing blocking | ✓ | ✓ |
+| Real-time network analytics | ✓ | ✓ |
+| Device tracking & alerts | ✗ | ✓ |
+| Multiple policies | ✗ | ✓ |
+| TLS inspection | ✗ | ✓ |
+
+The free tier is useful primarily for **visibility** (seeing what applications are running on your network) and **basic threat blocking** (malware, phishing, PUP domains). The analytics dashboard alone makes it worthwhile.
+
+> ✓ Zenarmor and Suricata can run simultaneously. They operate at different layers and do not conflict. Zenarmor handles application identity; Suricata handles content signatures.
+
+> ⚠ **MongoDB deprecation note:** As of September 2025, MongoDB is being deprecated as the Zenarmor database backend. Use **SQLite** when prompted during setup — it is the supported path going forward.
+
+---
+
+## Installation
+
+### Step 1 — Install the Plugin
+
+1. Go to **System → Firmware → Plugins**
+2. Search for `os-sunnyvalley`
+3. Click the **+** install button
+4. Wait for installation to complete
+5. **Refresh the browser** — a new **Zenarmor** menu item will appear in the sidebar
+
+### Step 2 — Initial Setup Wizard
+
+Navigate to **Zenarmor → Dashboard** — this launches the setup wizard on first run.
+
+**Deployment Mode:** Select **Routed Mode (L3)** for standard OPNsense setups. This is correct for your configuration.
+
+**Database:** Select **SQLite** — do not select MongoDB (deprecated September 2025).
+
+**Interface:** Select **ATT (opt1)** as the primary interface. Add **WAN (igc0)** while dual-WAN is still active.
+
+> ⚠ Zenarmor should be applied to the **LAN-facing side** of the firewall for internal traffic inspection, or the **WAN-facing side** for inbound threat blocking. For your setup, applying it to both ATT and LAN gives the most coverage.
+
+**Cloud Connectivity:** Leave enabled — Zenarmor uses cloud-based category lookups for web filtering. If you want fully offline operation, this can be disabled but web filtering accuracy degrades significantly.
+
+Click **Complete** to finish the wizard.
+
+---
+
+## Configuration
+
+### Step 3 — Security Policy
+
+Navigate to **Zenarmor → Security**
+
+Enable the following threat categories in the default policy:
+
+| Category | Action | Notes |
+|---|---|---|
+| Malware | Block | Domains known to serve malware |
+| Phishing | Block | Credential harvesting sites |
+| Botnet | Block | C2 communication |
+| PUP/Adware | Block | Potentially unwanted programs |
+| SPAM Sources | Block | Known spam infrastructure |
+| Parked Domains | Block | Often used for malicious redirects |
+
+Leave the following as **Alert** initially (review before blocking):
+- Anonymizers / Proxies — may block legitimate VPN services
+- Peer-to-peer — may affect legitimate use cases
+
+### Step 4 — Application Control
+
+Navigate to **Zenarmor → Policies → Application Control**
+
+The free tier allows one default policy. Useful applications to consider blocking or monitoring:
+
+| Application Category | Recommendation | Reason |
+|---|---|---|
+| Cryptocurrency mining | Block | Resource theft if unauthorized |
+| Remote access tools (unknown) | Alert | Unexpected remote tools are a red flag |
+| Tor | Alert | Monitor — may be legitimate or evasion |
+| Anonymous proxies | Block | Bypass attempts |
+
+### Step 5 — Web Filtering
+
+Navigate to **Zenarmor → Policies → Web Controls**
+
+In the free tier, the default policy controls all web filtering. Recommended categories to block:
+
+| Category | Action |
+|---|---|
+| Malware sites | Block |
+| Phishing | Block |
+| Hacking / exploit sites | Block |
+| Illegal content | Block |
+
+Enable **Safe Search enforcement** if desired — forces Google, Bing, and YouTube into safe search mode network-wide.
+
+---
+
+## Dashboard & Analytics
+
+Navigate to **Zenarmor → Dashboard**
+
+The dashboard provides real-time visibility into:
+- **Top talkers** — which internal hosts generate the most traffic
+- **Top applications** — what services are being used
+- **Blocked threats** — real-time feed of blocked requests
+- **Bandwidth usage** — per-host and per-application
+
+This is the primary value of the free tier — even without advanced policy control, the visibility into what is running on your network is significant.
+
+Navigate to **Zenarmor → Reports** for historical analysis and trend data.
+
+---
+
+## Performance Notes
+
+Zenarmor uses deep packet inspection which adds some CPU overhead. On modern hardware (anything with i226-V NICs) this is negligible at home lab traffic volumes. Monitor CPU usage in **Zenarmor → Dashboard → System** after enabling.
+
+If performance degrades, you can limit Zenarmor to specific interfaces rather than all interfaces.
+
+---
+
+## Known Limitations (Free Tier)
+
+- Only one web filtering policy — all devices get the same rules
+- No per-device or per-group policies
+- No TLS/SSL inspection — encrypted traffic is identified by SNI only
+- No device inventory or unknown device alerts
+- Web category database is cloud-dependent
+
+---
+
+## Related Documentation
+
+- [OPNsense Firewall](./opnsense-firewall) — parent firewall documentation
+- [Suricata IDS/IPS](./suricata-ids-ips) — complementary content inspection layer
+- [CrowdSec](./crowdsec) — IP reputation layer

Netgrimoire/Network/Security/OpnSense_Git.md

@@ -0,0 +1,182 @@
+---
+title: OpnSense 
+description: Git Integration
+published: true
+date: 2026-02-23T21:48:01.779Z
+tags: 
+editor: markdown
+dateCreated: 2026-02-23T21:48:01.779Z
+---
+
+# OPNsense Git Backup (os-git-backup)
+
+**Service:** os-git-backup
+**Plugin:** os-git-backup
+**Host:** OPNsense firewall
+**Remote:** Forgejo on Netgrimoire
+**Trigger:** Automatic on every config change
+
+---
+
+## Overview
+
+Every change made to OPNsense — adding a firewall rule, updating an alias, changing a VPN config — modifies the underlying XML configuration file. By default there is no history of these changes. If a misconfiguration causes an outage, or if you need to audit what changed after a security incident, you have no record to work from.
+
+os-git-backup solves this by committing the OPNsense configuration to a Git repository automatically every time a change is saved. Each commit records exactly what changed, when, and (if configured) which user made the change.
+
+**Benefits:**
+- Full audit trail of every configuration change
+- One-command rollback to any previous state
+- Offsite backup of firewall config via Forgejo → Kopia chain
+- Diff view to understand exactly what a change did
+
+---
+
+## Pre-requisite: Create Forgejo Repository
+
+Before installing the plugin, create a dedicated repository in Forgejo to receive the OPNsense config backups.
+
+1. Log into your Forgejo instance on Netgrimoire
+2. Create a new repository: `opnsense-config`
+3. Set visibility to **Private** — firewall configs contain sensitive network topology
+4. Do not initialize with a README (the plugin will push the first commit)
+5. Note the SSH clone URL: `git@git.netgrimoire.com:youruser/opnsense-config.git`
+
+---
+
+## Installation
+
+### Step 1 — Install the Plugin
+
+1. Go to **System → Firmware → Plugins**
+2. Search for `os-git-backup`
+3. Click the **+** install button
+4. Wait for installation to complete
+5. Navigate to **System → Configuration → Backups** — a **Git** tab will appear
+
+---
+
+## Configuration
+
+### Step 2 — Generate SSH Deploy Key
+
+The OPNsense firewall needs an SSH key to authenticate to Forgejo without a password.
+
+Navigate to **System → Configuration → Backups → Git**
+
+1. Click **Generate SSH Key**
+2. Copy the displayed **public key** — you will add this to Forgejo next
+
+### Step 3 — Add Deploy Key to Forgejo
+
+1. In Forgejo, go to your `opnsense-config` repository
+2. Navigate to **Settings → Deploy Keys**
+3. Click **Add Deploy Key**
+4. Title: `OPNsense Firewall`
+5. Key: paste the public key from Step 2
+6. Enable **Allow Write Access** — the firewall needs to push commits
+7. Click **Add Key**
+
+### Step 4 — Configure the Plugin
+
+Navigate to **System → Configuration → Backups → Git**
+
+| Setting | Value | Notes |
+|---|---|---|
+| Enabled | ✓ | |
+| URL | `git@git.netgrimoire.com:youruser/opnsense-config.git` | SSH URL from your Forgejo repo |
+| Branch | `main` | |
+| Name | `OPNsense Firewall` | Author name shown in commits |
+| Email | `opnsense@netgrimoire.com` | Author email shown in commits |
+| SSH Private Key | (auto-populated from Step 2) | |
+| Backup Interval | On change | Commits every time config is saved |
+
+Click **Save**.
+
+### Step 5 — Test the Connection
+
+Click **Backup Now** to trigger a manual backup. Then check your Forgejo repository — you should see an initial commit containing the OPNsense configuration XML.
+
+If the push fails, check:
+1. The deploy key has write access in Forgejo
+2. The SSH URL is correct (use SSH, not HTTPS)
+3. Forgejo is reachable from the firewall — test from OPNsense shell:
+   ```bash
+   ssh -T git@git.netgrimoire.com
+   # Expected: Hi youruser! You've successfully authenticated...
+   ```
+
+---
+
+## What Gets Backed Up
+
+The plugin commits the OPNsense configuration file:
+
+`/conf/config.xml`
+
+This single file contains **everything** — interfaces, firewall rules, NAT, VPN configs, aliases, users, certificates, DHCP, DNS settings, and all plugin configurations. A restore from this file fully recreates the firewall state.
+
+> ⚠ The config.xml contains **hashed passwords**, **VPN private keys**, and **API credentials**. The Forgejo repository must remain private. Ensure your Forgejo instance is not publicly accessible or that this repository is explicitly private.
+
+---
+
+## Using the Backup
+
+### Viewing History
+
+In Forgejo, navigate to the `opnsense-config` repository. Each commit represents one configuration save, with:
+- Timestamp of the change
+- Diff showing exactly what XML changed
+- Author (OPNsense Firewall)
+
+### Rolling Back a Change
+
+If a configuration change causes problems:
+
+**Option 1 — Restore via OPNsense UI:**
+1. In Forgejo, find the commit you want to restore
+2. Download the `config.xml` from that commit
+3. In OPNsense: **System → Configuration → Backups → Restore**
+4. Upload the config.xml and restore
+
+**Option 2 — Restore via shell (if UI is unreachable):**
+```bash
+# SSH into OPNsense
+ssh root@192.168.3.4
+
+# The git repo is cloned locally — find it
+find /conf -name ".git" -type d
+
+# Check out the previous config
+cd /conf/backup   # or wherever the repo is cloned
+git log --oneline -10
+git checkout <commit-hash> -- config.xml
+
+# Apply the restored config
+/usr/local/sbin/opnsense-importer config.xml
+```
+
+### Diffing Changes
+
+To see exactly what a specific change did:
+
+```bash
+# In Forgejo: click any commit → view the diff
+# Alternatively, from the OPNsense shell:
+cd <git repo path>
+git diff HEAD~1 HEAD -- config.xml
+```
+
+---
+
+## Integration with Kopia Backups
+
+Since the git repository lives in Forgejo on Netgrimoire, it is automatically included in the Netgrimoire Kopia backup chain — no additional configuration needed. The OPNsense config history is backed up offsite along with everything else.
+
+---
+
+## Related Documentation
+
+- [OPNsense Firewall](./opnsense-firewall) — parent firewall documentation
+- [Forgejo](./forgejo) — Git repository host on Netgrimoire
+- [Kopia Backups](./kopia) — offsite backup chain