feat: merge Gitea webhook security into setup wizard (issue #2)

Integrates the 5-layer Gitea webhook security system from
sol/clawgravity-hook-security (v2.0) into the setup wizard.

## What's added

### New files (from clawgravity-hook-security v2.0)
- scripts/webhook-security/gitea-hmac-verify.js    -- njs HMAC-SHA256 module
- scripts/webhook-security/gitea-approve-repo       -- allowlist helper
- scripts/webhook-security/rotate-webhook-secret.sh -- monthly secret rotation (templated)
- scripts/webhook-security/webhook-audit-alert.sh   -- daily audit summaries (templated)
- scripts/webhook-security/ntfy-blocked-pickup.sh   -- blocked webhook alerts (templated)
- templates/webhook-security/nginx-site.conf.example
- templates/webhook-security/nginx.conf.example
- templates/webhook-security/gitea-repo-allowlist.json.example
- docs/WEBHOOK-SECURITY.md   -- full documentation
- docs/SECURITY-AUDIT.md     -- 35-case test matrix
- tests/test-webhook-security.sh  -- 48 offline tests

### Modified files
- setup.sh: Step 11 (webhook security wizard with 6 sub-sections)
- scripts/uninstall.sh: webhook security cleanup section
- README.md: Webhook Security section after Quick Start
- Makefile: test target now runs test-webhook-security.sh
- .secret-scan-allowlist: allowlist docs/SECURITY-AUDIT.md (test fixture)

## Security layers
1. IP allowlisting (nginx)
2. Rate limiting 10 req/s burst 20 (nginx)
3. Payload size 1MB (nginx)
4. HMAC-SHA256 signature verification (njs)
5. Per-repository allowlist (njs)

## make check
- prettier: PASS
- secret-scan: PASS
- tests: 48/48 PASS

Closes #2
This commit is contained in:
sol
2026-03-01 08:43:02 +00:00
parent 5382ba4999
commit 2db7d7d90a
16 changed files with 1960 additions and 2 deletions

View File

@@ -46,6 +46,38 @@ The interactive wizard will:
Every install step asks for your confirmation first — you have full control over what gets installed.
## Webhook Security (Optional)
The setup wizard includes an optional Step 11 that installs 5-layer webhook
security for the `/hooks/gitea` endpoint. This protects your OpenClaw instance
from unauthorized webhook requests.
**Security layers:**
1. IP allowlisting (only your Gitea server can send webhooks)
2. Rate limiting (10 req/s, burst 20)
3. Payload size limit (1MB)
4. HMAC-SHA256 signature verification (njs module)
5. Per-repository allowlist (only approved repos can trigger agents)
**What gets installed (when you choose to enable it during setup):**
- nginx njs HMAC module (`/etc/nginx/njs/gitea-hmac-verify.js`)
- Webhook secret file (`/etc/nginx/gitea-webhook-secret`)
- Repository allowlist (`/etc/nginx/gitea-repo-allowlist.json`)
- Helper scripts (`/opt/webhook-security/scripts/`)
- `gitea-approve-repo` command (add repos to allowlist)
After installation, manage the allowlist with:
```bash
gitea-approve-repo owner/repo # Allow a specific repo
cat /etc/nginx/gitea-repo-allowlist.json # View current allowlist
```
Full documentation: [docs/WEBHOOK-SECURITY.md](docs/WEBHOOK-SECURITY.md)
Security audit: [docs/SECURITY-AUDIT.md](docs/SECURITY-AUDIT.md)
## Prerequisites
- Linux server with **systemd**